O servidor aceita tokens de acesso OAuth e chaves API do espaço. Ambos usam as mesmas permissões, licenças, créditos e limites. O Model Context Protocol é um padrão aberto para dar ferramentas a assistentes de IA. O Gradiently tem um servidor MCP alojado. O ChatGPT liga-se a https://, e o Claude e outros clientes a https://. 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.
- Um cliente com chave API envia
Authorization: Bearer gr_live_…. O ChatGPT e o Claude enviam o token OAuth após o início de sessão. - 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 aceita tokens de acesso OAuth e chaves API do espaço. Ambos usam as mesmas permissões, licenças, créditos e limites.
Ligar o ChatGPT e o Claude
Adiciona um conector personalizado com ChatGPT: https://; Claude: https:// e escolhe o início de sessão OAuth. Inicia sessão no Gradiently, escolhe um espaço e revê as permissões. Só os proprietários e administradores podem ligar um assistente.
As ligações expiram após uma hora e renovam-se automaticamente durante um máximo de 30 dias. Revoga uma ligação em Definições › API e agentes para parar imediatamente o acesso e a renovação.
Uma ligação personalizada e uma entrada no diretório público são distintas. A publicação no diretório exige a análise e aprovação da OpenAI ou da Anthropic.
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.
# Paste your key when asked. It stays hidden and out of your shell history.
read -rs GRADIENTLY_API_KEY && export GRADIENTLY_API_KEY
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.
- 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
- As ferramentas devolvem texto JSON.
inspect_designtambém devolve uma imagem PNG. As falhas devolvem uma mensagem de erro. - As ferramentas que precisam de uma marca aceitam um
personalityopcional (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
/do design em gradiently.design.studio/ <id> - Várias ferramentas procuram primeiro as tuas marcas através de
/, que precisa deapi/ me workspaces:reade dedesigns: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
search_marksO que faz
Entradas
q, tone (dark ou light), limit (de 1 a 120, 24 por omissão), todos opcionaisÂmbitos
marks:readget_markO que faz
Entradas
code (um código ou um id)Âmbitos
marks:readlist_marksO que faz
Entradas
Âmbitos
marks:readclaim_markO que faz
Entradas
codeÂmbitos
marks:read, marks:claimexport_markO que faz
Entradas
mark, width, height, personalityÂmbitos
workspaces:read, designs:read, designs:writerestore_mark_versionO que faz
Entradas
mark, versionÂmbitos
brand:generateupdate_mark_versionO que faz
Entradas
mark, version, label, starredÂmbitos
brand:generatedelete_mark_versionO que faz
Entradas
mark, versionÂmbitos
brand:generateUma 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
list_personalitiesO que faz
Entradas
Âmbitos
workspaces:read, designs:readcreate_personalityO que faz
Entradas
nameÂmbitos
personalities:writeget_brand_profileO que faz
Entradas
personalityÂmbitos
workspaces:read, designs:readupdate_brand_profileO que faz
Entradas
personality, profileÂmbitos
workspaces:read, designs:read, personalities:writemy_workspaceO que faz
Entradas
Âmbitos
workspaces:read, designs:read, marks:readlist_workspacesO que faz
Entradas
cursorÂmbitos
workspaces:readinvite_memberO que faz
Entradas
workspaceId, email, role (admin, editor ou viewer)Âmbitos
members:writetone 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
Para criar trabalho original, pede à tua IA ligada que leia o perfil da marca e get_design_guidance, crie com draw_design, analise a imagem real com inspect_design e refine com edit_design. Desenhar, editar e analisar diretamente não consome créditos de IA do Gradiently. Continuam a aplicar-se os limites do teu fornecedor e as permissões de conta e exportação. Um desenho pode incluir ilustrações vetoriais próprias do anfitrião, SVG limpo, gráficos nativos, gráficos da biblioteca e fotografias licenciadas; tudo continua editável no Studio. A pesquisa e a importação de fotografias acedem ao Openverse, um catálogo externo.
get_design_guidanceO que faz
Entradas
purpose, topicÂmbitos
draw_designO que faz
Entradas
drawing, personality, mark, designId, page, titleÂmbitos
designs:write, workspaces:read, designs:read, marks:readinspect_designO que faz
Entradas
id, page, maxDimensionÂmbitos
designs:readfind_iconsO que faz
Entradas
query, limitÂmbitos
find_graphicsO que faz
Entradas
query, limitÂmbitos
find_photosO que faz
Entradas
query, countÂmbitos
designs:readimport_photoO que faz
Entradas
idÂmbitos
designs:writedesignPede ao Designer do próprio Gradiently que crie um design, ou altere um, a partir de um pedido em palavras simples. Lê o perfil da marca e o Mark, cria o design, revê e guarda. Utiliza créditos de IA do Gradiently.Entradas
request, personality, size, designId, scope, selectionÂmbitos
workspaces:read, designs:read, designs:writecreate_designsO que faz
Entradas
brief, items (size, brief, title), title, personality, mark, waitÂmbitos
workspaces:read, designs:read, designs:writeget_design_setO que faz
Entradas
idÂmbitos
designs:readstop_design_setO que faz
Entradas
idÂmbitos
designs:writecompose_designO que faz
Entradas
composition, personality, designId, titleÂmbitos
workspaces:read, designs:read, designs:writelist_sizesO que faz
Entradas
Âmbitos
create_designO que faz
Entradas
form, size, copy, look, personalityÂmbitos
workspaces:read, designs:read, designs:writedesign 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" }
]
}
}compose_design. A resposta contém o id do design, o seu link do Estúdio, os problemas de revisão e os elementos que colocou.Editar e exportar
list_designsO que faz
Entradas
personalityÂmbitos
workspaces:read, designs:readget_designO que faz
Entradas
id, page, kind, name, textÂmbitos
designs:readedit_designO que faz
Entradas
id, ops, pageÂmbitos
designs:writeupdate_design_textO que faz
Entradas
id, text (id do elemento para as palavras)Âmbitos
designs:read, designs:writeresize_copiesO que faz
Entradas
id, sizesÂmbitos
designs:read, designs:writewear_markO que faz
Entradas
mark, e design ou personalityÂmbitos
render_designO que faz
Entradas
id, width, height, format, pageÂmbitos
designs:readexport_design_linkO que faz
/ d/ <id>, que qualquer pessoa que o tenha pode abrir.Entradas
idÂmbitos
designs:writewear_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.
Vídeo, áudio e legendas
Usa find_uploads para encontrar referências a fontes autorizadas e depois edit_design com add_video, update_video, split_video, add_audio, update_audio, split_audio, remove_audio, set_element_timing, set_captions ou remove_captions. Nunca inventes a duração de uma fonte. Os cortes de vídeo e os tempos dos elementos usam segundos da página; os inícios e cortes de áudio e as legendas usam segundos do documento inteiro. O áudio não prolonga as cenas. As legendas aceitam entradas com tempos ou conteúdo SRT/WebVTT; a transcrição automática não está disponível. get_design devolve a cronologia completa e as faixas. export_captions devolve conteúdo SRT/WebVTT em partes com até 100 legendas e 48 000 caracteres; usa nextOffset para a parte seguinte.
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. - “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_texteresize_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 deworkspaces: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.