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.
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 |
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. |
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:
{ "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)
- Overview:
get_overview — household snapshot (scope, freshness, backlog).
- Transactions:
query_transactions, transaction_summary, list_annotations
- Accounts and users:
list_accounts, list_users
- Categories:
list_categories
- Tags:
list_tags
- Rules:
list_transaction_rules, query_transaction_rules, preview_rule, find_matching_rules
- Connections and sync:
get_sync_status
- Recurring series:
list_series, get_series
- Counterparties:
list_counterparties, get_counterparty
- Workflows:
list_workflows
- Guidance docs:
get_reference
Mutations (write)
- Transactions:
update_transactions — 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
- Tags:
create_tag, update_tag, delete_tag
- Recurring series:
assign_series, update_series, unlink_series_transactions
- Counterparties:
update_counterparty, assign_counterparty, unlink_counterparty_transactions
- Reports:
submit_report
Last modified on June 25, 2026
