Mastra integration

Mastra agents load MCP tools through MCPClient from @mastra/mcp. Connect it to @burnbound/mcp and your agent gets fetch_paid and the other Burnbound tools: it 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 Mastra MCPClient reference and MCP overview.

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 @mastra/core @mastra/mcp @burnbound/mcp

Tested with @mastra/core 1.74, @mastra/mcp 2.1 and @burnbound/mcp 0.3.1 on Node.js 22. The example uses Mastra's model router with an Anthropic model; any model Mastra supports works.

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 { Agent } from "@mastra/core/agent";
import { MCPClient } from "@mastra/mcp";

const burnbound = new MCPClient({
  id: "burnbound",
  servers: {
    burnbound: {
      command: "npx",
      args: ["-y", "@burnbound/mcp"],
      env: { BURNBOUND_KEY: process.env.BURNBOUND_KEY! },
    },
  },
});

try {
  const agent = new Agent({
    id: "paying-agent",
    name: "Paying agent",
    instructions:
      "Pay for APIs only with the burnbound_fetch_paid tool. Call burnbound_get_budget first. " +
      "If a Burnbound tool returns an error, report its code instead of retrying.",
    model: "anthropic/claude-opus-5-5",
    tools: await burnbound.listTools(),
  });
  const result = await agent.generate(
    "Find WETH pools on Ethereum with CoinGecko: GET " +
      "https://pro-api.coingecko.com/api/v3/x402/onchain/search/pools?query=weth&network=eth " +
      'with maxAmountUsd "0.02".',
  );
  console.log(result.text);
} finally {
  await burnbound.disconnect();
}

The example pays CoinGecko (0.01 USDC per call on Base when we last verified it), so pro-api.coingecko.com must be in the agent's allowed hosts. Other sellers are in the x402 API catalog.

Tool names carry the server name

listTools() namespaces each tool as serverName_toolName, so the agent sees burnbound_fetch_paid, burnbound_get_budget, burnbound_list_payments, burnbound_get_approval_status and burnbound_search_paid_apis. Use those names in the instructions. For tools chosen per request, listToolsets() returns the same tools to pass to generate() or stream().

Pass every Burnbound variable in env

Mastra starts stdio servers with a short list of variables from your environment (HOME, PATH, USER and a few more), not all of it. Put every BURNBOUND_* variable the server needs in env: 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.

When a payment is refused

When Burnbound refuses a payment, the tool call fails with an error whose message is the server's error JSON, for example {"error": {"code": "policy_denied", "reasons": ["amount_exceeds_per_transaction"], …}}. Nothing was paid. The policy holds whatever the model decides; the instruction about errors only keeps the agent from looping on a refusal. Payments above the agent's approval threshold come back as pending_approval (a normal result, not an error); 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 Mastra agent, and it does not fit serverless or edge functions. If the agent signs with a local wallet, the key must be in that machine's keychain or ~/.burnbound; in a container or shared server, prefer a Coinbase CDP wallet. 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: MCPClient listed the five tools, get_budget returned the agent's budget, and fetch_paid paid a Base Sepolia test seller (status: "paid"), executing the Mastra tool objects directly. The agent call itself is standard Mastra code.

Related

• Vercel AI SDK and LangChain.js: 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.