Claude Code integration

Claude Code runs @burnbound/mcp as a local stdio MCP server. Once added, Claude Code can call fetch_paid to pay x402 APIs and get_budget to check what it may spend, and every payment is checked against your agent's policy before it is signed. This page has the exact configuration for each scope, the permission rules worth adding, and fixes for common problems. Syntax as documented in the Claude Code docs: Connect to MCP servers and the MCP reference.

Add the server for all your projects

You need Node.js 20 or later and an agent key (bb_agent_…) from the Burnbound dashboard, which shows this line with the key filled in:

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

• burnbound is the server name. Tools appear in Claude Code as mcp__burnbound__fetch_paid, mcp__burnbound__get_budget and so on.
• -e (--env) sets an environment variable for the server. BURNBOUND_KEY is the only required one.
• Everything after -- is the command Claude Code runs.

Check that it is registered and connected:

claude mcp list
claude mcp get burnbound

Inside a session, /mcp shows the server's status and its tools.

Which scope should I use?

If the same name exists in more than one scope, local wins over project, and project over user. One Burnbound agent per workload keeps caps and audit separate: you can register a different key per project with the default local scope.

Share it with a team without committing the key

A project .mcp.json is meant to be committed, so keep the key out of it. Claude Code expands ${VAR} (and ${VAR:-default}) from the environment in command, args and env:

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

Each developer exports their own agent key (export BURNBOUND_KEY=bb_agent_… in their shell profile) before starting Claude Code. Claude Code reads .mcp.json at session start and asks each person to approve a project server the first time; claude mcp reset-project-choices undoes a rejection.

Permissions: ask before paying

fetch_paid is the only tool that can spend money; the other four only read. A sensible setup lets the read-only tools run and keeps a prompt on every payment. In .claude/settings.json (project) or ~/.claude/settings.json (all projects):

{
  "permissions": {
    "allow": [
      "mcp__burnbound__get_budget",
      "mcp__burnbound__list_payments",
      "mcp__burnbound__get_approval_status",
      "mcp__burnbound__search_paid_apis"
    ],
    "ask": ["mcp__burnbound__fetch_paid"]
  }
}

The Burnbound policy applies whatever you choose here: a prompt you approve still cannot push a payment past the agent's caps or allowed hosts. Rule syntax is in the Claude Code permissions docs.

If the agent signs with a key on your machine (client-side signing), also deny the usual ways to read it. These rules reduce accidents; they are not a sandbox, which is why Coinbase CDP is the stronger choice for coding agents:

{
  "permissions": {
    "deny": [
      "Read(~/.burnbound/**)",
      "Edit(~/.burnbound/**)",
      "Bash(security find-generic-password:*)",
      "Bash(security dump-keychain:*)",
      "Bash(secret-tool lookup:*)",
      "Bash(npx -y @burnbound/mcp wallet export:*)"
    ]
  }
}

First call

Ask Claude Code:

What is my Burnbound budget?

Then a paid request on one of the agent's allowed hosts, for example Tavily search (0.01 USDC per call on Base when we last verified it):

Use fetch_paid to POST https://x402.tavily.com/search with the JSON body
{"query": "what is x402?", "max_results": 3}, the header
Content-Type: application/json, and maxAmountUsd "0.02".

More sellers, with their hosts and prices, are in the x402 API catalog. The full walkthrough is in How to pay an x402 API from Claude Code.

Windows

claude mcp add works the same in PowerShell and Command Prompt, so the command above needs no changes. On Windows, ~/.claude.json is %USERPROFILE%\.claude.json.

Client-side signing on Windows stores the wallet in a file and is experimental. Prefer Coinbase CDP there.

Troubleshooting

To remove the server: claude mcp remove burnbound (add --scope user if you added it there).

Related

• Quickstart: from sign-up to the first payment.
• MCP tools reference: every input, result and error code.
• Cursor and Claude Desktop setups.