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. Se a conexão falhar, não faça o diagnóstico apenas pelo status: verifique também o método de conexão e os detalhes do erro. Este artigo aborda 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. Altere apenas o que o erro real indicar e reconecte para verificar o resultado.

1. O que esse erro está dizendo

Por exemplo, o seguinte erro pode aparecer em um log. Não conclua apenas pela mensagem que o servidor não iniciou; confira também as entradas anteriores.

MCP error -32000: Connection closed

MCP error -32000: Connection closed indica que a conexão foi encerrada. O SDK TypeScript do MCP atribui -32000 a ConnectionClosed. Verifique os logs anteriores para descobrir o que a encerrou, como a saída do servidor ou uma conexão perdida. A mensagem não permite saber se o processo terminou antes da inicialização ou se a conexão caiu depois. Consulte o tratamento de encerramento de conexões no SDK.

Falhas externas à sua configuração também são possíveis. Por exemplo, a Issue #20713 contém o relato de um usuário sobre desconexão durante a inicialização com Claude Code 2.1.19 no macOS. Não trate o diagnóstico de um usuário como causa confirmada pela Anthropic nem como falha atual que afeta todos os ambientes. 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.

Para servidores locais (stdio), verifique comandos ou variáveis ausentes, encerramento do servidor e logs misturados ao stdout. Para servidores remotos (HTTP), confira URL incorreta, problemas de rede, respostas 5xx, tempos limite e autenticação. Localização, sintaxe e escopo da configuração importam nos dois casos. Não afirme que falhas são «quase sempre autenticação» ou «quase sempre caminhos» sem evidências sobre sua frequência.

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 sozinho não distingue falhas de inicialização local de problemas de comunicação remota. Leia o código HTTP ou o corpo do erro em Issue: de claude mcp get <name>, ou nos detalhes de /mcp. Um cabeçalho fixo Authorization rejeitado com 401/403 durante a conexão também produz failed. Além disso, zero ferramentas não é necessariamente um erro em um servidor que só fornece recursos ou prompts. Primeiro, confira se ele foi projetado para oferecer 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; consulte as regras oficiais de expansão. Sessões interativas pedem aprovação para servidores do projeto. Em contrapartida, claude -p e o SDK normalmente os carregam sem essa pergunta. Consulte a documentação oficial do escopo de projeto para configurações de rejeição e outras condições. Os fundamentos do MCP e o A2A também são relacionados.

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. Verifique também se Node/npm funciona e se o pacote especificado consegue iniciar. A documentação oficial do Node explica que arquivos .cmd não podem ser executados diretamente e mostra como iniciá-los por um shell ou por cmd.exe. Porém, isso não significa que especificar npx diretamente falhe em todos os ambientes do Claude Code.

{
  "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: adicionar servidores MCP demais faz com que as definições de ferramentas consumam contexto (especialmente com carregamento permanente). Por padrão, o Claude Code adia essas definições por meio da busca de ferramentas, reduzindo o impacto; ainda assim, convém desativar servidores que você não usa. Sobrecarregar o contexto pode até causar Prompt is too long.

6. Checklist de prevenção

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

(1) Confira 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 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.

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, portanto não presuma que seja um problema de inicialização local.

Q. Aparece "needs authentication" e as ferramentas não funcionam.
A. Isto é um servidor remoto (HTTP) pedindo autenticação (401/403). Abra o /mcp e execute a autenticação para aquele servidor; ele segue para a aprovação OAuth no navegador. Uma vez concluído, os tokens são armazenados com segurança e renovados automaticamente. Note que alguns serviços (Microsoft 365, Gmail, Google Calendar) não suportam autenticação local pelo Claude Code e precisam ser conectados via Settings → Connectors no claude.ai.

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 usar cmd.exe /c npx .... O WSL também precisa de um ambiente Linux funcional. Mudar de sistema operacional não garante uma solução.

P. Está connected, mas mostra 0 ferramentas.
R. Confira se esse servidor foi projetado para oferecer ferramentas. Zero ferramentas não é necessariamente um erro se ele só fornece recursos ou prompts. Se deveria oferecer ferramentas, inspecione capacidades expostas, permissões, configurações do servidor e logs; 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 permanece como texto literal ao carregar a configuração, o que pode causar falhas de inicialização ou autenticação. Especifique também type nas configurações HTTP. Repetir a aprovação não resolve sozinho configurações de rejeição ou políticas gerenciadas.

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