io.github.forgemeshlabs/x402-scan-mcp

x402-scan-mcp — the free x402 Endpoint Scanner

Is your paid endpoint actually payable by agents?

Shipping a 402 Payment Required response is not the same as shipping a correct one. A missing field in accepts[], a malformed Base64 envelope, or content that leaks for free when the payment gate is misconfigured all look fine in a browser and invisibly cost you every agent that would have paid.

x402-scan-mcp is the free, open-source x402 Endpoint Scanner — an MCP server that probes one or more x402 endpoints and reports whether an agent can actually discover, parse, and pay for them. The npm package is @forgemeshlabs/x402-scan-mcp.

No payment is ever sent. The scanner never supplies a PAYMENT-SIGNATURE, so it cannot authorize or settle a transaction — it only inspects the shape of the 402 challenge.

=== x402 Endpoint Scan: https://library.forgemesh.io/business-management ===
Reachable: true  HTTP: 402  Method: GET  (184ms)
402: true  Envelope: header  Valid: true  MPP: true
Grade: A
Findings:
  - Valid x402 envelope is advertised over both the classic PAYMENT-REQUIRED header
    and MPP's WWW-Authenticate: Payment header — maximally discoverable across agent
    payment stacks.

What it checks

• HTTP 402 status — does the route actually return 402 Payment Required, or does it 200/404/500 and go unnoticed by payment-aware agents?
• PAYMENT-REQUIRED envelope — is the header present, Base64-decodable, valid JSON, with a numeric x402Version and a non-empty accepts[]? Falls back to checking the response body for an x402Version field on endpoints that put the envelope there instead.
• Required payment fields — does every entry in accepts[] carry scheme, network, asset, payTo, and amount?
• MPP dual-stack — is the endpoint also discoverable via the WWW-Authenticate: Payment header, the MPP discovery path some agent stacks use instead of the classic header?
• Free-content leaks — does the route serve real content with a 200 when it should be gated behind 402?

Every result is graded A (valid envelope + MPP dual-stack), B (valid envelope, classic header only), C (402 but the envelope is missing or malformed), or F (not 402, unreachable, or serving paid content for free) — plus plain-English findings[] explaining what an agent sees and why it costs you traffic.

Install

Requires Node.js ≥ 20. Published on npm as @forgemeshlabs/x402-scan-mcp — no clone or build needed.

npm install -g @forgemeshlabs/x402-scan-mcp

Or skip the install entirely and run it with npx (recommended for MCP clients):

npx -y @forgemeshlabs/x402-scan-mcp

Claude Code

claude mcp add x402-scan -- npx -y @forgemeshlabs/x402-scan-mcp

Claude Desktop / Cursor / Windsurf (any MCP client)

{
  "mcpServers": {
    "x402-scan": {
      "command": "npx",
      "args": ["-y", "@forgemeshlabs/x402-scan-mcp"]
    }
  }
}

Development (from source)

Only needed if you're hacking on the scanner itself:

git clone https://github.com/forgemeshlabs/x402-scan-mcp
cd x402-scan-mcp
npm install && npm run build
claude mcp add x402-scan -- node /path/to/x402-scan-mcp/dist/index.js

Tools

Try it: "Scan my x402 route for a valid 402 challenge" · "Batch-scan these 5 endpoints and tell me which ones are broken" · "What did the August 2026 x402 health census find?"

CLI smoke test (from a source checkout)

npm run smoke -- https://your-endpoint.example.com

Beyond the free local scan

This MCP server is local-only and free: it never leaves your machine except to call the endpoint you point it at (and, for census_stats, ForgeMesh's own public stats endpoint). If you want more:

• Hosted, paid, server-side scan — POST https://x402.forgemesh.io/x402-endpoint-scan, $0.05 via x402. Useful when you want the probe to originate from a different network than yours, or you're calling it from an agent that already pays x402 for other tools.
• Browser tool — forgemesh.io/scan for a one-off scan with no MCP client or wallet needed.
• $5 full report with fixes — a deeper audit with ready-to-paste fixes for every failing check, at forgemesh.io/scan.

The August 2026 x402 Bazaar health census

census_stats bundles the headline numbers from ForgeMesh's own sweep of the x402 Bazaar catalog: 1,225 sellers probed, 74% healthy, 206 dead, 40 serving paid content for free, and only 15% MPP dual-stack. Full writeup: forgemesh.io/blog/x402-bazaar-health-census-august-2026.

Security

This scanner makes outbound requests to URLs you give it, so it is built to resist SSRF abuse:

• Scheme allow-list — only http/https; file:, ftp:, gopher:, data: etc. are rejected.
• Port allow-list — only 80, 443, 8080, and 8443. Any other explicit port is refused before any DNS lookup or network call.
• Local-hostname rejection — localhost, *.localhost, *.local, and *.internal are refused by name, before DNS resolution runs.
• Private-target blocking — after DNS resolution, requests to loopback, private (RFC 1918), link-local, CGNAT, reserved, multicast, and the cloud metadata address (169.254.169.254) are refused. IPv6 loopback/ULA/link-local and IPv4-mapped forms are covered too. If a hostname resolves to any private address, the scan is refused.
• Pinned-IP transport — the request dials the exact public IP that was validated, while TLS still verifies the original hostname. This closes the validate-then-connect DNS rebinding window.
• No redirect following — a 3xx response is reported as-is (status + Location, if any); the scanner never chases it. This matches how a strict agent client behaves and keeps the request count predictable.
• Bounded — at most 2 requests per scan_endpoint call (one GET, plus one POST retry only on 405), forgemesh-scan-mcp/0.1 UA, 8s timeout, 64KB body cap.
• Tested hardening — npm test covers unsafe URL rejection, private IP ranges, port allow-listing, and endpoint-scan grading against a local fixture server.

Deployment: stdio (local, per-user) is the safe default. A public HTTP deployment is a network-egress tool and must add authentication, per-client rate limiting, request logging, and an egress policy before exposure.

License

MIT — free for everyone. If the scanner found a broken 402, the fix is usually a one-line envelope correction.