Breadbox exposes its data to AI agents through the Model Context Protocol. 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 |
*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 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:
- Scope filtering —
read_only keys never see write tools.
- 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.
- 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.
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 |
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:
{ "code": "NOT_FOUND", "error": "transaction k7Xm9pQ2 not found" }
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.
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)
Mutations (write)
- Transactions:
update_transactions, flag_transaction, unflag_transaction — update_transactions is the compound write for category sets, tag adds/removes, and comments; the former individual tools were merged into it.
- Transaction metadata:
set_transaction_metadata, remove_transaction_metadata, replace_transaction_metadata, clear_transaction_metadata
- Rules:
create_transaction_rule, update_transaction_rule, delete_transaction_rule, batch_create_rules, apply_rules
- Tags:
create_tag, update_tag, delete_tag
- Recurring series:
review_series, assign_series, update_series, set_series_type, rekey_series, split_series, unlink_series_transactions, add_series_tag, remove_series_tag
- Reports:
submit_report
Last modified on June 8, 2026
