Agent account SDK & local MCP

Agents can use Bruce today over the REST API or the hosted MCP server. For agents that hold a local P-256 key on your machine, the @bruce/agent-sdk package and @bruce/agent-mcp stdio server wrap key generation, signup, session refresh, and local payment signing.

Use REST or Hosted MCP right now If @bruce/agent-sdk or @bruce/agent-mcp is not yet available from your npm registry mirror, use the zero-install REST quickstart (Node 20+ built-in WebCrypto) or the hosted MCP config below, or build the packages directly from the monorepo (npm run build --workspace=@bruce/agent-sdk --workspace=@bruce/agent-mcp).

Hosted MCP (one-line config, no install)

For delegated agent spend or merchant tools with no local package install, point any MCP client at https://mcp.bruce.money/mcp:

{
  "mcpServers": {
    "bruce": {
      "url": "https://mcp.bruce.money/mcp",
      "headers": { "Authorization": "Bearer bk_agent_live_…" }
    }
  }
}

REST quickstart (zero dependencies, Node 20+)

Every SDK method maps 1:1 to a documented REST endpoint in openapi-v1.json, including payment requests (POST /api/payment-requests) and signed sends (POST /api/transactions/send/prepare → POST /api/transactions/send):

import { createHash, subtle } from "node:crypto";

const API = "https://api.bruce.money";

// 1. Generate P-256 keypair & solve proof-of-work
const kp = await subtle.generateKey({ name: "ECDSA", namedCurve: "P-256" }, true, ["sign", "verify"]);
const publicKey = Buffer.from(await subtle.exportKey("spki", kp.publicKey)).toString("base64");
const pow = await fetch(`${API}/api/agent-auth/pow`).then((r) => r.json());
let nonce = 0;
while (true) {
  const digest = createHash("sha256").update(`${pow.token}:${nonce}`).digest();
  let zeros = 0;
  for (const b of digest) {
    if (b === 0) { zeros += 8; continue; }
    zeros += Math.clz32(b) - 24;
    break;
  }
  if (zeros >= pow.bits) break;
  nonce++;
}

// 2. Register & open a bas_ session
await fetch(`${API}/api/agent-auth/register`, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ publicKey, pow: { token: pow.token, nonce: String(nonce) }, displayName: "Research agent" }),
});
const { challengeId, message } = await fetch(`${API}/api/agent-auth/challenge`, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ publicKey }),
}).then((r) => r.json());
const sig = Buffer.from(
  await subtle.sign({ name: "ECDSA", hash: "SHA-256" }, kp.privateKey, new TextEncoder().encode(message)),
).toString("base64");
const { accessToken } = await fetch(`${API}/api/agent-auth/session`, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ challengeId, signature: sig }),
}).then((r) => r.json());

// 3. Check balance or create a payment request (amounts in USD/USDC)
const headers = { Authorization: `Bearer ${accessToken}`, "Content-Type": "application/json" };
const balance = await fetch(`${API}/api/me/balance`, { headers }).then((r) => r.json());
await fetch(`${API}/api/payment-requests`, {
  method: "POST",
  headers,
  body: JSON.stringify({ recipientUserId: "USER_UUID", amount: "12.00", memo: "Report" }),
});

TypeScript SDK

The SDK has no dependencies and uses WebCrypto. It runs on Node 20 and later, Deno, Bun, Workers and browsers.

import { BruceAgent } from "@bruce/agent-sdk";

// One time: creates the key and the account. Store `key` somewhere secret.
const { agent, key, account } = await BruceAgent.createAccount({
  displayName: "Research agent",
  username: "research_agent",
});

// Later: rebuild the client from the stored key.
const bruce = new BruceAgent({ key });

await bruce.balance();
await bruce.pay({ to: "alice", amount: "5.00", memo: "API credits" });
const details = await bruce.payDetails.share({ amount: "20" }); // handle, payUrl, wallet
await bruce.requests.create({ recipientUserId, amount: "12.00", memo: "Report" });
await bruce.paymentLinks.create({ amount: "9.99", memo: "Dataset" });
await bruce.escrow.relay(escrowId, "deposit");          // signed and auto-confirmed
await bruce.batch.send((await bruce.batch.create(rows)).batch.id);

// Any other prepare/submit pair:
await bruce.signedCall("/api/escrows/ID/relay/prepare", "/api/escrows/ID/relay", { action: "release" });
// Any other route:
await bruce.request("GET", "/api/notifications");

The SDK logs in again automatically before a session expires. Pass onSession to cache sessions, and orgId to act inside an organization.

With an owner

// Signup that a person approves in the Bruce app (they set the limits).
const { agent, key, request } = await BruceAgent.onboard({ owner: "alice", displayName: "Research agent" });
const result = await agent.waitForOnboarding(request.requestId); // approved | declined | expired

// Above a limit: asks the owner, waits, then pays.
await agent.payWithApproval({ to: "hosting_co", amount: "120.00", reason: "Monthly GPU hosting" });

// Safe retries: the same key never pays twice.
await agent.pay({ to: "alice", amount: "5.00", idempotencyKey: crypto.randomUUID() });

Also available: owner.link, owner.status, owner.confirm, owner.unlink, owner.activity, and approvals.request / get / wait / list / cancel. Errors carry code and a recovery hint.

Local MCP server

The hosted Bruce MCP spends a person's balance through delegated keys. The local server is different: it gives the agent its own account. The key is stored in ~/.bruce/agent.json with owner-only permissions and never leaves the machine.

{
  "mcpServers": {
    "bruce-agent": {
      "command": "npx",
      "args": ["-y", "@bruce/agent-mcp"],
      "env": { "BRUCE_API_BASE": "https://api.bruce.money" }
    }
  }
}

The package installs two equivalent binaries, agent-mcp and bruce-agent-mcp, so a global install (npm i -g @bruce/agent-mcp) can use either name as the command.

Tools:

Environment variables:

Back up the key file Whoever has agent.json controls the wallet. If you lose the file, Bruce cannot recover the funds.