Por que sua configuração MCP continua expirando em 60 segundos (e como eu consertei no Windows)

Todo desenvolvedor enfrenta esse obstáculo: adicionar mais de 8 servidores MCP ao Claude Desktop (ou Cursor, ou VSCode) → ele gira por exatamente 60 segundos → X vermelho, "tempo esgotado." Isso acontece em toda máquina com recursos limitados. Meu laptop i5-7300HQ? Exemplo perfeito do problema.

Os tutoriais ignoram isso. Artigos da AWS/Finch ignoram completamente o Windows. A documentação do Docker não cobre isso. Mas o problema é real, e passei semanas diagnosticando cada modo de falha até consertá-los todos.

Documentei 6 modos de falha do MCP específicos do Windows que ninguém mais escreveu, e então construí um único gateway Docker que carrega mais de 150 ferramentas sem atingir o tempo limite. Toda vez.

Os 6 Verdadeiros Assassinos

1. BOM em claude_desktop_config.json

O que você vê: Você edita a configuração no PowerShell, salva, reinicia o Claude Desktop. Nada muda. Nenhuma mensagem de erro. Claude simplesmente ignora sua configuração completamente.

Por que isso acontece: O Out-File -Encoding UTF8 do PowerShell adiciona um BOM invisível de 3 bytes (byte order mark) no início do arquivo. O parser JSON do Claude engasga com esses bytes sem te avisar.

Como verificar:

$bytes = [System.IO.File]::ReadAllBytes("$env:APPDATA\Claude\claude_desktop_config.json")
if ($bytes[0] -eq 0xEF -and $bytes[1] -eq 0xBB -and $bytes[2] -eq 0xBF) {
    Write-Host "BOM detectado — este é o seu problema"
}

A solução: Sempre escreva a configuração com UTF-8 sem BOM:

[System.IO.File]::WriteAllText(
    "$env:APPDATA\Claude\claude_desktop_config.json",
    $content,
    (New-Object System.Text.UTF8Encoding($false))  # $false = sem BOM
)

2. %USERPROFILE% Não Expande

O que você vê: Sua configuração faz referência a %USERPROFILE%\some\path e o servidor nunca inicia. Nenhum erro — apenas silêncio.

Por que isso acontece: O Claude Desktop não expande variáveis de ambiente do Windows na configuração JSON. Ele lê %USERPROFILE% como uma string literal e tenta encontrar um diretório com sinais de porcentagem no nome.

A solução: Codifique caminhos absolutos em todos os lugares. Sem exceções.

"command": "C:\\Users\\puddi\\AppData\\Local\\Programs\\node.exe"

Não:

"command": "%USERPROFILE%\\AppData\\Local\\Programs\\node.exe"

3. docker.exe Precisa do Caminho Absoluto Completo

O que você vê: A configuração parece correta, o Docker está rodando, mas o servidor MCP não inicia.

Por que isso acontece: O Claude Desktop inicia processos filhos sem herdar o PATH do sistema. Portanto, "command": "docker" ou até mesmo "command": "docker.exe" falham — ele não consegue encontrar o binário.

A solução: Use o caminho completo para docker.exe:

"command": "C:\\Program Files\\Docker\\Docker\\resources\\bin\\docker.exe"

Toda vez. Não confie no PATH.

4. Mismatch entre Pipe Nomeado do Docker e Socket Unix

O que você vê: Os comandos do Docker funcionam bem no seu terminal, mas os servidores MCP que precisam de acesso ao Docker dentro dos contêineres recebem erros de conexão.

Por que isso acontece: O Docker Desktop do Windows funciona através de um pipe nomeado (//./pipe/docker_engine), mas os contêineres esperam o socket Unix em /var/run/docker.sock. Pipes nomeados são instáveis quando passados para contêineres via WSL2.

A solução: Monte o socket Unix diretamente. O backend WSL2 do Docker Desktop o expõe:

"-v", "/var/run/docker.sock:/var/run/docker.sock"

Não use o pipe nomeado do Windows. O socket Unix é estável através da integração WSL2.

5. O Bloat de Inicialização Fria Mata o Orçamento de 60 Segundos

O que você vê: Um servidor funciona bem após a primeira carga, mas em uma inicialização fresca (inicialização a frio, após um Docker prune, ou primeira instalação), ele atinge o tempo limite.