Servidor MCP configurado, mas nenhuma ferramenta aparece? Aqui está provavelmente o porquê

Você adiciona um servidor MCP à sua configuração. O JSON é válido. O cliente até diz "conectado." E então: zero ferramentas. Nenhum erro. Nenhuma dica. O /doctor oficial não diz que há algo errado.

Se isso aconteceu com você, bem-vindo — os problemas no GitHub estão cheios de nós:

• Servidores MCP falham ao conectar com npx no Windows — 112 comentários
• Servidores MCP não funcionam com NVM — 182 reações
• Claude Desktop silenciosamente descarta todas as ferramentas quando uma chave de servidor contém parênteses
• O /doctor do Claude Code falha em detectar erros de configuração do MCP

Após ler esses tópicos, as falhas se agrupam em algumas causas — e nenhuma delas é culpa do servidor MCP. São falhas de configuração do cliente que as ferramentas oficiais não diagnosticam. Aqui está o guia de campo.

1. Parênteses (ou colchetes) no nome do servidor

{
  "mcpServers": {
    "Home Assistant (ha-mcp)": { "command": "npx", "args": ["-y", "ha-mcp"] }
  }
}

Isso parece inofensivo. Mas pelo menos um cliente importante silenciosamente descarta todas as ferramentas quando uma chave mcpServers contém parênteses. O servidor mostra conectado, tools/list completa, e a interface não exibe nada. Um usuário relatou ter perseguido isso por horas.

Solução: renomeie a chave — apenas letras, números, hífens, sublinhados.

2. Raw npx no Windows

{ "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem"] }

Aplicativos GUI no Windows frequentemente falham ao iniciar npx diretamente. O terminal funciona; o cliente de desktop não, porque processos GUI não obtêm seu ambiente de shell.

Solução: envolva-o:

{ "command": "cmd", "args": ["/c", "npx", "-y", "..."] }

3. Caminhos do NVM (ou qualquer gerenciador de versão)

npx funciona no seu terminal porque seu shell carrega o NVM. Aplicativos GUI não carregam seu perfil de shell, então o binário simplesmente não está no PATH deles. O problema de 182 reações acima é exatamente isso.

Solução: use o caminho absoluto para o binário ou um shim que a GUI possa resolver.

4. JSON que "parece bom"

Um caminho do Windows não escapado ("cwd": "C:\tools\my-server") e toda a configuração falha silenciosamente ao ser analisada. Alguns clientes relatam isso; outros simplesmente mostram zero servidores.

Solução: execute o arquivo através de qualquer validador JSON — python -m json.tool config.json.

5. Caches obsoletos e derivações de ambiente

Usuários relatam servidores lançados por uv que continuam falhando após o script subjacente ter sido corrigido, porque o executor da ferramenta armazenou em cache o ambiente quebrado. Além disso: blocos env que referenciam variáveis que o processo GUI não possui.

Solução: limpe o cache do executor da ferramenta; caminhos absolutos em linha no env.

Eu cansei de verificar isso manualmente

Então eu escrevi um pequeno CLI local que lê as configurações do cliente MCP e relata exatamente essas classes de falha — com a razão e uma sugestão de correção para cada:

pipx install git+https://github.com/lajiaojiang-ai/mcp-why.git
mcp-why                    # auto-descobrir configurações comuns do cliente
mcp-why --config path/to/claude_desktop_config.json

Exemplo de saída:

[ERROR] risky_server_name: O nome do servidor 'Home Assistant (ha-mcp)' contém parênteses ou colchetes
  por que: Alguns clientes silenciosamente descartam todas as ferramentas quando uma chave mcpServers contém parênteses.
  correção: Renomeie a chave para letras, números, hífen ou sublinhado apenas.

[WARNING] windows_npx: O servidor 'Home Assistant (ha-mcp)' inicia npx diretamente no Windows
  por que: Aplicativos GUI frequentemente falham ao iniciar npx a menos que envolto com cmd.exe /c.
  correção: Use {"command":"cmd","args":["/c","npx","-y","..."]}.

Há também um --probe opcional que envia apenas initialize + tools/list via stdio (ele nunca chama uma ferramenta, e não pode tocar seus verdadeiros endpoints — é um diagnóstico somente leitura contra a configuração + um handshake).

Repositório: https://github.com/lajiaojiang-ai/mcp-why

Limitações honestas

• v0.1 conhece seis classes de falha. Existem mais — envie problemas.
• É um diagnosticador de configuração. Se a configuração estiver boa e o servidor estiver quebrado, use o MCP Inspector — eles são complementares, não concorrentes.
• O comportamento do cliente muda rapidamente; uma regra que é verdadeira para uma versão do cliente pode suavizar na próxima.

Se isso te salvou de mais uma hora olhando para uma configuração que parece válida, esse é o objetivo. Dê uma estrela se for útil, abra um problema se estiver errado.