1. Timeout de conexão curto mata chamada longa

Se o servidor sobe um backend pesado na primeira chamada (navegador instrumentado, container, modelo), a fase de conexão pode levar um minuto. Um connect_timeout de 5 segundos derruba a sessão no meio da chamada, e a mensagem que chega não diz isso.

Regra: dimensione o timeout pela mínima observada do boot, não pelo tempo de resposta de uma chamada quente.

2. 401 que não é o servidor fora do ar

O app responde no health check, o MCP devolve 401. Não é queda: é o header da API key ausente na entrada do MCP. O erro aparece na tool, não na configuração — e você vai depurar o lugar errado.

Teste em duas camadas: (a) o app responde? (b) o header está na entrada do MCP? São falhas diferentes com a mesma cara.

3. Config lida no import é inerte

Você corrige o arquivo de configuração, reinicia só o servidor e continua falhando. Se a config foi lida no import do módulo, ela já está congelada em memória — a mudança só vale no próximo boot do processo que a leu. Leia no ponto de uso, ou reinicie quem importou.

4. Sessão morta no meio: outcome UNKNOWN

transport session expired … outcome UNKNOWN significa que o servidor reiniciou embaixo de você. A chamada não completou — e o “UNKNOWN” não é sucesso. Confirme pelo uptime do health check (alguns segundos = reiniciou), repita uma vez e, se repetir, reporte.

Repetir uma chamada que já deu erro definitivo queima o orçamento e esconde o bloqueio real.

Antes de dizer que está pronto

Verifique uma config nova com a chamada mais barata que existir (um ping) antes do trabalho real, e reverifique depois de qualquer restart. Um servidor MCP que responde ao ping e falha na primeira tool é um servidor que você nunca testou de ponta a ponta.

Ver a skill Ship Your MCP Server Ver todas as skills

Quer isso montado no seu projeto? Setup guiado a partir de R$ 1.500, com o primeiro ciclo rodado junto.