# 402 MCP — Restaurant Finder with Paid Tools

A demo MCP server that shows **agentic commerce** with [x402](https://x402.org): AI agents can browse restaurants and menus for free, but must pay USDC to place an order.

Built on Cloudflare Workers + Durable Objects using the [Agents SDK](https://developers.cloudflare.com/agents/).

## Tools

| Tool | Cost | Description |
|------|------|-------------|
| `list_restaurants` | Free | List all restaurants with cuisine and rating |
| `show_menu` | Free | Show the menu for a restaurant by ID |
| `add_to_cart` | Free | Add an item to the cart |
| `pay_order` | 0.05 USDC | Place an order (requires x402 payment) |

Free tools return `200 OK`. The `pay_order` tool returns `402 Payment Required` with machine-readable payment instructions until payment is settled.

## Prerequisites

1. **Node.js 20+** and **wrangler** (`npm i -g wrangler`)
2. **A wallet** — generate an EVM private key:
   ```bash
   npx viem generate-private-key
   ```
3. **Testnet USDC** — get free USDC on Base Sepolia from the [Circle Faucet](https://faucet.circle.com/)
4. **Cloudflare account** — `wrangler login`

## Setup

Install dependencies:

```bash
npm install
```

Set your wallet address as the payment recipient in `src/index.ts`:

```typescript
const X402_CONFIG: X402Config = {
  network: "base-sepolia",
  recipient: "0xYourWalletAddress", // ← replace with your wallet address
  facilitator: { url: "https://x402.org/facilitator" },
};
```

## Run locally

```bash
npm run dev
```

The MCP server is available at `http://localhost:8787/mcp`.

## Deploy

```bash
npm run deploy
```

The MCP server will be available at `https://402-mcp.<your-subdomain>.workers.dev/mcp`.

## Test the 402 response

Call the paid `pay_order` tool without payment — it returns `402`:

```bash
curl -X POST http://localhost:8787/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": { "name": "pay_order", "arguments": { "order_id": 1 } }
  }'
```

Free tools like `list_restaurants` return `200` with no payment required.

## Connect from an MCP client

### Cloudflare AI Playground

1. Go to [https://playground.ai.cloudflare.com/](https://playground.ai.cloudflare.com/)
2. Enter your MCP server URL (`https://402-mcp.<your-subdomain>.workers.dev/mcp`)
3. Use the tools directly from the playground

### Claude Desktop

Use the [mcp-remote proxy](https://www.npmjs.com/package/mcp-remote). In Claude Desktop, go to Settings > Developer > Edit Config:

```json
{
  "mcpServers": {
    "restaurant-finder": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://localhost:8787/mcp"
      ]
    }
  }
}
```

Restart Claude and the tools will be available.

## How it works

The server uses `withX402()` from `agents/x402` to wrap the `McpServer`. Free tools are registered with `this.server.registerTool(...)`. Paid tools use `this.server.paidTool(...)` with a price in USDC — the x402 middleware intercepts calls and returns `402 Payment Required` with payment instructions until the client settles payment on-chain.

```typescript
export class MyMCP extends McpAgent {
  server = withX402(
    new McpServer({ name: "Restaurant Finder", version: "1.0.0" }),
    X402_CONFIG,
  );

  async init() {
    // Free tool
    this.server.registerTool("list_restaurants", { ... }, async () => { ... });

    // Paid tool — 0.05 USDC per call
    this.server.paidTool("pay_order", "Pay to place order", 0.05, { ... }, {}, async () => { ... });
  }
}
```

## References

| Resource | URL |
|---|---|
| x402 docs | https://developers.cloudflare.com/agents/x402 |
| Charge for MCP tools | https://developers.cloudflare.com/agents/tools/payments/x402/charge-for-mcp-tools |
| Pay from Agents SDK | https://developers.cloudflare.com/agents/tools/payments/x402/pay-from-agents-sdk |
| x402 protocol spec | https://x402.org |
| Circle Faucet (testnet USDC) | https://faucet.circle.com |
| x402 Playground | https://playground.x402.cloudflare.com |