Skip to main content

​
O que é

O CaktoMCP é um servidor MCP (Model Context Protocol) que conecta assistentes de IA — como Claude, Codex, entre outros — diretamente à API pública da Cakto. Em vez de você (ou sua IA) precisar abrir esta documentação, montar cada requisição manualmente e adivinhar payloads, o CaktoMCP ensina a própria IA a entender e operar a API pela conversa.
O CaktoMCP é um servidor MCP remoto, sobre HTTP. Não há pacote para instalar nem processo local para manter rodando: basta apontar seu cliente MCP para o endereço abaixo e entrar com a sua conta Cakto pelo próprio cliente, ou configurar as credenciais da sua Chave de API.

​
Como funciona

O CaktoMCP não tem uma lista fixa de operações escritas à mão. Ele lê o contrato real da API (o mesmo schema que gera esta documentação) e expõe duas frentes de ferramentas para a IA conversar com ele:

Descoberta

Buscar endpoint por intenção, ler o contrato completo de qualquer operação, gerar exemplo de chamada, entender conceitos (autenticação, paginação, erros, webhooks). Não precisa de nenhuma credencial.

Execução

Executar qualquer operação da API real. Criação, alteração ou remoção chamada sem confirmação devolve um preview em vez de executar.
Na prática, isso significa poder pedir para a sua IA, em português:
  • “Cria um produto de R$ 197 chamado Curso de Fotografia”
  • “Lista minhas vendas dos últimos 7 dias”
  • “Quais eventos de webhook existem, e por que meu webhook de pedido pago não chegou?”
  • “Quantas vendas eu tenho no total esse mês?”
A IA consulta o contrato real da API antes de agir e, em qualquer escrita, mostra um preview exato do que vai fazer para você aprovar antes de executar.

​
Por dentro do fluxo

1

A IA descobre o que fazer

Sem nenhuma credencial, a IA busca a operação certa pela sua intenção, lê o contrato completo (campos, obrigatoriedade, exemplo) e entende conceitos transversais como autenticação e paginação.
2

A IA confirma a identidade

Com você conectado (pelo login no cliente de IA ou pela Chave de API), a IA confirma a conta, o ambiente e os escopos concedidos antes de tentar qualquer operação.
3

Leitura, direto

Consultas (produtos, pedidos, assinaturas, análises de venda) rodam imediatamente, com paginação e valores já formatados para a conversa.
4

Escrita, com confirmação

Uma criação, alteração ou remoção chamada sem confirmação devolve um preview — método, URL, corpo exato e o efeito em português — em vez de executar. A execução acontece quando a IA repete a chamada com confirm: true, depois que você aprova.
Essa confirmação é uma convenção do fluxo, não uma trava do servidor: o transporte é HTTP stateless e não há como o servidor verificar se o preview chegou até você. O detalhe do que o gate garante — e como impor aprovação humana de verdade, no cliente — está em Ferramentas de Execução.

​
Como conectar

O CaktoMCP é um endpoint HTTP. O endereço de produção é:
Não confunda com app.cakto.com.br/mcp, que é a página do painel explicando o CaktoMCP. O endereço acima é o do servidor, o que vai no seu cliente MCP.

​
Comece sem credencial

Você não precisa de Chave de API para conectar. Configure só o endereço, e as cinco ferramentas de descoberta já funcionam: buscar o endpoint certo pela sua intenção, ler o contrato completo de qualquer operação, ver os eventos de webhook e consultar os guias. Nenhuma delas acessa dado da sua conta.
É o jeito mais rápido de descobrir se o CaktoMCP resolve o seu caso antes de criar qualquer credencial. Quando quiser executar de verdade, conecte a sua conta por um dos dois jeitos abaixo.

​
Para executar de verdade

Há dois jeitos de autenticar, e os dois dão acesso à mesma API:

​
Login pelo cliente de IA

Configure só o endereço, como em Comece sem credencial. Na primeira vez que a IA precisar da sua conta (por exemplo, ao listar suas vendas), o cliente abre uma janela da Cakto:
  1. Você informa o e-mail da sua conta na Cakto e recebe um código de 6 dígitos.
  2. Se a sua conta tem verificação em duas etapas por aplicativo (TOTP ou App Cakto), a tela pede também o código dessa verificação. Contas da equipe Cakto só conectam com essa verificação ligada.
  3. Você confere o aplicativo e as permissões pedidas e autoriza.
O cliente guarda o acesso e o renova sozinho; você não copia nenhuma credencial. O login não concede saque nem tokenização de cartão: para isso, use uma Chave de API com o escopo correspondente. O login começa só com leitura. Na primeira vez que a IA for executar uma operação que altera a sua conta (criar ou editar produto, estornar pedido, aprovar reembolso, cadastrar webhook), depois de você aprovar o preview, o cliente abre outra janela da Cakto pedindo a permissão de escrita. Ela diz o que a escrita libera, e você decide se autoriza.
Se a janela da escrita não abrir, o seu cliente ainda não pede permissão adicional durante a conversa: a leitura continua funcionando, e a escrita responde com o erro de permissão. Para escrever por esse cliente, use uma Chave de API com os escopos write e o do recurso. No Claude Code, outra saída é configurar o servidor com oauth.scopes incluindo write.
O login conecta uma conta Cakto que já existe. Ainda não tem conta? Crie a sua em app.cakto.com.br antes de conectar.

​
Chave de API por header

Continua funcionando como sempre. A autenticação usa a sua Chave de API — o mesmo client_id/client_secret do fluxo OAuth2 — enviada em dois headers:
Cliente MCP que só aceita um campo de autenticação? Use Authorization: Basic com o base64 de client_id:client_secret.
Sua Chave de API dá acesso de escrita à sua conta. Trate o client_secret como senha: não compartilhe nem versione em repositório. Ele é exibido uma única vez, no momento em que a chave é criada.
Com a Chave de API nos headers, o cliente não abre a tela de login: a chave já identifica a conta, e as operações usam os escopos que ela tem.
O painel da Cakto mostra esses mesmos snippets já preenchidos com a sua credencial, na página de Chaves de API.

​
Explore

Ferramentas de Descoberta

Referência completa: busca, catálogo, contrato de endpoint, eventos de webhook

Ferramentas de Execução

Como a execução real funciona: confirmação, idempotência, erros, paginação

Guias

Os conceitos que a IA já sabe explicar sem consultar nada externo

Autenticação

Chaves de API e escopos, para quem prefere configurar a credencial à mão