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 mantém um servidor MCP hospedado. O ChatGPT se conecta a https://, e o Claude e outros clientes a https://. 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.
- Um cliente com chave API envia
Authorization: Bearer gr_live_…. O ChatGPT e o Claude enviam o token OAuth após o login. - 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 tokens de acesso OAuth e chaves API do espaço. Ambos usam as mesmas permissões, licenças, créditos e limites.
Conectar o ChatGPT e o Claude
Adicione um conector personalizado com ChatGPT: https://; Claude: https:// e escolha o login OAuth. Entre no Gradiently, escolha um espaço e revise as permissões. Somente os proprietários e administradores podem conectar um assistente.
As conexões expiram após uma hora e se renovam automaticamente por até 30 dias. Revogue uma conexão em Configurações › API e agentes para parar o acesso e a renovação imediatamente.
Uma conexão personalizada e uma entrada no diretório público são diferentes. A publicação no diretório exige a análise e aprovação da OpenAI ou da Anthropic.
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.
# 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"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.
- 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
- As ferramentas retornam texto JSON.
inspect_designtambém retorna uma imagem PNG. As falhas retornam uma mensagem de erro. - As ferramentas que precisam de uma marca aceitam um
personalityopcional (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
/do design em gradiently.design.studio/ <id> - Várias ferramentas primeiro consultam suas marcas por
/, que precisa deapi/ me workspaces:readedesigns: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
search_marksO que faz
Entradas
q, tone (dark ou light), limit (de 1 a 120, padrão 24), todos opcionaisEscopos
marks:readget_markO que faz
Entradas
code (um código ou um id)Escopos
marks:readlist_marksO que faz
Entradas
Escopos
marks:readclaim_markO que faz
Entradas
codeEscopos
marks:read, marks:claimexport_markO que faz
Entradas
mark, width, height, personalityEscopos
workspaces:read, designs:read, designs:writerestore_mark_versionO que faz
Entradas
mark, versionEscopos
brand:generateupdate_mark_versionO que faz
Entradas
mark, version, label, starredEscopos
brand:generatedelete_mark_versionO que faz
Entradas
mark, versionEscopos
brand:generateUma 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
list_personalitiesO que faz
Entradas
Escopos
workspaces:read, designs:readcreate_personalityO que faz
Entradas
nameEscopos
personalities:writeget_brand_profileO que faz
Entradas
personalityEscopos
workspaces:read, designs:readupdate_brand_profileO que faz
Entradas
personality, profileEscopos
workspaces:read, designs:read, personalities:writemy_workspaceO que faz
Entradas
Escopos
workspaces:read, designs:read, marks:readlist_workspacesO que faz
Entradas
cursorEscopos
workspaces:readinvite_memberO que faz
Entradas
workspaceId, email, role (admin, editor ou viewer)Escopos
members:writetone 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
Para criar trabalhos originais, peça à sua IA conectada 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. Os limites do seu provedor e as permissões de conta e exportação continuam válidos. Um desenho pode incluir ilustrações vetoriais próprias do host, SVG higienizado, gráficos nativos, gráficos da biblioteca e fotos licenciadas; tudo continua editável no Studio. A busca e a importação de fotos acessam o Openverse, um catálogo externo.
get_design_guidanceO que faz
Entradas
purpose, topicEscopos
draw_designO que faz
Entradas
drawing, personality, mark, designId, page, titleEscopos
designs:write, workspaces:read, designs:read, marks:readinspect_designO que faz
Entradas
id, page, maxDimensionEscopos
designs:readfind_iconsO que faz
Entradas
query, limitEscopos
find_graphicsO que faz
Entradas
query, limitEscopos
find_photosO que faz
Entradas
query, countEscopos
designs:readimport_photoO que faz
Entradas
idEscopos
designs:writedesignPede ao próprio Designer do Gradiently para criar um design, ou alterar um, a partir de um pedido em palavras simples. Ele lê o perfil da marca e o Mark, cria, revisa e salva. Usa créditos de IA do Gradiently.Entradas
request, personality, size, designId, scope, selectionEscopos
workspaces:read, designs:read, designs:writecreate_designsO que faz
Entradas
brief, items (size, brief, title), title, personality, mark, waitEscopos
workspaces:read, designs:read, designs:writeget_design_setO que faz
Entradas
idEscopos
designs:readstop_design_setO que faz
Entradas
idEscopos
designs:writecompose_designO que faz
Entradas
composition, personality, designId, titleEscopos
workspaces:read, designs:read, designs:writelist_sizesO que faz
Entradas
Escopos
create_designO que faz
Entradas
form, size, copy, look, personalityEscopos
workspaces:read, designs:read, designs:writedesign 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" }
]
}
}compose_design. A resposta traz o id do design, o link do Studio, os problemas da revisão e os elementos que foram colocados.Editar e exportar
list_designsO que faz
Entradas
personalityEscopos
workspaces:read, designs:readget_designO que faz
Entradas
id, page, kind, name, textEscopos
designs:readedit_designO que faz
Entradas
id, ops, pageEscopos
designs:writeupdate_design_textO que faz
Entradas
id, text (id do elemento para as palavras)Escopos
designs:read, designs:writeresize_copiesO que faz
Entradas
id, sizesEscopos
designs:read, designs:writewear_markO que faz
Entradas
mark, e design ou personalityEscopos
render_designO que faz
Entradas
id, width, height, format, pageEscopos
designs:readexport_design_linkO que faz
/ d/ <id>, que qualquer pessoa com ele pode abrir.Entradas
idEscopos
designs:writewear_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.
Vídeo, áudio e legendas
Use 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 invente 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 retorna a linha do tempo completa e as faixas. export_captions retorna conteúdo SRT/WebVTT em partes de até 100 legendas e 48.000 caracteres; use nextOffset para a próxima parte.
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. - “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_texteresize_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 deworkspaces: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.