01 · crate
mcp-pay-schema
The JSON Schema for pay.json plus its typed Rust representation. Parse, validate, and serialize manifests from a single source of truth.
Architecture
The 402 handshake, end to end
mcp-pay adds no new envelope and no bespoke transport. It reuses the HTTP 402 status code and two headers. Here is exactly what flows between an agent, a paid MCP server, and a facilitator.
Agent / MCP client Paid MCP server Facilitator │ │ │ │ 1. GET pay.json ───────────▶│ │ │ ◀─────── pricing + accepts │ │ │ │ │ │ 2. call paid tool ─────────▶│ │ │ ◀── 402 X-PAYMENT-REQUIRED │ │ │ │ │ │ 3. retry + X-PAYMENT ──────▶│ │ │ │ 4. verify proof ───────▶│ │ │ ◀────── { valid: true } │ │ ◀──────── 200 + result │ │ ▼ ▼ ▼
The manifest is fetched once and cached; verification happens server-to-facilitator, out of band, so settlement never blocks inside mcp-pay.
The three crates
02 · crate
mcp-pay-server
An axum reference server. Serves the manifest, returns 402 on paid tools, reads X-PAYMENT proofs, and verifies them with a facilitator before running the tool.
03 · crate
mcp-pay-cli
A command-line tool for authoring and validating manifests and for exercising the 402 flow end to end during development.
Why 402 and not a custom protocol
402 Payment Required is a reserved HTTP status code that has waited decades for a use. Reusing it means existing agents, proxies, and HTTP clients already have a place to hook payment logic. mcp-pay only standardizes the two headers — X-PAYMENT-REQUIRED and X-PAYMENT — and the shape of the manifest that describes what a call costs.
Why verification is server-to-facilitator
mcp-pay is deliberately not a payment processor. Settlement happens on the underlying rail — an x402 facilitator, a Lightning node, MPP, or a card processor. The server asks the facilitator whether a proof is valid and only then runs the tool. This keeps mcp-pay small and rail-agnostic: the manifest advertises rails, and the facilitator settles them.
See the full feature surface, or read why mcp-pay exists and what it is not.