x402-mcp

Minimal MCP server that calls an x402-paid HTTP API and automatically pays when it receives an HTTP 402 Payment Required.

This is basically the official guide implemented as a standalone repo so we can reuse it as context for:

• seo402
• agent-casino
• any other x402-enabled project

What this does

• Exposes an MCP tool: get-data-from-resource-server
• Tool calls GET ${ENDPOINT_PATH} against ${RESOURCE_SERVER_URL}
• If the API responds with 402 + PAYMENT-REQUIRED, the x402 axios wrapper:
  • parses requirements
  • signs a payment with your wallet
  • retries the request with the payment signature

Prerequisites

• Node.js 20+
• pnpm 10+
• An EVM wallet with USDC on Base Sepolia (recommended for testing)
• An x402-compatible server to call
  • easiest: Coinbase x402 example server (servers/express)

Setup

pnpm install
cp .env.example .env

Edit .env:

• EVM_PRIVATE_KEY=0x...
• RESOURCE_SERVER_URL=http://localhost:4021
• ENDPOINT_PATH=/weather

Run (MCP server)

pnpm dev

This runs an MCP server over stdio (what Claude Desktop expects).

Run (x402 example resource server)

In another terminal (separate repo):

git clone https://github.com/coinbase/x402.git
cd x402/examples/typescript
pnpm install && pnpm build
cd servers/express
pnpm dev

Claude Desktop config

Add this to your Claude Desktop config (exact file location depends on OS):

{
  "mcpServers": {
    "x402": {
      "command": "pnpm",
      "args": [
        "--silent",
        "-C",
        "<ABS_PATH_TO>/x402-mcp",
        "dev"
      ],
      "env": {
        "EVM_PRIVATE_KEY": "0x...",
        "RESOURCE_SERVER_URL": "http://localhost:4021",
        "ENDPOINT_PATH": "/weather"
      }
    }
  }
}

Restart Claude Desktop.

Then ask Claude to call the tool get-data-from-resource-server.

---

How do non-crypto people / agents pay?

x402 always needs a signer somewhere. There are basically 3 viable UX models:

1. Power-user model (today): the human running the agent sets EVM_PRIVATE_KEY (or a wallet connector) and pre-funds it with USDC.

   • simple, works now
   • best for builders

2. Custodial / hosted wallet (most mainstream): the app generates a wallet for the user and stores the key server-side (or in an HSM).

   • the agent never touches keys
   • user pays with Stripe / card → we top up their USDC balance behind the scenes
   • best UX, but adds legal/ops complexity

3. Delegated spender / allowance model: user keeps their own wallet, but grants allowance to a payer service.

   • payer service signs x402 payments up to limits
   • better than full custody, but still more complex than (1)

For MVP, we should assume (1). For real distribution, we probably evolve toward (2) or (3).