X402 MCP

A server and client implementation for integrating X402 payment protocol with Model Context Protocol (MCP), enabling micropayments for MCP tool invocations.

Demo

Try this out with your LLM by adding the following MCP server:

{
  "mcpServers": {
    "x402": {
      "command": "npx",
      "args": [ "@civic/[email protected]" ],
      "env": {
        "PRIVATE_KEY": "Your wallet private key",
        "TARGET_URL": "https://x402-mcp.fly.dev/mcp"
      }
    }
  }
}

This will connect to a hosted X402 MCP server that charges for tool invocations in USDC.

The demo uses the Base Sepolia testnet. Obtain testnet ETH (for gas) and USDC (for payments) from a faucet like the Coinbase developer platform faucet.

Quick Start

Enable micropayments for your MCP tools with X402 - get paid in USDC for every tool invocation.

Server: Charge for tool usage

const transport = makePaymentAwareServerTransport(
  "0x123...",
  { "my-tool": "$0.01" }
);
await mcpServer.connect(transport);

Client: Automatic payment handling

const transport = makePaymentAwareClientTransport(
  "http://localhost:3000/mcp",
  wallet
);
await mcpClient.connect(transport);

Table of Contents

• Demo
• Quick Start
• What is X402?
• What is MCP?
• How MCP Works with Streaming HTTP
• Integrating MCP and X402
• Installation
• Usage
  • Server Setup
  • Client Setup
  • Streaming Limitation
• Proxy Support
  • Client Proxy
  • Server Proxy
  • Use Cases
  • Architecture
• License

What is X402?

X402 is an open payment protocol developed by Coinbase that enables instant, automatic stablecoin payments directly over HTTP. It revives the HTTP 402 Payment Required status code to create a simple, programmatic payment flow:

1. Client requests a resource from the server
2. Server responds with 402 status and payment requirements
3. Client constructs and sends a payment payload
4. Server verifies and settles the payment via a facilitator
5. Server returns the requested resource

Key features:

• Programmatic payments without accounts or complex authentication
• Direct on-chain payments with minimal setup
• Machine-to-machine transaction support
• Micropayments and usage-based billing

Learn more: https://x402.org

What is MCP?

Model Context Protocol (MCP) is an open protocol that standardizes how applications provide context to AI models. It enables:

• Standardized server implementations exposing tools and resources
• Client libraries for connecting to MCP servers
• Transport layers for communication between clients and servers