# x402-list-mcp [Health: Active]

**Category:** 💰 Finance & Fintech  
**Repository:** https://github.com/mcccsm/x402-list-mcp  
**GitHub Stars:** 27  
**Views:** 4  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/x402-list-mcp-2

## Description
Read-only MCP server for the x402-list directory: discover x402 services and facilitator volume.

## Tools
Capabilities this server exposes over MCP:

- **x402_search_services** — Your first call when you do not know which x402 service exists for a job: it narrows a directory of 500+ listed services to candidates. Filter by free-text query, category, network, live status, and whether the last observed 402 envelope is signable by a standard x402 client; sort by newest, uptime, cheapest, or endpoints. Returns up to 100 compact summaries a page: price in decimal USD, uptime, status, verification. Then x402_get_service for the full record.
- **x402_get_service** — Call this once you hold a slug and are deciding whether to commit to that service: the full record behind a directory row. Live status, uptime over 24h/7d/30d/90d, average response time, networks and settlement asset, every priced endpoint, and the assessment block. include_series=true adds 90 daily points of on-chain volume and distinct buyers. Read the units map in the response: the per-endpoint price field is atomic token units, not dollars.
- **x402_find_best_service** — Call this when you have a need in words and want one service to call rather than a list to read: it is the free ranking step between searching and paying. Pass the need as q, plus any category, network, price cap or verification requirement, and get up to 20 ranked recommendations with the basis each one placed on. Ranking is mostly per-service reliability (live status, verification, uptime, response time), x402 compliance, and price in USD, with a small (about 10%) weight on measured on-chain settlement traction that can never dominate those three. The response carries ranking_version (currently 3), need_blind_ranking (true when no q was given, so the order is global quality rather than your need), and a units map holding every scoring caveat in full: the compliance cap, the pro-quota rule for shared payout addresses, renormalization, the $10 volume floor, and the single-buyer discount. Read units before comparing scores across generations.
- **x402_check_health** — Call this before you send a payment, or right after a call unexpectedly failed: is this service up right now. With no slug, the directory snapshot: five status counts across 500+ services (include_services=true attaches every row). With a slug: that service's status, its 24h/7d/30d/90d uptime windows, response time, consecutive failures, daily snapshots. No money fields.
- **x402_facilitator_volumes** — Call this when the question is about the rail rather than the service: which x402 facilitator actually settles money, and how much. Returns on-chain-verified settlement volume and transaction counts per facilitator for today (UTC), 7d, 30d and all-time, plus a verification flag ('on-chain' once volume has been observed on-chain, else 'listed'), across more than 30 facilitators. Optional daily timeseries (up to 90 days) and per-chain breakdown. Volume is decimal USD. Caveats: PER-FACILITATOR, never per-service; the *_24h fields cover today (UTC) so far, not a trailing 24 hours, and reset at 00:00 UTC, so prefer 7d.
- **x402_assess_services** — Call this when the free signals have run out: you hold 2 to 8 finalists from x402_search_services or x402_find_best_service, their stored fields do not separate them for YOUR stated need, and choosing wrong costs more than a quarter. It buys one fresh AI assessment reasoned against your question, not a cached grade; reading an already-computed assessment stays free via x402_get_service. Price: a one-time $0.25 USDC on Base, over two calls. Call once WITHOUT payment_signature_b64 to receive the x402 payment challenge verbatim (accepts[], amount, payTo, and a base64 PAYMENT-REQUIRED header); sign accepts[0] client-side with your own wallet; call again with the SAME question and services plus payment_signature_b64 to receive the report and a base64 PAYMENT-RESPONSE settlement receipt. This server holds no keys, never signs and never settles: it only relays the challenge. Optionally add probe { slug, endpoint_path? } to have one listed service paid and called for real and its answer analyzed: the challenge is then priced at $0.25 plus that endpoint price X, and the report gains a probe_report block with a verdict and truncated extracts, never the verbatim third-party body. When live probing is not armed the probe is ignored. Caveats: read the amount to sign from accepts[0].amount, never from a fixed figure, since a probe changes it; probe fees are non-refundable whatever the verdict; if the fresh run cannot be produced the server answers before settling, so you are never charged for nothing; there is no refund. Prices are US dollars.
- **x402_change_events** — Call this before you trust anything you cached about a service, and right after a payment failed for no obvious reason: the monitor's log of what moved under you. Returns payTo, price and 402-schema changes observed on listed services, most recent first, in exactly three event types (payto_changed, price_changed, schema_changed). Filter with service (the slug), type, and days (1 to 365, default 90). Caveats: prices here are atomic token amounts, never dollars, and every payTo is masked by design, so the feed reports THAT the payout address changed, never the address. Free and read-only.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "x402-list-mcp": {
    "command": "npx",
    "args": ["-y","x402-list-mcp"],
    "env": {
      "X402_LIST_BASE_URL": "",
      "X402_LIST_TIMEOUT_MS": "",
      "MCP_HTTP_PORT": "",
      "PORT": "",
      "MCP_ALLOWED_ORIGINS": "",
      "MCP_ALLOWED_HOSTS": ""
    }
  }
}
```

**Requires environment variables:** `X402_LIST_BASE_URL`, `X402_LIST_TIMEOUT_MS`, `MCP_HTTP_PORT`, `PORT`, `MCP_ALLOWED_ORIGINS`, `MCP_ALLOWED_HOSTS` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## What x402-list-mcp MCP server does

The x402-list-mcp MCP server gives AI agents access to the x402-list directory through seven MCP tools. Six tools are free and read-only. They cover service search, service details, ranked recommendations, health checks, facilitator settlement volumes, and observed service changes.

The seventh tool, `x402_assess_services`, provides a paid comparison of a shortlist for a stated need. It costs $0.25 USDC on Base through x402, before any optional live probe cost. The tool passes the payment challenge through to the client: it does not hold keys, sign payments, or settle transactions.

## How it works

The x402-list-mcp MCP server is a thin wrapper around the public x402-list REST API. Search can filter by query, category, network, status, and whether the latest observed payment envelope contains the EIP-712 domain fields needed for standard client signing. Service records include endpoints, USD pricing, uptime windows, supported networks, and settlement assets.

Recommendations are calculated by the API and return a ranking generation plus a units map describing the scoring details. Ranking emphasizes reliability, x402 compliance, and price, while on-chain service traction contributes a smaller weighting. Facilitator-volume results are a separate ecosystem-level signal and should not be treated as revenue for an individual service.

Change events report monitor observations for payment destination, price, or schema changes. Event prices are raw atomic token amounts rather than dollar values, and payout addresses are masked. The `*_24h` volume fields represent the current UTC day, not a rolling 24-hour period.

For an assessment, call the tool without `payment_signature_b64` to receive the x402 challenge. Sign it in the client, then retry with the signature. An optional probe can test one listed endpoint; its endpoint price is added to the $0.25 assessment fee and is non-refundable.

## Setup and configuration

Run the x402-list-mcp MCP server over stdio with:

```text
npx -y x402-list-mcp
```

A Claude Desktop or other generic MCP client can launch it with the `npx` command and the `-y` and `x402-list-mcp` arguments. HTTP mode is available by setting `MCP_HTTP_PORT`, then starting the process with `--http`, for example on port 3000. The hosted endpoint is `https://mcp.x402-list.com/mcp`, and `/healthz` provides a basic status response.

`X402_LIST_BASE_URL` changes the API host, while `X402_LIST_TIMEOUT_MS` sets the per-request timeout. In HTTP mode, `MCP_ALLOWED_ORIGINS` restricts CORS origins and `MCP_ALLOWED_HOSTS` enables DNS-rebinding protection for listed hosts. The API path automatically receives the `/api/v1` prefix.

## Limitations and notes

The package does not expose a local database or directory write operations. Monetary values are passed through as decimal USD values where the API defines them that way. Endpoint `pricing[].price` values are uint256 token amounts in atomic units, so they are not dollar prices; use `price_usd` for the dollar figure.

Facilitator volume is aggregated by facilitator and verified on-chain. Service traction is measured separately through recognized settlers and can be conservative or absent when attribution is unavailable. Shared payout addresses use a declared pro-quota volume convention, so that figure should not be read as directly observed revenue for one service.

Tool names use the `x402_*` namespace. Older names from the 0.4.x release are removed rather than aliased, so client allow lists and prompts must use the current names.

_Full upstream README: https://allmcps.com/mcp/x402-list-mcp-2/readme_