Servidor MCP Mostra 'Desconectado'? Veja o que Está Acontecendo

Seu servidor MCP estava funcionando cinco minutos atrás. Agora, Claude Desktop, Claude Code ou Cursor apenas mostram "desconectado" sem rastreamento de pilha, sem número de linha, apenas um ponto de status vermelho.

A questão é a seguinte: os servidores MCP funcionam como um subprocesso do seu cliente de IA, não como um serviço remoto que você pode acessar com curl. Esse único fato explica quase todas as desconexões que você verá.

Na verdade, existem apenas 4 causas possíveis:

1. O processo nunca começou

Um caminho relativo como ./server.py funciona bem no seu terminal porque o diretório de trabalho do seu shell é a pasta do seu projeto. Seu cliente de IA é iniciado de outro lugar completamente, então esse caminho não resolve nada.

Mesma história com npx, python ou uv. Aplicativos GUI no macOS não herdam o PATH do seu shell, já que nunca carregam seu .zshrc ou .bash_profile.

Correção: use caminhos absolutos tanto para command quanto para args.

{
  "mcpServers": {
    "my-server": {
      "command": "/usr/local/bin/python3",
      "args": ["/Users/you/projects/my-server/server.py"]
    }
  }
}

Execute which python3 ou which node para obter o caminho real, não um shim de gerenciador de versões.

2. Poluição do stdout

Esse é um problema que atinge todo mundo pelo menos uma vez. Com o transporte stdio, o stdout é reservado inteiramente para mensagens JSON-RPC. Qualquer print(), qualquer biblioteca de registro que por padrão envia para stdout, corrompe o fluxo.

# Quebra seu servidor
print("Servidor iniciando...")

# Correto
import sys
print("Servidor iniciando...", file=sys.stderr)

// Quebra
console.log("Conectado ao banco de dados");

// Correto
console.error("Conectado ao banco de dados");

Funciona quando você executa manualmente, mas desconecta apenas através do cliente? Verifique suas dependências também, um ORM ou um banner de framework registrando no stdout fará o mesmo dano.

3. Problemas de caminho e ambiente

Aplicativos GUI são iniciados com um ambiente mínimo, não o que foi construído pelo seu perfil de shell. Se seu servidor lê uma chave de API ou URL de DB de uma variável de ambiente, você precisa declará-la explicitamente na configuração, mesmo que já esteja exportada no seu terminal.

{
  "mcpServers": {
    "my-server": {
      "command": "/usr/local/bin/python3",
      "args": ["/Users/you/projects/my-server/server.py"],
      "env": {
        "DATABASE_URL": "postgres://localhost/mydb",
        "API_KEY": "sua-chave-aqui"
      }
    }
  }
}

Sintoma a ser observado: o cliente mostra brevemente "conectando", depois muda para desconectado um segundo depois. Esse atraso geralmente significa que o processo começou, mas depois falhou devido a uma variável de ambiente ausente.

4. Incompatibilidade de transporte

Menos comum, mas vale a pena descartar para servidores remotos ou auto-hospedados. Sua configuração pode especificar uma url para HTTP Streamable quando seu servidor só se comunica via stdio, ou vice-versa. Parece idêntico a todas as outras causas à primeira vista, apenas um ponto vermelho sem explicação.

Como realmente depurá-lo

Evite adivinhações. Execute o comando exato da sua configuração diretamente em um terminal primeiro.

node /Users/you/projects/my-server/index.js

Se falhar aqui, é seu código, não o MCP.

Se funcionar bem de forma independente, teste com o MCP Inspector oficial:

npx @modelcontextprotocol/inspector node my-server.js

Isso abre uma interface de usuário no navegador mostrando o tráfego JSON-RPC bruto e permite que você chame cada ferramenta individualmente. Se funcionar no Inspector, mas ainda falhar no seu cliente, você restringiu a causa especificamente à configuração, caminho, variáveis de ambiente ou diretório de trabalho.

Eu escrevi uma análise completa com uma tabela específica para o cliente para Claude Desktop, Claude Code e Cursor, além de uma nota para Windows/WSL2, aqui:
🔗 https://devencyclopedia.com/blog/mcp-server-disconnected-fix

Também criei uma ferramenta gratuita para navegador que verifica seu mcp.json ou claude_desktop_config.json para esses erros exatos: MCPConfigCheck

Você encontrou uma causa de desconexão do MCP mais estranha que não está coberta aqui? Curioso para saber o que mais as pessoas encontraram.