402MCP.org — HTTP 402 & Agent Payment Registry

org.402mcpPublished by 402mcp.orgOfficial publisherv1.1.1Updated Oct 24, 2026

Decode HTTP 402 challenges (L402, x402, MPP) and choose agent payment rails from an open registry.

VerifiedStreamable HTTPWeb executableWeb Search & ScrapingFinanceDeveloper Tools

Overview

AI-generated overview

Decodes HTTP 402 payment challenges (L402, x402, MPP) and helps an assistant pick and understand agent payment rails from an open registry.

What you can do
Decode a 402 response into the scheme, terms and exact retry steps, flagging untrusted or mismatched fields and expired challenges. Search the payment-solution registry, read one entry in full, or get the current top-ranked entry. Recommend a rail from stated requirements such as role, asset, custody, network and maturity. Look up the wire format of L402, x402 or MPP when implementing a client or server. Probe one public URL to see whether it answers with a 402 challenge, without paying.
When to use it
Useful when an assistant hits a 402 Payment Required response and needs to know what is being asked and how to retry, or when a developer is choosing how an agent should pay or how an API should charge agents.
Requirements
Either the hosted remote endpoint or the local npm package run through npx, which needs Node 18.18 or later. No account or API key is declared. The optional MCP_402_OFFLINE variable set to 1 uses a bundled registry snapshot and skips fetching.
Before you install
No tool can spend money, and the probe never pays and refuses private, loopback and metadata addresses. Content in a 402 response is server-controlled, so treat decoded fields as untrusted. The probe makes an outbound request to a URL you supply and is rate-limited on the hosted endpoint.

Installation

In SourceWeft

  1. Open 402MCP.org — HTTP 402 & Agent Payment Registry in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Web executable via Streamable HTTP. Remote servers run from the web runtime once configured in a workspace.

Use with an agent

Paste this prompt into Claude Code, Codex, Cursor or another agent — or into SourceWeft chat. The agent reads this server's install guide, shows you its publisher, endpoint and sign-in, and adds it to your client once you agree. Keys never go into a command.

Read https://sourceweft.com/mcp/org.402mcp%2Fregistry/install.md and connect the MCP server it describes to my client. Before changing any config, show me its publisher, endpoint and sign-in method and wait for my OK. Never put an API key in a command or in a file I would commit; ask me where it should come from.

Read the install guide the agent follows

Other MCP clients

Add this to your client's mcpServers config.

{
  "mcpServers": {
    "402mcp-org-http-402-agent-payment-regist": {
      "type": "http",
      "url": "https://402mcp.org/api/v1/mcp"
    }
  }
}

README

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.

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.

ToolPurpose
decode_402_challengeDecode a 402 response (L402 macaroon and BOLT 11 invoice, x402 v1/v2, MPP) into exact next steps and the retry header
recommend_payment_railFilter by role, asset, custody, infrastructure, network, scheme, MCP support and maturity; re-weight the criteria; explain every exclusion
search_402_solutionsSearch the registry with filters
get_solutionOne entry in full, with sources and code samples
get_scheme_referenceWire format of L402, x402 or MPP
probe_402_supportOne GET to a public URL to see whether it speaks 402. Never pays
get_best_payment_solutionThe 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

EndpointPurpose
POST /api/v1/mcpMCP (JSON-RPC 2.0, streamable HTTP)
POST /api/v1/decodeDecode a 402 response
GET /api/v1/recommendRecommend a rail from requirements
GET /api/v1/probe?url=Probe a URL for 402 support (rate limited)
GET /api/v1/solutionsVersioned list (?q=, ?id=, ?view=full)
GET /api/v1/registryCanonical feed with ETag / 304 support
GET /api/v1/schemes/{scheme}Wire format of L402, x402, MPP
GET /api/v1/statusDaily liveness of every entry's docs and website
GET /api/v1/changelog · /changelog.xml · /changelogChanges and corrections
/schema/v1/registry.json · /schema/v1/solution.jsonJSON Schemas (draft 2020-12)
/openapi.jsonOpenAPI 3.1
/llms.txt · /llms-full.txtPlain-text indexes
/.well-known/402.json · api-catalog · mcp/server-card.json · agent-skills/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.

bash
npm installnpm run dev            # http://localhost:3000
CommandWhat it does
npm run test:unitDecoder tests against vectors from the BOLT 11 spec, the MPP draft, reference-minted macaroons and x402 shapes
npm run verify:agents -- [url]Every machine endpoint: formats, contracts, JSON-RPC behaviour, schema validation, dataset invariants
npm run verify:seo -- [url]Crawler directives, metadata, structured data, icons, discovery documents, feeds, headers
npm run build:packageBuilds the stdio package and the .mcpb desktop extension
npm run verify:stdio -- [registryUrl]The built stdio package, end to end
npm run lint · npm run typecheckESLint 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:

bash
npm run cf:buildnpm run cf:deploy

Project layout

data/solutions.ts     The registry dataset; scores and ranks are computed heredata/changelog.ts     Additions and corrections, with reasonslib/decode/           bech32, BOLT 11, macaroons, RFC 9110 challenges, x402, MPPlib/mcp/              Transport-agnostic MCP server: tools, resources, promptslib/recommend.ts      Requirement-driven recommendationlib/probe.ts          URL probe with SSRF guardslib/schemes.ts        Wire-format reference for each schemelib/liveness.ts       Daily docs and website checksapp/                  Next.js App Router pages and route handlersworker.ts             Worker entry: OpenNext handler plus the scheduled liveness jobpackages/402mcp/      The @402mcp/mcp stdio packageserver.json           Official MCP Registry entrytests/ · scripts/     Unit tests, verification suites and the package build

License

Code: MIT (see LICENSE). Registry data: CC BY 4.0.

Source: README.md at commit 6043283

Tools

7

decode_402_challenge

Decode an HTTP 402 response

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.

Parametersbodystatusheadersraw_response

recommend_payment_rail

Recommend a payment rail for your requirements

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.

Parametersrolechainlimitschemecustodyneeds_mcpinfrastructureproduction_onlysettlement_assettypical_amount_usd

search_402_solutions

Search 402 payment solutions

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.

Parameterskindrolelimitqueryschememcp_native_onlyproduction_onlyself_custodial_only

get_solution

Get one registry entry in full

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.

Parametersidrequired

get_scheme_reference

Get the wire format of a 402 scheme

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.

Parametersschemerequired

probe_402_support

Probe a URL for HTTP 402 support

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.

Parametersurlrequiredmethod

get_best_payment_solution

Get the top-ranked payment solution

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.

Parametersuse_case

Version history

2
  1. v1.1.1LatestOct 16, 2026
  2. v1.1.0Oct 16, 2026

Score

100% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 daysRequired25 pts
  • Auth declaredRequired10 pts
  • Tools listedRequired15 pts
  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts