Servidor MCP

Conecte sua loja ao Claude, ChatGPT, Cursor, Lovable e qualquer cliente compatível com o Model Context Protocol. Conforme as permissões explícitas da API Key, o agente pode consultar o catálogo, criar links de pagamento, administrar produtos e preparar temas em rascunhos e publicar as alterações diretamente. Para gerar código de integração, veja Integração via llms.txt e OpenAPI.

Dados de conexão

Endpoint (Streamable HTTP): https://api.aproveicheckout.com.br/mcp

Autenticação: a mesma API Key Bearer da API Aprovei, enviada no header Authorization: Bearer SEU_TOKEN. Crie a key no painel pelo avatar/menu do usuário no topo direito → API Keys. Diferente da API REST, o header X-Store-Slug não é necessário: a loja é informada por chamada via parâmetro storeSlug (opcional quando o token tem acesso a uma única loja). O parâmetro antigo storeId não é aceito nas tools MCP.

Como conectar

Antes de qualquer cliente, crie a API Key no painel da Aprovei pelo avatar/menu do usuário no topo direito → API Keys. Guarde-a com segurança e use somente em clientes que suportem segredo ou header privado.

Claude Code CLI (terminal)

Para quem usa o Claude Code instalado na máquina, pelo terminal ou dentro da IDE.

1. No terminal, rode o comando abaixo substituindo SEU_TOKEN pelo token criado no painel:
   Terminal Copiar

   claude mcp add aprovei-checkout https://api.aproveicheckout.com.br/mcp \
     --transport http \
     --header "Authorization: Bearer SEU_TOKEN"

2. Abra uma sessão do Claude Code e confirme a conexão com o comando /mcp — o servidor aprovei-checkout deve aparecer como conectado.
3. Peça algo à IA, como "liste os produtos da minha loja e gere um link de pagamento para o mais barato".

Claude Code Web (claude.ai/code, no navegador)

Para quem usa o Claude Code pelo navegador, em claude.ai/code. Aqui não há terminal: a conexão é feita uma única vez na UI de conectores da conta claude.ai.

1. Acesse claude.ai, abra o menu da sua conta e vá em Configurações → Conectores.
2. Clique em Adicionar conector personalizado, informe um nome (ex.: Aprovei Checkout) e a URL https://api.aproveicheckout.com.br/mcp, e conclua a autenticação com o seu token quando solicitada.
3. Abra claude.ai/code: o conector fica disponível nas suas sessões do Claude Code Web e o agente já pode consultar o catálogo e criar checkouts.

CLI ou Web? O Claude Code CLI roda no seu terminal e guarda a configuração na sua máquina — a conexão vale para o ambiente local onde o comando foi executado. O Claude Code Web roda no navegador e usa os conectores da sua conta claude.ai — a conexão acompanha a conta, em qualquer dispositivo, sem reconfigurar. Use o CLI se você trabalha no terminal ou na IDE; use o Web se prefere o navegador ou quer a loja conectada em todas as suas sessões.

Cursor

1. Na raiz do projeto, crie (ou edite) o arquivo .cursor/mcp.json com o conteúdo abaixo, substituindo SEU_TOKEN:
   .cursor/mcp.json Copiar

   {
     "mcpServers": {
       "aprovei-checkout": {
         "url": "https://api.aproveicheckout.com.br/mcp",
         "headers": {
           "Authorization": "Bearer SEU_TOKEN"
         }
       }
     }
   }

2. Em Settings → MCP, confirme que o servidor aprovei-checkout aparece ativo (indicador verde) com as tools listadas.
3. No chat do Cursor, peça por exemplo "busque o produto X na minha loja Aprovei Checkout e crie um link de pagamento".

Lovable

1. Abra Connectors → Chat connectors → New MCP server.
2. Informe um nome (ex.: Aprovei Checkout), a URL https://api.aproveicheckout.com.br/mcp e autentique com Bearer token usando seu API Key.
3. No chat da Lovable, o agente passa a usar as tools da loja durante a construção do seu app.

Claude (web/desktop) e ChatGPT

1. No Claude (web ou desktop), adicione um conector personalizado em Configurações → Conectores — mesmo caminho descrito no tutorial do Claude Code Web, e a conexão vale para os dois.
2. No ChatGPT, adicione o servidor em Settings → Connectors (recurso disponível conforme o plano), apontando para o endpoint acima.
3. Informe o token Bearer quando solicitado. Em clientes que só aceitam URL sem headers, use um cliente com suporte a headers customizados ou o Claude Code/Cursor.

Tools disponíveis

Permissões sensíveis: webhooks:update, webhooks:delete, products:create, products:update, checkout-customization:read e checkout-customization:draft precisam estar declaradas no token. A ability * não autoriza essas ações. As quatro permissões de produto/personalização exigem API Key com expiração máxima de 90 dias.

Fluxo típico do agente

1. list_stores — descobre a loja e o slug (dispensável com loja única).
2. list_products ou search_products — encontra o variantId comprável.
3. create_checkout — gera o link e envia a checkoutUrl ao comprador.

Criar produto com segurança

1. list_stores — confirme products:create em capabilities.
2. Vínculos de temas com produtos e kits são definidos na aprovação da personalização.
3. create_product — use idempotencyKey; o default é draft.

Editar produto com PATCH mínimo

1. get_product(view=management) — leia o estado atual e guarde revision.
2. update_product — envie somente os campos alterados, expectedRevision e idempotencyKey.
3. Use clearFields ou operações remove...; omitir nunca remove.

Designer de checkout — contrato 4.0.0

Ao criar a API Key, selecione as permissões storefront:read, checkout-customization:read, checkout-customization:draft e checkout-customization:publish. Chaves existentes não recebem publicação automaticamente. A concessão é explícita, com validade máxima de 90 dias e autorização operacional do proprietário na loja.

1. Descubra temas, controles e recursos com list_checkout_themes, get_checkout_customization_schema e list_checkout_customization_options.
2. Crie um rascunho com create_checkout_customization_draft. O modo create recebe themeSlug; edit e duplicate recebem checkoutCustomizationId. Informe name e idempotencyKey.
3. Edite com update_checkout_customization_draft, informando draftId, expectedRevision, idempotencyKey e patch. Campos omitidos são preservados; use clearFields, resetSections ou remoções explícitas.
4. Publique com publish_checkout_customization, enviando draftId, expectedRevision, expectedDependencyRevision retornada pelo rascunho, idempotencyKey e os destinos: setAsDefault, productIds e kitIds. A resposta retorna checkoutCustomizationId, revision, status=applied e impact. Não há tela intermediária de aprovação.
5. Consulte get_checkout_customization_draft para acompanhar status e result.

O fundo principal (conteudo.fundo_checkout) deve ser branco ou pastel claro, com luminosidade relativa mínima de 0,8. A regra é validada no servidor, inclusive em importações e na publicação. Cabeçalho, banners e botões podem usar as cores da marca. Exemplos aceitos: ffffff, f4f7fb e fcfaff.

Os links temporários de upload e leitura de mídias usam o domínio do painel. Não altere o domínio de um link recebido: isso invalida sua assinatura.

O impacto retorna as contagens completas de produtos e kits, incluindo herança do padrão e vídeos compartilhados. As listas detalhadas mostram até 100 identificadores por tipo, com listedDestinationsTruncated quando necessário. Widgets de vantagens e depoimentos aceitam até 12 itens; uma lista vazia remove seus itens explicitamente.

Rascunhos permanecem isolados até a publicação. Alterações concorrentes no rascunho, configuração publicada, padrões, vínculos ou dependências impedem a publicação com revisões antigas. Tokens revogados ou expirados impedem escrita. Repita mutações somente com a mesma chave e conteúdo.

{
  "name": "update_checkout_customization_draft",
  "arguments": {
    "storeSlug": "minha-loja",
    "draftId": "UUID retornado na criação",
    "expectedRevision": "sha256:REVISÃO_ATUAL",
    "idempotencyKey": "tema-campanha-02",
    "patch": {
      "name": "Campanha de outubro",
      "set": {"conteudo": {"fundo_checkout": "f4f5f8"}},
      "widgets": [{"zone": "topo", "upsert": [{"id": "titulo", "type": "texto", "settings": {"content": "<p><strong>Bem-vindo!</strong></p>"}}]}]
    }
  }
}

Mídias e importação

upload_checkout_media recebe finalidade, tipo e tamanho. Imagens até 2 MiB podem usar dataBase64; para arquivos maiores, envie os bytes por POST à uploadUrl temporária. Consulte a revisão depois de concluir o upload. Vídeos MP4/WebM têm limite de 50 MiB, com até seis vídeos de criadores por loja. Esses vídeos são compartilhados e esse alcance aparece na aprovação.

Use images.logo.mediaId e os demais slots do schema; widgets de imagem usam settings.imageMediaId e fotos de depoimentos usam photoMediaId. Arquivos novos ficam privados até a aplicação. Uploads abandonados sem referências são removidos pelo comando agendado checkout-drafts:cleanup-media.

Exportação e importação usam o mesmo formato 3.0 no painel e no MCP, preservando sobrescritas, widgets, campos removidos e manifesto de mídias. A importação não baixa URLs arbitrárias. Referências não resolvidas precisam ser substituídas ou removidas antes da aprovação.

Limites e segurança

• O agente pode preparar e publicar temas diretamente quando a API Key possui as permissões explícitas necessárias. A publicação não exige aprovação no painel.
• Rate limits por token+loja: catálogo 300/min; leitura administrativa 120/min; rascunhos e prévias 30/min; criação de produto 10/min; atualização de produto 20/min.
• create_checkout é idempotente: informe idempotencyKey para repetir com replay seguro; sem ela, uma chave é gerada automaticamente.
• create_checkout aceita até 50 itens e quantidade de 1 a 999 por item; o variantId deve vir do catálogo público.
• Use storeSlug para tokens com múltiplas lojas; storeId retorna erro de validação.
• create_checkout cria somente o link/token de checkout; não cria pedido e não cobra o cliente automaticamente.
• O endpoint MCP também aplica limite global pré-autenticação de 600 chamadas/min por IP.
• A allowlist de IPs do token também vale para o MCP.
• As mutações aceitam somente o proprietário operacional da loja e nunca aceitam storeId, IDs internos, custo, origem externa, CSS, JavaScript, Blade ou URL remota de imagem.
• Imagens MCP aceitam JPEG, PNG ou GIF em base64 puro, até 2 MiB por arquivo; MIME e conteúdo precisam coincidir.
• Nunca compartilhe o token Bearer com usuários finais; o agente que carrega o token age em nome da sua conta.
• Todas as chamadas são auditadas como as da API pública v1.

Integração via código

Para gerar código que integra com a API REST (Lovable, Cursor, v0, Bolt), veja a página Integração via llms.txt e OpenAPI, que reúne o contrato completo para LLMs e a spec OpenAPI.