> ## 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.

# 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`.

## Reads-as-tools, no MCP resources

Earlier versions of Breadbox exposed the orientation data and the operating-guidance docs as a parallel `breadbox://` resources surface. That surface has been retired entirely — the registry advertises **0 resources, 35 tools**. Resources weren't visible to MCP clients that can't call `resources/list` (notably Claude.ai), so every read is now a tool call.

The migration is mechanical:

| Old resource URI                | Now                                            |
| ------------------------------- | ---------------------------------------------- |
| `breadbox://overview`           | `get_overview` tool                            |
| `breadbox://accounts`           | `list_accounts` tool                           |
| `breadbox://categories`         | `list_categories` tool                         |
| `breadbox://tags`               | `list_tags` tool                               |
| `breadbox://users`              | `list_users` tool                              |
| `breadbox://sync-status`        | `get_sync_status` tool                         |
| `breadbox://rules` (rules list) | `list_transaction_rules` tool                  |
| `breadbox://instructions`       | `get_reference` tool, `kind=instructions`      |
| `breadbox://rule-dsl`           | `get_reference` tool, `kind=rule-dsl`          |
| `breadbox://review-guidelines`  | `get_reference` tool, `kind=review-guidelines` |
| `breadbox://report-format`      | `get_reference` tool, `kind=report-format`     |

A new agent is expected to call `get_overview` first to orient itself, and to call `get_reference(kind="review-guidelines")` before processing review work.

### Guidance docs via `get_reference`

`get_reference` is a single read tool that serves the near-static markdown that teaches an agent how to drive the server. Pass a `kind`:

| `kind`              | Returns                                                                                                                                                           |
| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `instructions`      | Data-model + conventions overview, how the tool surface is organized.                                                                                             |
| `rule-dsl`          | The full transaction-rule condition grammar, action types, pipeline-stage ordering, and sync-vs-retroactive semantics. Fixed grammar — not operator-customizable. |
| `review-guidelines` | Principles for reviewing transactions and creating rules. Reflects operator customization from the MCP Settings page.                                             |
| `report-format`     | Structure and formatting conventions for `submit_report`. Reflects operator customization.                                                                        |

The response is a single markdown content block.

### `get_overview` shape

`get_overview` 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).

## 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 (scope, freshness, backlog).
* 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, flag toggles, 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)