mcp-pay

Payment awareness layer for MCP (Model Context Protocol)

Website: mcp-pay.neullabs.com · Docs: docs.neullabs.com/mcp-pay · Source: github.com/neul-labs/mcp-pay

mcp-pay extends the MCP ecosystem with payment capabilities. It provides:

• Schema: A JSON manifest (mcp-pay.json) for declaring pricing and payment rails
• Reference Server: A Rust implementation demonstrating payment-gated MCP tools
• Protocol: HTTP 402 payment flow compatible with x402, MPP, Lightning, and card payments

The Gap

mcp-pay bridges these ecosystems by providing a rail-agnostic payment manifest that works with all payment protocols.

Quick Start

Run the Reference Server

# Clone and build
git clone https://github.com/neul-labs/mcp-pay
cd mcp-pay
cargo build --release

# Configure (optional)
export PAY_TO_ADDRESS=0x1234567890abcdef1234567890abcdef12345678
export HTTP_ADDR=127.0.0.1:3000

# Run
cargo run -p mcp-pay-server

Test the Endpoints

# Get payment manifest
curl http://localhost:3000/.well-known/mcp/pay.json | jq

# Get weather (FREE)
curl "http://localhost:3000/api/weather?city=London" | jq

# Get forecast (PAID - returns 402)
curl -i "http://localhost:3000/api/forecast?city=Tokyo"
# HTTP/1.1 402 Payment Required
# X-PAYMENT-REQUIRED: eyJ4NDAyX3ZlcnNpb24i...

Project Structure

mcp-pay/
├── crates/
│   ├── mcp-pay-schema/     # Schema types + validation
│   ├── mcp-pay-server/     # Reference implementation
│   └── mcp-pay-cli/        # Registry queries (Phase 2)
├── specs/
│   ├── schema/
│   │   └── mcp-pay.schema.json
│   └── mcp-pay-specification.md
└── README.md

Schema Example

Serve at /.well-known/mcp/pay.json:

{
  "mcp_pay": "0.1",
  "server_card": "/.well-known/mcp/server-card.json",
  "pricing": {
    "default": { "model": "free" },
    "tools": {
      "get_forecast": {
        "model": "per_call",
        "amount": "0.003",
        "currency": "USD"
      }
    }
  },
  "accepts": [
    {
      "rail": "x402",
      "network": "eip155:8453",
      "asset": "USDC",
      "pay_to": "0x1234..."
    },
    {
      "rail": "lightning",
      "lnurl": "lnurl1dp68gurn8ghj7..."
    }
  ],
  "payment_sla": {
    "settlement_time_seconds": { "x402": 2, "lightning": 5 },
    "refund_policy": "full_refund_on_failure"
  }
}

Usage

As a Library

use mcp_pay_schema::{
    McpPayManifest, Pricing, PricingRule, PaymentRail,
};

// Create a manifest
let mut pricing = Pricing::with_default(PricingRule::free());
pricing.add_tool("get_forecast", PricingRule::per_call("0.003", "USD"));

let manifest = McpPayManifest::new(
    "0.1",
    pricing,
    vec![PaymentRail::x402_base_usdc("0x1234...")],
);

// Serialize to JSON
let json = serde_json::to_string_pretty(&manifest)?;

Environment Variables

Payment Flow

Agent                          MCP Server                    Facilitator
  |                                |                              |
  |  GET /api/forecast             |                              |
  |------------------------------->|                              |
  |                                |                              |
  |  402 Payment Required          |                              |
  |  X-PAYMENT-REQUIRED: {...}     |                              |
  |<-------------------------------|                              |
  |                                |                              |
  |  [Create payment proof]        |                              |
  |                                |                              |
  |  GET /api/forecast             |                              |
  |  X-PAYMENT: {...}              |                              |
  |------------------------------->|                              |
  |                                |  POST /verify                |
  |                                |----------------------------->|
  |                                |                              |
  |                                |  { valid: true }             |
  |                                |<-----------------------------|
  |                                |                              |
  |  200 OK                        |                              |
  |  X-PAYMENT-RESPONSE: {...}     |                              |
  |  { forecast: ... }             |                              |
  |<-------------------------------|                              |

Supported Payment Rails

Specification

See specs/mcp-pay-specification.md for the full specification.

Key design principles:

• Complementary: Works alongside MCP Server Card (SEP-2127)
• Rail-agnostic: Supports multiple payment protocols
• Minimal: Only payment-specific fields, no duplication
• Cacheable: Static manifest, dynamic stats

Roadmap

• Phase 1: Schema + Reference Server
• Phase 2: Registry Crawler
• Phase 3: Rail Router (cost optimization)
• Phase 4: Submit as SEP to MCP WG

License

Licensed under the MIT license (LICENSE or https://opensource.org/licenses/MIT).

Contributing

Contributions welcome! Please read the specification before submitting PRs.

Part of the Neul Labs toolchain

Part of the Neul Labs agent-infrastructure toolchain: