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. The same server also refunds Stripe charges through your action gateway, under the same policy.
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 eight tools
@burnbound/mcp 0.10 exposes eight tools. Only fetch_paid and stripe_refund can move money. propose_rule writes a rule that can only restrict the agent; the other five are read-only.
| Tool | What the agent uses it for |
|---|---|
fetch_paid |
Request a URL on an allowed host and pay its x402 challenge, or its MPP tempo.charge when the agent has it enabled, under the policy. GET, POST and other methods, headers, body, and a per-call maxAmountUsd. |
get_budget |
Today's spend, the daily cap, what remains, the maximum per payment, the approval threshold, allowed hosts and network. |
list_payments |
Recent payments, with status, amount, host and transaction hash. |
get_approval_status |
Whether a human approved a payment that returned pending_approval. |
search_paid_apis |
Search Burnbound's catalog of verified x402 APIs, with price and whether the policy allows each one. |
diagnose_payment |
Find out, without paying, why a URL cannot be paid: a bad 402, a network or token Burnbound cannot pay, not enough USDC, or a seller that is down. |
stripe_refund |
Refund a Stripe charge under the agent's policy, through the action gateway you run with your own Stripe key (BURNBOUND_GATEWAY_URL). Large refunds wait for a human like payments do. |
propose_rule |
When you ask for it in the chat, add a rule that only restricts the agent's own payments ("no more than 2 USD a day on this host"). Only a human removes it. |
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
npxon thePATHyour MCP client sees. - A Burnbound agent with its caps and allowed hosts, and its agent key (
bb_agent_…). Go to burnbound.dev and click Sign up: the onboarding 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@latest
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@latest"],
"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.