Mcp Pay

mcp-pay

Payment awareness layer for MCP (Model Context Protocol)

[](https://crates.io/crates/mcp-pay-schema) [](LICENSE)

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: {...}     |                              |
  ||                              |
  |                                |  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](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

• [x] 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](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. |

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: neul-labs
• Source: neul-labs/mcp-pay
• License: MIT
• Homepage: https://mcp-pay.neullabs.com

Install and usage instructions live in the source repository linked above.