xarmian/rome-x402-mcp

X402 USDC Bridge MCP

Bridge USDC from Base to Algorand/Voi via Aramid protocol, with X402 micropayments.

Architecture

Claude Desktop ──MCP──▶ MCP Server ──X402 request (pay USDC)──▶ Bridge API
                                                              └─▶ Executes Aramid bridge tx
                                                              └─▶ Returns status/tx hash
MCP Server ◀─────────────────────────────────────────────────────────────────┘

Setup

1. X402 Bridge Server

cd x402-server
cp .env.example .env
# Edit .env with your Coinbase API credentials
npm install
npm start

2. MCP Server

cd mcp-server  
cp .env.example .env
# Edit .env with your payment wallet private key
npm install

3. Configure Claude Desktop

1. Find your Claude Desktop config file:

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json

2. Add the MCP server configuration:

{
  "mcpServers": {
    "x402-usdc-bridge": {
      "command": "/Users/dave/Dev/coinbase-hackathon/mcp2/mcp-server/start.sh",
      "env": {
        "RESOURCE_SERVER_URL": "http://localhost:4021",
        "PRIVATE_KEY": "your_private_key_here"
      }
    }
  }
}

3. Restart Claude Desktop after saving the config file

Usage

1. Start the X402 Bridge Server:

   cd x402-server
   npm start
   

2. Use in Claude Desktop:

   Bridge 5 USDC to Algorand address ABC123XYZ
   

   The MCP server will:

   1. Make X402 request to bridge API
   2. Automatically pay 5 USDC via X402
   3. API executes Aramid bridge transaction with that 5 USDC
   4. Returns transaction result

Testing the Setup

You can verify the MCP server is working by checking Claude Desktop's MCP logs or testing the bridge API directly:

curl -X POST http://localhost:4021/bridge \
  -H "Content-Type: application/json" \
  -d '{
    "chain": "algorand",
    "amount": "1.0", 
    "destinationAddress": "TEST123",
    "memo": "test bridge"
  }'

This should return a 402 Payment Required response with X402 headers.

Required Environment Variables

X402 Server (.env):

• CDP_API_KEY_ID - Coinbase CDP API key ID
• CDP_API_KEY_SECRET - Coinbase CDP API key secret
• CDP_WALLET_SECRET - Coinbase CDP wallet secret
• CDP_ACCOUNT_NAME - Name of the CDP account to use for transactions
• PAYMENT_RECIPIENT - Address to receive X402 payments

MCP Server (.env):

• RESOURCE_SERVER_URL - Bridge API URL (default: http://localhost:4021)
• PRIVATE_KEY - Private key for account making payments (needs USDC balance)