X402 Scan MCP

What x402-scan-mcp does

The x402-scan-mcp MCP server examines whether an HTTP endpoint presents a usable x402 payment challenge. It is intended for developers operating paid APIs, feeds, or other routes that should return 402 Payment Required until an agent pays.

A scan evaluates the response status, finds the payment envelope in the PAYMENT-REQUIRED header or response body, and checks whether the encoded value can be decoded into valid JSON. It also verifies that the envelope has a numeric x402Version, a non-empty accepts[] list, and the required scheme, network, asset, payTo, and amount fields on each payment option.

Results include an A–F grade and plain-language findings. The grading distinguishes a valid classic envelope with MPP discovery from a classic-only result, malformed or missing payment data, unreachable routes, incorrect statuses, and routes that return paid content without payment.

How it works

The server exposes MCP tools that make outbound requests to the URLs supplied by the user. scan_endpoint probes one URL, while scan_batch runs the same check sequentially for up to 10 URLs and produces a short aggregate count. census_stats retrieves live ForgeMesh catalog statistics and reports headline figures from the August 2026 x402 Bazaar health census.

The scanner never includes a PAYMENT-SIGNATURE, so it cannot authorize or settle a transaction. Redirects are reported rather than followed. A scan normally makes one GET request and may make one POST retry when the endpoint responds with 405; requests have an 8-second timeout and a 64 KB body limit.

Setup and configuration

Install Node.js 20 or newer, then run the published package through npx or install it globally with npm. For MCP clients, the recommended command is npx -y @forgemeshlabs/x402-scan-mcp. Claude Code can register that command directly, while Claude Desktop, Cursor, and Windsurf can use an MCP server entry with npx as the command and the package arguments.

The x402-scan-mcp MCP server uses stdio by default and does not require environment variables, an API key, a wallet, or a source checkout. A source build is available for development with the repository's npm install and build commands. A CLI smoke test can scan a URL from a source checkout.

Tools and capabilities

• scan_endpoint: checks one endpoint's status, envelope location and validity, payment-option summary, MPP support, grade, and findings.
• scan_batch: checks up to 10 URLs sequentially and summarizes healthy, unavailable, and malformed results.
• census_stats: returns ForgeMesh catalog statistics and the published census headline numbers.

The x402-scan-mcp MCP server also applies SSRF protections. Only http and https schemes are accepted, and explicit ports are limited to 80, 443, 8080, and 8443. Local names and private, loopback, link-local, reserved, multicast, CGNAT, and cloud-metadata destinations are rejected after DNS validation. The request connects to the validated public IP while retaining hostname verification for TLS.

Limitations and notes

This is a local probe: apart from the endpoint being tested, census_stats may contact ForgeMesh's public statistics endpoint. It does not perform a payment or verify settlement. The scanner reports a redirect without inspecting the destination, and it cannot test endpoints blocked by its scheme, port, hostname, or destination policies.

The hosted ForgeMesh scan and browser tool are separate services. A public HTTP deployment of this MCP server should add authentication, per-client rate limits, request logging, and an egress policy before exposure. The package is distributed under the MIT license.