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

# Ferramentas de Execução

> Como o CaktoMCP executa operações reais — com login ou credencial, confirmação e idempotência.

> [!NOTE]
>
> As ferramentas desta página precisam da sua conta: pelo
> [login da Cakto](https://docs.cakto.com.br/mcp/visao-geral.md#como-conectar) ou por uma
> [Chave de API](https://docs.cakto.com.br/authentication.md). Sem nenhum dos dois, a IA abre o login da
> Cakto (ou, no cliente que não abre, recebe um erro dizendo o que falta). O
> restante do CaktoMCP (descoberta) continua funcionando normalmente.

## `cakto_whoami`

Identifica a conta ou a credencial ativa: ambiente (produção ou staging),
quem está conectado e os escopos concedidos. Chamada no início de qualquer
trabalho de integração, e sempre que uma operação falhar por permissão.

Sem parâmetros. Com o **login da Cakto**, retorna:

| Campo | Descrição |
| - | - |
| `ambiente` | `producao` ou `staging` |
| `autenticacao` | `login OAuth da Cakto` |
| `conta` | E-mail e nome da conta que autorizou |
| `cliente_mcp` | A IA que fez o login (ex.: `MCP · Claude`) |
| `escopos_concedidos` | Lista de escopos que o login de fato tem. Começa só com leitura |
| `expira_em` | Quando o acesso precisa ser renovado (a IA renova sozinha) |

Com a **Chave de API**, retorna:

| Campo | Descrição |
| - | - |
| `ambiente` | `producao` ou `staging` |
| `client_id` | A Chave de API em uso |
| `escopos_concedidos` | Lista de escopos que o token atual de fato tem |
| `expira_em` | Quando o token precisa ser renovado |
| `claims_do_token` | Dados adicionais decodificados do token, quando existirem |

## `cakto_call`

Executa qualquer operação da API pelo seu `operation_id` — o mesmo
identificador retornado por `cakto_search_api`/`cakto_list_endpoints` e
detalhado por `cakto_get_endpoint`. Uma única ferramenta cobre a API
inteira, então ela acompanha o contrato automaticamente: se um endpoint
muda, o comportamento de `cakto_call` muda com ele, sem esperar uma
atualização manual.

| Parâmetro | Tipo | Obrigatório | Descrição |
| - | - | - | - |
| `operation_id` | string | Sim | Identificador exato da operação |
| `path_params` | objeto | Não | Parâmetros de caminho, ex.: `{"id": "abc123"}` |
| `query` | objeto | Não | Parâmetros de query string, com os nomes exatos do contrato |
| `body` | objeto | Não | Corpo da requisição, conforme o schema da operação |
| `fields` | lista de strings | Não | Projeção: retorna só esses campos por item, para economizar contexto em listagens |
| `idempotency_key` | string | Não | Reenvia a mesma chave de uma tentativa anterior para repetir com segurança. Gerada automaticamente se omitida |
| `confirm` | boolean | Não (default `false`) | Sem isso, escrita devolve preview em vez de executar; leitura roda direto — ver a seção **Confirmação em duas etapas** abaixo |

### Allowlist pelo contrato real

`cakto_call` só executa operações que existem de fato no contrato da API.
Um `operation_id` desconhecido nunca é interpretado como uma tentativa de
adivinhar uma URL — a ferramenta responde com as operações mais parecidas
encontradas na busca, para você (ou a IA) escolher a certa.

### Validação antes de qualquer chamada

Antes de enviar qualquer coisa pela rede, `cakto_call` valida `path_params`,
`query` e `body` contra o schema real da operação. Campo obrigatório
ausente, tipo errado ou valor fora do permitido é rejeitado **antes** da
chamada — nenhuma requisição chega a sair, e nenhum limite de uso é gasto
com uma tentativa que já sabíamos que ia falhar.

### Confirmação em duas etapas

Uma operação de escrita (criar, atualizar ou remover) chamada com `confirm`
no default devolve um preview em vez de executar:

**1. Preview**

A chamada sem `confirm: true` não executa nada. Retorna o método, a URL
final, o corpo exato que seria enviado e uma descrição do efeito em
português. Se o ambiente ativo for **produção**, essa descrição vem
prefixada por um aviso destacando isso; operações sem suporte confirmado
de idempotência trazem também um `aviso_idempotencia`.

**2. Confirmação**

Depois de você revisar o preview e aprovar, a mesma chamada é repetida
com `confirm: true` — e então a operação executa de verdade.

> [!WARNING]
>
> Essas duas etapas são uma convenção que o cliente MCP precisa cumprir, não
> uma trava do servidor. O transporte é HTTP stateless: sem estado entre
> requisições, o servidor não tem como verificar se o preview foi mostrado a
> alguém. Um agente que já mande `confirm: true` na **primeira** chamada
> executa direto, sem preview.
>
> O que o gate garante é que uma escrita nunca acontece como efeito colateral
> acidental de uma leitura — o modelo tem de decidir explicitamente enviar
> `confirm: true`. Se o seu caso exige aprovação humana obrigatória, imponha
> isso no cliente (por exemplo, na aprovação manual de chamadas de
> ferramenta), em vez de presumir que o servidor a garante.

### Idempotência

Toda operação de escrita recebe automaticamente uma chave de idempotência
(gerada ou reaproveitada de `idempotency_key`), pensada para permitir
repetir uma chamada com segurança depois de uma falha de rede, sem duplicar
a operação.

> [!WARNING]
>
> Hoje, o suporte real de idempotência no backend está disponível para
> operações de cobrança (criação de pagamento). Para as demais operações
> de escrita, `cakto_call` continua enviando a chave e avisa explicitamente
> no resultado quando a proteção completa ainda não está confirmada para
> aquela operação específica — para você decidir com informação, em vez de
> assumir uma garantia que não existe.

### Paginação

Listagens vêm com um objeto `pagination` traduzido — `total`, `page_size`,
`has_more` e `next_page` — em vez das URLs cruas de próxima/página
anterior. Para pegar a página seguinte, basta repetir a chamada com
`query.page` igual a `next_page`.

Respostas muito grandes (mais de 50 itens, ou acima de um teto de tamanho)
são truncadas automaticamente, sempre com um aviso explícito de quanto foi
cortado e como reduzir — nunca em silêncio. Use `fields` para reduzir o
tamanho por item antes de pedir mais páginas.

### Tratamento de erro

Todo erro de `cakto_call` vem num formato consistente:

```json theme={null}
{
  "ok": false,
  "kind": "scope",
  "fatal": true,
  "http_status": 403,
  "message": "A credencial não tem o escopo necessário para esta operação.",
  "next_step": "Chame cakto_whoami para ver os escopos atuais..."
}
```

| `kind` | Significado |
| - | - |
| `validation` | Payload ou parâmetro inválido — corrigível na mesma sessão |
| `auth` | Credencial ausente, inválida ou expirada |
| `scope` | O login ou a Chave de API não tem o escopo necessário |
| `not_found` | Recurso não encontrado |
| `conflict` | Resultado de negócio (ex.: já processado, já expirado) — não é uma falha técnica |
| `rate_limit` | Limite de requisições excedido |
| `server` | Erro do lado da Cakto |
| `network` | Falha de conectividade |

O retry automático (até 2 tentativas, com backoff exponencial) só acontece
quando repetir a chamada é comprovadamente seguro: em **leituras** (`GET`),
ou em uma escrita que o backend confirmadamente honra a chave de
idempotência — hoje, apenas a criação de pagamento.

> [!WARNING]
>
> Qualquer outra escrita (criar produto, atualizar oferta, cancelar
> assinatura, remover webhook) **nunca é retentada automaticamente**, mesmo
> em `rate_limit` ou `server`. Fora de criação de pagamento, o backend
> ignora a chave de idempotência e uma repetição cria um recurso duplicado
> de verdade — ver [Idempotência](https://docs.cakto.com.br/conceitos/idempotencia.md). Nesses casos
> repetir é uma decisão sua, e só é seguro se você tiver certeza de que a
> tentativa anterior falhou antes de chegar ao backend.

O campo `next_step` sempre diz se um retry automático já aconteceu ou não,
para não haver dúvida sobre repetir manualmente.

## Próximos passos

> [card] [Ferramentas de Descoberta](https://docs.cakto.com.br/mcp/ferramentas-de-descoberta.md)
>
> Buscar e entender operações sem precisar de credencial

> [card] [Guias](https://docs.cakto.com.br/mcp/guias.md)
>
> Conceitos que a IA já sabe explicar


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.