Vercel AI SDK integration

The Vercel AI SDK can load tools from any MCP server. Point its MCP client at @burnbound/mcp and generateText or streamText get fetch_paid and the other Burnbound tools: your agent can pay x402 APIs, and each payment is checked against its Burnbound policy (allowed hosts, maximum per payment, daily cap, approvals) before it is signed. Client API as documented in the AI SDK MCP tools guide.

This page uses the MCP server because the Burnbound JavaScript SDK is not published on npm yet (see SDK). Everything here is a published package.

Install

npm install ai @ai-sdk/mcp @ai-sdk/anthropic @burnbound/mcp

Tested with ai 7.0, @ai-sdk/mcp 2.0 and @burnbound/mcp 0.3.1 on Node.js 22. Any model provider works; the example uses Anthropic.

You need an agent key (bb_agent_…) from the Burnbound dashboard, for an agent with its caps, allowed hosts and a connected wallet. The Quickstart sets that up.

Connect the Burnbound tools

import { anthropic } from "@ai-sdk/anthropic";
import { createMCPClient } from "@ai-sdk/mcp";
import { Experimental_StdioMCPTransport } from "@ai-sdk/mcp/mcp-stdio";
import { generateText, isStepCount } from "ai";

const burnbound = await createMCPClient({
  transport: new Experimental_StdioMCPTransport({
    command: "npx",
    args: ["-y", "@burnbound/mcp"],
    env: { BURNBOUND_KEY: process.env.BURNBOUND_KEY! },
  }),
});

try {
  const { text } = await generateText({
    model: anthropic("claude-opus-5-5"),
    tools: await burnbound.tools(),
    stopWhen: isStepCount(10),
    system:
      "Pay for APIs only with the fetch_paid tool. Call get_budget first. " +
      "If fetch_paid returns an error, report its code instead of retrying.",
    prompt:
      'Search the web with Exa for "x402 payments": POST https://api.exa.ai/search ' +
      'with the JSON body {"query": "x402 payments", "numResults": 5}, maxAmountUsd "0.02".',
  });
  console.log(text);
} finally {
  await burnbound.close();
}

burnbound.tools() returns the five tools under their own names: fetch_paid, get_budget, list_payments, get_approval_status and search_paid_apis. The example pays Exa (0.007 USDC per search on Base when we last verified it), so api.exa.ai must be in the agent's allowed hosts. Other sellers are in the x402 API catalog.

Pass every Burnbound variable in env

The stdio transport does not hand your whole environment to the server, only a few variables such as PATH and HOME. Put every BURNBOUND_* variable the server needs in env explicitly: BURNBOUND_KEY always, and BURNBOUND_WALLET_PROFILE if the agent signs with a non-default local wallet. The full list is in the MCP tools reference.

What the model sees when a payment is refused

A denied payment does not throw. The MCP result comes back with isError: true and a JSON body, and the AI SDK returns it to the model without retrying, so the model can read the code and tell you:

{
  "error": {
    "code": "policy_denied",
    "message": "The agent's spending policy denied this payment, so nothing was paid. See reasons.",
    "reasons": ["daily_cap_exceeded"],
    "policyVersion": 4
  }
}

The policy holds whatever the model decides. The prompt line about errors only keeps the model from looping on a refusal. Payments above the agent's approval threshold come back as pending_approval; see Human approval for agent payments with Slack for the retry flow.

Where it can run

The server is a child process started with npx, so it needs Node.js 20 or later on the machine that runs your agent. The AI SDK docs say the stdio transport is for local servers and cannot be deployed to production environments, and @burnbound/mcp only speaks stdio. So this setup fits agents that run where they can start a child process (your machine, a CI job, a long-running process you operate), not serverless or edge functions.

If the agent signs with a local wallet (client-side signing), the key must be in the same machine's keychain or in ~/.burnbound. In a container or a shared server, prefer a Coinbase CDP wallet: nothing on the machine can then sign. See Agent wallets: Coinbase CDP vs a local key.

How this example was tested

We ran this wiring end to end with @burnbound/mcp 0.3.1: the AI SDK client listed the five tools, get_budget returned the agent's budget, and fetch_paid paid a Base Sepolia test seller (status: "paid"), calling the tool through the AI SDK's own tool object. The model call itself is standard AI SDK code.

Related

• LangChain.js and Mastra: the same server in other frameworks.
• How to limit an AI agent's spending: every limit the policy applies.
• Quickstart: create the agent and its key.