Resposta rápida
Se um servidor MCP remoto continua desconectado no Claude Code depois de uma queda curta, confirme primeiro a versão. A versão 2.1.295, publicada em 8 de outubro de 2026, corrigiu sessões headless e SDK que não se recuperavam quando a interrupção durava mais de 15 segundos. Atualize para essa versão ou uma posterior, reinicie a sessão e execute claude mcp list.
Se o estado for Needs authentication, refaça o login pelo comando /mcp. Se aparecer Failed to connect, abra os detalhes com claude mcp get e revise URL, transporte, autorização e disponibilidade. A atualização melhora a reconexão; ela não corrige credenciais vencidas, servidor fora do ar ou configuração errada.
O que a versão 2.1.295 corrigiu
As notas oficiais registram que servidores MCP remotos em sessões headless ou iniciadas pelo SDK podiam permanecer desconectados depois de uma interrupção superior a 15 segundos. A mesma correção eliminou ciclos apertados de reconexão: quando a conexão cai repetidamente, o cliente agora aumenta a espera entre tentativas, chegando a 30 segundos.
A versão também corrigiu conexões descartadas quando uma resposta de erro do servidor continha o nome de um erro de rede e um caso de paginação em que o mesmo cursor podia repetir a mesma página até 20 vezes por conexão. Esses pontos ajudam a separar falha do cliente de erro de OAuth, configuração ou do próprio servidor.
Atualize e confirme a versão
Use o método oficial pelo qual o Claude Code foi instalado e confirme o resultado com claude --version. Em máquinas de CI, containers e imagens de desenvolvimento, atualizar apenas a instalação local não altera o binário fixado na automação; revise também a imagem, o cache e a etapa de instalação do pipeline.
Depois da atualização, encerre a sessão antiga e inicie outra. Uma sessão já aberta pode preservar processos e conexões anteriores. Em seguida, compare o comportamento com o servidor ativo e sem alterar vários parâmetros ao mesmo tempo.
- Execute claude --version e confirme 2.1.295 ou posterior.
- Atualize a instalação usada pela sessão headless, SDK, CI ou container.
- Encerre o processo antigo e inicie uma sessão nova.
- Espere até 30 segundos após quedas repetidas antes de concluir que não houve reconexão.
- Execute claude mcp list para verificar o estado atual.
Leia o estado antes de mudar a configuração
O comando claude mcp list mostra os servidores cadastrados. claude mcp get abre os detalhes de um servidor, enquanto /mcp permite consultar o estado dentro da sessão. A documentação diferencia Connected, Needs authentication e Failed to connect. Trate cada resultado como uma causa diferente.
Connected indica que a conexão foi estabelecida, mas não garante que todas as ferramentas estejam autorizadas. Needs authentication pede um novo fluxo OAuth. Failed to connect exige examinar a mensagem exibida, o endpoint e a disponibilidade. O Claude Code remove textos parecidos com credenciais dos detalhes, mas ainda assim não publique logs completos sem revisão.
Revise URL, transporte, OAuth e aprovação
Para um servidor HTTP remoto, confira se o cadastro aponta para o endpoint completo esperado pelo provedor, por exemplo https://mcp.exemplo.com/mcp. Um endereço que responde no navegador pode ainda falhar no transporte MCP, no TLS, no redirecionamento ou na autorização. Compare o cadastro com a documentação oficial do servidor.
Servidores definidos no arquivo .mcp.json do projeto podem ficar pendentes de aprovação até que o diretório seja confiável. Em OAuth, use /mcp para autenticar novamente. Se o client secret foi alterado, a documentação orienta remover e adicionar de novo o servidor. Quando houver escopos configuráveis, declare somente os necessários.
- Confirme o nome, a URL completa e o transporte do servidor.
- Verifique se o projeto e o arquivo .mcp.json foram aprovados.
- Refaça o OAuth somente quando o estado pedir autenticação.
- Procure conflito entre servidores de mesmo nome em escopos diferentes.
- Revise espaços invisíveis em nomes, URLs e variáveis de ambiente.
Timeout não resolve toda desconexão
O Claude Code separa tempos diferentes. MCP_TIMEOUT controla quanto o cliente espera o servidor iniciar. O campo timeout de um servidor no .mcp.json limita a duração total de uma chamada de ferramenta. Já CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT controla quanto uma ferramenta pode ficar sem produzir saída; para HTTP, SSE, WebSocket e conectores, o padrão documentado é cinco minutos.
Aumentar um limite pode ajudar uma inicialização ou tarefa realmente lenta, mas não recupera token inválido, endpoint incorreto ou serviço indisponível. Mude um limite somente depois de identificar em qual etapa o tempo expirou e registre o valor anterior para poder reverter.
Isole o cliente, a rede e o servidor
Use claude doctor ou /doctor para checar a instalação. Se o problema desaparecer com claude --safe-mode, investigue plugins, hooks e servidores MCP carregados pela configuração normal. Para um endpoint próprio, teste DNS, HTTPS e resposta web separadamente, sem inserir tokens em ferramentas públicas.
Consulte também o Claude Status. Uma página de status operacional reduz a probabilidade de uma falha ampla, mas não comprova que o seu servidor MCP, a sua rota ou a sua conta estejam funcionando. Se apenas um servidor falha, priorize os detalhes desse cadastro e os logs do servidor.
Limitações e próxima ação útil
Este guia foi verificado em 12 de outubro de 2026. A correção documentada da versão 2.1.295 cita especificamente servidores MCP remotos em sessões headless e SDK. Uma falha na interface interativa, em stdio ou no servidor remoto pode ter outra origem. O recuo de até 30 segundos também significa que uma reconexão não precisa ser imediata.
Faça um teste controlado: atualize o cliente, registre versão e estado, interrompa apenas um servidor de teste e confirme se ele volta a Connected depois da retomada. Se não voltar, guarde a mensagem sem segredos, o horário, o transporte e os comandos list/get; essas evidências permitem corrigir a camada certa ou abrir um relato reproduzível.
Faça o próximo teste
Fontes consultadas
Os links abaixo servem para conferir conceitos, orientações oficiais e o critério editorial usado neste conteúdo.
- Claude Code v2.1.295Anthropic on GitHub
- Connect Claude Code to tools via MCPAnthropic
- Troubleshooting Claude CodeAnthropic
- Claude StatusAnthropic