MercadoExplorarExperimentar
Preços
Iniciar sessãoComeçar
Programadores

MCP e assistentes de IA

O Gradiently tem uma API HTTP e um servidor MCP alojado. Liga um assistente com OAuth ou uma chave API limitada a um espaço.

Atualizado a 11 de outubro de 2026

Documentação para programadores

  • Visão geral
  • MCP e assistentes de IA
  • Referência da API
  • Chaves de API e âmbitos

Nesta página

Antes de ligarLigar o ChatGPT e o ClaudeLigar o Claude CodeOutros clientesComo as ferramentas se comportamMarksMarcas e espaço de trabalhoCriar designsEditar e exportarVídeo, áudio e legendasExemplos de pedidos

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://gradiently.design/api/mcp/chatgpt, e o Claude e outros clientes a 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.
  • 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://gradiently.design/api/mcp/chatgpt; Claude: https://gradiently.design/api/mcp 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.

bash
# 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.
json
{
  "mcpServers": {
    "gradiently": {
      "url": "https://gradiently.design/api/mcp",
      "headers": { "Authorization": "Bearer gr_live_…" }
    }
  }
}

Permite chamadas de ferramentas longas

A maioria das ferramentas responde em segundos. render_design, inspect_design e export_mark podem demorar até três minutos, design até cerca de cinco, e create_designs com wait até cerca de quatro. Se o teu cliente tiver uma definição de tempo limite para ferramentas, aumenta-a em conformidade.

Como as ferramentas se comportam

  • As ferramentas devolvem texto JSON. inspect_design também devolve uma imagem PNG. As falhas devolvem uma mensagem de erro.
  • 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.

Os âmbitos a dar a um assistente

Uma chave criada nas Definições começa com designs:read, designs:write, marks:read, brand:generate e workspaces:read: o suficiente para todas as ferramentas de design. Adiciona marks:claim para reservar Marks, personalities:write para criar marcas ou alterar o seu Mark e perfil, e members:write para enviar convites.

Marks

search_marks

O que faz

Pesquisa o Mercado público por nome ou código. Devolve cores, materiais, estado e detentor.

Entradas

q, tone (dark ou light), limit (de 1 a 120, 24 por omissão), todos opcionais

Âmbitos

marks:read
get_mark

O que faz

Um Mark e a sua receita completa.

Entradas

code (um código ou um id)

Âmbitos

marks:read
list_marks

O que faz

Os Marks detidos para este espaço de trabalho, com o estado da licença, e os teus rascunhos nele.

Entradas

nenhuma

Âmbitos

marks:read
claim_mark

O que faz

Reserva um Mark disponível. O criador da chave fica como detentor, nunca o espaço de trabalho.

Entradas

code

Âmbitos

marks:read, marks:claim
export_mark

O que faz

Gera um Mark sozinho em PNG, até 4096 px de lado.

Entradas

mark, width, height, personality

Âmbitos

workspaces:read, designs:read, designs:write
restore_mark_version

O que faz

Repõe uma versão como rascunho. O estado atual é primeiro guardado como versão.

Entradas

mark, version

Âmbitos

brand:generate
update_mark_version

O que faz

Renomeia ou marca com estrela uma versão. As versões com estrela são mantidas.

Entradas

mark, version, label, starred

Âmbitos

brand:generate
delete_mark_version

O que faz

Elimina uma versão, nunca a publicada.

Entradas

mark, version

Âmbitos

brand:generate
FerramentaO que fazEntradasÂmbitos
search_marksPesquisa o Mercado público por nome ou código. Devolve cores, materiais, estado e detentor.q, tone (dark ou light), limit (de 1 a 120, 24 por omissão), todos opcionaismarks:read
get_markUm Mark e a sua receita completa.code (um código ou um id)marks:read
list_marksOs Marks detidos para este espaço de trabalho, com o estado da licença, e os teus rascunhos nele.nenhumamarks:read
claim_markReserva um Mark disponível. O criador da chave fica como detentor, nunca o espaço de trabalho.codemarks:read, marks:claim
export_markGera um Mark sozinho em PNG, até 4096 px de lado.mark, width, height, personalityworkspaces:read, designs:read, designs:write
restore_mark_versionRepõe uma versão como rascunho. O estado atual é primeiro guardado como versão.mark, versionbrand:generate
update_mark_versionRenomeia ou marca com estrela uma versão. As versões com estrela são mantidas.mark, version, label, starredbrand:generate
delete_mark_versionElimina uma versão, nunca a publicada.mark, versionbrand:generate

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

list_personalities

O que faz

As marcas do espaço de trabalho, com os seus ids.

Entradas

nenhuma

Âmbitos

workspaces:read, designs:read
create_personality

O que faz

Cria uma marca com nome.

Entradas

name

Âmbitos

personalities:write
get_brand_profile

O que faz

O que uma marca é, para quem é, o seu tom de voz, o que fazer e não fazer, e os tipos de letra.

Entradas

personality

Âmbitos

workspaces:read, designs:read
update_brand_profile

O que faz

Substitui o perfil de uma marca. O Designer lê-o antes de cada design.

Entradas

personality, profile

Âmbitos

workspaces:read, designs:read, personalities:write
my_workspace

O que faz

Tu, as marcas do espaço de trabalho com os códigos dos seus Marks, e os Marks detidos para ele.

Entradas

nenhuma

Âmbitos

workspaces:read, designs:read, marks:read
list_workspaces

O que faz

O espaço de trabalho da chave e a tua função nele.

Entradas

cursor

Âmbitos

workspaces:read
invite_member

O que faz

Envia por email um convite válido por sete dias para entrar no espaço de trabalho.

Entradas

workspaceId, email, role (admin, editor ou viewer)

Âmbitos

members:write
FerramentaO que fazEntradasÂmbitos
list_personalitiesAs marcas do espaço de trabalho, com os seus ids.nenhumaworkspaces:read, designs:read
create_personalityCria uma marca com nome.namepersonalities:write
get_brand_profileO que uma marca é, para quem é, o seu tom de voz, o que fazer e não fazer, e os tipos de letra.personalityworkspaces:read, designs:read
update_brand_profileSubstitui o perfil de uma marca. O Designer lê-o antes de cada design.personality, profileworkspaces:read, designs:read, personalities:write
my_workspaceTu, as marcas do espaço de trabalho com os códigos dos seus Marks, e os Marks detidos para ele.nenhumaworkspaces:read, designs:read, marks:read
list_workspacesO espaço de trabalho da chave e a tua função nele.cursorworkspaces:read
invite_memberEnvia por email um convite válido por sete dias para entrar no espaço de trabalho.workspaceId, email, role (admin, editor ou viewer)members:write

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

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_guidance

O que faz

Direção de arte escrita e revista: o nível de qualidade, as capacidades de desenho, o método de conceito e o ciclo de revisão, com temas aprofundados como ilustração, dados e tipografia. Não são modelos para copiar nem treino de modelos.

Entradas

purpose, topic

Âmbitos

qualquer chave
draw_design

O que faz

Desenha um design original e editável com a tua IA ligada: texto, formas, ilustrações vetoriais próprias, SVG, gráficos nativos, gráficos da biblioteca, fotografias, janelas da Mark e tabelas. Apenas a página selecionada é redesenhada.

Entradas

drawing, personality, mark, designId, page, title

Âmbitos

designs:write, workspaces:read, designs:read, marks:read
inspect_design

O que faz

Devolve uma imagem PNG real que o assistente pode analisar e melhorar. Os tamanhos mais pequenos são a página inteira reduzida, como um feed a mostra.

Entradas

id, page, maxDimension

Âmbitos

designs:read
find_icons

O que faz

Encontra nomes válidos de ícones integrados.

Entradas

query, limit

Âmbitos

qualquer chave
find_graphics

O que faz

Encontra os gráficos originais do Gradiently, que podem ser recoloridos, para usar como detalhes de apoio.

Entradas

query, limit

Âmbitos

qualquer chave
find_photos

O que faz

Pesquisa fotografias licenciadas no Openverse e devolve miniaturas que o assistente pode ver. Avisa quando uma miniatura não está disponível. Nada é guardado.

Entradas

query, count

Âmbitos

designs:read
import_photo

O que faz

Copia a fotografia escolhida para os carregamentos do espaço de trabalho com a atribuição, dentro da tua quota de carregamentos.

Entradas

id

Âmbitos

designs:write
designPede 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:write
create_designs

O que faz

Cria um conjunto de até doze designs a partir de um só briefing, em segundo plano. Utiliza créditos de IA do Gradiently.

Entradas

brief, items (size, brief, title), title, personality, mark, wait

Âmbitos

workspaces:read, designs:read, designs:write
get_design_set

O que faz

O progresso de um conjunto e o link do Estúdio de cada design assim que existe.

Entradas

id

Âmbitos

designs:read
stop_design_set

O que faz

Para um conjunto em curso. Os designs já desenhados ficam guardados.

Entradas

id

Âmbitos

designs:write
compose_design

O que faz

Pagina o teu texto com o motor de paginação e guarda-o. Devolve problemas de revisão a corrigir.

Entradas

composition, personality, designId, title

Âmbitos

workspaces:read, designs:read, designs:write
list_sizes

O que faz

Cada tamanho predefinido, com o seu tamanho em píxeis.

Entradas

nenhuma

Âmbitos

qualquer chave
create_design

O que faz

Cria um design a partir de uma forma (em branco por predefinição), de um tamanho predefinido e de texto associado aos ids dos elementos.

Entradas

form, size, copy, look, personality

Âmbitos

workspaces:read, designs:read, designs:write
FerramentaO que fazEntradasÂmbitos
get_design_guidanceDireção de arte escrita e revista: o nível de qualidade, as capacidades de desenho, o método de conceito e o ciclo de revisão, com temas aprofundados como ilustração, dados e tipografia. Não são modelos para copiar nem treino de modelos.purpose, topicqualquer chave
draw_designDesenha um design original e editável com a tua IA ligada: texto, formas, ilustrações vetoriais próprias, SVG, gráficos nativos, gráficos da biblioteca, fotografias, janelas da Mark e tabelas. Apenas a página selecionada é redesenhada.drawing, personality, mark, designId, page, titledesigns:write, workspaces:read, designs:read, marks:read
inspect_designDevolve uma imagem PNG real que o assistente pode analisar e melhorar. Os tamanhos mais pequenos são a página inteira reduzida, como um feed a mostra.id, page, maxDimensiondesigns:read
find_iconsEncontra nomes válidos de ícones integrados.query, limitqualquer chave
find_graphicsEncontra os gráficos originais do Gradiently, que podem ser recoloridos, para usar como detalhes de apoio.query, limitqualquer chave
find_photosPesquisa fotografias licenciadas no Openverse e devolve miniaturas que o assistente pode ver. Avisa quando uma miniatura não está disponível. Nada é guardado.query, countdesigns:read
import_photoCopia a fotografia escolhida para os carregamentos do espaço de trabalho com a atribuição, dentro da tua quota de carregamentos.iddesigns:write
designPede 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.request, personality, size, designId, scope, selectionworkspaces:read, designs:read, designs:write
create_designsCria um conjunto de até doze designs a partir de um só briefing, em segundo plano. Utiliza créditos de IA do Gradiently.brief, items (size, brief, title), title, personality, mark, waitworkspaces:read, designs:read, designs:write
get_design_setO progresso de um conjunto e o link do Estúdio de cada design assim que existe.iddesigns:read
stop_design_setPara um conjunto em curso. Os designs já desenhados ficam guardados.iddesigns:write
compose_designPagina o teu texto com o motor de paginação e guarda-o. Devolve problemas de revisão a corrigir.composition, personality, designId, titleworkspaces:read, designs:read, designs:write
list_sizesCada tamanho predefinido, com o seu tamanho em píxeis.nenhumaqualquer chave
create_designCria um design a partir de uma forma (em branco por predefinição), de um tamanho predefinido e de texto associado aos ids dos elementos.form, size, copy, look, personalityworkspaces:read, designs:read, designs:write

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.

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. 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_designs

O que faz

Os designs guardados de uma marca, com links do Estúdio.

Entradas

personality

Âmbitos

workspaces:read, designs:read
get_design

O que faz

O tamanho, as páginas e cada elemento de um design com as suas propriedades. Filtra designs longos por página, tipo, nome ou texto.

Entradas

id, page, kind, name, text

Âmbitos

designs:read
edit_design

O que faz

Altera um design com até 100 operações, como uma pessoa faria no Estúdio, e guarda-o.

Entradas

id, ops, page

Âmbitos

designs:write
update_design_text

O que faz

Substitui as palavras dos elementos de texto escolhidos e mantém a paginação.

Entradas

id, text (id do elemento para as palavras)

Âmbitos

designs:read, designs:write
resize_copies

O que faz

Guarda cópias em até oito outros tamanhos, reorganizadas como faz o Estúdio. O original não muda.

Entradas

id, sizes

Âmbitos

designs:read, designs:write
wear_mark

O que faz

Põe um Mark num design, ou torna-o o Mark de uma marca para novos designs.

Entradas

mark, e design ou personality

Âmbitos

ver abaixo
render_design

O que faz

Gera um design guardado em PNG ou PDF com o motor do Estúdio. Devolve o ficheiro em base64.

Entradas

id, width, height, format, page

Âmbitos

designs:read
export_design_link

O que faz

Publica um link de visualização, /d/<id>, que qualquer pessoa que o tenha pode abrir.

Entradas

id

Âmbitos

designs:write
FerramentaO que fazEntradasÂmbitos
list_designsOs designs guardados de uma marca, com links do Estúdio.personalityworkspaces:read, designs:read
get_designO tamanho, as páginas e cada elemento de um design com as suas propriedades. Filtra designs longos por página, tipo, nome ou texto.id, page, kind, name, textdesigns:read
edit_designAltera um design com até 100 operações, como uma pessoa faria no Estúdio, e guarda-o.id, ops, pagedesigns:write
update_design_textSubstitui as palavras dos elementos de texto escolhidos e mantém a paginação.id, text (id do elemento para as palavras)designs:read, designs:write
resize_copiesGuarda cópias em até oito outros tamanhos, reorganizadas como faz o Estúdio. O original não muda.id, sizesdesigns:read, designs:write
wear_markPõe um Mark num design, ou torna-o o Mark de uma marca para novos designs.mark, e design ou personalityver abaixo
render_designGera um design guardado em PNG ou PDF com o motor do Estúdio. Devolve o ficheiro em base64.id, width, height, format, pagedesigns:read
export_design_linkPublica um link de visualização, /d/<id>, que qualquer pessoa que o tenha pode abrir.iddesigns:write

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.

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_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.

Precisas de ajuda?

Envia-nos um pedido com o tema API e MCP, e uma pessoa responde-te.

Enviar um pedido

Encontra o visual que é só teu.

Cada Mark é um fundo vivo com um só dono. Experimenta um Mark ainda disponível e reserva o teu quando te parecer certo.

Começar a criarVer a oferta de lançamento

Marks por reservar

50de 1000

950 reservados até agoraEncontra o teu

Verificar um certificado

Escreve um número de certificado ou o código de um Mark para veres quem é o dono.

Funciona com o ChatGPT e o Claude

Pede um design à tua IA. Ela cria-o no teu Mark, pronto a editar.

ChatGPTClaude
Como ligar

Produto

  • Mercado
  • Explorar
  • Preços
  • Pacotes de lançamento
  • Certificados

Aprender

  • Guia Prático
  • Centro de ajuda
  • Novidades

Programadores

  • Visão geral
  • ChatGPT e Claude
  • Referência da API
  • Chaves de API

Empresa

  • Sobre nós
  • Contactos
  • Iniciar sessão

Legal

  • Termos
  • Privacidade
  • Reembolsos
  • Proteção de Marks
  • Cookies
  • Todas as políticas
Passa pelas letras. Cada uma veste um Mark real.Toca numa letra para veres o seu Mark.Um nome. Dez Marks lá dentro.
© 2026 Gradiently