> ## Documentation Index
> Fetch the complete documentation index at: https://breadbox-mintlify-7401d007.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Give AI agents access to your finances with Breadbox MCP

> Breadbox exposes your household financial data to AI agents via the Model Context Protocol, letting Claude query accounts, transactions, and more.

Breadbox includes a built-in [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server that lets AI agents like Claude, ChatGPT, Manus, and Openclaw read your financial data directly — no copy-pasting exports, no custom scripts. Once connected, an agent can analyze spending patterns, detect unusual transactions, answer questions about your accounts, write rules that keep improving your categorization, and submit structured reports — all against live data that you control and host yourself.

## What MCP is

MCP is an open standard for giving AI agents structured access to external data sources and tools. Instead of asking Claude to reason over a paste of bank statements, you give it a live connection to Breadbox. The agent calls tools to query your data, reads context resources to understand your household setup, and responds based on real, up-to-date information.

## Two transports

Breadbox supports two ways to connect an MCP client.

**Streamable HTTP** is the primary transport. The MCP endpoint lives at `/mcp` on your Breadbox server — the same process that serves the REST API and admin dashboard. This transport works for any deployment: Docker, remote server, or a local binary running as a server. HTTP connections require an API key passed in the `X-API-Key` header.

**Stdio** is a convenience mode for local setups. Running `breadbox mcp-stdio` starts an MCP session over stdin/stdout. Because the process connects directly to your database, no API key is required. This mode is ideal when Claude Desktop is running on the same machine as Breadbox.

## What the MCP server exposes

The server advertises a single capability type: **tools**. Earlier versions of Breadbox also published a parallel `breadbox://` resources surface, but that has been retired — every read is now a tool call, including the orientation reads and the operating-guidance docs.

**Tools** are callable functions the agent uses to query and change your data — listing accounts, searching transactions, counting results, categorizing, tagging, creating rules, triggering syncs, and submitting reports. The registry has 35 tools. See the [MCP Reference](/mcp/reference/overview) tab for the complete enumeration, or [MCP tools](/mcp/tools) for a human walkthrough of the ones you're most likely to grant access to.

### Orientation reads

The first thing a connecting agent should do is orient itself with the bounded reference reads — each one is a dedicated tool:

| Tool                     | What it returns                                                                                                                                                                                     |
| ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `get_overview`           | Live dataset summary organized as scope (counts, date range), freshness (last sync, ingest signals, errored connections), and backlog (needs-review and unmapped counts), plus the household roster |
| `list_accounts`          | Bank accounts (checking, savings, credit cards, loans, investments) with balances, institution names, and currency                                                                                  |
| `list_categories`        | Two-level category taxonomy keyed by slug; the source of valid `category_slug` values                                                                                                               |
| `list_tags`              | Current tag vocabulary keyed by slug; the `needs-review` tag is the review-queue handle                                                                                                             |
| `list_users`             | Household members with their roles (admin, editor, viewer)                                                                                                                                          |
| `get_sync_status`        | Per-connection sync status and last-sync timestamps                                                                                                                                                 |
| `list_transaction_rules` | The active rule roster                                                                                                                                                                              |

Calling `get_overview` first gives the agent ambient context about your household's financial state — how big the dataset is, whether it's currently in sync, and what's open in the review backlog — before it asks a single question.

### Operating guidance

The near-static markdown that teaches an agent how to drive the server (the rule DSL grammar, the review playbook, report-format conventions) is served by a single `get_reference` tool, keyed by `kind`:

| `kind`              | What it returns                                                                                              |
| ------------------- | ------------------------------------------------------------------------------------------------------------ |
| `instructions`      | Data model overview and how the tool surface is organized                                                    |
| `rule-dsl`          | Reference grammar for transaction rules: condition fields, action types, priority bands, and provider quirks |
| `review-guidelines` | Guidelines for reviewing transactions and creating categorization rules; editable from the MCP Settings page |
| `report-format`     | Templates and formatting rules for agent-submitted reports; editable from the MCP Settings page              |

`get_reference` returns markdown. The `instructions`, `review-guidelines`, and `report-format` documents reflect any operator customization made on the MCP Settings page; `rule-dsl` is the fixed grammar.

## What agents can do

With an MCP connection to Breadbox, an agent can:

* Summarize monthly spending by category across all accounts or per family member
* Flag transactions that look unusual given your typical patterns
* Identify uncategorized transactions and suggest categories based on your existing data and the agent's own context (inbox, calendar, household history)
* **Write and maintain categorization rules** so patterns it figures out once get applied automatically on every future sync
* Answer questions like "how much did we spend on groceries last quarter?"
* Trigger a manual sync to pull the latest transactions before running an analysis
* Submit a formatted spending report for your records

<Note>
  MCP access can be scoped to read-only or read-write depending on your API key configuration. A read-only key prevents the agent from triggering syncs or submitting reports. See [API keys](/configuration/api-keys) for details.
</Note>

## API key requirement

HTTP transport requires a valid API key in every request. Generate one from the API Keys section of the admin dashboard and pass it as the `X-API-Key` header in your MCP client config. Stdio mode does not require an API key because the process has direct database access.

## Next steps

<Columns cols={2}>
  <Card title="Set up MCP" icon="plug" href="/mcp/setup">
    Connect Claude (Desktop, web, mobile), Claude Code, ChatGPT, Openclaw, Manus, or any other MCP-compatible agent to Breadbox.
  </Card>

  <Card title="MCP reference" icon="wrench" href="/mcp/reference/overview">
    Complete reference for every MCP tool Breadbox exposes — parameters, example inputs, example outputs, and scope labels.
  </Card>
</Columns>