A resposta curta
Quando uma chamada de ferramenta MCP dá timeout, não dá para saber se a alteração aconteceu. Sua IA pode ter perdido a resposta, não o trabalho. Confira antes de repetir: procure na ferramenta o que ela tentou criar. Repita só se não estiver lá. Nunca repita um envio por conta própria.
Neste guia
Por que o timeout não diz se a alteração aconteceu?
Sua IA pediu a uma ferramenta que fizesse uma alteração e esperou. Não veio resposta, então o app de IA parou de esperar e informou uma falha. Esse rótulo descreve a espera, não a alteração. Repetir uma alteração que já foi feita gera dois tickets, duas páginas ou duas mensagens.
Quem programa chama uma alteração assim de escrita. Três coisas podem ter acontecido.
| O que aconteceu | A alteração está na ferramenta? | Se você repetir |
|---|---|---|
| A requisição nunca chegou. | Não. | Repetir é o certo: a alteração é feita uma vez. |
| A ferramenta ainda está trabalhando. | Ainda não. Ela aparece depois que sua IA desistiu. | A alteração é feita duas vezes, a menos que repeti-la não cause dano. |
| A ferramenta terminou e a resposta se perdeu. | Sim. | A alteração é feita duas vezes, a menos que repeti-la não cause dano. |
A especificação do MCP prevê isso. Um cliente deve definir um timeout em cada requisição e, quando ele passar, cancelar a requisição e parar de esperar. O cancelamento não é garantia. O servidor pode ignorá-lo quando o trabalho já está pronto ou não pode ser interrompido. Ele também pode chegar depois que a resposta foi enviada.
O guia de API da Stripe diz o mesmo: depois que uma conexão falha, você pode não saber se a requisição foi executada. Ele também orienta a tratar um erro do servidor como resultado desconhecido.
O que fazer depois de um timeout, em ordem?
Faça isso nesta ordem. Os dois primeiros levam um minuto.
- Pare a nova tentativaAgora
Diga à sua IA que não repita a chamada: “Don’t retry. First check whether it was made.” Repetir sozinho é como uma alteração acaba feita duas vezes.
- Olhe na ferramenta, não no chat1 minuto
Abra a própria ferramenta: a página do Notion, as issues do GitHub, a pasta. Procure pelo título ou pelo id que você pediu. O chat só sabe que a chamada falhou.
- Leia o que encontrar2 minutos
Encontrada e completa: a alteração foi feita. Siga em frente e não a repita.
Encontrada pela metade: termine a parte que falta com uma atualização, não com uma criação nova.
Não encontrada: ela nunca chegou, ou ainda está rodando. Espere um minuto e olhe de novo. - Repita uma vez, e só uma chamada seguraEm seguida
Se ainda não estiver lá, repita uma vez. A tabela abaixo diz quais chamadas são seguras para repetir. Antes de um envio, veja onde ele chegou.
- Se continuar dando timeout, corrija a causaDepois
Uma chamada que sempre dá timeout tem um limite curto demais ou uma tarefa grande demais. Aumente o limite desse servidor, ou peça menos por chamada.
Quais chamadas são seguras para repetir?
Uma chamada é segura para repetir quando fazê-la duas vezes deixa o mesmo resultado que fazê-la uma vez. As leituras entram nessa regra. Muitas alterações não. O padrão HTTP trata PUT (definir um valor) e DELETE como seguros para repetir, e as linhas abaixo seguem isso. A dica idempotentHint ou a descrição da própria ferramenta vale mais que essas regras.
| A chamada | Repetir como está? | Conferir antes, por |
|---|---|---|
| Leitura: buscar, listar, abrir | Sim. Não muda nada. | Nada a conferir. |
| Definir um valor: um status, um título, um rótulo | Geralmente. Definir o mesmo valor duas vezes deixa o mesmo resultado, como no PUT do HTTP. | Lendo o campo. Se alguém mudou o valor depois, uma nova tentativa sobrescreve a edição dessa pessoa. |
| Adicionar a algo: um comentário, um registro, uma linha | Não. Duas vezes adiciona duas vezes. | Abrir o item e procurar o que você adicionou. |
| Criar: uma página, uma issue, um arquivo | Não. Uma nova tentativa cria a segunda. | Procurando pelo título ou id que você deu. Repita só se nada corresponder. |
| Apagar | Geralmente, quando nomeia um item exato, como no DELETE do HTTP. Não “o mais recente”: a segunda chamada atinge outro item. | Procurando o item. Se sumiu, está feito. |
| Enviar: uma mensagem, um e-mail, uma notificação | Nunca por conta própria. Um envio não pode ser desfeito. | Procurando onde ele chegou: a lista de enviados, o canal, o outro lado. Se não der para saber, pergunte antes de enviar de novo. |
Uma chave de idempotência evita a duplicata?
Às vezes. Uma chave de idempotência é um rótulo único enviado com a requisição. Se o mesmo rótulo chega duas vezes, o serviço faz o trabalho uma vez e devolve de novo a primeira resposta. Ela foi feita para uma requisição que não recebeu resposta.
- Como uma chave funciona na Stripe. A API v1 dela aceita uma chave em requisições
POST. Ela guarda o primeiro resultado, mesmo um erro, e o devolve de novo para uma nova tentativa com a mesma chave. Mantém as chaves por pelo menos 24 horas. A mesma chave com outros parâmetros é recusada. - O que uma nova tentativa precisa fazer. Envie a mesma chave e os mesmos parâmetros. A Stripe diz para não repetir com uma chave nova antes de saber o resultado da primeira vez. Uma chave nova a cada tentativa não dá proteção nenhuma.
- O que o MCP oferece. Uma requisição
tools/callleva o nome da ferramenta e os argumentos dela. O schema da especificação não define chave de idempotência para ela. Uma ferramenta ainda pode receber uma como argumento próprio, então leia os argumentos dela. - O que uma ferramenta pode declarar. A dica
idempotentHintdiz que chamar a ferramenta de novo com os mesmos argumentos não tem efeito adicional. É só uma dica. A especificação diz que os clientes nunca devem basear decisões em dicas de servidores em que não confiam.
Então a chave é um bônus, não um plano. Quando a ferramenta não oferece nenhuma, a conferência acima protege você.
Como mudar o timeout do MCP?
Um limite curto demais corta trabalho legítimo. Um longo demais deixa você esperando. Onde você define depende do app de IA. Veja as configurações do Claude Code.
| Configuração | O que limita | Padrão |
|---|---|---|
MCP_TOOL_TIMEOUT | Quanto tempo uma chamada de ferramenta pode rodar, em milissegundos. | 100.000.000 ms, cerca de 28 horas |
timeout em .mcp.json | O mesmo, para um servidor. Tem prioridade sobre a variável para esse servidor. Um limite rígido: notificações de progresso não o estendem. | O valor da variável |
CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT | Quanto tempo uma chamada pode ficar em silêncio, sem resposta e sem progresso, antes de ser abortada. 0 desliga a verificação. | 5 minutos para servidores de rede, 30 minutos para stdio |
MCP_TIMEOUT | Para iniciar um servidor. Em um servidor remoto, ele também conta no temporizador por requisição abaixo. | 30.000 ms, 30 segundos |
CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS | Quando uma chamada que ainda roda na conversa principal passa para uma tarefa em segundo plano. 0 desliga. Versão 2.1.212 ou posterior. | 120.000 ms, 2 minutos |
O padrão de 60 segundos para servidores remotos. Um servidor acessado por HTTP, SSE ou como conector do claude.ai tem um segundo temporizador. Ele roda em cada requisição até o primeiro byte de resposta do servidor. Dura 60 segundos, a menos que MCP_TOOL_TIMEOUT, o timeout do servidor ou MCP_TIMEOUT esteja configurado com um valor maior. Servidores stdio locais não têm temporizador por requisição.
Para definir para um servidor, acrescente "timeout": 600000 à entrada dele em .mcp.json. São dez minutos.
Uma chamada lenta nem sempre é uma que falhou. A partir da versão 2.1.212, o Claude Code passa uma chamada MCP da conversa principal para uma tarefa em segundo plano depois de dois minutos. Ele entrega o resultado quando a chamada termina.
A documentação de MCP do Cursor não descreve nenhuma configuração de timeout. A especificação do MCP não cita nenhum número. Ela diz que os SDKs devem permitir configurar timeouts por requisição, e que um cliente deve sempre manter um máximo.
Para trabalho que leva minutos, um servidor pode usar MCP Tasks. Ele devolve um identificador na hora, e o cliente consulta o resultado de tempos em tempos, mesmo depois de reconectar. Os dois lados precisam oferecer suporte, e o suporte dos clientes varia.
O que o Delta MCP faz quando uma resposta se perde?
O Delta MCP é um app gratuito no seu computador, entre sua IA e as ferramentas dela. Quando uma alteração não recebe resposta, ele não adivinha e não simplesmente repete. Ele lê a ferramenta.
Antes de a alteração sair, o Delta MCP escolhe uma leitura que possa mostrar se ela aconteceu. Essa leitura é o objeto lido de novo, ou uma lista lida de novo. Quando não vem resposta, ele faz essa leitura na hora. O que a leitura mostra decide:
| A leitura mostra | O Delta MCP |
|---|---|
| A alteração foi feita. | A tarefa segue, e a resposta diz que ela foi verificada. |
| A alteração não foi feita. | Ele envia a alteração mais uma vez, com os mesmos argumentos. Nunca faz isso sozinho para uma mensagem ou outro envio. Nesses casos, a resposta diz que ela não foi vista, que ainda pode aparecer, e a tarefa para. |
| Não está claro, ou não dá para ler nada que mostre. | A resposta diz que o resultado é desconhecido, e por quê. A tarefa para. Olhe a ferramenta antes de fazer a alteração de novo. |
Uma ferramenta chamada do jeito que está não pode ser revertida pelo Delta MCP. Se uma chamada anterior deu certo, ela continua feita, e a resposta a lista para que sua IA não a repita. Cada tarefa que altera algo fica guardada em Activity, com cada alteração antes e depois.
Como uma tarefa é verificada e aplicada
Perguntas
É seguro repetir uma chamada MCP depois de um timeout?
Uma leitura, sim. Uma alteração, não, antes de conferir. O timeout só diz que não veio resposta: a ferramenta pode ter feito a alteração mesmo assim. Procure-a na ferramenta, e repita só se ela não estiver lá. Nunca repita um envio por conta própria.
Se a requisição deu timeout, minha alteração no MCP foi feita?
Pelo timeout, não dá para saber. A requisição pode nunca ter chegado, a ferramenta pode ainda estar trabalhando, ou ela terminou e a resposta se perdeu. Abra a ferramenta e procure a alteração.
Como aumentar o timeout da ferramenta MCP no Claude Code?
Defina MCP_TOOL_TIMEOUT em milissegundos, ou acrescente um campo timeout à entrada do servidor em .mcp.json. Em um servidor remoto, defina um valor acima de 60.000 para tirar o temporizador de 60 segundos por requisição. MCP_TIMEOUT é a espera para iniciar, não o limite da chamada de ferramenta.
Como mudar o timeout do MCP no Cursor?
A documentação de MCP do Cursor não descreve nenhuma configuração de timeout. Ela diz que uma chamada que falhou aparece marcada como falha no chat, e que você pode repetir ou consultar os registros. Confira primeiro o que a ferramenta já tem.
O MCP tem chaves de idempotência?
Não. Uma chamada de ferramenta leva o nome da ferramenta e os argumentos, e o schema da especificação não define chave de idempotência para ela. Uma ferramenta pode receber uma chave própria como argumento. Ela também pode definir idempotentHint, que é só uma dica.
O que o Delta MCP faz quando uma chamada de ferramenta não recebe resposta?
Ele lê a ferramenta na hora para ver se a alteração aconteceu. Feita: a tarefa segue. Não feita: ele envia a alteração mais uma vez. Uma mensagem ou outro envio nunca é enviado de novo por conta própria. Não está claro: a resposta diz que o resultado é desconhecido, e a tarefa para.
Fontes
- Model Context Protocol, Cancellation Os clientes devem definir timeouts, cancelar e parar de esperar; um cancelamento pode chegar depois que o trabalho já foi feito (revisão 2026-07-28).
- Model Context Protocol, Schema Reference Uma chamada de ferramenta leva nome e argumentos, sem chave de idempotência; a anotação idempotentHint, e anotações são só dicas (revisão 2026-07-28).
- Model Context Protocol, Tasks Um identificador durável para operações longas, consultado e recuperado depois de reconectar; os dois lados precisam optar por usar.
- Claude Code, Connect Claude Code to tools via MCP O timeout por servidor, o temporizador de 60 segundos por requisição para servidores remotos, a janela de inatividade, a passagem para segundo plano depois de dois minutos.
- Claude Code, Environment variables MCP_TOOL_TIMEOUT, MCP_TIMEOUT, CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT e CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS, com os padrões.
- Cursor, Model Context Protocol (MCP) Uma chamada MCP que falhou aparece marcada como falha no chat; repetir ou consultar os registros; nenhuma configuração de timeout é descrita.
- Stripe, Idempotent requests Como funciona uma chave de idempotência: o primeiro resultado é guardado e devolvido de novo; as chaves duram pelo menos 24 horas; outros parâmetros são recusados.
- Stripe, Advanced error handling Depois que uma conexão falha, você pode não saber se a requisição foi executada; um erro do servidor é um resultado desconhecido; nenhuma chave nova antes de saber o resultado.
- IETF, RFC 9110: HTTP Semantics Métodos idempotentes (métodos seguros, PUT e DELETE), e não repetir uma requisição não idempotente, a menos que você saiba que a primeira nunca foi aplicada.
- Delta MCP, Writing a task O que o Delta MCP faz quando uma alteração não recebe resposta: feita, não feita ou resultado desconhecido; um envio não é enviado de novo por conta própria.
- Delta MCP, Activity and Undo Cada tarefa que alterou algo fica guardada em Activity, com cada alteração antes e depois.
Continue lendo
- Como desfazer alterações de IA no Notion, GitHub e arquivosUma IA alterou ou apagou algo? Veja o que mudou, como desfazer alterações de IA no Notion, no GitHub e nos seus arquivos, e o que não tem volta.
- MCP vs CLI para agentes de IA: de onde vem a conta de tokensMCP ou CLI para seu agente de IA? O custo de cada um em tokens, o que as medições mostram, quando a CLI ganha, quando o MCP ganha e onde o código vence os dois.
