A JSON manifest at /.well-known/mcp/pay.json
Declare pricing per tool, resource, or prompt. List which payment rails you accept. Publish a payment-specific SLA. The manifest is static, cacheable, and rail-agnostic.
v0.1 draft · Phase 1: schema + reference server
Payment awareness for MCP, not paywalls.
mcp-pay extends the Model Context Protocol with a small payment-awareness layer: a static manifest at /.well-known/mcp/pay.json, an HTTP 402 flow, and a Rust reference server. Rail-agnostic by design.
manifest
/.well-known/mcp/pay.json
Static, cacheable, no auth required to read.
status code
402 Payment Required
Standard HTTP. Agents already know how to handle it.
rails (today)
x402 on Base & Solana
MPP, Lightning, and card are in the schema; planned for the reference server.
What ships
Three pieces, kept small on purpose
mcp-pay is not a payment processor and not an MCP registry. It is the smallest thing that makes payments first-class in the MCP ecosystem.
A Rust implementation of payment-gated MCP tools
A working axum-based server that returns 402 Payment Required on paid tools, accepts X-PAYMENT headers, and verifies with an x402 facilitator before serving results.
HTTP 402 flow compatible with x402, MPP, Lightning, card
mcp-pay is rail-agnostic. The 402 response carries X-PAYMENT-REQUIRED with everything an agent needs to construct a payment proof for any supported rail.
The gap
Discovery and payment, in one place
The MCP Registry indexes tools, resources, and prompts, but knows nothing about pricing. x402 Bazaar discovers paid services only after a payment. Tempo's MPP only sees its own in-network endpoints. mcp-pay closes the loop at /.well-known/.
| Ecosystem | Discovery | Payment |
|---|---|---|
| MCP Registry | Tools, resources, prompts | None |
| x402 Bazaar | After payment | x402 only |
| Tempo MPP | In-network | MPP only |
| mcp-pay | At /.well-known/ | All rails |
Source: README of github.com/neul-labs/mcp-pay.
Schema
A manifest you can paste into your server
Pricing per tool. Accepted rails listed explicitly. Optional payment SLA so agents can budget for settlement.
/.well-known/mcp/pay.json v0.1
{
"mcp_pay": "0.1",
"server_card": "/.well-known/mcp/server-card.json",
"pricing": {
"default": { "model": "free" },
"tools": {
"get_forecast": {
"model": "per_call",
"amount": "0.003",
"currency": "USD"
}
}
},
"accepts": [
{
"rail": "x402",
"network": "eip155:8453",
"asset": "USDC",
"pay_to": "0x1234..."
},
{
"rail": "lightning",
"lnurl": "lnurl1dp68gurn8ghj7..."
}
],
"payment_sla": {
"settlement_time_seconds": { "x402": 2, "lightning": 5 },
"refund_policy": "full_refund_on_failure"
}
}pricing models
The schema supports free, per_call, subscription, tiered, and metered.
scopes
Pricing rules attach to a default, named tools, resources patterns, or prompts.
SLA fields
Declare per-rail settlement time and a refund policy. Agents use this to pick the right rail for a budget.
Protocol
The 402 flow, six messages end to end
No new envelope. No bespoke handshake. mcp-pay reuses the HTTP 402 status code and two small headers.
- 01 · Agent → Server request
GET /api/forecast
Initial call to a paid MCP tool.
- 02 · Server → Agent response
402 Payment Required X-PAYMENT-REQUIRED: {…}Server returns the payment requirements.
- 03 · Agent → Server request
GET /api/forecast X-PAYMENT: {…}Agent retries with a constructed payment proof.
- 04 · Server → Facilitator response
POST /verify
Server verifies the proof out-of-band.
- 05 · Facilitator → Server request
{ valid: true }Facilitator confirms settlement.
- 06 · Server → Agent response
200 OK X-PAYMENT-RESPONSE: {…}Server returns the result with settlement metadata.
Supported rails
Rail-agnostic on paper, x402-first in code
The schema accepts five rail families. The reference server implements x402 today; the others are planned in subsequent phases.
| Rail | Network | Status |
|---|---|---|
| x402 | Base, Solana | Implemented |
| MPP | Tempo | Planned |
| Lightning | Bitcoin | Planned |
| Card | Stripe | Planned |
Roadmap
Four phases, in order
phase 1 · done
Schema + reference server
JSON Schema, three Rust crates, and a working axum server with 402 + x402.
phase 2 · planned
Registry crawler
A CLI that walks public MCP servers, fetches their pay.json, and indexes them by capability + rail.
phase 3 · planned
Rail router
A wallet-side library that picks the cheapest acceptable rail per call given the agent's budget and policy.
phase 4 · planned
Submit as SEP
Submit the spec to the MCP Working Group as a SEP, alongside SEP-2127.
Honest comparisons
Where mcp-pay sits in the payment-protocol landscape
We don't replace L402 or x402. We sit one layer up, in the MCP discovery surface, and point at whichever rail your agent is configured for.
mcp-pay vs L402
→L402 is Lightning-shaped, with macaroons and HTTP 402. mcp-pay is MCP-shaped: one manifest can advertise an L402 endpoint alongside x402 and card.
mcp-pay vs x402 (Coinbase)
→x402 is one of the rails mcp-pay supports first. The difference is scope: x402 is the rail; mcp-pay is the discovery + manifest layer wrapping it for MCP servers.
FAQ
Questions builders ask first
+ Is mcp-pay a payment processor?
No. It is a manifest schema, a 402 flow, and a reference server. Settlement happens on the underlying rail — x402 facilitator, Lightning node, MPP, or card processor — not inside mcp-pay.
+ Does it require a blockchain?
No. The protocol is rail-agnostic. The reference server ships with x402 first because that path is shortest, but card and ACH are in the schema and on the roadmap.
+ How does it relate to the MCP Server Card?
mcp-pay complements SEP-2127. server-card.json describes identity, remotes, and capabilities. pay.json describes pricing, accepted rails, and payment SLA. No field duplication; the two link to each other.
+ Does this replace L402 or x402?
No. L402 is Lightning-shaped; x402 is HTTP/EVM-shaped. mcp-pay is MCP-shaped — it lets one MCP server advertise pricing for both kinds of payment, plus card or ACH, in a single manifest.
+ What pricing models are supported?
The schema defines free, per_call, subscription, tiered, and metered. Each can apply as a default, per tool, per resource pattern, or per prompt.
+ Where can I read the full spec?
specs/mcp-pay-specification.md in the repository, alongside the JSON Schema at specs/schema/pay.schema.json. Both are version 0.1 (draft) — feedback welcome before submission as a SEP to the MCP working group.
Build a paid MCP tool this week
Clone the reference server, publish your pay.json, point a facilitator at it, and your tool can charge agents in two lines of config.