mcpdoctor

Read-only checks for MCP tool schemas and x402 payment endpoints. Use it before an agent client or buyer depends on an endpoint.

Find the right guide

• Public documentation site
• MCP schema checker
• x402 endpoint inspector
• MCP security CI
• Troubleshooting
• OAuth scope and current limits

Run it now

Check an MCP server without calling any tools:

npx @eidonze/[email protected] schema https://your-mcp-server.example/mcp --json

Check an x402 endpoint without paying:

npx @eidonze/[email protected] inspect https://your-api.example/paid --method=POST --json

Requires Node.js 18+. No API key or wallet is needed.

Example schema run against a live endpoint:

$ npx @eidonze/mcpdoctor schema https://your-mcp-server.example/mcp

MCP Tool Schema Report
- Status: FAIL
- Endpoint: https://your-mcp-server.example/mcp
- Protocol: 2025-06-18
- Tools: 12

- FAIL REQUIRED_PROPERTY_UNDEFINED: tools[3] requires undeclared property query
- WARN PROPERTY_DESCRIPTION_MISSING: tools[7].limit has no description

The exact same run against a healthy server prints Status: PASS and exits 0, so CI can gate on it.

Which command?

| Command | Checks | Does not do | |---|---|---| | schema | MCP initialize, tools/list, tool names, descriptions, and JSON schemas | Does not call tools or prove runtime behavior | | inspect | HTTP 402, x402 v1/v2 payment document, accepts[], discovery manifests, latency and response digest | Does not sign, pay, settle, retry, or verify delivery |

Exit codes are stable for automation: 0 PASS, 1 FAIL, 2 UNKNOWN/network error, 3 usage error.

GitHub Actions

Add a read-only check to pull requests:

name: MCP Trust Check
on: [pull_request]

jobs:
  mcp-trust:
    runs-on: ubuntu-latest
    steps:
      - uses: xka0085-byte/mcp-doctor@v1
        with:
          endpoint: https://your-mcp-server.example/mcp
          mode: schema
          format: markdown

Use mode: inspect for an x402 preflight. The action fails on FAIL or UNKNOWN by default; set fail-on: false for an informational check.

Starter template

Start a new MCP project with this check already wired in:

• Secure MCP Server Starter

The check is read-only and should target a public test endpoint. Do not place private keys or credentials in workflow inputs.

What the report means

PASS means the observed response matched the checks in this version. It is not a security audit, protocol certification, payment-success guarantee, or proof that an endpoint is safe. UNKNOWN means the endpoint could not be observed within the timeout or response-size limits.

Example schema failure:

FAIL REQUIRED_PROPERTY_UNDEFINED tools[0] requires undeclared property query

Example x402 failure:

FAIL NO_402 Expected HTTP 402, received 400

Why it exists

The checks come from failure modes observed while building ReceiptRail: body validation that prevents an x402 challenge, payment documents in multiple headers/body shapes, and vendor hint headers that can hide the real accepts[] document.

mcpdoctor is not an MCP server. It is an independent, read-only endpoint inspector. It is not affiliated with mcpdoctor.dev; verify the npm scope is @eidonze/mcpdoctor.

Feedback

Found a false positive or a protocol shape we should support? Open an issue. Include the command, redacted output, Node version, and whether the endpoint is MCP or x402. Never include tokens, payment signatures, or private URLs.

License

MIT