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

# MCP reference overview

> Breadbox MCP transports, authentication, scope-based tool filtering, write-session requirements, and how MCP tools map to the REST API.

Breadbox exposes its data to AI agents through the [Model Context Protocol](https://modelcontextprotocol.io). An MCP client connects to the server, receives a catalog of typed tools at handshake time, and calls them to read and write the same PostgreSQL dataset the admin dashboard and REST API sit on top of. Every tool is a thin wrapper around the internal service layer — there is no HTTP round-trip between the MCP handler and the database.

This reference enumerates every tool the server registers, along with inputs, outputs, and the REST endpoint each one mirrors when one exists.

## Transports

Breadbox ships with two MCP transports. Both expose the same tool set.

| Transport       | Endpoint                          | Auth               | Typical client                                                     |
| --------------- | --------------------------------- | ------------------ | ------------------------------------------------------------------ |
| Streamable HTTP | `POST /mcp` on your Breadbox host | `X-API-Key` header | Claude.ai custom connector, Claude Code via `--mcp`, remote agents |
| stdio           | `breadbox mcp-stdio` subcommand   | None (local only)  | Claude Desktop, local scripts, anything embedding the binary       |

The HTTP transport is filtered per request: every call builds a fresh `*mcpsdk.Server` from the tool registry, applying the current global MCP mode, per-tool disable list, and the API key's scope. The stdio transport is unfiltered — it's intended for local, trusted use. See [Set up MCP](/mcp/setup) for connection examples.

## Authentication and scopes

The HTTP transport authenticates with an API key. The key's scope controls which tools are visible:

* `full_access` — every tool in the registry is registered on the per-request server, subject to the global mode and disable list.
* `read_only` — write tools are filtered out entirely. The client never sees them in its tool catalog, so it can't call them even if it tries.

The global MCP mode (`app_config.mcp_mode`) overlays a second filter. When set to `read_only`, writes are suppressed for every key regardless of scope. The admin UI at `/mcp` controls the mode and per-tool disable list.

## Write session discipline

Audit sessions are bound automatically to the transport connection — `MCP-Session-Id` for Streamable HTTP, a per-process ID for stdio. The server creates the session row on the first tool call in a connection and stamps it with the client's `initialize` info. There is no `create_session` tool; the binding is implicit.

Per-call rationale travels in `tools/call._meta.reason` in the MCP request envelope, not as a field on the tool input schema. The dispatcher reads it and stamps it on the activity log entry for every call.

Write tools enforce scope and mode before the handler runs: the server verifies that the API key has `full_access` scope and that the global `mcp_mode` is not `read_only`.

## Read vs write classification

Each tool in this reference is tagged **Read** or **Write**. The distinction drives:

1. Scope filtering — `read_only` keys never see write tools.
2. Session enforcement — write calls are bound to the connection's audit session automatically; pass `_meta.reason` on a call to attach a per-call label.
3. Activity logging — every call is logged asynchronously with the classification.

Write tools also run an in-handler `checkWritePermission` check as a belt-and-suspenders guard against TOCTOU races between config changes and server construction.

## ID format in responses

Entity IDs in MCP responses are compact 8-character base62 strings (e.g., `k7Xm9pQ2`). Internally every row has both a full UUID and a short ID; the MCP response pipeline replaces every `id` field with the short ID value and drops the `short_id` field entirely to save tokens. Tool inputs accept either form — both the UUID and the short ID resolve to the same row.

This differs from the REST API, which returns both `id` (UUID) and `short_id` on every record. If you're cross-referencing between an agent session and the admin UI, remember that what the agent sees as `id` is what the UI calls `short_id`.

## Resources

MCP resources are static or live documents the server exposes alongside tools. Breadbox serves nine, each annotated with an audience (`assistant`-only by default; the four with real attach-in-chat flows are dual-audience for both `user` and `assistant`), a priority, and a `lastModified` timestamp (build time for static prompts, read time for live data).

| URI                            | MIME               | Audience        | What it returns                                                                                                                             |
| ------------------------------ | ------------------ | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `breadbox://overview`          | `application/json` | user, assistant | Live dataset summary clustered as `scope`, `freshness`, and `backlog`, plus the household `users` roster                                    |
| `breadbox://accounts`          | `application/json` | user, assistant | Bank accounts (checking, savings, credit cards, loans, investments) with balances, institution names, and currency                          |
| `breadbox://categories`        | `application/json` | assistant       | Two-level category taxonomy keyed by slug; source for valid `category_slug` values when categorizing or authoring rules                     |
| `breadbox://tags`              | `application/json` | assistant       | Current tag vocabulary keyed by slug; the `needs-review` tag is the review-queue handle                                                     |
| `breadbox://users`             | `application/json` | assistant       | Household members with their roles (admin, editor, viewer)                                                                                  |
| `breadbox://sync-status`       | `application/json` | assistant       | Per-connection sync status and last-sync timestamps                                                                                         |
| `breadbox://review-guidelines` | `text/markdown`    | user, assistant | Guidance for reviewing transactions and creating rules (user-editable in `/mcp` admin)                                                      |
| `breadbox://report-format`     | `text/markdown`    | user, assistant | Report structure templates used by `submit_report` (user-editable)                                                                          |
| `breadbox://rule-dsl`          | `text/markdown`    | assistant       | Reference grammar for transaction rules: condition fields, action types, priority bands, sync vs retroactive semantics, and provider quirks |

The live `accounts`, `categories`, `tags`, `users`, and `sync-status` resources replace what would otherwise be redundant `list_*` tool calls — agents can read them on connect instead of paying for a round-trip per list.

Agents are expected to read `breadbox://overview` first to orient themselves, and to read `breadbox://review-guidelines` before processing review work.

### `breadbox://overview` shape

The overview resource returns a JSON object with four top-level keys:

* `users` — minimal household roster (`id`, `name`).
* `scope` — dataset size: `transaction_count`, `account_count`, `category_count`, `earliest_transaction_date`, `latest_transaction_date`.
* `freshness` — ingest-time signals: `last_sync_at` (most recent successful sync across active connections), `errored_connection_count`, `pending_transaction_count`, `transactions_added_last_24h`, `transactions_added_last_7d`. The `transactions_added_last_*` counters track when Breadbox first ingested each row, not when the underlying transaction occurred.
* `backlog` — what's open: `needs_review_count` (transactions tagged `needs-review`) and `unmapped_transaction_count` (transactions with no category).

The 30-day spending summary, the per-connection list, and the `accounts_by_type` histogram that earlier versions of this resource returned have been removed — read `breadbox://accounts`, `breadbox://sync-status`, or call `transaction_summary` for that detail.

## Error shape

Tool errors return a standard MCP call result with `isError: true` and a single text content block containing JSON:

```json theme={null}
{ "code": "NOT_FOUND", "error": "transaction k7Xm9pQ2 not found" }
```

Transport-level errors (bad authentication, malformed JSON-RPC) come back as JSON-RPC error responses and never reach the tool handler.

## Relationship to the REST API

Many MCP tools mirror a REST endpoint. Where one exists, the reference page cross-links to it. Both layers call the same service methods — there are no behavioral differences beyond the ID compaction above and the session-tracking layer. If a feature is available in one surface but not the other, that's a gap, not a design choice, and worth flagging.

## Grouped tool index

A complete list of every tool Breadbox exposes, grouped by domain. Tools without a dedicated reference page are listed by name only.

**Data access (read)**

* Overview: `get_overview` — household snapshot; mirrors `breadbox://overview`.
* Transactions: [`query_transactions`, `transaction_summary`, `list_annotations`](/mcp/reference/transactions)
* Accounts and users: [`list_accounts`, `list_users`](/mcp/reference/accounts)
* Categories: [`list_categories`](/mcp/reference/categories)
* Tags: [`list_tags`](/mcp/reference/tags)
* Rules: [`list_transaction_rules`, `query_transaction_rules`, `preview_rule`, `find_matching_rules`](/mcp/reference/rules)
* Connections and sync: [`get_sync_status`](/mcp/reference/connections-sync)
* Recurring series: `list_series`, `get_series`
* Counterparties: `list_counterparties`, `get_counterparty`
* Workflows: `list_workflows`
* Guidance docs: `get_reference`

**Mutations (write)**

* Transactions: [`update_transactions`](/mcp/reference/transactions-write) — compound write for category sets, tag adds/removes, and comments.
* Transaction metadata: `set_transaction_metadata`
* Rules: [`create_transaction_rule`, `update_transaction_rule`, `delete_transaction_rule`, `apply_rules`](/mcp/reference/rules-write)
* Tags: [`create_tag`, `update_tag`, `delete_tag`](/mcp/reference/tags-write)
* Recurring series: `assign_series`, `update_series`, `unlink_series_transactions`
* Counterparties: `update_counterparty`, `assign_counterparty`, `unlink_counterparty_transactions`
* Reports: [`submit_report`](/mcp/reference/reports)