# mcp-pay

> A v0.1 draft specification, JSON Schema, and Rust reference server for adding payment awareness to MCP (Model Context Protocol) servers. Rail-agnostic across x402, MPP, Lightning, and card. From Neul Labs.

## What mcp-pay Is

mcp-pay is three things kept deliberately small:

1. A JSON manifest, served at `/.well-known/mcp/pay.json`, that declares pricing and accepted payment rails for an MCP server.
2. A Rust reference server (`mcp-pay-server`) that returns HTTP 402 on paid tools, accepts X-PAYMENT headers, and verifies proofs out-of-band with a facilitator.
3. A protocol — an HTTP 402 flow with X-PAYMENT-REQUIRED and X-PAYMENT headers — that is rail-agnostic and works alongside the MCP Server Card (SEP-2127).

It is not a payment processor, not an MCP registry, and not a token. Source-of-truth settlement always lives on the underlying rail.

## Verified From the Repository

- Workspace contains three Rust crates: `mcp-pay-schema` (schema types and validation), `mcp-pay-server` (reference axum implementation), and `mcp-pay-cli` (Phase 2 registry queries).
- Specification at `specs/mcp-pay-specification.md` (v0.1 draft, March 2026).
- JSON Schema at `specs/schema/pay.schema.json`.
- License: MIT or Apache-2.0, at the user's option.
- Status: Phase 1 (schema + reference server) is complete. Phase 2 (registry crawler), Phase 3 (rail router), and Phase 4 (SEP submission to the MCP working group) are planned.

## The Manifest Schema (v0.1)

Root fields:

- `mcp_pay` (required): version string, currently "0.1".
- `server_card` (optional): path to the MCP Server Card.
- `pricing` (required): pricing object with `default`, `tools`, `resources`, and `prompts` sub-objects.
- `accepts` (required): array of payment rails.
- `payment_sla` (optional): per-rail settlement times and refund policy.
- `stats` (optional): usage statistics.
- `extensions` (optional): vendor extensions.

Pricing models supported: `free`, `per_call`, `subscription`, `tiered`, `metered`.

Pricing rule fields: `model`, `amount` (decimal string), `currency` (ISO 4217 or token symbol), `unit` (`call`, `request`, `token`, `byte`, `second`, `month`), `tiers`, `free_quota`.

Payment rail fields: `rail` (one of `x402`, `mpp`, `lightning`, `card`, `ach`, `custom`), `network` (CAIP-2 chain ID), `asset`, `contract`, `pay_to`, `facilitator`, `provider`, `lnurl`.

## Supported Rails

- **x402**: implemented in the reference server. Networks listed in the README: Base and Solana.
- **MPP** (Tempo): planned.
- **Lightning** (Bitcoin): planned.
- **Card** (Stripe): planned.

## The 402 Flow

Six messages end-to-end:

1. Agent → Server: `GET /api/forecast` (no payment).
2. Server → Agent: `402 Payment Required` with `X-PAYMENT-REQUIRED: {…}` header.
3. Agent → Server: `GET /api/forecast` with `X-PAYMENT: {…}` header containing the constructed proof.
4. Server → Facilitator: `POST /verify` with the proof.
5. Facilitator → Server: `{ valid: true }`.
6. Server → Agent: `200 OK` with `X-PAYMENT-RESPONSE: {…}` header and the actual result body.

The agent never talks to the facilitator directly. Verification is server-mediated.

## Environment Variables (Reference Server)

- `HTTP_ADDR`: bind address (default `127.0.0.1:3000`).
- `PAY_TO_ADDRESS`: payment recipient.
- `X402_FACILITATOR`: facilitator URL (default `https://x402.org/facilitator`).
- `NETWORK`: CAIP-2 chain ID (default `eip155:8453`, Base).
- `ASSET`: payment asset (default `USDC`).
- `PRICE_PER_CALL`: price in USD (default `0.003`).

## Who Should Adopt It

- MCP server builders who want to monetize tools without writing a paywall.
- Agentic AI infrastructure teams who need a uniform discovery surface for paid tools.
- Wallets that want to budget agent spend ahead of dispatch.

## Honest Comparisons

- **vs L402**: L402 is a Lightning-shaped HTTP 402 authentication scheme using macaroons. mcp-pay sits one layer up: a discovery manifest that can advertise L402 alongside x402, card, and ACH. Different layers; compose well.
- **vs x402 (Coinbase)**: x402 is the rail. mcp-pay is the manifest layer wrapping it for MCP servers. The reference server uses x402 as its first implemented rail. Different scope; designed to compose.

## Pages

- /
- /about/
- /blog/
- /blog/payment-awareness-not-paywalls/
- /blog/payment-flows-that-dont-break-llm-calls/
- /blog/wallet-side-vs-server-side-metering/
- /compare/l402/
- /compare/x402/