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](https://x402-list.com) 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, read-only wrapper** over the public x402-list HTTP JSON API. It holds no keys, touches no database, and makes no writes. 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:

```json
{ "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; 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. 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. |
| `check_health` | Live status, directory-wide or per service (uptime snapshots, consecutive failures). |
| `get_facilitator_volumes` | Per-facilitator on-chain-verified settlement volume (24h/7d/30d/all) in USD, tx counts, and an on-chain vs listed flag. |

## 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