MCP e assistentes de IA

O Model Context Protocol é um padrão aberto para dar ferramentas a assistentes de IA. O Gradiently mantém um servidor MCP hospedado em https://gradiently.design/api/mcp. Conecte uma vez com uma chave de API, e seu assistente pode chamar as ferramentas do Gradiently enquanto você conversa com ele. Cada ferramenta faz as mesmas requisições à API que o seu próprio código faria, então tem as mesmas permissões, licenças, créditos e limites.

Antes de conectar

• Crie uma chave em Configurações › API e agentes (veja Chaves de API e escopos). A chave decide em qual workspace o assistente trabalha e quais ferramentas vão funcionar.
• Toda requisição ao servidor precisa levar a chave como Authorization: Bearer gr_live_…, inclusive a primeira. Sem ela, o servidor responde 401.
• O servidor usa Streamable HTTP, sem estado, com respostas em JSON. Ele não precisa de sessão e não tem um fluxo de eventos separado para abrir.
• O servidor aceita só chaves de API. Ele não oferece login por OAuth.

Conectar o Claude Code

Adicione o Gradiently como servidor remoto por HTTP, com sua chave no cabeçalho. Guarde a chave em uma variável de ambiente para que ela nunca vá parar no histórico do shell nem em um arquivo com commit.

export GRADIENTLY_API_KEY="gr_live_…"

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

Abra uma nova sessão do Claude Code e peça para ele listar as ferramentas do Gradiently para testar a conexão. Se ele informar um erro de autenticação, a chave foi digitada errado, foi revogada, ou quem a criou não é mais proprietário ou admin do workspace.

Outros clientes

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

• Claude Desktop e claude.ai adicionam servidores remotos como conectores personalizados. Se o formulário do conector permitir definir um cabeçalho Authorization, use a URL e o cabeçalho acima. Se ele só oferecer login por OAuth, o Gradiently ainda não pode ser conectado ali.
• ChatGPT e outros assistentes: a mesma regra. Onde o cliente aceita servidores MCP remotos com um cabeçalho bearer, conecte com a URL e sua chave.
• Clientes configurados por um arquivo JSON costumam aceitar o formato abaixo, que também aparece em Configurações, em Conectar um cliente MCP. Confira a documentação do seu cliente para ver 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 escopo faltando ou um modelo desconhecido.
• As ferramentas que precisam de uma marca aceitam um personality opcional (o id ou o slug dela). Sem ele, usam a primeira marca do workspace.
• As ferramentas que salvam um design devolvem o link do Studio, o endereço /studio/<id> do design em gradiently.design.
• Várias ferramentas primeiro consultam suas marcas por /api/me, que precisa de workspaces:read e designs:read. Essas ferramentas listam os dois escopos abaixo.
• Uma chamada de ferramenta conta para o limite de requisições da sua chave uma vez pela requisição MCP e uma vez para cada requisição à API que a ferramenta faz.

Marks

Uma reserva que exige pagamento falha com uma mensagem dizendo que precisa de checkout; conclua no Gradiently. Uma chave não pode pagar por nada.

Marcas e workspace

tone aceita até três destes: calm, bold, warm, cool, playful, luxe, natural, technical, editorial e nocturnal; uma requisição com mais é recusada. colours aceita até oito cores hex e count pede de uma a oito propostas; acima disso, a requisição também é recusada. Para adotar uma proposta, envie exatamente a entrada que a gerou junto com a key da proposta: o servidor cria a proposta de novo a partir dessa entrada e nunca confia em uma receita enviada pelo cliente.

Criar designs

design e create_designs gastam os créditos de IA do workspace, como o Designer faz no Studio. Quando o saldo é baixo demais, elas falham com uma mensagem avisando; faça uma recarga em Configurações › Créditos de IA. No máximo dois conjuntos rodam ao mesmo tempo por pessoa, e um conjunto concluído fica disponível para leitura por uns vinte minutos. Os designs em si continuam salvos.

Uma composição indica um size (o id de um tamanho predefinido, como ig-post, x-post ou li-banner, ou {w, h} em pixels), um layout (statement, editorial, poster, split, stat, quote, list, event ou minimal) e blocks na 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 em um 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 que seja seu com uma licença ativa. Indicar o Mark pelo código também precisa de marks:read.

render_design aceita width e height de 1 a 4096 pixels e format png ou pdf. page conta a partir de 0: o PNG renderiza a primeira página por padrão e o PDF, todas as páginas. Um PDF mantém cada página no tamanho dela no Studio, então o tamanho que você pedir precisa ser o mesmo. Renderizar exige a mesma licença de exportação do Mark do design que o Studio exige, e nunca publica nem altera o design.

Exemplos de pedidos

• “Encontre no Mercado Marks escuros com cromado e me mostre os três mais próximos de um azul-petróleo profundo.” Usa search_marks.
• “Gere direções de marca para a Hearth, uma padaria de bairro, calma e acolhedora, e adote a que tiver a paleta mais suave.” Usa generate_brand e adopt_brand.
• “Forje um Mark chamado Night Harbour: um fundo vazio, do azul-marinho ao laranja de lâmpada de sódio, uma camada discreta de granulação. Corrija o que a revisão apontar e depois salve.” Usa make_mark e save_mark.
• “Mude o título do design 4f1c… para ‘Portas abertas às sete’ e faça cópias para um story do Instagram e um post do X.” Usa get_design, update_design_text e resize_copies.
• “Renderize o design 4f1c… como PNG de 1080 por 1350 e salve em launch.png.” Usa render_design.
• “Crie um pôster para a nossa festa de 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 dessas ferramentas está em Referência da API. Para qualquer outra coisa, envie uma solicitação.