> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cakto.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# CaktoMCP

> Conecte assistentes de IA à API da Cakto via protocolo MCP (Model Context Protocol).

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

<Note>
  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 com as credenciais da sua Chave de API.
</Note>

## 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:

<CardGroup cols={2}>
  <Card title="Descoberta" icon="magnifying-glass" href="/mcp/ferramentas-de-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.
  </Card>

  <Card title="Execução" icon="bolt" href="/mcp/ferramentas-de-execucao">
    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.
  </Card>
</CardGroup>

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

<Steps>
  <Step title="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.
  </Step>

  <Step title="A IA confirma a identidade">
    Com sua Chave de API configurada, a IA confirma o ambiente e os
    escopos concedidos antes de tentar qualquer operação.
  </Step>

  <Step title="Leitura, direto">
    Consultas (produtos, pedidos, assinaturas, análises de venda) rodam
    imediatamente, com paginação e valores já formatados para a
    conversa.
  </Step>

  <Step title="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.
  </Step>
</Steps>

<Note>
  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](/mcp/ferramentas-de-execucao).
</Note>

## Como conectar

O CaktoMCP é um endpoint HTTP. O endereço de produção é:

```
https://mcp.cakto.com.br
```

<Note>
  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.
</Note>

### Comece sem credencial

**Você não precisa de Chave de API para conectar.** Configure só o endereço, e
as cinco [ferramentas de descoberta](/mcp/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.

<CodeGroup>
  ```bash Claude Code theme={null}
  claude mcp add --transport http cakto https://mcp.cakto.com.br
  ```

  ```json Claude Desktop theme={null}
  {
    "mcpServers": {
      "cakto": {
        "type": "http",
        "url": "https://mcp.cakto.com.br"
      }
    }
  }
  ```

  ```json Cursor / VS Code theme={null}
  {
    "servers": {
      "cakto": {
        "type": "http",
        "url": "https://mcp.cakto.com.br"
      }
    }
  }
  ```
</CodeGroup>

É o jeito mais rápido de descobrir se o CaktoMCP resolve o seu caso antes de
criar qualquer credencial. Quando quiser executar de verdade, acrescente a
chave conforme abaixo.

### Para executar de verdade

A autenticação usa a sua [Chave de API](/authentication) — o mesmo
`client_id`/`client_secret` do fluxo OAuth2 — enviada em dois headers:

| Header                  | Valor                                 |
| ----------------------- | ------------------------------------- |
| `X-Cakto-Client-Id`     | O `client_id` da sua Chave de API     |
| `X-Cakto-Client-Secret` | O `client_secret` da sua Chave de API |

<CodeGroup>
  ```bash Claude Code theme={null}
  claude mcp add --transport http cakto https://mcp.cakto.com.br \
    --header "X-Cakto-Client-Id: SEU_CLIENT_ID" \
    --header "X-Cakto-Client-Secret: SEU_CLIENT_SECRET"
  ```

  ```json Claude Desktop theme={null}
  {
    "mcpServers": {
      "cakto": {
        "type": "http",
        "url": "https://mcp.cakto.com.br",
        "headers": {
          "X-Cakto-Client-Id": "SEU_CLIENT_ID",
          "X-Cakto-Client-Secret": "SEU_CLIENT_SECRET"
        }
      }
    }
  }
  ```

  ```json Cursor / VS Code theme={null}
  {
    "servers": {
      "cakto": {
        "type": "http",
        "url": "https://mcp.cakto.com.br",
        "headers": {
          "X-Cakto-Client-Id": "SEU_CLIENT_ID",
          "X-Cakto-Client-Secret": "SEU_CLIENT_SECRET"
        }
      }
    }
  }
  ```
</CodeGroup>

<Note>
  Cliente MCP que só aceita um campo de autenticação? Use
  `Authorization: Basic` com o base64 de `client_id:client_secret`.
</Note>

<Warning>
  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.
</Warning>

<Note>
  **Seu cliente tentou `/authorize` ou `/.well-known/oauth-*` e recebeu 404?**
  É esperado. O CaktoMCP ainda não implementa descoberta OAuth, então clientes
  que procuram esse fluxo automaticamente não encontram e caem na configuração
  por header, que é a descrita acima. Não é erro, e não impede nada.
</Note>

O painel da Cakto mostra esses mesmos snippets já preenchidos com a sua
credencial, na página de Chaves de API.

## Explore

<CardGroup cols={2}>
  <Card title="Ferramentas de Descoberta" icon="magnifying-glass" href="/mcp/ferramentas-de-descoberta">
    Referência completa: busca, catálogo, contrato de endpoint, eventos de webhook
  </Card>

  <Card title="Ferramentas de Execução" icon="bolt" href="/mcp/ferramentas-de-execucao">
    Como a execução real funciona: confirmação, idempotência, erros, paginação
  </Card>

  <Card title="Guias" icon="book-open" href="/mcp/guias">
    Os conceitos que a IA já sabe explicar sem consultar nada externo
  </Card>

  <Card title="Autenticação" icon="key" href="/authentication">
    O CaktoMCP usa o mesmo fluxo OAuth2 — crie sua Chave de API desde já
  </Card>
</CardGroup>