x402 MCP server: setup for Claude Code and Cursor

An x402 MCP server gives an AI agent a tool that fetches a URL and, when the URL answers 402 Payment Required, pays it in USDC and returns the paid response. Because it is an MCP server, the same package works in Claude Code, Cursor, Claude Desktop and any agent framework with an MCP client. This guide explains what such a server should do and sets up @burnbound/mcp, an x402 MCP server that pays only within limits you set, in Claude Code and Cursor.

What an x402 MCP server does

Without one, an agent that meets a 402 is stuck: it would need a wallet, the x402 headers and the signing code. An x402 MCP server wraps that in a tool call. The agent asks for a URL; the server handles the challenge, the signature and the retry.

That convenience is also the risk. A tool that can pay is a tool that can overspend, and the model decides when to call it. So a payment tool should check every payment against rules the agent cannot change, before anything is signed. @burnbound/mcp does this by asking the Burnbound API to evaluate the agent's policy (allowed hosts, a maximum per payment, a daily cap, optional human approval) for every 402. The wallet is yours: Coinbase CDP or a key on your machine.

The five tools

@burnbound/mcp 0.3 exposes five tools. Only fetch_paid can spend money; the other four are read-only.

fetch_paid returns paid, ok (no payment needed) or pending_approval; anything else is an error with a stable code such as host_not_allowed or policy_denied. The MCP tools reference documents every field and error.

Before you install

• Node.js 20 or later, with npx on the PATH your MCP client sees.
• A Burnbound agent with its caps and allowed hosts, and its agent key (bb_agent_…). The onboarding at app.burnbound.dev creates both and shows the key once.
• A wallet connected to the agent, with a small USDC balance on its network (Base, or Base Sepolia for tests).

The server reads its configuration from environment variables only. BURNBOUND_KEY is the only required one.

Setup in Claude Code

One command registers the server for every project (--scope user):

claude mcp add burnbound --scope user -e BURNBOUND_KEY=bb_agent_… -- npx -y @burnbound/mcp

Check it with claude mcp list, or /mcp inside a session. To share the server with a team through a project .mcp.json without committing the key, and to set permissions for fetch_paid, see the Claude Code integration.

Setup in Cursor

Add the server to ~/.cursor/mcp.json (every project) or .cursor/mcp.json (one project):

{
  "mcpServers": {
    "burnbound": {
      "command": "npx",
      "args": ["-y", "@burnbound/mcp"],
      "env": {
        "BURNBOUND_KEY": "bb_agent_…"
      }
    }
  }
}

Do not commit a file that contains the key. The Cursor integration shows how to read the key from your environment instead, and where to see the server's logs.

Check the connection

Ask the agent: "What is my Burnbound budget?". It calls get_budget. If the server does not start, its stderr says why:

• BURNBOUND_KEY is required.: the key is missing from the config.
• BURNBOUND_KEY has an invalid format.: it was pasted with extra characters.

If it starts but every tool answers unauthorized, the key was revoked or mistyped.

Make a first paid call

Pick a seller and add its host to the agent's allowed hosts. The x402 API catalog lists verified sellers with their host and price, for example You.com search at api.you.com, which charged 0.005 USDC per call on Base when we last verified it. Then:

Use fetch_paid to GET https://api.you.com/v1/search?query=x402&count=5 with maxAmountUsd "0.02".

Or let the agent find one: Use search_paid_apis to find a web search API I can pay. Each result says whether the policy allows it and, if not, why (host_not_allowed, network_not_allowed…).

For a first test without real money, put the agent on Base Sepolia and use our testnet demo seller at https://demo.burnbound.dev/premium (0.01 test USDC), as described in the Quickstart.

What the server protects against

Beyond the policy, the server adds guards on your machine:

• the agent key goes only to the Burnbound API, never to the URLs it fetches, and never appears in tool results;
• it requests only allowed hosts, and blocks private, loopback and link-local addresses;
• it never follows a redirect after paying, and refuses a challenge for another host;
• seller responses come back fenced and labelled as untrusted, so a paid API cannot pass its text off as your instructions;
• it fails closed: if Burnbound cannot be reached, nothing is paid.

Signing with a key on your machine is cooperative: an agent that can run shell commands could read it. Agent wallets: Coinbase CDP vs a local key explains when to use CDP instead.

Other clients and frameworks

The same server works with any MCP client that runs stdio servers: see the setups for Claude Desktop, the Vercel AI SDK, LangChain.js and Mastra. Starting from zero? The Quickstart takes you from sign-up to the first payment.