MCP y asistentes de IA

El Model Context Protocol es un estándar abierto para dar herramientas a los asistentes de IA. Gradiently tiene un servidor MCP alojado en https://gradiently.design/api/mcp. Conéctalo una vez con una clave de API y tu asistente podrá llamar a las herramientas de Gradiently mientras hablas con él. Cada herramienta hace las mismas peticiones a la API que haría tu propio código, así que tiene los mismos permisos, licencias, créditos y límites.

Antes de conectar

Crea una clave en Ajustes › API y agentes (consulta Claves de API y permisos). La clave decide en qué espacio de trabajo trabaja el asistente y qué herramientas funcionarán.
Cada petición al servidor debe llevar la clave como Authorization: Bearer gr_live_…, incluida la primera. Sin ella, el servidor responde 401.
El servidor usa Streamable HTTP, sin estado, con respuestas JSON. No necesita sesión ni tiene un flujo de eventos aparte que abrir.
El servidor solo acepta claves de API. No ofrece inicio de sesión con OAuth.

Conectar Claude Code

Añade Gradiently como servidor remoto por HTTP, con tu clave en la cabecera. Guarda la clave en una variable de entorno para que nunca acabe en el historial de tu terminal ni en un archivo del repositorio.

bash

export GRADIENTLY_API_KEY="gr_live_…"

claude mcp add --transport http gradiently https://gradiently.design/api/mcp \
  --header "Authorization: Bearer $GRADIENTLY_API_KEY"

Abre una sesión nueva de Claude Code y pídele que enumere las herramientas de Gradiently para comprobar la conexión. Si indica un error de autenticación, la clave se escribió mal, se revocó o su creador ya no es propietario ni administrador del espacio de trabajo.

Otros clientes

Cualquier cliente que pueda añadir un servidor MCP remoto por Streamable HTTP y enviar una cabecera personalizada puede usar Gradiently con la misma URL y la misma cabecera. Que el tuyo pueda depende del cliente y de su versión.

Claude Desktop y claude.ai añaden servidores remotos como conectores personalizados. Si el formulario del conector te deja definir una cabecera Authorization, usa la URL y la cabecera de arriba. Si solo ofrece inicio de sesión con OAuth, Gradiently todavía no se puede conectar ahí.
ChatGPT y otros asistentes: la misma regla. Si el cliente admite servidores MCP remotos con una cabecera bearer, conéctalo con la URL y tu clave.
Los clientes que se configuran con un archivo JSON suelen aceptar la estructura de abajo, que también aparece en Ajustes en Conectar un cliente MCP. Consulta la documentación de tu cliente para ver su formato exacto.

json

{
  "mcpServers": {
    "gradiently": {
      "url": "https://gradiently.design/api/mcp",
      "headers": { "Authorization": "Bearer gr_live_…" }
    }
  }
}

Cómo se comportan las herramientas

Cada herramienta devuelve su resultado como texto JSON. Si algo falla, la herramienta devuelve en su lugar el mensaje de error de la API, como un permiso que falta o una plantilla desconocida.
Las herramientas que necesitan una marca aceptan un personality opcional (su id o slug). Sin él, usan la primera marca del espacio de trabajo.
Las herramientas que guardan un diseño devuelven su enlace al Estudio, la dirección /studio/<id> del diseño en gradiently.design.
Varias herramientas buscan primero tus marcas mediante /api/me, que necesita workspaces:read y designs:read. Esas herramientas indican ambos permisos abajo.
Una llamada a una herramienta cuenta para el límite de uso de tu clave una vez por la petición MCP y una vez por cada petición a la API que hace la herramienta.

Marks

Herramienta	Qué hace	Entradas	Permisos
`search_marks`	Busca en el Mercado público por nombre o código. Devuelve colores, materiales, estado y titular.	`q`, `tone` (dark o light), `limit` (de 1 a 120, 24 por defecto), todos opcionales	`marks:read`
`get_mark`	Un Mark y su receta completa.	`code` (un código o un id)	`marks:read`
`list_marks`	Los Marks reservados para este espacio de trabajo, con el estado de su licencia, y tus borradores en él.	ninguna	`marks:read`
`claim_mark`	Reserva un Mark disponible. El titular es el creador de la clave, nunca el espacio de trabajo.	`code`	`marks:read`, `marks:claim`
`make_mark`	Crea una receta de Mark a partir de una intención, o edita una, con una revisión de color y legibilidad y el Mark más parecido del Mercado. No guarda nada.	`spec`, o `recipe` y `edit`	`marks:read`
`save_mark`	Guarda una receta como tu Mark privado en borrador, o actualiza un borrador tuyo. Devuelve su enlace a la Forge.	`name`, `recipe`, `id` (opcional)	`brand:generate`
`export_mark`	Renderiza un Mark por sí solo como PNG, hasta 4096 px por lado.	`mark`, `width`, `height`, `personality`	`workspaces:read`, `designs:read`, `designs:write`
`list_mark_versions`	Las versiones guardadas de un borrador, de la más reciente a la más antigua. Solo las ve el creador del Mark.	`mark`, `cursor`	`marks:read`
`save_mark_version`	Conserva un borrador tal como está ahora, o una receta dada, como versión con nombre.	`mark`, `label`, `recipe`	`brand:generate`
`restore_mark_version`	Vuelve a poner una versión como borrador. Antes, el estado actual se guarda como versión.	`mark`, `version`	`brand:generate`
`update_mark_version`	Cambia el nombre de una versión o la marca con estrella. Las versiones con estrella se conservan.	`mark`, `version`, `label`, `starred`	`brand:generate`
`delete_mark_version`	Elimina una versión, nunca la publicada.	`mark`, `version`	`brand:generate`

Una reserva que requiere pago falla con un mensaje que indica que hay que pasar por caja; termínala en Gradiently. Una clave no puede pagar nada.

Marcas y espacio de trabajo

Herramienta	Qué hace	Entradas	Permisos
`generate_brand`	Crea propuestas de marca a partir de un nombre y una descripción. La misma entrada siempre da las mismas propuestas.	`input`: `name`, `description`, `industry`, `tone`, `colours`, `count`, `nonce`	`brand:generate`
`adopt_brand`	Convierte una propuesta en un Mark en borrador, una marca y tres diseños iniciales, en un solo paso.	`input` (sin cambios), `key`	`brand:generate`
`list_personalities`	Las marcas del espacio de trabajo, con sus ids.	ninguna	`workspaces:read`, `designs:read`
`create_personality`	Crea una marca con nombre.	`name`	`personalities:write`
`get_brand_profile`	Qué es una marca, para quién es, su tono, lo que hace y lo que evita, y sus fuentes.	`personality`	`workspaces:read`, `designs:read`
`update_brand_profile`	Sustituye el perfil de una marca. El Designer lo lee antes de cada diseño.	`personality`, `profile`	`workspaces:read`, `designs:read`, `personalities:write`
`my_workspace`	Tú, las marcas del espacio de trabajo con los códigos de sus Marks, y los Marks reservados para él.	ninguna	`workspaces:read`, `designs:read`, `marks:read`
`list_workspaces`	El espacio de trabajo de la clave y tu rol en él.	`cursor`	`workspaces:read`
`invite_member`	Envía por correo una invitación de siete días para unirse al espacio de trabajo.	`workspaceId`, `email`, `role` (admin, editor o viewer)	`members:write`

tone acepta hasta tres de calm, bold, warm, cool, playful, luxe, natural, technical, editorial y nocturnal; una petición con más se rechaza. colours acepta hasta ocho colores hex y count pide de una a ocho propuestas; por encima de eso, la petición también se rechaza. Para adoptar una propuesta, envía exactamente la entrada que la generó con la key de la propuesta: el servidor vuelve a crear la propuesta a partir de esa entrada y nunca se fía de una receta enviada por el cliente.

Diseñar

Herramienta	Qué hace	Entradas	Permisos
`design`	Pide al propio Designer de Gradiently que cree un diseño, o que cambie uno, a partir de una petición en lenguaje natural. Lee el perfil de marca y el Mark, diseña, revisa y guarda.	`request`, `personality`, `size`, `designId`, `scope`, `selection`	`workspaces:read`, `designs:read`, `designs:write`
`create_designs`	Crea un conjunto de hasta doce diseños a partir de un solo brief, en segundo plano.	`brief`, `items` (`size`, `brief`, `title`), `title`, `personality`, `mark`, `wait`	`workspaces:read`, `designs:read`, `designs:write`
`get_design_set`	El progreso de un conjunto y el enlace al Estudio de cada diseño en cuanto existe.	`id`	`designs:read`
`stop_design_set`	Detiene un conjunto en curso. Los diseños ya creados siguen guardados.	`id`	`designs:write`
`compose_design`	Maqueta tus textos con el motor de maquetación y guarda el diseño. Devuelve los problemas de la revisión que hay que corregir.	`composition`, `personality`, `designId`, `title`	`workspaces:read`, `designs:read`, `designs:write`
`find_templates`	Busca entre los diseños hechos a mano de Gradiently. Devuelve hasta seis, con una imagen y sus huecos.	`query`, `size`	cualquier clave
`use_template`	Crea un diseño guardado a partir de una plantilla, conservando su composición.	`template`, `text`, `photos`, `icons`, `hide`, `personality`, `designId`	`workspaces:read`, `designs:read`, `designs:write`
`list_templates`	Los ids de las plantillas iniciales con los ids de sus elementos de texto, y todos los tamaños predefinidos.	ninguna	cualquier clave
`create_design`	Crea un diseño a partir del id de una plantilla inicial, un tamaño predefinido y textos indexados por id de elemento.	`template`, `size`, `copy`, `look`, `personality`	`workspaces:read`, `designs:read`, `designs:write`

design y create_designs gastan los créditos de IA del espacio de trabajo, igual que el Designer en el Estudio. Si el saldo es demasiado bajo, fallan con un mensaje que lo indica; recarga en Ajustes › Créditos de IA. Cada persona puede tener como máximo dos conjuntos en curso a la vez, y un conjunto terminado se puede consultar durante unos veinte minutos. Los diseños en sí se conservan.

Una composición indica un size (el id de un tamaño predefinido como ig-post, x-post o li-banner, o {w, h} en píxeles), un layout (statement, editorial, poster, split, stat, quote, list, event o minimal) y blocks en orden de lectura, cada uno con un role como headline, body o cta y su text.

json

{
  "composition": {
    "size": "ig-post",
    "layout": "event",
    "blocks": [
      { "role": "eyebrow", "text": "Summer supper club" },
      { "role": "headline", "text": "Long table on the roof" },
      { "role": "details", "text": "", "items": ["Saturday 21 June", "7pm till late"] },
      { "role": "cta", "text": "Book a seat" }
    ]
  }
}

Entrada para compose_design. La respuesta incluye el id del diseño, su enlace al Estudio, los problemas de la revisión y los elementos que ha colocado.

Editar y exportar

Herramienta	Qué hace	Entradas	Permisos
`list_designs`	Los diseños guardados de una marca, con enlaces al Estudio.	`personality`	`workspaces:read`, `designs:read`
`get_design`	El tamaño, las páginas y cada elemento de un diseño con sus propiedades. Filtra los diseños largos por página, tipo, nombre o texto.	`id`, `page`, `kind`, `name`, `text`	`designs:read`
`edit_design`	Cambia un diseño con hasta 100 operaciones, como lo haría una persona en el Estudio, y lo guarda.	`id`, `ops`, `page`	`designs:write`
`update_design_text`	Sustituye las palabras de los elementos de texto elegidos y conserva la maquetación.	`id`, `text` (id de elemento a palabras)	`designs:read`, `designs:write`
`resize_copies`	Guarda copias en hasta ocho tamaños más, recolocadas como lo hace el Estudio. El original no cambia.	`id`, `sizes`	`designs:read`, `designs:write`
`wear_mark`	Pone un Mark en un diseño, o lo convierte en el Mark de una marca para los diseños nuevos.	`mark`, y `design` o `personality`	ver abajo
`render_design`	Renderiza un diseño guardado en PNG o PDF con el motor del Estudio. Devuelve el archivo en base64.	`id`, `width`, `height`, `format`, `page`	`designs:read`
`export_design_link`	Publica un enlace de visualización, `/d/<id>`, que puede abrir cualquiera que lo tenga.	`id`	`designs:write`

wear_mark en un diseño necesita designs:read y designs:write. Convertir un Mark en el Mark de una marca necesita workspaces:read, designs:read y personalities:write, y un Mark del que seas titular con una licencia activa. Indicar el Mark por su código también necesita marks:read.

render_design acepta width y height de 1 a 4096 píxeles y format png o pdf. page empieza en 0: en PNG se renderiza por defecto la primera página y en PDF todas. Un PDF mantiene cada página a su tamaño del Estudio, así que el tamaño que pidas debe coincidir. Renderizar requiere la misma licencia de exportación para el Mark del diseño que el Estudio, y nunca publica ni cambia el diseño.

Peticiones de ejemplo

«Busca en el Mercado Marks oscuros con cromo y muéstrame los tres más cercanos al verde azulado profundo.» Usa search_marks.
«Genera direcciones de marca para Hearth, una panadería de barrio, tranquila y cálida, y adopta la de la paleta más suave.» Usa generate_brand y adopt_brand.
«Forja un Mark llamado Night Harbour: un fondo void, del azul marino al naranja sodio, con una sola capa de grano suave. Corrige lo que señale la revisión y guárdalo.» Usa make_mark y save_mark.
«Cambia el titular del diseño 4f1c… por “Abrimos a las siete” y haz copias para una historia de Instagram y una publicación de X.» Usa get_design, update_design_text y resize_copies.
«Renderiza el diseño 4f1c… como PNG de 1080 por 1350 y guárdalo en launch.png.» Usa render_design.
«Haz un póster para nuestra fiesta del solsticio en la azotea, el 21 de junio, del atardecer al amanecer.» Usa design, que necesita workspaces:read.

La referencia completa de los endpoints que hay detrás de estas herramientas está en Referencia de la API. Para cualquier otra cosa, envíanos una solicitud.