MCP Doctor

mcpdoctor

mcpdoctor es una CLI de solo lectura para inspeccionar endpoints MCP y x402.

Apúntalo a una URL y obtén un informe PASS / FAIL / UNKNOWN:

• el documento de pago HTTP 402 — analizado desde las ubicaciones conocidas (cabeceras Payment-Required / X-Payment-Required / WWW-Authenticate o el cuerpo de la respuesta), tanto en los formatos x402 v1 (accepts[]) como v2 (x402.accepts), con cada campo scheme / network / asset / amount / payTo verificado;
• los manifiestos de descubrimiento — si /.well-known/mcp/server.json y /.well-known/x402 son accesibles, con un SHA-256 de cada uno;
• un resumen SHA-256 del cuerpo de la respuesta, además de latencia y tamaño.

mcpdoctor no es un servidor MCP y no implementa el protocolo MCP. Es el inspector de endpoints que ejecutas antes de apuntar un cliente MCP o un comprador x402 a un endpoint — una herramienta de preflight/depuración para la infraestructura de pagos de agentes de IA. Cero dependencias. Node ≥ 18. Nunca toca claves, nunca paga.

Instalación

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

Uso

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

Opción	Predeterminado	Descripción
--method	GET	Verbo HTTP para la sonda (POST envía {})
--format	markdown	json para informes legibles por máquina / CI
--json	—	abreviatura de --format=json

Códigos de salida: 0 PASS · 1 FAIL · 2 UNKNOWN (red/timeout) · 3 error de uso.

Ejemplos reales (capturados el 2026-09-29, contra endpoints en vivo)

Inspeccionando un endpoint MCP que es gratuito (sin pasarela de pago) — la herramienta informa el 200 en lugar de un 402, y aún así verifica los manifiestos de descubrimiento:

{
  "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 }
  ]
}

Inspeccionando el endpoint de demostración oficial de x402 — sí devuelve 402, pero incluye un documento de pago que mcpdoctor no puede analizar, que es exactamente la clase de fallo silencioso que esta 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" }
  ]
}

Lo que NO hace

• Sin sesión de protocolo MCP: sin initialize, sin tools/list — mcpdoctor verifica lo que un endpoint anuncia (documentos 402, manifiestos de descubrimiento), no un handshake MCP completo.
• Sin billetera, firma, liquidación ni reintentos. Solo preflight de solo lectura.
• PASS significa que el documento 402 observado tenía campos reconocibles y completos — no es una certificación de seguridad ni de éxito de pago.

Por qué

Nosotros mismos ofrecemos un servicio x402 (ReceiptRail) y hemos encontrado todas las formas en que un endpoint de pago puede fallar silenciosamente:

• un endpoint que valida el cuerpo de la solicitud antes de devolver el desafío 402 es invisible para todos los clientes x402 — solo reaccionan a 402;
• los documentos de pago llegan en cuatro lugares diferentes y en dos formatos diferentes; los analizadores que solo miran un lugar informan fallos falsos;
• las cabeceras de sugerencia del proveedor sin accepts[] pueden ocultar el documento de pago real.

Cada verificación en mcpdoctor corresponde a un modo de fallo que realmente encontramos en producción.

Parte del conjunto de herramientas Agent / Chain Evidence

Diagnósticos de solo lectura para agentes de IA en Web3 — hub y documentación · ReceiptRail (servicio MCP en vivo) · npm: @eidonze/mcpdoctor

Licencia MIT. Las limitaciones conocidas están documentadas, no ocultas.