x402r MCP Server

MCP server enabling AI agents to make x402 payments and interact with the x402r refund protocol.

Quick Start

pnpm install
pnpm run build
pnpm run inspector  # Test tools interactively

Configuration

Set environment variables:

EVM_PRIVATE_KEY=your_private_key        # Required
PINATA_API_KEY=your_key                  # Required for refund requests
PINATA_SECRET_KEY=your_secret            # Required for refund requests

Get free Pinata keys at pinata.cloud.

MCP Client Setup

Add to your MCP client config (Claude Desktop, VS Code, Cursor):

{
  "mcpServers": {
    "x402r": {
      "command": "node",
      "args": ["/path/to/x402r-mcp/build/index.js"],
      "env": {
        "EVM_PRIVATE_KEY": "0x..."
      }
    }
  }
}

Config locations:

• Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json
• VS Code: .vscode/mcp.json

Tools

E2E Testing

Quick way to test the full refund flow:

1. Create 3 test wallets — merchant, arbiter, client
2. Start a sample merchant server using x402r-extensions example
3. Register merchant & arbiter at app.x402r.org
4. Test as client — use pnpm run inspector with this MCP server to make payments and request refunds
5. Handle disputes — log in as arbiter at app.x402r.org to approve/deny refunds

Related

• x402r Protocol - Full protocol documentation
• x402r Contracts - Smart contracts
• x402r Interface - Web interface