Quickstart: Claude Code and Cursor
This guide takes you from a new Burnbound account to your agent's first decision under a policy. You create an agent with caps, choose what it does with money (refund Stripe charges, pay with a Stripe Issuing card, or pay x402 APIs), connect that rail, and add the Burnbound MCP server to Claude Code or Cursor. Start with test mode or a testnet: nothing real has to move.
Which rail do I start with?
Burnbound is spend control for AI agents. An agent can move money in three ways, and you turn each one on per agent. Pick the one your agent needs; you can add the others later.
| Rail | What the agent does | What you connect | How the agent asks |
|---|---|---|---|
| Refunds | Refunds a Stripe charge, for example a support agent | An action gateway you run, with your own restricted Stripe key | The MCP tool stripe_refund |
| Cards | Pays a merchant with a card | Your own Stripe Issuing account, through a card connector | No tool: Stripe asks Burnbound each time |
| Paid APIs | Pays an API that answers 402 Payment Required |
A wallet you bring: Coinbase CDP or a key on your own machine | The MCP tool fetch_paid |
Whatever the rail, the controls are the same: a maximum per payment and a daily cap in USD, team budgets, your own rules, human approval above a threshold, and one audit log for every decision. A refund, a card authorization and an API payment all count toward the same caps. Refunds and cards are in beta: start in Stripe's test mode.
What do I need before I start?
You need a Burnbound account and, for refunds and paid APIs, an MCP client. Burnbound never holds funds: refunds leave your Stripe account, card money stays in your Stripe Issuing balance, and API payments come from your own wallet.
- A Burnbound account: go to burnbound.dev and click Sign up.
- An MCP client: Claude Code or Cursor, with Node.js 20 or later (
npxon itsPATH; check withnode --version). Any other MCP client that runs stdio servers works the same way. - Refunds: a Stripe account in test mode with a test charge to refund, and Docker on the machine that runs the gateway (it ships as a public image). You need
@burnbound/mcp0.10.0 or later. - Cards: a Stripe account with Issuing enabled. Stripe has to approve Issuing for your account, and it is not available in every country. An owner or admin of your Burnbound organization sets up the connector.
- Paid APIs: a wallet with a small USDC balance on the agent's network: Base for real payments, or Base Sepolia to test with free test USDC.
Step 1: How do I create an agent and its key?
Create the agent in the Burnbound dashboard. An agent has a name, a daily cap, a maximum per payment, a list of allowed hosts and, for paid APIs, the network it pays on. Keep the caps small at first.
The onboarding starts right after you register and walks you through the paid-API rail:
- Open the onboarding in the dashboard and create the agent.
- Set the daily cap, the maximum per payment and the hosts the agent may pay, for example
api.example.comor*.example.com. x402 calls usually cost cents. - Choose the network: Base for real payments (the default) or Base Sepolia to test with test USDC. See Which network should my agent use?.
- Continue to the wallet step (Step 2). The key is created in the step after it.
For refunds or cards, create the agent from Agents → + New agent instead, set its caps, and create its key in the agent's Keys tab. A card-only agent needs no key: Stripe asks Burnbound, not the agent.
The agent key starts with bb_agent_. The dashboard shows it only once, inside a ready-to-paste install command. Burnbound stores only a hash of it, so a lost key cannot be shown again: revoke it and create a new one.
Step 2: How do I connect the rail?
Each rail connects to where the money really is. Burnbound decides; your gateway, your Stripe account or your wallet moves the money. Every method is off until you turn it on in the agent's Network tab, under Payment methods (x402 is on by default).
Refunds: run the action gateway
The action gateway is a small service you run next to your agents, with a restricted Stripe key (Charges, Customers and PaymentIntents read, Refunds write). It reads the real charge from Stripe, asks Burnbound, and refunds only on allow. Your Stripe key never reaches Burnbound, and the gateway refuses a live key unless you set GATEWAY_ALLOW_LIVE=1.
- In the dashboard, under Organization, create an action gateway and copy its id and
bbgw_…secret (shown once). - Run the gateway with your test-mode key and those two values.
- On the agent, turn on Stripe · refund and add
stripe-refund.actionto its allowed hosts.
Action gateway: Stripe refunds under your agent's policy has the exact commands. Step 3 below adds the gateway's URL to the MCP server.
Cards: connect Stripe Issuing
Stripe asks Burnbound before every authorization on the agent's card, and Burnbound answers within Stripe's 2-second window. Burnbound keeps only the webhook's signing secret, encrypted; no Stripe key.
- Under Organization → Cards (Stripe Issuing), create the connector and copy its webhook URL.
- In Stripe, point real-time authorizations and an events endpoint at that URL, and paste their signing secrets into the connector.
- Tag each card with
burnbound_agent_id, then turn on Stripe Issuing · card on the agent and allow its merchants.
Cards for AI agents with Stripe Issuing walks through each step. A card cannot wait for a person: a payment that would need an approval is declined.
Paid APIs: connect the wallet that signs
An agent that pays APIs needs a wallet that signs its payments. Burnbound decides whether a payment is allowed; the wallet signs it. You choose one of two modes in the dashboard. See Concepts for the trade-offs.
Coinbase CDP. Paste your Coinbase Developer Platform credentials (API key ID, API key secret, wallet secret) and the wallet address. The private key stays with Coinbase.
Wallet on your machine (client-side signing). Create the wallet locally and register only its public address:
npx -y @burnbound/mcp@latest wallet init
The command prints the address. Paste it in the dashboard. The private key stays in your OS keychain (or a file only your user can read) and is never sent to Burnbound.
Then fund the wallet with a small USDC balance on the agent's network: real USDC on Base, or test USDC from the Circle faucet on Base Sepolia. It needs no ETH: in x402 the seller's facilitator submits the transfer and pays the gas.
Refunds and cards need no wallet.
Which network should my agent use?
Each agent pays USDC over x402 on one network (paying USDC.e over MPP on Tempo is a separate opt-in, see Concepts). The seller's x402 API must charge on that same network; if it asks for another one, the payment is denied with network_not_allowed and nothing is signed.
| Network | Id | Use it for |
|---|---|---|
| Base | eip155:8453 |
Real payments in USDC. The default for new agents. |
| Base Sepolia | eip155:84532 |
Tests. The USDC has no value; get it from the Circle faucet. A test network. |
You choose the network when you create the agent in the onboarding. To change it later, open the agent in the dashboard and use its Network tab. The change applies to the agent's next payment. Fund the wallet on the network you chose: USDC on Base Sepolia cannot pay a seller on Base, and the other way round.
Step 3: How do I add Burnbound to Claude Code?
Run claude mcp add with your agent key in BURNBOUND_KEY. The dashboard shows this exact line with your key already filled in; copy it from there.
claude mcp add burnbound --scope user -e BURNBOUND_KEY=bb_agent_… -- npx -y @burnbound/mcp@latest
Check that the server is registered:
claude mcp list
For refunds, add the gateway's URL too: without BURNBOUND_GATEWAY_URL, stripe_refund refunds nothing.
claude mcp add burnbound --scope user -e BURNBOUND_KEY=bb_agent_… \
-e BURNBOUND_GATEWAY_URL=<gateway URL> -- npx -y @burnbound/mcp@latest
How do I add Burnbound to Cursor?
Add the server to .cursor/mcp.json in your project, or to ~/.cursor/mcp.json for every project, with your agent key in env:
{
"mcpServers": {
"burnbound": {
"command": "npx",
"args": ["-y", "@burnbound/mcp@latest"],
"env": {
"BURNBOUND_KEY": "bb_agent_…"
}
}
}
}
For refunds, add "BURNBOUND_GATEWAY_URL": "<gateway URL>" next to the key. Do not commit a file that contains the key. Restart Cursor or reload its MCP servers after you edit the file.
Using Claude Desktop, the Vercel AI SDK, LangChain.js or Mastra? The integrations have the exact setup for each, and the Claude Code and Cursor pages cover project-level config, permissions and troubleshooting.
Step 4: How do I check that the agent is connected?
Ask your agent: "What is my Burnbound budget?". It calls get_budget, which returns what the agent spent today, its daily cap, what remains, the maximum per payment, its approval threshold, when the daily spend resets, its network and its allowed hosts. If that works, the key and the connection to Burnbound are fine.
If the server does not start, read its log on stderr (in Claude Code, claude mcp list shows it as failed):
BURNBOUND_KEY is required.: the key is missing from the MCP config.BURNBOUND_KEY has an invalid format.: the value was pasted with extra characters.
If it starts but every tool answers unauthorized, the key was revoked or mistyped. Create a new one in the dashboard.
Step 5: How do I get the first decision?
Make one request on the rail you connected. A block is a good first test too: it proves the policy is enforced. Every decision, allowed or not, is in the dashboard audit with its reason.
A refund
Ask the agent: "Refund 3 euros of charge ch_… to the customer", with a test charge. It calls stripe_refund. The result is refunded with the Stripe refund id, pending_approval if the amount is at or above the agent's approval threshold (a person approves it in the dashboard, and the agent retries with the same idempotencyKey), or a tool error such as refund_denied with its reasons. Asked twice, the same refund happens once.
A card authorization
Create a test authorization on the tagged card with Stripe's test helpers, for example 5.00 EUR at computer_software_stores. Within the caps it is approved; over the maximum per payment it is declined. It shows in Spend with the merchant and the amount in both currencies. The cards guide has the commands.
A paid API call
Ask the agent to fetch a URL of an x402 API on one of its allowed hosts, with a small maxAmountUsd. The API must charge on the agent's network: for a first test without real money, use an agent on Base Sepolia and an x402 API that charges on Base Sepolia. The agent calls fetch_paid; if the URL answers HTTP 402, Burnbound checks the payment against your rules, the wallet signs it, and the agent gets the paid response.
A prompt like this is enough:
Use fetch_paid to GET https://api.example.com/v1/report with maxAmountUsd "0.05".
The result tells you what happened:
paid: the payment was signed and sent. It includesamountUsd,intentIdand areceipt. The payment appears in the dashboard.ok: the URL did not ask for payment, so nothing was paid.pending_approval: a human must approve first, for example because it is the first payment to this seller's receiving address (reason: "new_pay_to") or the amount is at or above the agent's approval threshold. A human approves it in the dashboard, then the agent retries (see Concepts).- A tool error with a code, such as
policy_deniedorhost_not_allowed: nothing was paid. A denial is also a good first test: it proves the rules are enforced. Denials are listed in the dashboard audit with their reason.
Try it against our demo seller (Base Sepolia)
To try the whole flow without a real seller, use our demo x402 seller at https://demo.burnbound.dev. It is testnet only: it sells on Base Sepolia (eip155:84532) for test USDC, and nothing it serves has real value. Never pay it from a wallet that holds real funds.
| URL | Price | What it shows with the onboarding defaults (1 USD per payment, 10 USD a day) |
|---|---|---|
https://demo.burnbound.dev/premium |
0.01 USDC | A paid request. |
https://demo.burnbound.dev/report |
0.50 USDC | pending_approval if the agent's approval threshold is 0.50 USD or lower; otherwise paid. |
https://demo.burnbound.dev/dataset |
2.00 USDC | policy_denied with amount_exceeds_per_transaction. |
Before you start, add demo.burnbound.dev to the agent's allowed hosts and fund its wallet with Base Sepolia USDC from Circle's faucet. The agent's policy must allow Base Sepolia: an agent that allows Base mainnet only, the default for new agents, gets policy_denied with network_not_allowed, and nothing is paid. Give fetch_paid a maxAmountUsd at or above the price, for example:
Use fetch_paid to GET https://demo.burnbound.dev/premium with maxAmountUsd "0.05".
The demo seller is in the Burnbound catalog with its receiving address pinned, so its first payment does not wait for an approval: /premium is paid at once. If it ever asked to be paid at another address, the payment would be denied with pay_to_not_verified. Other sellers are different: the first payment of your organization to a receiving address it has not paid before waits once for your approval (pending_approval with reason: "new_pay_to"), unless the seller is listed in the catalog and asks to be paid at an address Burnbound pinned for it.
What can go wrong on the first call?
Most first-call errors come from the agent's rules, its wallet or its gateway, and every one means no money moved. The table lists the common ones; the MCP tools reference has the full list.
| Error | What to do |
|---|---|
host_not_allowed |
Add the URL's host to the agent's allowed hosts in the dashboard. Nothing was requested. |
policy_denied with daily_cap_exceeded |
The payment would go over today's cap (UTC day). Raise the cap or wait for the next day. |
policy_denied with amount_exceeds_per_transaction |
The price is over the maximum per payment. Raise it if you trust the seller. |
policy_denied with rule_limit_exceeded or rule_denied |
A custom rule refused the payment: the agent's (such as the weekly cap tope-semanal), its subteam's or the organization's. rules names it. Change it in the dashboard, or wait until its window resets. |
policy_denied with network_not_allowed |
The seller charges on a network the agent does not use. Change the agent's network in its Network tab, or pay a seller on the agent's network. |
amount_exceeds_max |
The price is over the maxAmountUsd of that call. |
client_wallet_not_initialized |
Client-side signing: run npx -y @burnbound/mcp@latest wallet init and register the address. |
client_wallet_mismatch |
Client-side signing: the local wallet is not the one registered for the agent. Register localAddress, or set BURNBOUND_WALLET_PROFILE. |
method_not_allowed (also in refund_denied) |
The rail is off for this agent. Turn it on in the agent's Network tab, under Payment methods. |
gateway_not_configured |
Refunds: BURNBOUND_GATEWAY_URL is not in the MCP config. Add the gateway's URL and restart the MCP server. |
currency_not_supported |
Refunds and cards: the currency has no exchange rate. USD always works; other currencies use the European Central Bank's daily rate, and any other needs a pinned rate on the server. |
card_not_linked |
Cards: the card has no burnbound_agent_id in its metadata, or it names an agent of another organization. |
approval_required |
Cards: the payment is at or above the agent's approval threshold, and a card cannot wait. Raise the threshold above what the card should pay on its own. |
plan_limit_reached |
Your plan's limit was reached (for example the Free plan's 3 agents). A human can upgrade at upgradeUrl. |
What next?
- Add custom rules to the agent: a weekly cap, a cap per host or merchant category, or an approval for new payees. Try them in observe mode first.
- See what counts as spend on each rail in Concepts, and every control in How to limit an AI agent's spending.
- Running several agents, or an agent with sub-agents? Give each one its own key and put them in a subteam with a shared budget.
- Read the security model before you move real money: a live Stripe key or a funded wallet.