MCP e assistentes de IA

O Model Context Protocol é um padrão aberto para dar ferramentas a assistentes de IA. O Gradiently tem um servidor MCP alojado em https://gradiently.design/api/mcp. Liga-o uma vez com uma chave de API, e o teu assistente pode chamar as ferramentas do Gradiently enquanto falas com ele. Cada ferramenta faz os mesmos pedidos à API que o teu próprio código faria, por isso tem as mesmas permissões, licenças, créditos e limites.

Antes de ligar

• Cria uma chave em Definições › API e agentes (vê Chaves de API e âmbitos). A chave decide em que espaço de trabalho o assistente trabalha e que ferramentas vão funcionar.
• Cada pedido ao servidor tem de levar a chave como Authorization: Bearer gr_live_…, incluindo o primeiro. Sem ela, o servidor responde 401.
• O servidor fala Streamable HTTP, sem estado, com respostas JSON. Não precisa de sessão nem tem um fluxo de eventos separado para abrir.
• O servidor só aceita chaves de API. Não oferece início de sessão OAuth.

Ligar o Claude Code

Adiciona o Gradiently como servidor remoto por HTTP, com a tua chave no cabeçalho. Guarda a chave numa variável de ambiente para que nunca fique no histórico da shell nem num ficheiro enviado para o repositório.

export GRADIENTLY_API_KEY="gr_live_…"

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

Inicia uma nova sessão do Claude Code e pede-lhe para listar as ferramentas do Gradiently para verificar a ligação. Se indicar um erro de autenticação, a chave foi mal escrita, foi revogada, ou o seu criador já não é proprietário nem admin do espaço de trabalho.

Outros clientes

Qualquer cliente que consiga adicionar um servidor MCP remoto por Streamable HTTP e enviar um cabeçalho de pedido personalizado pode usar o Gradiently com o mesmo URL e cabeçalho. Se o teu consegue ou não depende do cliente e da sua versão.

• Claude Desktop e claude.ai adicionam servidores remotos como conectores personalizados. Se o formulário do conector te deixar definir um cabeçalho Authorization, usa o URL e o cabeçalho acima. Se só oferecer início de sessão OAuth, o Gradiently ainda não pode ser ligado aí.
• ChatGPT e outros assistentes: a mesma regra. Onde o cliente suportar servidores MCP remotos com um cabeçalho bearer, liga-o com o URL e a tua chave.
• Clientes configurados com um ficheiro JSON aceitam muitas vezes o formato abaixo, que também aparece nas Definições em Ligar um cliente MCP. Consulta a documentação do teu cliente para o formato exato.

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

Como as ferramentas se comportam

• Cada ferramenta devolve o resultado como texto JSON. Quando algo falha, a ferramenta devolve a mensagem de erro da API, como um âmbito em falta ou um modelo desconhecido.
• As ferramentas que precisam de uma marca aceitam um personality opcional (o seu id ou slug). Sem ele, usam a primeira marca do espaço de trabalho.
• As ferramentas que guardam um design devolvem o seu link do Estúdio, o endereço /studio/<id> do design em gradiently.design.
• Várias ferramentas procuram primeiro as tuas marcas através de /api/me, que precisa de workspaces:read e de designs:read. Essas ferramentas indicam os dois âmbitos abaixo.
• Uma chamada de ferramenta conta para o limite de pedidos da tua chave uma vez pelo pedido MCP e uma vez por cada pedido à API que a ferramenta faz.

Marks

Uma reserva que exija pagamento falha com uma mensagem a indicar que precisa de checkout; conclui-a no Gradiently. Uma chave não pode pagar nada.

Marcas e espaço de trabalho

tone aceita até três de calm, bold, warm, cool, playful, luxe, natural, technical, editorial e nocturnal; um pedido com mais é recusado. colours aceita até oito cores hex e count pede de uma a oito propostas; acima disso, o pedido também é recusado. Para adotar uma proposta, envia exatamente a entrada que a gerou com a key da proposta: o servidor volta a criar a proposta a partir dessa entrada e nunca confia numa receita enviada pelo cliente.

Criar designs

design e create_designs gastam os créditos de IA do espaço de trabalho, tal como o Designer no Estúdio. Quando o saldo é demasiado baixo, falham com uma mensagem a indicá-lo; recarrega em Definições › Créditos de IA. No máximo, correm dois conjuntos de cada vez por pessoa, e um conjunto terminado continua legível durante cerca de vinte minutos. Os designs em si ficam.

Uma composição indica um size (o id de uma predefinição como ig-post, x-post ou li-banner, ou {w, h} em píxeis), um layout (statement, editorial, poster, split, stat, quote, list, event ou minimal) e blocks por ordem de leitura, cada um com um role como headline, body ou cta e o seu text.

{
  "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" }
    ]
  }
}

Editar e exportar

wear_mark num design precisa de designs:read e designs:write. Tornar um Mark o Mark de uma marca precisa de workspaces:read, designs:read e personalities:write, e de um Mark de que és detentor com uma licença ativa. Indicar o Mark pelo seu código também precisa de marks:read.

render_design aceita width e height de 1 a 4096 píxeis e format png ou pdf. page conta a partir de 0: o PNG gera a primeira página por predefinição e o PDF todas as páginas. Um PDF mantém cada página no seu tamanho do Estúdio, por isso o tamanho que pedes tem de corresponder. Gerar precisa da mesma licença de exportação para o Mark do design que o Estúdio, e nunca publica nem altera o design.

Exemplos de pedidos

• “Encontra no Mercado Marks escuros com cromado e mostra-me os três mais próximos de azul-petróleo profundo.” Usa search_marks.
• “Gera direções de marca para a Hearth, uma padaria de bairro, calma e acolhedora, e adota a que tiver a paleta mais suave.” Usa generate_brand e adopt_brand.
• “Forja um Mark chamado Night Harbour: um fundo vazio, de azul-marinho a laranja de sódio, uma camada de grão discreta. Corrige o que a revisão assinalar e depois guarda-o.” Usa make_mark e save_mark.
• “Muda o título do design 4f1c… para ‘Portas abertas às sete’ e faz cópias para uma story do Instagram e uma publicação no X.” Usa get_design, update_design_text e resize_copies.
• “Gera o design 4f1c… como PNG de 1080 por 1350 e guarda-o em launch.png.” Usa render_design.
• “Faz um cartaz para a nossa festa do solstício no terraço, 21 de junho, do pôr do sol ao nascer do sol.” Usa design, que precisa de workspaces:read.

A referência completa dos endpoints por trás destas ferramentas está em Referência da API. Para tudo o resto, envia-nos um pedido.