Índice
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 approvalO MCP dá ao Claude Code "mãos" — ferramentas externas (operações de arquivos, GitHub, bancos de dados, diversas APIs) — mas suas conexões falham com mais frequência do que se imagina. As causas se dividem em três famílias: "falha ao iniciar o subprocesso local", "autenticação remota" e "erros no arquivo de configuração", e o status do /mcp indica qual delas é. Este artigo apresenta como ler o status, correções causa por causa, a principal armadilha do Windows e o fluxo de diagnóstico — com base em informações oficiais.
Os pontos-chave logo de início. (1) Olhe o status com /mcp (e claude mcp list) primeiro — failed (falha ao iniciar), needs authentication (autenticação) e pending approval (aguardando aprovação) exigem correções completamente diferentes. (2) Para o local (stdio) os culpados de praxe são os caminhos e as variáveis de ambiente, além do problema do npx no Windows. (3) Para o remoto (HTTP) o culpado de praxe é o OAuth. (4) Quando estiver travado, execute claude --debug mcp para ver a saída de erro do servidor (stderr). Comportamentos e padrões mudam conforme a versão, então confirme contra a documentação oficial mais recente.
O status indica a correção
— failed / needs auth / pending têm cada um uma cura diferente
✗ failed = um problema de início local, △ needs auth = autenticação remota, ⏸ pending = aguardando aprovação.
Não junte tudo em "não conecta" — classifique pelo status primeiro; é o caminho mais curto.
1. O que esse erro está dizendo
Os servidores MCP vêm em dois grandes tipos de conexão. (1) stdio (local) — o Claude Code inicia o comando do servidor como um subprocesso na sua máquina e conversa por entrada/saída padrão. (2) HTTP (remoto) — ele se conecta a um servidor na nuvem por URL (o antigo SSE está descontinuado). O que "não conecta" significa depende fortemente do tipo.
Uma falha local (stdio) é quase sempre "o próprio comando falhou ao iniciar" — caminho errado, npx não resolvendo (especialmente no Windows), ou o servidor travando de imediato porque falta uma variável de ambiente obrigatória. Uma falha remota (HTTP) costuma ser "o OAuth não foi concluído" — o servidor retorna 401/403 e mostra needs authentication. E quando não é nenhum dos dois, mas a configuração não tem efeito, suspeite do local do arquivo de configuração, um erro de digitação no JSON, ou a aprovação do projeto.
Então o primeiro passo é "abrir o /mcp, ler o status e identificar qual das três famílias é." Tratar todo erro como um genérico "não conecta" e mexer ao acaso é o caminho mais longo. A próxima seção cobre como ler o status.
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:
| Status | Significado | Onde olhar primeiro |
|---|---|---|
| ✓ connected | Conectado. A contagem de ferramentas aparece ao lado | Se a contagem de ferramentas for 0: "conectado, mas sem ferramentas" → reconectar / depurar |
| ✗ failed | Falhou ao iniciar, ou esgotou as tentativas | Início local = comando, caminho, npx, variáveis de ambiente (§3, §4) |
| △ needs authentication | O remoto retornou 401/403. OAuth não concluído | Execute a autenticação a partir do /mcp (aprove no navegador) |
| ⏸ pending approval | Aguardando aprovação de um servidor do .mcp.json do projeto | Aprove em /mcp. Se rejeitou por engano: claude mcp reset-project-choices |
| ✗ rejected | Um servidor de projeto que você recusou anteriormente | Idem (reset-project-choices para reaprovar) |
A ideia: "failed = um problema de início, needs authentication = autenticação, pending = aprovação" — o status determina de forma única o seu próximo passo. Um caso comumente ignorado é "conectado, mas 0 ferramentas" — o servidor iniciou, mas não está retornando uma lista de ferramentas; parta para uma reconexão ou verifique os logs com claude --debug mcp.
3. Principais causas de falha e correções
Aqui estão as causas representativas de failed (falha ao iniciar o local) e dos problemas de configuração, em conjunto com as correções.
Principais motivos de failed / problemas de configuração
spawn ... ENOENT.env por servidor (em .mcp.json ou --env). O env do settings.json NÃO chega ao MCP.MCP_TIMEOUT (ms) na inicialização, ex.: MCP_TIMEOUT=10000 claude..mcp.json de projeto fica na raiz do repositório (não dentro de .claude/, nem no settings.json). Um ${VAR} indefinido faz a análise da configuração falhar.needs authentication. OAuth a partir do /mcp. Atenção: um cabeçalho de autenticação estático rejeitado é reportado como failed.
Para o local, verifique nesta ordem: 1) caminho → 2) variáveis de ambiente → 4) local da configuração.
Para o remoto, 6) autenticação é quase tudo. A armadilha do Windows na próxima seção também é muito comum.
Um .mcp.json de projeto pode ser compartilhado via git e pede aprovação na primeira vez. Se você dispensar esse prompt por engano, o servidor fica desabilitado (pending/rejected). Execute claude mcp reset-project-choices para refazer a aprovação. Combine isso com os fundamentos do MCP e a comunicação entre agentes A2A para ter o quadro completo de conectividade.
4. Quando falha no Windows (a maior armadilha)
No Windows nativo, servidores MCP baseados em npx que não conectam com spawn npx ENOENT / Failed to connect são extremamente comuns. A causa: o npx do Windows é, na verdade, um atalho em batch (npx.cmd), e o spawn de processos do Node não consegue resolver um .cmd diretamente.
Correção: envolva com cmd /c
Faça o command ser cmd em vez do npx diretamente, e passe /c npx ... como args:
{
"command": "cmd",
"args": ["/c", "npx", "-y", "@scope/your-mcp-server"]
}Ou execute-o sob o WSL, que é confiável. Se o where npx mostrar um caminho e ainda assim falhar, suspeite primeiro desse problema do .cmd. Algumas ocorrências específicas de versão podem estar corrigidas em releases posteriores, então tente também atualizar para a versão mais recente.
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.
Isole de cima para baixo
/mcp e claude mcp list / get para verificar o status (failed vs auth vs pending).claude --debug mcp para ler o stderr (saída de erro) do servidor. O motivo do travamento normalmente está bem aqui.npx ... roda no mesmo shell?). Se não, é um problema anterior ao Claude Code.npx @modelcontextprotocol/inspector) — inspecione sua lista de ferramentas e invoque ferramentas em uma interface.mcp*.log. O /doctor também verifica.
A regra: confirme primeiro "o servidor roda sozinho?".
Uma vez resolvido isso, o resto se restringe à configuração (caminho, env, local) ou à autenticação.
Observação: adicionar servidores MCP demais faz com que as definições de ferramentas consumam o contexto (especialmente em configurações de carregamento permanente). O Claude Code adia as definições de ferramentas via busca de ferramentas por padrão, então o impacto é pequeno, mas ainda é sensato desabilitar os servidores que você não usa. Sobrecarregar o contexto pode até disparar o Prompt is too long.
6. Checklist de prevenção
Hábitos para não travar nas conexões MCP.
(1) Especifique scripts locais com caminhos absolutos. (2) Coloque as chaves do servidor no campo env por servidor (não no settings.json). (3) No Windows, envolva com cmd /c npx ... (ou use o WSL). (4) Mantenha o .mcp.json na raiz do repositório; atenção à sintaxe JSON e a ${VAR} indefinido. (5) Os servidores não devem registrar logs no stdout (use o stderr). (6) Após mudanças na configuração, recarregue (reinicie o Desktop por completo; reaprove os servidores de projeto). (7) Quando travar, isole com claude --debug mcp e um início isolado do servidor, e atualize para a versão mais recente se necessário.
Resumo
Para os erros de conexão de servidor MCP do Claude Code, o caminho mais curto é classificar em três famílias pelo status do /mcp. ✗ failed é um problema de início local (caminho, variáveis de ambiente, timeout, local da configuração — e no Windows, envolva o npx com cmd /c), △ needs authentication é OAuth remoto (autentique a partir do /mcp), e ⏸ pending approval é um servidor de projeto aguardando aprovação (aprove em /mcp; uma recusa indevida é corrigida com claude mcp reset-project-choices).
Diagnostique nesta ordem: (1) status com /mcp -> (2) stderr com claude --debug mcp -> (3) início isolado -> (4) MCP Inspector -> (5) reinício completo do Desktop. Confirme que o servidor roda sozinho antes de culpar o Claude Code, e o resto se restringe à configuração ou à autenticação. Apenas três hábitos — variáveis de ambiente no campo env por servidor, .mcp.json na raiz do repositório, logs para o stderr — reduzem drasticamente os incidentes. Relacionados: O que é MCP, Monetizando servidores MCP, Coletânea de erros do Claude Code.
FAQ
Q. O /mcp mostra "failed". Por onde começo?
A. failed é, na maioria das vezes, uma falha ao iniciar um servidor local (stdio). Verifique nesta ordem: (1) o caminho do comando/script (use caminhos absolutos), (2) as variáveis de ambiente obrigatórias (coloque-as no campo env por servidor), e (3) no Windows, envolva com cmd /c npx .... Se a causa ainda não estiver clara, leia o stderr do servidor com claude --debug mcp e teste primeiro se o servidor inicia sozinho no mesmo shell.
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.
Q. No Windows, meu servidor com npx simplesmente não conecta.
A. O npx do Windows é, na verdade, um atalho em batch (npx.cmd), que muitas vezes falha ao iniciar com spawn npx ENOENT. Mude o command para cmd e os args para ["/c","npx","-y","nome-do-pacote"] para envolvê-lo. Rodar sob o WSL também é confiável. Se o where npx mostrar um caminho e mesmo assim falhar, é quase certo que seja esse problema do .cmd. Pode estar corrigido em versões mais novas, então tente atualizar também.
Q. Está "connected", mas mostra 0 ferramentas.
A. O servidor iniciou com sucesso, mas não está retornando uma lista de ferramentas. Uma causa comum é um servidor stdio escrevendo logs no stdout e corrompendo o protocolo — sempre envie os logs para o stderr. Primeiro reconecte pelo /mcp; se isso não resolver, verifique a saída do servidor com claude --debug mcp.
Q. Configurei um servidor, mas ele não aparece no /mcp.
A. O local do arquivo de configuração é o problema provável. Um servidor de projeto compartilhado vai no .mcp.json na raiz do repositório (ele não é lido dentro de .claude/ nem do settings.json). Um ${VAR} indefinido também faz a análise da configuração falhar. Servidores de projeto precisam de uma aprovação inicial; se você dispensar o prompt, ele fica pending — refaça com claude mcp reset-project-choices.
