Quickstart: Claude Code and Cursor

This guide takes you from a new Burnbound account to your agent's first fetch_paid call. You create an agent with spending rules, connect the wallet that signs its payments, add the Burnbound MCP server to Claude Code or Cursor, and make a first request.

What do I need before I start?

You need Node.js 20 or later (with npx on the PATH of your MCP client), Claude Code or Cursor, and a Burnbound account. To pay for something, you also need a wallet with a small USDC balance on Base. Burnbound never holds funds: payments come from your own wallet.

• Node.js 20 or later: check with node --version.
• An MCP client: Claude Code or Cursor. Any other MCP client that runs stdio servers works the same way.
• A Burnbound account: create one at app.burnbound.dev.

Step 1: How do I create an agent and its key?

Create the agent in the Burnbound dashboard; the onboarding starts right after you register. An agent has a name, a daily cap, a maximum per payment and a list of allowed hosts. Keep the caps small at first: x402 calls usually cost cents.

1. Open the onboarding in the dashboard and create the agent.
2. Set the daily cap, the maximum per payment and the hosts the agent may pay, for example api.example.com or *.example.com.
3. Continue to the wallet step (Step 2). The key is created in the step after it.

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 wallet that signs?

Every agent 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 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 Base. It needs no ETH: in x402 the seller's facilitator submits the transfer and pays the gas.

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 -e BURNBOUND_KEY=bb_agent_… -- npx -y @burnbound/mcp

Check that the server is registered:

claude mcp list

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"],
      "env": {
        "BURNBOUND_KEY": "bb_agent_…"
      }
    }
  }
}

Do not commit a file that contains the key. Restart Cursor or reload its MCP servers after you edit the file.

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 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 make the first paid request?

Ask the agent to fetch a URL of an x402 API on one of its allowed hosts, with a small maxAmountUsd. 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 includes amountUsd, intentId and a receipt. The payment appears in the dashboard.
• ok: the URL did not ask for payment, so nothing was paid.
• pending_approval: 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_denied or host_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.

What can go wrong on the first call?

Most first-call errors come from the agent's rules or its wallet, and every one means nothing was paid. The table lists the common ones; the MCP tools reference has the full list.