x402-list is a directory of services that accept x402 (HTTP 402 stablecoin) payments. It monitors the uptime, response time, and status of listed services, and measures facilitator settlement volume on-chain. x402-list-mcp is the MCP server wrapper for this directory, letting AI agents access this information through the Model Context Protocol.
Purpose This package is used to discover x402 payment APIs, check uptime and pricing, and view on-chain-verified settlement volume by facilitator via MCP. It is a lightweight wrapper around the public x402-list HTTP JSON API: it holds no keys, touches no database, and writes nothing to the directory.
Main capabilities It exposes seven tools to AI agents via MCP: six of them are free and read-only, and the seventh, x402_assess_services, is the only paid tool. It is a pass-through that relays the x402 payment challenge you sign yourself on the client side; the package itself never holds keys, never signs, and never settles. Regarding scoring, x402_find_best_service returns the scoring generation in ranking_version, and scores can only be compared within the same generation. Generation 2 caps the compliance item at 0.6, the lower bound of grade C, when it observes that at least one EVM route for a service lacks the EIP-712 domain parameters (extra.name, extra.version) required for standard x402 client-signed payments; this is a fact about the on-wire envelope, not a judgment on the service's own value. Generation 3 adds anti-gaming rules to the traction item: the absolute 30-day settlement volume floor is $10, and below the floor this item scores 0, because volume below the floor is indistinguishable from dust and should not affect rankings; when a single buyer contributes all settlement volume, concentrated payments are discounted, reducing the traction item by up to half, because one buyer is just one relationship, not the broad demand this item is meant to reward; services that do not publish a mappable payTo now score 0 on this item instead of having the weight normalized away, so hiding the payout address is no longer better than having a measurable address. All amounts are decimal dollars and are passed through as-is, with no cent-unit conversion. The pricing[].price field for each endpoint is the raw atomic on-chain token amount (a uint256 string), not dollars; only price_usd is a dollar figure. Do not confuse the two on-chain volume signals: facilitator volume (x402_facilitator_volumes) is the ecosystem headline, aggregated by facilitator; per-service traction (the traction block on each service, weighted about 10% in x402_find_best_service) is settlement volume measured to the service's own payTo through recognized settlers, and is a deliberately conservative underestimate rather than an estimate: unattributed settlements are excluded and never inflated. When a payTo is shared by multiple services (shared_payout: true), only settlement volume is attributed proportionally—operator-level volume on that address is split among the services sharing that address, which is a declarative convention rather than a separately observed metric, while transaction counts and unique buyers remain full operator-level integers; if a service's network has not yet been measured, or probing of a shared payout member keeps failing, then no traction item is included at all, and the remaining weights are renormalized over it. Never read shared, proportional, or unmeasured volume as a single service's revenue. To ask "which facilitators have real on-chain volume," use x402_facilitator_volumes and read the verification flag.
Usage Connect to the hosted server using Streamable HTTP https://mcp.x402-list.com/mcp，或本地通过 Run the npm package via stdio. Local use requires Node.js 20 or higher and npm; hosted connections do not require a local Node.js installation. Choose a transport method. The hosted server can be added to Cursor: the configuration corresponding to the installation link is the same as the manual entry in .cursor/mcp.json (project) or ~/.cursor/mcp.json (global). VS Code: add the corresponding entry to .vscode/mcp.json in the project, then start the server in the editor and use it in Copilot agent mode. Codex: add the hosted server with the Codex CLI, or add the entry to ~/.codex/config.toml; the CLI and IDE extension share this configuration. Claude Desktop and other local stdio clients: add the entry to claude_desktop_config.json or the equivalent stdio client configuration, then restart the client; the client will start the same command you run in the terminal. Self-hosted Streamable HTTP: run your own HTTP instance in a POSIX shell, and the client connects http://localhost:3000/mcp，健康探针 http://localhost:3000/healthz returns {"status":"ok"}.
Use cases Suitable for developers and agent builders who need to let AI agents query the x402 payment service directory, compare service prices and uptime, and check facilitator settlement volume.
Limitations The free tools are read-only; the paid tools only pass through the payment challenge signed by the client, and the package does not hold keys, sign, or settle. Running locally requires Node.js 20+ and npm. The specific environment variables, the original configuration commands, and complete examples of various configuration files are mentioned only as placeholders in the materials, and the specific content is not yet provided.
