Skip to main content
As ferramentas desta página exigem uma Chave de API 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:

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

​
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.
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:
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. 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

Ferramentas de Descoberta

Buscar e entender operações sem precisar de credencial

Guias

Conceitos que a IA já sabe explicar