LangChain.js integration

LangChain.js loads MCP tools through @langchain/mcp-adapters. 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. Adapter API as documented in LangChain's MCP 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 langchain @langchain/core @langchain/mcp-adapters @langchain/anthropic @burnbound/mcp

Tested with langchain 1.5, @langchain/mcp-adapters 2.0 and @burnbound/mcp 0.3.1 on Node.js 22. Any chat model 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 { MCPAdapter } from "@langchain/mcp-adapters";
import { createAgent } from "langchain";

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

try {
  const agent = createAgent({
    model: "anthropic:claude-opus-5-5",
    tools: await burnbound.listTools(),
    systemPrompt:
      "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.",
  });
  const result = await agent.invoke({
    messages: [
      {
        role: "user",
        content:
          'Search the web with Tavily for "what is x402": POST https://x402.tavily.com/search ' +
          'with the JSON body {"query": "what is x402", "max_results": 3}, maxAmountUsd "0.02".',
      },
    ],
  });
  console.log(result.messages.at(-1)?.content);
} finally {
  await burnbound.close();
}

Keep the adapter open while the agent runs and close it in finally, as LangChain recommends. The example pays Tavily (0.01 USDC per search on Base when we last verified it), so x402.tavily.com must be in the agent's allowed hosts. Other sellers are in the x402 API catalog.

Tool names carry the server name

@langchain/mcp-adapters 2.0 prefixes each tool with the server name, 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 your prompts. (Version 1.x called the class MultiServerMCPClient, used mcpServers and getTools(), and did not prefix names; those names still work in 2.0 but are deprecated.)

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: 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 adapter raises a ToolException whose message carries the server's error JSON, for example:

{
  "error": {
    "code": "host_not_allowed",
    "message": "The URL's host is not in this agent's allowHosts, so nothing was requested. Check get_budget.",
    "host": "api.example.com"
  }
}

Nothing was paid in that case. 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 (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 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: the adapter listed the five tools, get_budget returned the agent's budget, and fetch_paid paid a Base Sepolia test seller (status: "paid"), invoking the LangChain tool objects directly. The agent call itself is standard LangChain code.

Related

• Vercel AI SDK and Mastra: the same server in other frameworks.
• x402 v2 buyer flow explained: what fetch_paid does on each call.
• Quickstart: create the agent and its key.