x402-list-mcp

x402-list-mcp

MCP server for x402-list: discover x402 payment services and on-chain-verified facilitator settlement volume.

What is x402-list

x402-list is the directory of services that accept x402 (HTTP 402 stablecoin) payments. Its distinctive, defensible data is on-chain-verified settlement volume per facilitator, not self-reported numbers. Listed services are continuously health-monitored (uptime, response time, status).

This package is a thin wrapper over the public x402-list HTTP JSON API. It holds no keys, touches no database, and makes no writes to the directory. Every tool but one is read-only; the single paid tool, assess_services, only relays an x402 payment challenge that you sign yourself client-side (the package never holds keys, never signs, and never settles). It exposes the directory to AI agents through the Model Context Protocol.

Install and quick start

stdio (local MCP clients)

npx -y x402-list-mcp

Claude Desktop / generic MCP client config:

{ "mcpServers": { "x402-list": { "command": "npx", "args": ["-y", "x402-list-mcp"] } } }

Hosted HTTP (Streamable HTTP transport)

MCP_HTTP_PORT=3000 npx -y x402-list-mcp --http

Hosted endpoint: https://mcp.x402-list.com/mcp. Health probe: GET /healthz returns {"status":"ok"}.

Environment variables

Variable	Default	Purpose
X402_LIST_BASE_URL	https://x402-list.com	API base URL. The /api/v1 prefix is appended automatically.
X402_LIST_TIMEOUT_MS	15000	Per-request timeout in milliseconds.
MCP_HTTP_PORT / PORT	3000	HTTP port. Setting MCP_HTTP_PORT selects HTTP transport.
MCP_ALLOWED_ORIGINS	(empty, permissive)	Comma list of allowed CORS origins for HTTP mode.
MCP_ALLOWED_HOSTS	(empty, off)	Comma list that enables DNS-rebinding protection in HTTP mode.

Tools

Tool	What it does
search_x402_services	Search and filter the directory by query, category, network, status, and signable (whether the last observed 402 envelope carries the EIP-712 domain parameters a standard x402 client needs in order to sign); sort by newest/uptime/cheapest/endpoints.
get_service	Full detail for one service by slug: endpoints, per-endpoint USD pricing, uptime windows, networks, settlement asset.
find_best_service	Ranked recommendation for a need, computed server-side (GET /api/v1/best). Ranks mostly by reliability, x402 compliance and price (status, verified, uptime, response time, USD price), with a small (~10%) weight on per-service on-chain traction; shared-payout and unmeasured-network services stay neutral. The compliance term is capped at 0.6 (the floor of the C band) when at least one EVM route is missing the EIP-712 domain parameters a standard x402 client needs in order to sign, which is why ranking_version is now 2.
check_health	Live status, directory-wide or per service (uptime snapshots, consecutive failures).
get_facilitator_volumes	Per-facilitator on-chain-verified settlement volume (today UTC/7d/30d/all) in USD, tx counts, and an on-chain vs listed flag. The *_24h fields cover today (UTC) so far, not a trailing 24-hour window.
assess_services	Paid ($0.25 USDC on Base, x402). Fresh on-demand AI comparison of a shortlist of listed services for a stated need. Pass-through: it never holds keys, never signs, and never settles. Call without payment_signature_b64 to get the x402 challenge verbatim, sign it client-side, then retry with the signature to get the report. Optionally add a probe target { slug, endpoint_path? } to also test one listed service live: the price becomes $0.25 plus that endpoint price X (non-refundable), and the report gains a probe_report block with a verdict and truncated extracts, never the verbatim third-party body.

Units note

All monetary values are decimal US dollars and are passed through verbatim. There is no cents conversion anywhere. The per-endpoint pricing[].price field is a raw atomic on-chain token amount (a uint256 string), not dollars; only price_usd is the dollar figure.

Honesty note

Two different on-chain volume signals; do not conflate them. Facilitator volume (get_facilitator_volumes) is the ecosystem headline, aggregated per facilitator. Per-service traction (the traction block on each service, weighed at ~10% inside find_best_service) is settlement measured over a service's own payTo via recognized settlers - a deliberate conservative undercount, not an estimate: unattributed settlements are left out, never scaled up. A service whose payTo is shared across services (operator-level volume, shared_payout: true) or that sits on a network not yet measured carries no per-service figure and stays neutral in the ranking; never read shared or unmeasured volume as one service's revenue. To ask "which facilitators have real on-chain volume", use get_facilitator_volumes and read the verification flag.

Source

The source code is not public yet. This package is a thin read-only wrapper over the public x402-list REST API, documented at https://x402-list.com/api.

License

MIT