mcp-pay

July 2, 2026 · View on GitHub

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

Ecosystem	Discovery	Payment
MCP Registry	Tools, resources, prompts	None
x402 Bazaar	After payment	x402 only
Tempo MPP	In-network	MPP only
mcp-pay	At `.well-known`	All rails

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

Variable	Default	Description
`HTTP_ADDR`	`127.0.0.1:3000`	Server bind address
`PAY_TO_ADDRESS`	`0x0...`	Payment recipient
`X402_FACILITATOR`	`https://x402.org/facilitator`	x402 facilitator URL
`NETWORK`	`eip155:8453`	Chain ID (Base)
`ASSET`	`USDC`	Payment asset
`PRICE_PER_CALL`	`0.003`	Price in USD

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

Rail	Network	Status
x402	Base, Solana	Implemented
MPP	Tempo	Planned
Lightning	Bitcoin	Planned
Card	Stripe	Planned

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:

Project	Description
agentvfs	Workspace runtime and execution boundary for AI agents.
memorg	Give your LLM a memory that actually works.
ormai	Give your AI agents database access without the risk — safe text-to-SQL.
closegate	The policy chokepoint for finance AI agents.
regulus	The EU & UK compliance plane for Google ADK.