402 MCP — Restaurant Finder with Paid Tools

A demo MCP server that shows agentic commerce with x402: 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.

Tools

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

Related MCP server: x402-discovery

Prerequisites

1. Node.js 20+ and wrangler (npm i -g wrangler)

2. A wallet — generate an EVM private key:

   npx viem generate-private-key

3. Testnet USDC — get free USDC on Base Sepolia from the Circle Faucet

4. Cloudflare account — wrangler login

Setup

Install dependencies:

npm install

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

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

Run locally

npm run dev

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

Deploy

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:

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/

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. In Claude Desktop, go to Settings > Developer > Edit Config:

{
  "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.

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