MercadoExplorarExperimentar
Preços
EntrarComeçar
Desenvolvedores

MCP e assistentes de IA

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

Atualizado em 11 de outubro de 2026

Documentação para desenvolvedores

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

Nesta página

Antes de conectarConectar o ChatGPT e o ClaudeConectar o Claude CodeOutros clientesComo as ferramentas se comportamMarksMarcas e workspaceCriar 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 mantém um servidor MCP hospedado. O ChatGPT se conecta a https://gradiently.design/api/mcp/chatgpt, e o Claude e outros clientes a 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.
  • 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://gradiently.design/api/mcp/chatgpt; Claude: https://gradiently.design/api/mcp 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.

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"

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

Permita chamadas longas

A maioria das ferramentas responde em segundos. render_design, inspect_design e export_mark podem levar até três minutos, design até uns cinco, e create_designs com wait até uns quatro. Se o seu cliente tiver uma configuração de tempo limite para ferramentas, aumente para acompanhar.

Como as ferramentas se comportam

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

Os escopos para dar a um assistente

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

Marks

search_marks

O que faz

Busca no Mercado público por nome ou código. Devolve cores, materiais, status e titular.

Entradas

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

Escopos

marks:read
get_mark

O que faz

Um Mark e a receita completa dele.

Entradas

code (um código ou um id)

Escopos

marks:read
list_marks

O que faz

Os Marks mantidos para este workspace, com o estado da licença, e seus rascunhos nele.

Entradas

nenhuma

Escopos

marks:read
claim_mark

O que faz

Reserva um Mark disponível. Quem criou a chave fica com ele, nunca o workspace.

Entradas

code

Escopos

marks:read, marks:claim
export_mark

O que faz

Renderiza um Mark sozinho como PNG, com até 4096 px de lado.

Entradas

mark, width, height, personality

Escopos

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

O que faz

Volta uma versão para o rascunho. O estado atual é guardado antes como versão.

Entradas

mark, version

Escopos

brand:generate
update_mark_version

O que faz

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

Entradas

mark, version, label, starred

Escopos

brand:generate
delete_mark_version

O que faz

Exclui uma versão, nunca a publicada.

Entradas

mark, version

Escopos

brand:generate
FerramentaO que fazEntradasEscopos
search_marksBusca no Mercado público por nome ou código. Devolve cores, materiais, status e titular.q, tone (dark ou light), limit (de 1 a 120, padrão 24), todos opcionaismarks:read
get_markUm Mark e a receita completa dele.code (um código ou um id)marks:read
list_marksOs Marks mantidos para este workspace, com o estado da licença, e seus rascunhos nele.nenhumamarks:read
claim_markReserva um Mark disponível. Quem criou a chave fica com ele, nunca o workspace.codemarks:read, marks:claim
export_markRenderiza um Mark sozinho como PNG, com até 4096 px de lado.mark, width, height, personalityworkspaces:read, designs:read, designs:write
restore_mark_versionVolta uma versão para o rascunho. O estado atual é guardado antes como versão.mark, versionbrand:generate
update_mark_versionRenomeia ou marca uma versão com estrela. As versões com estrela são mantidas.mark, version, label, starredbrand:generate
delete_mark_versionExclui uma versão, nunca a publicada.mark, versionbrand:generate

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

list_personalities

O que faz

As marcas do workspace, com os ids delas.

Entradas

nenhuma

Escopos

workspaces:read, designs:read
create_personality

O que faz

Cria uma marca com nome.

Entradas

name

Escopos

personalities:write
get_brand_profile

O que faz

O que uma marca é, para quem ela é, o tom de voz, o que fazer e o que evitar, e as fontes.

Entradas

personality

Escopos

workspaces:read, designs:read
update_brand_profile

O que faz

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

Entradas

personality, profile

Escopos

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

O que faz

Você, as marcas do workspace com os códigos dos Marks delas, e os Marks mantidos para ele.

Entradas

nenhuma

Escopos

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

O que faz

O workspace da chave e a sua função nele.

Entradas

cursor

Escopos

workspaces:read
invite_member

O que faz

Envia por e-mail um convite de sete dias para entrar no workspace.

Entradas

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

Escopos

members:write
FerramentaO que fazEntradasEscopos
list_personalitiesAs marcas do workspace, com os ids delas.nenhumaworkspaces:read, designs:read
create_personalityCria uma marca com nome.namepersonalities:write
get_brand_profileO que uma marca é, para quem ela é, o tom de voz, o que fazer e o que evitar, e as fontes.personalityworkspaces:read, designs:read
update_brand_profileSubstitui o perfil de uma marca. O Designer lê esse perfil antes de cada design.personality, profileworkspaces:read, designs:read, personalities:write
my_workspaceVocê, as marcas do workspace com os códigos dos Marks delas, e os Marks mantidos para ele.nenhumaworkspaces:read, designs:read, marks:read
list_workspacesO workspace da chave e a sua função nele.cursorworkspaces:read
invite_memberEnvia por e-mail um convite de sete dias para entrar no workspace.workspaceId, email, role (admin, editor ou viewer)members:write

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

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_guidance

O que faz

Direção de arte escrita e revisada: o padrão de qualidade, os recursos 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 prontos nem treinamento de modelos.

Entradas

purpose, topic

Escopos

qualquer chave
draw_design

O que faz

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

Entradas

drawing, personality, mark, designId, page, title

Escopos

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

O que faz

Retorna uma imagem PNG real que o assistente pode analisar e melhorar. Tamanhos menores são a página inteira reduzida, como um feed a exibe.

Entradas

id, page, maxDimension

Escopos

designs:read
find_icons

O que faz

Encontra nomes válidos de ícones integrados.

Entradas

query, limit

Escopos

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

Escopos

qualquer chave
find_photos

O que faz

Busca fotos licenciadas no Openverse e retorna miniaturas que o assistente pode ver. Avisa quando uma miniatura não está disponível. Nada é salvo.

Entradas

query, count

Escopos

designs:read
import_photo

O que faz

Copia a foto escolhida para os uploads do espaço de trabalho com a atribuição, dentro da sua cota de uploads.

Entradas

id

Escopos

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

Escopos

workspaces:read, designs:read, designs:write
create_designs

O que faz

Cria um conjunto de até doze designs a partir de um único briefing, em segundo plano. Usa créditos de IA do Gradiently.

Entradas

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

Escopos

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

O que faz

O progresso de um conjunto e o link do Studio de cada design assim que ele existir.

Entradas

id

Escopos

designs:read
stop_design_set

O que faz

Para um conjunto em andamento. Os designs já feitos continuam salvos.

Entradas

id

Escopos

designs:write
compose_design

O que faz

Diagrama o seu texto com o motor de layout e salva. Devolve os problemas da revisão para corrigir.

Entradas

composition, personality, designId, title

Escopos

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

O que faz

Cada tamanho predefinido, com seu tamanho em pixels.

Entradas

nenhuma

Escopos

qualquer chave
create_design

O que faz

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

Entradas

form, size, copy, look, personality

Escopos

workspaces:read, designs:read, designs:write
FerramentaO que fazEntradasEscopos
get_design_guidanceDireção de arte escrita e revisada: o padrão de qualidade, os recursos 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 prontos nem treinamento de modelos.purpose, topicqualquer chave
draw_designDesenha um design original e editável com sua IA conectada: texto, formas, ilustrações vetoriais próprias, SVG, gráficos nativos, gráficos da biblioteca, fotos, janelas da Mark e tabelas. Somente a página selecionada é redesenhada.drawing, personality, mark, designId, page, titledesigns:write, workspaces:read, designs:read, marks:read
inspect_designRetorna uma imagem PNG real que o assistente pode analisar e melhorar. Tamanhos menores são a página inteira reduzida, como um feed a exibe.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_photosBusca fotos licenciadas no Openverse e retorna miniaturas que o assistente pode ver. Avisa quando uma miniatura não está disponível. Nada é salvo.query, countdesigns:read
import_photoCopia a foto escolhida para os uploads do espaço de trabalho com a atribuição, dentro da sua cota de uploads.iddesigns:write
designPede 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.request, personality, size, designId, scope, selectionworkspaces:read, designs:read, designs:write
create_designsCria um conjunto de até doze designs a partir de um único briefing, em segundo plano. Usa 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 Studio de cada design assim que ele existir.iddesigns:read
stop_design_setPara um conjunto em andamento. Os designs já feitos continuam salvos.iddesigns:write
compose_designDiagrama o seu texto com o motor de layout e salva. Devolve os problemas da revisão para corrigir.composition, personality, designId, titleworkspaces:read, designs:read, designs:write
list_sizesCada tamanho predefinido, com seu tamanho em pixels.nenhumaqualquer chave
create_designCria um design a partir de uma forma (em branco por padrã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 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.

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 traz o id do design, o link do Studio, os problemas da revisão e os elementos que foram colocados.

Editar e exportar

list_designs

O que faz

Os designs salvos de uma marca, com links do Studio.

Entradas

personality

Escopos

workspaces:read, designs:read
get_design

O que faz

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

Entradas

id, page, kind, name, text

Escopos

designs:read
edit_design

O que faz

Altera um design com até 100 operações, como uma pessoa faria no Studio, e salva.

Entradas

id, ops, page

Escopos

designs:write
update_design_text

O que faz

Substitui as palavras dos elementos de texto escolhidos e mantém o layout.

Entradas

id, text (id do elemento para as palavras)

Escopos

designs:read, designs:write
resize_copies

O que faz

Salva cópias em até oito outros tamanhos, reorganizadas como o Studio faz. O original não muda.

Entradas

id, sizes

Escopos

designs:read, designs:write
wear_mark

O que faz

Coloca um Mark em um design, ou o torna o Mark de uma marca para os novos designs.

Entradas

mark, e design ou personality

Escopos

veja abaixo
render_design

O que faz

Renderiza um design salvo em PNG ou PDF com o motor do Studio. Devolve o arquivo em base64.

Entradas

id, width, height, format, page

Escopos

designs:read
export_design_link

O que faz

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

Entradas

id

Escopos

designs:write
FerramentaO que fazEntradasEscopos
list_designsOs designs salvos de uma marca, com links do Studio.personalityworkspaces:read, designs:read
get_designO tamanho, as páginas e cada elemento de um design com as propriedades dele. Filtre 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 Studio, e salva.id, ops, pagedesigns:write
update_design_textSubstitui as palavras dos elementos de texto escolhidos e mantém o layout.id, text (id do elemento para as palavras)designs:read, designs:write
resize_copiesSalva cópias em até oito outros tamanhos, reorganizadas como o Studio faz. O original não muda.id, sizesdesigns:read, designs:write
wear_markColoca um Mark em um design, ou o torna o Mark de uma marca para os novos designs.mark, e design ou personalityveja abaixo
render_designRenderiza um design salvo em PNG ou PDF com o motor do Studio. Devolve o arquivo em base64.id, width, height, format, pagedesigns:read
export_design_linkPublica um link de visualização, /d/<id>, que qualquer pessoa com ele pode abrir.iddesigns:write

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.

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

Precisa de ajuda?

Envie uma solicitação com o tópico API e MCP, e uma pessoa vai responder.

Enviar uma solicitação

Encontre o visual que é só seu.

Cada Mark é um fundo vivo com um único dono. Experimente um Mark ainda disponível e reserve o seu quando sentir que é ele.

Começar a criarVer a oferta de lançamento

Marks livres para reservar

50de 1.000

950 reservados até agoraEncontre o seu

Verificar um certificado

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

Funciona com ChatGPT e Claude

Peça um design à sua IA. Ela cria no seu Mark, pronto para editar.

ChatGPTClaude
Como conectar

Produto

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

Aprender

  • Guia prático
  • Central de ajuda
  • Novidades

Desenvolvedores

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

Empresa

  • Sobre
  • Fale conosco
  • Entrar

Jurídico

  • Termos
  • Privacidade
  • Reembolsos
  • Proteção do Mark
  • Cookies
  • Todas as políticas
Passe pelas letras. Cada uma veste um Mark de verdade.Toque em uma letra para ver o Mark dela.Um nome. Dez Marks dentro dele.
© 2026 Gradiently