MCP Doctor

mcpdoctor

mcpdoctor é um CLI somente leitura para inspecionar endpoints MCP e x402.

Aponte para uma URL e obtenha um relatório PASS / FAIL / UNKNOWN:

• o documento de pagamento HTTP 402 — analisado nos locais conhecidos (cabeçalhos Payment-Required / X-Payment-Required / WWW-Authenticate ou o corpo da resposta), tanto nos formatos x402 v1 (accepts[]) quanto v2 (x402.accepts), com cada campo scheme / network / asset / amount / payTo verificado;
• os manifests de descoberta — se /.well-known/mcp/server.json e /.well-known/x402 estão acessíveis, com um SHA-256 de cada;
• um digest SHA-256 do corpo da resposta, além de latência e tamanho.

mcpdoctor não é um servidor MCP e não implementa o protocolo MCP. É o inspetor de endpoints que você executa antes de apontar um cliente MCP ou um comprador x402 para um endpoint — uma ferramenta de pré-verificação/depuração para infraestrutura de pagamento de agentes de IA. Zero dependências. Node ≥ 18. Nunca toca em chaves, nunca paga.

Instalação

npm install -g @eidonze/mcpdoctor    # or run without installing:
npx @eidonze/mcpdoctor inspect <url>

Uso

mcpdoctor inspect <url> [--method=GET|POST] [--format=json|markdown]

Opção	Padrão	Descrição
--method	GET	Verbo HTTP para a sondagem (POST envia {})
--format	markdown	json para relatórios legíveis por máquina / CI
--json	—	abreviação para --format=json

Códigos de saída: 0 PASS · 1 FAIL · 2 UNKNOWN (rede/timeout) · 3 erro de uso.

Exemplos reais (capturados em 2026-09-29, contra endpoints ao vivo)

Inspecionando um endpoint MCP gratuito (sem portão de pagamento) — a ferramenta relata o 200 em vez de um 402 e ainda verifica os manifests de descoberta:

{
  "endpoint": "https://agenttoll-receipts.app.workbuddy.host/mcp",
  "method": "POST",
  "finalStatus": "FAIL",
  "http": { "status": 200, "elapsedMs": 2830, "bodyBytes": 82,
            "bodySha256": "598dc097dcca1e573c742100863899c00724a021b421a5bb49952d49fec6b4f4" },
  "findings": [
    { "status": "FAIL", "code": "NO_402", "message": "Expected HTTP 402, received 200" }
  ],
  "metadata": [
    { "path": "/.well-known/mcp/server.json", "status": 200, "reachable": true }
  ]
}

Inspecionando o endpoint de demonstração oficial do x402 — ele retorna 402, mas envia um documento de pagamento que o mcpdoctor não consegue analisar, que é exatamente a classe de quebra silenciosa que este CLI existe para detectar:

{
  "endpoint": "https://x402.org/protected",
  "finalStatus": "FAIL",
  "http": { "status": 402 },
  "headers": { "paymentRequired": true },
  "findings": [
    { "status": "FAIL", "code": "NO_ACCEPTS",
      "message": "No recognizable payment requirement found" }
  ]
}

O que ele NÃO faz

• Sem sessão de protocolo MCP: sem initialize, sem tools/list — o mcpdoctor verifica o que um endpoint anuncia (documentos 402, manifests de descoberta), não um handshake MCP completo.
• Sem carteira, assinatura, liquidação ou tentativas. Somente pré-verificação somente leitura.
• PASS significa que o documento 402 observado tinha campos reconhecíveis e completos — não é uma certificação de segurança ou sucesso de pagamento.

Por quê

Nós mesmos fornecemos um serviço x402 (ReceiptRail) e encontramos todas as formas de um endpoint pago quebrar silenciosamente:

• um endpoint que valida o corpo da solicitação antes de retornar o desafio 402 é invisível para todo cliente x402 — eles só reagem a 402;
• documentos de pagamento chegam em quatro lugares diferentes e dois formatos diferentes; analisadores que só olham para um lugar relatam falhas falsas;
• cabeçalhos de dica do fornecedor sem accepts[] podem ocultar o documento de pagamento real.

Cada verificação no mcpdoctor corresponde a um modo de falha que realmente encontramos em produção.

Parte do conjunto de ferramentas Agent / Chain Evidence

Diagnósticos somente leitura para agentes de IA na Web3 — hub e docs · ReceiptRail (serviço MCP ao vivo) · npm: @eidonze/mcpdoctor

Licenciado sob MIT. Limitações conhecidas são documentadas, não ocultadas.