> ## 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 credencial, confirmação e idempotência. As ferramentas desta página exigem uma [Chave de API](/authentication) configurada. Sem ela, retornam um erro claro explicando o que falta — o restante do CaktoMCP (descoberta) continua funcionando normalmente. ## `cakto_whoami` Identifica a credencial ativa: ambiente (produção ou staging), `client_id` configurado, e os escopos concedidos pelo token OAuth2 atual. Chamada no início de qualquer trabalho de integração, e sempre que uma operação falhar por permissão. Sem parâmetros. 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: 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`. Depois de você revisar o preview e aprovar, a mesma chamada é repetida com `confirm: true` — e então a operação executa de verdade. 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. 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` | 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. 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](/conceitos/idempotencia). 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 Buscar e entender operações sem precisar de credencial Conceitos que a IA já sabe explicar