402MCP/402mcp

The MCP server and open registry for HTTP 402 agent payments.
When an AI agent receives 402 Payment Required, 402MCP tells it which scheme
the server speaks (L402, x402 or MPP), what is being asked for, and exactly how
to pay and retry. When a developer is choosing how an agent should pay, or how an
API should charge agents, it recommends a rail from stated requirements. Behind
both sits an open registry of sourced, scored payment solutions.
Site: https://402mcp.org
Remote MCP endpoint: https://402mcp.org/api/v1/mcp (streamable HTTP)
npm: @402mcp/mcp (stdio)
Install guides: https://402mcp.org/docs#install
## Install
Claude Code:
bash
claude mcp add --transport http 402mcp https://402mcp.org/api/v1/mcp
Any stdio MCP client (Claude Desktop, Cursor, Windsurf and others):
json
"mcpServers": {
"402mcp": { "command": "npx", "args": ["-y", "@402mcp/mcp"] }
## MCP server
One transport-agnostic core (lib/mcp/) serves both the hosted endpoint and the
stdio package, so the two expose the same tools, resources and prompts.
| Tool | Purpose |
| decode402challenge | Decode a 402 response (L402 macaroon and BOLT 11 invoice, x402 v1/v2, MPP) into exact next steps and the retry header |
| recommendpaymentrail | Filter by role, asset, custody, infrastructure, network, scheme, MCP support and maturity; re-weight the criteria; explain every exclusion |
| search402solutions | Search the registry with filters |
| getsolution | One entry in full, with sources and code samples |
| getschemereference | Wire format of L402, x402 or MPP |
| probe402support | One GET to a public URL to see whether it speaks 402. Never pays |
| getbestpaymentsolution | The entry with the highest composite score |
Resources: 402mcp://registry, 402mcp://methodology,
402mcp://solutions/{id}, 402mcp://schemes/{scheme}. Prompts:
choosepaymentrail, handle402response. Every tool is annotated
readOnlyHint.
Safety. Everything in a 402 response is server-controlled, so the decoder
lists those fields in untrustedfields and never repeats their text as
instructions. It flags expired challenges and macaroons that commit to a
different payment hash than their invoice. The probe refuses private, loopback,
link-local and metadata addresses (including hostnames that resolve to them) and
non-web ports, and the hosted endpoint rate-limits it per client. No tool can
spend money.
## Machine interfaces
| Endpoint | Purpose |
| POST /api/v1/mcp | MCP (JSON-RPC 2.0, streamable HTTP) |
| POST /api/v1/decode | Decode a 402 response |
| GET /api/v1/recommend | Recommend a rail from requirements |
| GET /api/v1/probe?url= | Probe a URL for 402 support (rate limited) |
| GET /api/v1/solutions | Versioned list (?q=, ?id=, ?view=full) |
| GET /api/v1/registry | Canonical feed with ETag / 304 support |
| GET /api/v1/schemes/{scheme} | Wire format of L402, x402, MPP |
| GET /api/v1/status | Daily liveness of every entry's docs and website |
| GET /api/v1/changelog · /changelog.xml · /changelog | Changes and corrections |
| /schema/v1/registry.json · /schema/v1/solution.json | JSON Schemas (draft 2020-12) |
| /openapi.json | OpenAPI 3.1 |
| /llms.txt · /llms-full.txt | Plain-text indexes |
| /.well-known/402.json · api-catalog · mcp/server-card.json · agent-skills/ | Discovery |