Quatro Armadilhas na Verificação de Saúde do MCP: O Que Quebrou Meus Lotes Noturnos

Um servidor MCP morrendo às 2 da manhã costumava significar acordar com um log cheio de connection refused e nenhum trabalho feito. Construir um hook de verificação de saúde que registra falhas fora da janela de contexto resolveu isso — meus lotes noturnos não foram interrompidos por uma queda do MCP desde então.

Por Que Este Mecanismo Funciona

O Que Aconteceu Quando um Servidor MCP Caiu

Quando comecei a automatizar com Claude Code, havia um modo de falha que eu odiava mais do que qualquer outro: um trabalho em lote iniciado à noite, parado por um tempo limite do servidor MCP. Eu acordava com uma pilha de logs de connection refused e nada avançado desde a noite anterior. Para a automação de postagens do SNS, isso é suportável, mas na vez em que parou uma geração de entregáveis para um cliente, eu realmente entrei em pânico.

O MCP é o mecanismo que permite que o Claude Code use operações de navegador, consultas de banco de dados, chamadas de API externas, e assim por diante como ferramentas. Do lado do Claude, parece apenas chamar uma ferramenta chamada algo como mcp__obsidian__search, mas por baixo, a comunicação com um processo local ou um servidor HTTP remoto está em execução. Quando esse servidor para de responder por qualquer motivo, o Claude Code retorna a chamada da ferramenta como um erro e todo o fluxo da sessão fica travado.

O problema não era apenas "por que parou". Havia casos em que foi interrompido por um 429 (limite de taxa), mas re-chamava 30 segundos depois → outro 429 → parava novamente, em um loop infinito. Também havia casos em que um 503 (serviço temporariamente indisponível) era julgado da mesma forma que um 401 (autenticação expirada), executando desnecessariamente um fluxo de re-autenticação. A menos que você varie a estratégia por código de status, não importa quão rápido um modelo você use — é desperdiçado.

A Essência de Corrigir o "Ambiente" em vez do "Trabalho"

Mantendo um ambiente autônomo com receita de ¥1,2M/mês, o que percebi é que o tempo gasto em "mecanismos que impedem que as coisas parem" tem um ROI a longo prazo maior do que o código adicionado para aumentar os ganhos.

De volta a ¥600K/mês, eu pensava "mais tarefas significam mais ganhos". Depois de ser demitido e cair para zero, minha forma de pensar mudou enquanto reconstruía tudo do zero. Adicionar tarefas não ajuda se o ambiente é instável — a taxa de transferência atinge um teto. Por outro lado, resolver um único problema de nível de infraestrutura aumenta a taxa de conclusão em todas as tarefas existentes.

A verificação de saúde do MCP é o exemplo clássico disso. Ao conectar ~/.claude/scripts/hooks/mcp-health-check.js em um hook, uma sondagem HTTP é executada antes que o Claude Code chame uma ferramenta, e dependendo do status da resposta, ele despacha para "bloquear imediatamente", "tentar novamente após espera" ou "executar um comando de reconexão e re-sondar". O veredicto é persistido em ~/.claude/mcp-health-cache.json, então mesmo quando o contexto é compactado, o registro de saúde é mantido.

Por Que o Cache Conta Como uma "Medida de Compactação de Contexto"

Quando uma sessão do Claude Code roda por um longo tempo, o histórico da conversa é compactado. Mesmo que houvesse informações no passado dizendo "este servidor estava fora do ar", isso não sobrevive ao contexto pós-compactação. O resultado é desperdício: tentando repetidamente chamadas de ferramentas contra um servidor já conhecido como não saudável, e recebendo um erro a cada vez.

Um cache baseado em arquivo é independente do contexto. ~/.claude/mcp-health-cache.json não desaparece não importa quanto o sessão seja compactada. Quando o hook de verificação de saúde é executado na próxima vez, ele carrega o estado anterior do arquivo, e até que nextRetryAt tenha passado, ele bloqueia imediatamente sem nem mesmo re-sondar. A ideia de manter o estado fora da janela de contexto é o que importa fundamentalmente.

Conceitos Errôneos Comuns

Algumas pessoas pensam: "por que não apenas fazer o tratamento de erros no prompt do Claude?" Eu realmente tentei. Um prompt de sistema dizendo "se esta ferramenta der erro, tente outra abordagem" funciona razoavelmente bem para um erro isolado. Mas em uma situação onde o servidor MCP está fora do ar e as falhas acontecem uma após a outra, o modelo consome um grande número de tokens tentando. E na próxima vez, ele volta a chamar o mesmo servidor. Escrever o fato de que "o servidor está morto" fora do contexto e bloquear no nível do hook é muito mais limpo.

Outro conceito errôneo comum é "as próprias configurações de repetição do MCP são suficientes". O protocolo MCP tem repetições de camada de transporte, mas não tem recurso para ler códigos de status e mudar de estratégia. 429 e 503 exigem diferentes durações de espera, e 401/403 são casos que precisam de re-autenticação em vez de uma repetição. Implementar esse despacho na camada de aplicação é para isso que serve este hook.

O Fluxo Geral

Quando o Hook Intervém

mcp-health-check.js responde a dois tipos de eventos de hook do Claude Code. Está escrito literalmente no comentário no topo do código (linhas 7–12).

- PreToolUse: sondar a saúde do servidor MCP antes da execução da ferramenta MCP
- PostToolUseFailure: marcar servidores não saudáveis, tentar reconexão e re-sondar

PreToolUse é chamado antes da execução da ferramenta. Aqui ele dispara uma sondagem, verifica se o servidor está vivo e decide se permite a execução ou bloqueia com o código de saída 2. PostToolUseFailure é chamado após uma ferramenta retornar um erro. Ele analisa o texto do erro para identificar o padrão de falha, marca o servidor como não saudável e tenta uma reconexão.

Diagrama de Fluxo Completo

Claude Code が mcp__* ツールを呼ぶ
        │
        ▼ PreToolUse フック起動
┌──────────────────────────────────────────────────────┐
│            mcp-health-check.js                       │
│                                                      │
│  ① mcp-health-cache.json を読む                      │
│     status=healthy かつ expiresAt が未来？            │
│     YES ─────────────────────────────────────────→  │ exit 0
│     NO  ↓                                            │ （ツール実行へ）
│                                                      │
│  ② nextRetryAt が未来（unhealthy クールダウン中）？   │
│     YES → ブロック ──────────────────────────────→  │ exit 2
│     NO  ↓                                            │ （ツールをスキップ）
│                                                      │
│  ③ プローブ実行                                       │
│     HTTPサーバー → GET リクエスト（5秒タイムアウト）  │
│     stdioサーバー → プロセス起動（5秒生存確認）       │
│                                                      │
│     レスポンスのステータスコード判定                   │
│     ┌──────────────────────────────────────────┐    │
│     │ ECONNREFUSED / ENOTFOUND / タイムアウト   │──→ │
│     │  → 即 markUnhealthy & exit 2             │    │
│     ├──────────────────────────────────────────┤    │
│     │ 401 / 403 / 429 / 503                    │──→ │
│     │  → reconnect コマンドを実行               │    │
│     │  → 成功すれば再プローブ                   │    │
│     │  → 再プローブ OK → markHealthy & exit 0  │    │
│     │  → 再プローブ NG → markUnhealthy & exit 2│    │
│     ├──────────────────────────────────────────┤    │
│     │ 200 系 / 400 / 401 / 403 / 405 / 406    │    │
│     │（"到達できた"証明として healthy 扱い）    │──→ │ exit 0
│     └──────────────────────────────────────────┘    │
│                                                      │
│  ④ 状態を mcp-health-cache.json に書き出す            │
└──────────────────────────────────────────────────────┘
        │
        ▼ ツール実行後にエラーが出た場合
┌──────────────────────────────────────────────────────┐
│ PostToolUseFailure フック                             │
│   エラーテキストを FAILURE_PATTERNS と照合            │
│   failureCode 特定 → markUnhealthy → reconnect試行  │
│   → 再プローブ OK なら markHealthy                   │
└──────────────────────────────────────────────────────┘