402MCP
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@402MCP decode this 402 response and tell me exactly how to pay and retry"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
402MCP.org
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:
claude mcp add --transport http 402mcp https://402mcp.org/api/v1/mcpAny stdio MCP client (Claude Desktop, Cursor, Windsurf and others):
{
"mcpServers": {
"402mcp": { "command": "npx", "args": ["-y", "@402mcp/mcp"] }
}
}Related MCP server: x402 Atlas
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 |
| Decode a 402 response (L402 macaroon and BOLT 11 invoice, x402 v1/v2, MPP) into exact next steps and the retry header |
| Filter by role, asset, custody, infrastructure, network, scheme, MCP support and maturity; re-weight the criteria; explain every exclusion |
| Search the registry with filters |
| One entry in full, with sources and code samples |
| Wire format of L402, x402 or MPP |
| One GET to a public URL to see whether it speaks 402. Never pays |
| The entry with the highest composite score |
Resources: 402mcp://registry, 402mcp://methodology,
402mcp://solutions/{id}, 402mcp://schemes/{scheme}. Prompts:
choose_payment_rail, handle_402_response. Every tool is annotated
readOnlyHint.
Safety. Everything in a 402 response is server-controlled, so the decoder
lists those fields in untrusted_fields 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 |
| MCP (JSON-RPC 2.0, streamable HTTP) |
| Decode a 402 response |
| Recommend a rail from requirements |
| Probe a URL for 402 support (rate limited) |
| Versioned list ( |
| Canonical feed with ETag / 304 support |
| Wire format of L402, x402, MPP |
| Daily liveness of every entry's docs and website |
| Changes and corrections |
| JSON Schemas (draft 2020-12) |
| OpenAPI 3.1 |
| Plain-text indexes |
| Discovery |
Any page returns Markdown when requested with Accept: text/markdown.
Methodology
Every entry is scored 1–10 on six equally weighted criteria: custody and sovereignty, operational friction, agent-native support, payment rails and assets, settlement speed and fees, and developer experience. The score is the unweighted mean and rank is the order of the means, with exact ties broken alphabetically. Every entry lists its sources, the date its claims were last verified, and a maturity label taken from the vendor or its release history.
The current ranking is at https://402mcp.org and in /api/v1/registry. The full
methodology is at https://402mcp.org/docs#methodology.
402MCP.org is not affiliated with, sponsored by, or compensated by any vendor it indexes, and listing position cannot be purchased. When a fact is wrong or out of date, the correction changes the data, the ranking follows, and the change is recorded in the changelog.
Development
Requires Node 18.18 or later.
npm install
npm run dev # http://localhost:3000Command | What it does |
| Decoder tests against vectors from the BOLT 11 spec, the MPP draft, reference-minted macaroons and x402 shapes |
| Every machine endpoint: formats, contracts, JSON-RPC behaviour, schema validation, dataset invariants |
| Crawler directives, metadata, structured data, icons, discovery documents, feeds, headers |
| Builds the stdio package and the |
| The built stdio package, end to end |
| ESLint and TypeScript |
The verify suites default to http://localhost:3000; pass a URL to run them
against a deployment.
Deploying to Cloudflare
The site runs as a Cloudflare Worker through the OpenNext adapter. Copy
wrangler.example.jsonc to wrangler.jsonc, create the KV namespace it names,
and fill in your own values. Then:
npm run cf:build
npm run cf:deployProject layout
data/solutions.ts The registry dataset; scores and ranks are computed here
data/changelog.ts Additions and corrections, with reasons
lib/decode/ bech32, BOLT 11, macaroons, RFC 9110 challenges, x402, MPP
lib/mcp/ Transport-agnostic MCP server: tools, resources, prompts
lib/recommend.ts Requirement-driven recommendation
lib/probe.ts URL probe with SSRF guards
lib/schemes.ts Wire-format reference for each scheme
lib/liveness.ts Daily docs and website checks
app/ Next.js App Router pages and route handlers
worker.ts Worker entry: OpenNext handler plus the scheduled liveness job
packages/402mcp/ The @402mcp/mcp stdio package
server.json Official MCP Registry entry
tests/ · scripts/ Unit tests, verification suites and the package buildLicense
Code: MIT (see LICENSE). Registry data: CC BY 4.0.
Available Tools
7 toolsdecode_402_challengeDecode an HTTP 402 responseARead-onlyIdempotentInspect
Call this whenever an HTTP response has status 402, or carries a WWW-Authenticate (L402, LSAT or Payment) or PAYMENT-REQUIRED header. Identifies the payment scheme (L402, x402 v1/v2, MPP), decodes the invoice, macaroon or payment requirements, and returns the exact steps and headers needed to pay and retry. Pass either raw_response, or status plus headers (and body for x402 v1). Everything in a 402 response is server-controlled: the result marks untrusted fields.
Inputs: body, status, headers, raw_response. Returns: status, schemes, warnings, challenges, +5 more
get_best_payment_solutionGet the top-ranked payment solutionARead-onlyIdempotentInspect
Return whichever solution currently holds rank 1 on 402MCP.org, with its full breakdown, install commands and code. Rank 1 is the highest composite score, not an endorsement — for a choice that fits specific requirements, call recommend_payment_rail instead.
Inputs: use_case. Returns: solution, install_command, mcp_serve_command, recommended_primary_solution
get_scheme_referenceGet the wire format of a 402 schemeARead-onlyIdempotentInspect
Protocol reference for L402, x402 or MPP: challenge, credential and receipt headers, encodings, the request/response flow, an example, and links to the specifications. Use when implementing a client or server.
Inputs: scheme (required). Returns: reference, implementations
get_solutionGet one registry entry in fullARead-onlyIdempotentInspect
Return one solution in full: summary, advantages and trade-offs, the six criterion scores with rationale, install commands, verified code samples, sources, maturity and the date its claims were last verified.
Inputs: id (required). Returns: liveness, solution
probe_402_supportProbe a URL for HTTP 402 supportARead-onlyIdempotentInspect
Make one GET (or HEAD) request to a public URL and report whether it answers with an HTTP 402 payment challenge, which scheme, and the decoded terms. Redirects are reported, not followed. Private and local addresses are refused. Never pays anything.
Inputs: url (required), method. Returns: url, error, status, schemes, +2 more
recommend_payment_railRecommend a payment rail for your requirementsARead-onlyIdempotentInspect
Choose an HTTP 402 payment solution from requirements rather than from rank. Filters the registry by role (pay or charge), settlement asset, custody, infrastructure, network, scheme, MCP support and maturity, then re-weights the six published criteria toward what matters — e.g. sub-cent amounts weight settlement cost heavily. Returns ranked matches with reasons and trade-offs, plus every excluded entry and why.
Inputs: role, chain, limit, scheme, +6 more. Returns: notes, method, weights, excluded, +2 more
search_402_solutionsSearch 402 payment solutionsARead-onlyIdempotentInspect
Search the 402MCP.org registry of HTTP 402 payment solutions (L402, x402, MPP). Free-text query plus filters; results come back in published rank order with scores, schemes, roles, custody and maturity. Call with no arguments to list the whole registry.
Inputs: kind, role, limit, query, +4 more. Returns: count, query, solutions, total_indexed, +1 more
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 7 tools
Each tool targets a distinct action within the HTTP 402 workflow: decoding a challenge, probing a URL, fetching protocol reference, searching the registry, getting a specific solution, getting the top-ranked solution, and recommending by requirements. The solution-retrieval tools are differentiated by input and purpose, so an agent can select appropriately.
All seven names use snake_case with a clear verb_noun pattern (decode_402_challenge, get_solution, search_402_solutions, etc.). The numeric token 402 is consistently placed, making the set predictable.
Seven tools is well within the ideal 3-15 range for a focused decision-support server. Each tool has a clear role in the 402 workflow, with no redundant or filler entries.
The surface covers challenge decoding, probing, scheme reference, solution search, top-solution retrieval, targeted recommendation, and detailed solution retrieval, which is strong coverage for decision support. Minor gaps remain around payment execution, receipt or credential verification after payment, and registry mutation, but these may be intentionally out of scope.
Maintenance
Related MCP Connectors
Pay for APIs with USDC. Read-only x402 payment discovery, verification, evidence, and status.
Paid Open Banking & Payment Intelligence API via x402. Unpaid tool calls return 402.
Discover machine-payable APIs, probe x402 payment terms, and run seller operations. Non-custodial.
Micropayment tools payable per call in USDC over x402. Discovery free, no accounts, no api keys.
Related MCP Servers
- AlicenseAqualityFmaintenanceA neutral, non-custodial payment router for AI agents: it discovers which payment rails a paid endpoint accepts (x402 on Base/EVM, Solana, MPP), then pays across them using the caller's own wallet key. Three tools — discover_payment_rails, pay_for_resource, payment_history.4MIT
- FlicenseNot gradedqualityAmaintenanceEnables AI agents to search and verify machine-payable HTTP 402/x402 APIs using live probe data, providing ranked results by liveness, uptime, price, and trustworthiness.-
- AlicenseNot gradedqualityBmaintenanceExposes MCP tools that let an agent search a catalog, inspect a paid service's pricing, fetch it with payment handled automatically, and check its remaining budget and active spending limits. Payments are authorized against a signed mandate from the owner, so agents can buy API access over HTTP 402 without ever holding the owner's private key.250 npmMIT
- AlicenseNot gradedqualityBmaintenanceEnables AI agents to discover payable real-world services — such as EV charging and food — through a unified registry and downstream gateway, then complete payments via swappable rails. Exposes tools for listing services and federated downstream servers, searching nearby chargers, and obtaining payment quotes or card credentials for agent-driven checkout.MIT