/.well-known/mcp/pay.json
A static, cacheable JSON manifest served with no auth required to read. Agents fetch it before calling a paid tool to learn what a call costs and how to pay.
Features
Everything in the v0.1 draft
mcp-pay keeps its surface small on purpose: a manifest, a flow, a set of rails, and a reference implementation. Here is the full picture.
The manifest
A static pay.json that makes pricing discoverable.
Per-tool pricing
Attach a pricing rule to a default, a named tool, a resource pattern, or a prompt. Supported models: free, per_call, subscription, tiered, and metered.
Declared payment SLA
Optional per-rail settlement time and a refund policy, so an agent can budget for latency and pick a rail that fits its constraints.
Links to the Server Card
pay.json references /.well-known/mcp/server-card.json. Identity and capabilities live in SEP-2127; pricing lives here. No field duplication.
The 402 flow
Standard HTTP status code, two small headers.
402 Payment Required
Paid tools respond with the standard 402 status code. No bespoke envelope — agents and proxies already understand it.
X-PAYMENT-REQUIRED
The 402 response carries everything an agent needs to construct a payment proof for any accepted rail.
X-PAYMENT retry
The agent retries the same request with an X-PAYMENT header carrying the constructed proof.
Server-to-facilitator verify
The server verifies the proof out-of-band with a facilitator before serving results — settlement never blocks inside mcp-pay itself.
Rail-agnostic
One manifest, many payment rails.
x402
HTTP/EVM-shaped payments. The reference server implements x402 first because that path is shortest.
MPP
Declared in the schema as an accepted rail; planned for the reference server in a later phase.
Lightning
Bitcoin Lightning is expressible in the accepts array via an LNURL; planned for the reference server.
Card
Traditional card rails are part of the schema, so a single manifest can advertise on-chain and off-chain payment side by side.
Reference implementation
A Rust codebase you can read and run.
mcp-pay-schema
The JSON Schema and typed Rust representation of the pay.json manifest.
mcp-pay-server
An axum-based reference server that returns 402 on paid tools and verifies X-PAYMENT proofs with a facilitator.
mcp-pay-cli
A command-line tool for working with manifests and exercising the 402 flow during development.
Draft, MIT/Apache-2.0
mcp-pay is a v0.1 draft. The spec and schema are versioned so feedback can land before it is submitted as a SEP.
See how it fits together
Read the 402 handshake in the architecture, browse use cases, or follow a guide.