mcp-pay vs x402: a rail-agnostic payment layer for MCP
mcp-pay extends the Model Context Protocol with a .well-known pricing manifest and a reference HTTP 402 server. Rail-agnostic across x402, MPP and cards.
mcp-pay is a Rust-backed drop-in for
x402. Same API, faster hot paths.
Install: see docs.
Rail-agnostic: x402, MPP (Tempo), Lightning, and card.
mcp-pay vs x402: the facts
Rail-agnostic: x402, MPP (Tempo), Lightning, and card.
x402 only.
`.well-known/mcp-pay.json` discovery manifest.
No standard discovery format.
Reference Rust server implementing HTTP 402 + X-PAYMENT-REQUIRED.
Multiple competing reference implementations.
Agent-side SDK for parsing payment requests and choosing a rail.
No standardised agent-side library.
MIT licensed.
Mixed licensing.
The two problems: discovery and settlement
Charging for a tool call involves two separate questions that are easy to conflate. The first is discovery: how does an agent find out, before it calls, that a tool costs money and what it costs? The second is settlement: how does value actually move once the agent agrees to pay?
x402 is an answer to the second question. It defines how an HTTP 402 response carries a payment request so a client can satisfy it and retry. mcp-pay treats that as one backend among several and concentrates on the first question, publishing a .well-known/mcp-pay.json manifest that declares per-tool pricing in a form an agent can read ahead of time. The two compose rather than compete.
Why rail-agnostic matters for tool pricing
A tool provider and an agent operator rarely start with the same payment rail. One has a card processor and an accounting system; the other wants to settle in whatever its wallet already holds. Binding the tool protocol to a single rail forces one of them to adopt the other's infrastructure before the first call can happen.
Separating declaration from settlement avoids that. The manifest says what a tool costs and which rails it accepts; the agent-side library picks a rail it can actually use. Adding a rail later is a backend change rather than a protocol change, which is the property that makes this survivable as the payment landscape moves.
Limitations and where x402 alone wins
If your entire ecosystem is already x402-native — the tools, the agents and the wallets — then a dedicated x402 library is a smaller dependency and a shorter path. The abstraction mcp-pay adds only earns its cost when more than one rail is genuinely in play.
This is also a young area. Treat the reference server as a demonstration of the flow rather than a hardened payment system, verify current behaviour against the repository before putting money through it, and keep the usual controls around an agent that can spend — including a budget enforced before the call, as described in cost control for production AI agents.
When to use mcp-pay
- You want to monetise MCP tools and need to support multiple payment rails (x402, Lightning, card).
- You want a standard `.well-known` discovery manifest so agents can find your pricing.
- You publish MCP tools and want agents to discover pricing before calling rather than after a 402.
When NOT to use mcp-pay
- You only ever need x402 — use a x402-native library directly.
- You are prototyping and nobody is charging anyone yet — the manifest is overhead until money is real.
Frequently asked questions
Is mcp-pay a replacement for x402?
No — mcp-pay is *compatible* with x402. The x402 protocol defines how an HTTP 402 response carries a payment request; mcp-pay standardises the discovery layer and ships a reference server that implements the 402 flow with multiple rail backends.
Which payment rails does mcp-pay support?
x402, MPP (Tempo), Lightning, and traditional card payments. The reference server demonstrates the x402 flow; the MPP and Lightning backends are pluggable.
Do I have to use Rust to integrate mcp-pay?
No — the `.well-known/mcp-pay.json` manifest is just JSON, and the reference server exposes a standard HTTP API. Any MCP client can consume it.
Does an agent need a wallet to read the manifest?
No. The manifest is plain JSON served from a well-known path, so discovery and price comparison work with no payment capability at all. A wallet is only needed to settle.
How should I cap what an agent can spend?
Outside the protocol, in your own runtime, enforced before the call rather than reconciled afterwards. A declared price makes the budget checkable; it does not enforce it for you.