mcccsm/x402-list-mcp

Discover x402 payment APIs, check uptime and pricing, and inspect on-chain-verified settlement volume per facilitator through MCP.
What is x402-list
x402-list is a directory of services that accept x402 (HTTP 402 stablecoin) payments. It monitors listed services for uptime, response time and status, and measures facilitator settlement volume on-chain.
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. It exposes the directory to AI agents through the Model Context Protocol as seven tools: six are free and read-only, and the seventh, x402_assess_services, is the only paid one, a pass-through that relays an x402 payment challenge you sign yourself client-side (the package never holds keys, never signs, and never settles).
Install and quick start
Connect to the hosted server at https://mcp.x402-list.com/mcp using Streamable HTTP, or run the npm package locally over stdio. Local use requires Node.js 20 or newer and npm; the hosted connection needs no local Node.js installation.
Claude Code
Connect to the hosted server:
Or use the local package instead:
Choose one transport. See the Claude Code MCP documentation for configuration scopes.
Cursor
Add the hosted server to Cursor, then confirm the installation in Cursor.
The install link encodes the same configuration as this manual entry in .cursor/mcp.json (project) or ~/.cursor/mcp.json (global):
See the Cursor MCP documentation and install-link format.
VS Code
Add this entry to .vscode/mcp.json in your project, then start the server from the editor and use it in Copilot agent mode:
See the VS Code MCP documentation for other configuration locations.
Codex
Add the hosted server with the Codex CLI:
Or add this entry to ~/.codex/config.toml; the CLI and IDE extension share this configuration:
See the Codex MCP documentation.
Claude Desktop and other local stdio clients
Add this entry to claude_desktop_config.json, or the equivalent configuration for your stdio client, and restart the client:
See the local MCP connection guide for the Claude Desktop configuration file location.
The client launches the same command you can run in a terminal:
Self-host Streamable HTTP
To run your own HTTP instance in a POSIX shell:
Connect your client to http://localhost:3000/mcp. The health probe at http://localhost:3000/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 |
| --- | --- |
| x402_search_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. |
| x402_get_service | Full detail for one service by slug: endpoints, per-endpoint USD pricing, uptime windows, networks, settlement asset. |
| x402_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 that can never dominate those three. Read the answer's ranking_version to identify its scoring generation (see below), and its units map for scoring caveats. |