# 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

```bash
pnpm install
cp .env.example .env
```

Edit `.env`:

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

## Run (MCP server)

```bash
pnpm dev
```

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

## Run (x402 example resource server)

In another terminal (separate repo):

```bash
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):

```json
{
  "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).