Frequently asked questions

mcp-pay is a payment-awareness layer for the Model Context Protocol (MCP). It is three deliberately small things: a static JSON manifest served at /.well-known/mcp/pay.json that declares per-tool pricing and accepted payment rails; a Rust reference server (axum) that returns HTTP 402 on paid tools and verifies payment proofs with a facilitator; and a rail-agnostic 402 flow using X-PAYMENT-REQUIRED and X-PAYMENT headers. It is not a payment processor, not an MCP registry, and not a token — settlement always lives on the underlying rail. Status is v0.1 draft, from Neul Labs.

It is the mcp-pay manifest: a static, cacheable JSON file, readable without auth, that an MCP server publishes to advertise what it charges. Root fields are mcp_pay (version, currently "0.1"), an optional server_card link, pricing (default plus per-tool, per-resource, and per-prompt rules), accepts (the list of payment rails), and optional payment_sla, stats, and extensions. Pricing models are free, per_call, subscription, tiered, and metered. Because it lives at a predictable well-known path, agents and crawlers can read a tool’s price before making a call.

Publish one /.well-known/mcp/pay.json manifest. Under pricing, set a price for each tool (per_call, subscription, tiered, metered, or free), and under accepts list every rail you take — x402, mpp, lightning, card, or ach — side by side. The manifest is rail-agnostic and settlement-neutral, so a single server can advertise card, Lightning, and x402 at the same time. An agent reads the manifest before it calls and picks whichever rail fits its budget and policy; settlement happens on that rail, not inside mcp-pay, so you are never bound to one chain. The optional payment_sla field lets you declare per-rail settlement times so agents can choose accordingly. Today the reference server implements x402 (Base and Solana); MPP, Lightning, and card are in the schema and planned for later phases.

They sit at different layers, so in practice they compose rather than compete. x402 is Coinbase’s settlement standard — it defines how a payment happens over HTTP 402 once both sides have agreed to use it. AP2 is the authorization-mandate standard from Google and Coinbase, backed by a large multi-org group, governing how an agent is authorized to spend. MCPay (mcpay.tech) is another project in the MCP payments space. mcp-pay is the rail-agnostic, settlement-neutral pricing-discovery manifest: it is where an MCP server declares what each tool costs and which rails it accepts, before any payment is attempted. A pay.json manifest can list x402 as one of its accepted rails; an AP2 mandate can authorize the spend; the actual transfer settles on the chosen rail. mcp-pay does not replace any of them — it is the discovery surface they can be advertised through.

Add the tool to pricing.tools in your pay.json with model: per_call, an amount (a decimal string such as "0.003"), and a currency, then serve the manifest statically at /.well-known/mcp/pay.json (no auth needed to read it). Run the Rust reference server (mcp-pay-server): it returns 402 Payment Required with an X-PAYMENT-REQUIRED header on the paid tool, accepts the agent’s retry carrying an X-PAYMENT proof, verifies that proof out-of-band with a facilitator, and returns 200 OK with the result. This is payment awareness, not a paywall: the price is discoverable up front and the tool stays visible in discovery — the agent simply pays per call instead of being blocked behind a gate.

The MCP Registry indexes tools, resources, and prompts, but knows nothing about pricing. x402 Bazaar only surfaces a paid service after a payment, and Tempo’s MPP sees only its own in-network endpoints. mcp-pay puts pricing discovery at a predictable static location — /.well-known/mcp/pay.json — next to the MCP Server Card (SEP-2127), which handles identity, remotes, and capabilities. There is no field duplication: the Server Card describes what a server can do, pay.json describes what it costs and which rails it accepts, and the two link to each other. Because the manifest is cacheable and readable without auth, an agent or a crawler can learn a tool’s price and accepted rails before dispatching a call.