Build a personal finance agent with the Claude Agent SDK

1. Get an API key

Sign up at bankbridge.money, connect at least one bank, and copy your bbk_ key from the dashboard. Put it in an environment variable, not in code:

export BANKBRIDGE_API_KEY=bbk_your_key_here

Keys are shown once and stored only as a hash on our side. If one leaks, rotate it; see rotating your API key.

2. Install the SDK

bun add @anthropic-ai/claude-agent-sdk

The examples below are TypeScript run with Bun. The Python SDK takes the same options with snake_case names.

3. Connect the MCP server

BankBridge speaks streamable HTTP, so it goes in mcpServers with type: "http" and your key in the headers:

// finance-agent.ts
import { query } from "@anthropic-ai/claude-agent-sdk";

const READ_TOOLS = [
  "list_accounts",
  "get_account",
  "list_transactions",
  "search_transactions",
  "get_spending_summary",
  "get_recurring_charges",
  "get_monthly_cashflow",
  "get_merchant_history",
  "list_categories",
  "list_holdings",
  "list_investment_transactions",
].map((t) => `mcp__bankbridge__${t}`);

const prompt =
  process.argv.slice(2).join(" ") ||
  "How much did I spend last month, by category? Exclude credit card payments and transfers between my accounts.";

for await (const message of query({
  prompt,
  options: {
    mcpServers: {
      bankbridge: {
        type: "http",
        url: "https://bankbridge.money/api/mcp",
        headers: { Authorization: `Bearer ${process.env.BANKBRIDGE_API_KEY}` },
      },
    },
    allowedTools: READ_TOOLS,
  },
})) {
  if (message.type === "system" && message.subtype === "init") {
    const bb = message.mcp_servers.find((s) => s.name === "bankbridge");
    if (bb?.status === "failed" || bb?.status === "needs-auth") {
      console.error("BankBridge not connected:", bb.status);
    }
  }
  if (message.type === "result" && message.subtype === "success") {
    console.log(message.result);
  }
}

bun finance-agent.ts "What are my recurring charges, and which went up this year?"

Tool names follow the SDK convention mcp__<server>__<tool>. The init message reports the server's status; a status of failed usually means a wrong or revoked key.

4. Allow only the read tools

You could allow everything with mcp__bankbridge__*. The explicit list above leaves out connect_bank, which returns a URL for a person to open in a browser. An unattended agent has no use for it. Every tool in the list is read-only: none can move money, edit transactions, or trade.

A few details that save debugging time:

• Sign convention. Positive amounts are money leaving the account; negative amounts are money coming in.
• Default windows. Transaction and spending tools default to the last 30 days, categories and investment transactions to 90 days, recurring charges to 6 months, and merchant history to 12 months. Ask for the range you want in the prompt.
• Card payments. Spending summaries count every outflow, including card payments from checking. Tell the agent to exclude them, as in the default prompt above.

More on each tool in getting the most from the MCP tools.

5. Handle warnings and disconnected banks

Banks occasionally need re-authentication, after a password change for example. When one of several banks cannot answer, the tool still returns data from the others plus a warnings array with a reconnect URL, and an instruction telling the model to relay it. If no bank can answer, the result is an error.

For an agent that runs unattended, make the warning visible. Add a line to your prompt such as “If any tool returns warnings, start your answer with them,” and send the result somewhere you will read it. The fix for the user is in reconnecting after a password change.

6. Run it on a schedule

A weekly review is a good first job. Use a prompt like:

bun finance-agent.ts "Review the last 7 days across all accounts: total spent,
the 5 largest charges, any merchant I have not paid before, and any recurring
charge that changed amount. Start with any warnings. Keep it under 200 words."

Run it from cron or launchd on your machine and send the output to email or a notification service. Since BankBridge fetches live on every call, the report reflects your accounts at run time; there is no sync to wait for. For ideas on what to check, see making your agent watch for a charge and the monthly money review.