Erros de conexão de servidor MCP no Claude Code: causas e soluções

Você configurou um servidor MCP (Model Context Protocol), mas ao abrir /mcp ele aparece travado em um estado como este — soa familiar?

/mcp

  filesystem      ✓ connected      (12 tools)
  github          ✗ failed
  notion          △ needs authentication
  my-server       ⏸ pending approval

O MCP permite ao Claude Code trabalhar com ferramentas e dados externos. Quando a conexão falha, o log às vezes mostra a linha MCP error -32000: Connection closed. A causa pode ser restringida combinando três elementos: status, método de conexão e detalhes do erro. Este artigo investiga, nesta ordem, a inicialização local, a comunicação e a autenticação remotas, a configuração e a aprovação.

O essencial: (1) Leia o status e os detalhes com /mcp e claude mcp get <name>. (2) failed pode ocorrer tanto em servidores locais quanto remotos. Para stdio, verifique o comando e as variáveis de ambiente; para HTTP, a URL, a rede, a resposta do servidor e a autenticação. (3) Se a causa não estiver clara, consulte os logs de conexão com claude --debug=mcp. Corrija apenas o que corresponde ao erro real e reconecte para verificar o resultado.

1. O que esse erro está dizendo

Quando a conexão é encerrada, o log mostra a linha a seguir.

MCP error -32000: Connection closed

MCP error -32000: Connection closed indica que a conexão MCP foi encerrada. O SDK TypeScript do MCP atribui -32000 a ConnectionClosed e emite essa mensagem quando uma conexão é encerrada (veja o tratamento de encerramento de conexões no SDK). Essa linha informa apenas o resultado, que a conexão foi encerrada; o motivo está nas entradas de log imediatamente anteriores. É nelas que você distingue um processo do servidor que terminou antes da inicialização de uma conexão que caiu depois.

A conexão pode cair mesmo com a configuração correta. A Issue #20713 é o relato de um usuário cuja conexão foi encerrada durante a inicialização com Claude Code 2.1.19 no macOS. A causa «condição de corrida» é a hipótese do próprio autor, e a Issue foi fechada como not planned em abril de 2026. Ao relatar um problema, inclua sistema operacional, versão, método de conexão e logs sem segredos.

Os servidores MCP costumam usar dois tipos de conexão. (1) stdio (local): o Claude Code inicia o comando do servidor como subprocesso no seu computador e se comunica pela entrada e saída padrão. (2) HTTP (remoto): conecta-se a um servidor na nuvem por URL (o antigo SSE está obsoleto). O significado de «não conecta» depende bastante do tipo.

Com servidores locais (stdio), as falhas são comando ausente, variáveis ausentes, servidor que termina logo em seguida ou logs misturados ao stdout. Com servidores remotos (HTTP), as causas são URL incorreta, problemas de rede, respostas 5xx, tempos limite e autenticação. Erros de localização, sintaxe ou escopo do arquivo de configuração podem ocorrer nos dois tipos.

Primeiro, registre o status e os detalhes do erro e identifique se a conexão usa stdio ou HTTP. Alterar várias configurações de uma vez dificulta saber qual mudança ajudou. Use a tabela a seguir como ponto de partida e investigue uma causa pertinente por vez.

2. Leia o status com /mcp primeiro

Execute /mcp na sessão (ou claude mcp list / claude mcp get <name> a partir do shell) para ver o estado de cada servidor. Os principais status e seus significados:

failed aparece tanto em falhas de inicialização local quanto em falhas de comunicação remota. A pista para distingui-las está nos detalhes: claude mcp list os acrescenta ao final da linha ✘ Failed to connect, e claude mcp get <name> e a tela de detalhes de /mcp os mostram na linha Issue:, com o status HTTP ou o código de erro e o texto de erro devolvido pelo servidor. Um cabeçalho fixo Authorization rejeitado com 401/403 durante a conexão também produz failed.

Quando um servidor remoto cai no meio da sessão, o Claude Code tenta reconectar automaticamente, e /mcp o mostra como pending enquanto isso (um sentido diferente de aguardar aprovação). Se as cinco tentativas falharem e ele passar a failed, aparece a notificação MCP server "<name>" disconnected · open /mcp to reconnect (se for preciso autenticar de novo, ele passa a needs authentication). Servidores stdio não são reconectados automaticamente; reconecte-os manualmente em /mcp. O /mcp também marca servidores que declaram a capacidade de ferramentas, mas não expõem nenhuma. Um servidor que só fornece recursos ou prompts funciona normalmente mesmo com zero ferramentas. Consulte os detalhes oficiais dos status do servidor.

3. Principais causas de falha e correções

Estas verificações ajudam a investigar falhas de conexão e divergências na configuração. Comece pelos itens pertinentes ao seu método de conexão.

Você pode compartilhar o .mcp.json do projeto, mas não inclua valores secretos diretamente nos commits. Por exemplo, referencie ${API_KEY} e defina o valor necessário em cada ambiente. Alguns nomes de variáveis protegidos, incluindo as credenciais do próprio Claude Code, resultam em strings vazias nas URLs e nos cabeçalhos remotos (regras oficiais de expansão). Sessões interativas pedem aprovação para servidores do projeto, mas claude -p e o SDK os carregam sem essa pergunta. Para impedir que um servidor seja carregado mesmo assim, inclua-o em disabledMcpjsonServers (documentação oficial do escopo de projeto). Relacionados: fundamentos do MCP e A2A.

4. Verifique a inicialização do npx no Windows

Se o Windows informar spawn npx ENOENT, primeiro confira o executável e PATH com where.exe npx. Em seguida, teste se Node/npm funciona e se o pacote especificado consegue iniciar sozinho. Segundo a documentação oficial do Node, arquivos .cmd do Windows não podem ser executados sozinhos: é preciso iniciá-los por um shell ou por cmd.exe.

{
  "command": "cmd.exe",
  "args": ["/c", "npx", "-y", "@scope/your-mcp-server"]
}

5. O fluxo de diagnóstico

Quando a causa não está clara, trabalhe de cima para baixo. O truque é confirmar que o servidor roda sozinho antes de culpar o Claude Code.

Nota: por padrão, o Claude Code carrega as definições de ferramentas por meio da busca de ferramentas só quando necessárias, então acrescentar servidores tem pouco impacto no contexto. Porém, em servidores com alwaysLoad ou em configurações com a busca de ferramentas desativada, as definições entram desde o início; por isso, é mais seguro desativar os servidores que você não usa com /mcp disable <name>. Sobrecarregar o contexto leva a Prompt is too long.

6. Checklist de prevenção

Hábitos para não travar nas conexões MCP.

(1) Escreva os caminhos reais de executáveis e scripts stdio. (2) Diferencie variáveis stdio de cabeçalhos de autenticação HTTP e mantenha segredos fora de arquivos compartilhados. (3) No Windows, verifique where.exe npx e Node/npm; tente cmd.exe /c apenas quando o problema for o método de inicialização. (4) Coloque .mcp.json na raiz do projeto e confira sintaxe JSON, variáveis e aprovação. (5) Envie logs stdio para stderr, não stdout. (6) Faça uma mudança por vez, reconecte e teste a operação necessária.

Resumo

Investigue erros de conexão MCP do Claude Code combinando status, método de conexão e detalhes do erro. failed não se limita a falhas de inicialização local: problemas de comunicação HTTP e cabeçalhos fixos de autenticação rejeitados também podem causá-lo. needs authentication aponta para a verificação da autenticação; pending approval, para a revisão da aprovação de um servidor do projeto.

Siga estas etapas: leia o status e Issue: → confira os logs adequados ao método de conexão → teste o funcionamento independente ou a comunicação → reconecte e verifique a operação. Selecione a categoria de depuração com claude --debug=mcp. Acrescente --debug-file ./claude-mcp-debug.log para salvar os logs. Remova segredos antes de compartilhá-los. Leituras relacionadas: O que é MCP, Monetização de servidores MCP, Erros comuns do Claude Code.

Quando o aplicativo Codex mostra o histórico, mas só o envio falha, o problema não é o MCP, e sim o estado da conversa. Esse caso é tratado em Codex “thread not found”: diagnóstico e um caso de recuperação.

FAQ

P. /mcp mostra failed. Por onde começo?
R. Confira o método de conexão e Issue:. Para stdio, inspecione comando, caminho, variáveis de ambiente e stderr; para HTTP, URL, rede, resposta do servidor e autenticação. Um cabeçalho fixo Authorization rejeitado com 401/403 durante a conexão também produz failed, e o status HTTP aparece em Issue:.

P. Aparece "needs authentication" e as ferramentas não funcionam.
R. A solução depende do método de autenticação. Para um servidor OAuth, autentique-se em /mcp. Com um headersHelper próprio, esse estado aparece quando uma chamada de ferramenta retorna 401/403 e a nova tentativa com credenciais obtidas de novo também falha. Se o helper fornece um cabeçalho Authorization, o Claude Code não muda para OAuth: corrija a origem e o valor das credenciais e reconecte. Conectores hospedados pela Anthropic, como Microsoft 365, Gmail e Google Calendar, não aceitam OAuth local a partir do Claude Code. Se você os adicionar com claude mcp add ou .mcp.json e tentar entrar por /mcp, aparece is Anthropic-hosted and doesn't support local OAuth; remova esse registro e conecte-os nas configurações de conectores do claude.ai. Veja a documentação oficial sobre autenticação própria.

P. Meu servidor npx não conecta no Windows.
R. Verifique where.exe npx e Node/npm e tente iniciar o mesmo pacote com os mesmos argumentos. Se o problema for a forma de iniciar o arquivo .cmd, você pode iniciá-lo com cmd.exe /c npx .... Para rodar no WSL, prepare Node e os pacotes no lado Linux.

P. Está connected, mas mostra 0 ferramentas.
R. Primeiro, veja se esse servidor foi projetado para oferecer ferramentas. Se ele só fornece recursos ou prompts, zero ferramentas é normal. Se ele declara a capacidade de ferramentas, mas mostra 0, o /mcp marca esse servidor; inspecione capacidades expostas, permissões, configurações do servidor e logs e depois reconecte. Envie logs de diagnóstico stdio para stderr, não para o fluxo stdout usado pelo protocolo.

P. Configurei um servidor, mas não consigo usá-lo.
R. Verifique se o .mcp.json compartilhado está na raiz do projeto; depois, confira sintaxe, escopo e aprovação. Uma ${VAR} indefinida e sem valor padrão gera um aviso e é carregada como texto literal, o que leva a falhas de inicialização ou autenticação. Nas configurações HTTP, escreva também type. Se claude mcp get <name> retornar ✘ Rejected, o servidor está em disabledMcpjsonServers em algum arquivo de configuração: além de refazer a aprovação, remova essa entrada.

Referências de configuração e comandos: configurações env, referência da CLI, referência de conexões MCP.