MCP tools for querying financial data

Breadbox exposes seven MCP tools that give AI agents structured access to your financial data. Each tool is a thin, callable function — the agent invokes it with a JSON input, and gets back a JSON response it can reason over. This page documents every tool, its parameters, and example inputs and outputs.

Amount convention: Amounts follow Plaid’s convention. Positive values are debits (money leaving an account). Negative values are credits (money entering). When an agent summarizes spending, it should sum positive amounts only.

Recommended agent workflow

Before querying transactions, a well-behaved agent should orient itself and size the result set:

Understand the data structure

Call list_users and list_accounts to learn who is in the household and which accounts exist. This gives the agent the IDs it needs to filter by person or account.

Estimate result size

Call count_transactions with your intended filters before calling query_transactions. This tells the agent how many results to expect so it can decide whether to narrow the filters or paginate.

Query with appropriate filters and pagination

Call query_transactions with specific filters. Use the cursor from each response to fetch the next page when has_more is true.

`list_accounts`

Lists all connected bank accounts with their current balances. Call this early in any session to understand what accounts exist. Input parameters

Parameter	Type	Required	Description
`user_id`	string	No	Return only accounts owned by this family member. Omit to return all accounts.

{}

Example output

{
  "data": [
    {
      "id": "acc_xyz789",
      "name": "Chase Checking",
      "type": "depository",
      "subtype": "checking",
      "mask": "4321",
      "balance_current": 2450.18,
      "balance_available": 2380.00,
      "balance_limit": null,
      "iso_currency_code": "USD",
      "institution_name": "Chase",
      "user_id": "usr_abc123",
      "user_name": "Alice"
    },
    {
      "id": "acc_def456",
      "name": "Amex Gold",
      "type": "credit",
      "subtype": "credit card",
      "mask": "1008",
      "balance_current": -541.20,
      "balance_available": null,
      "balance_limit": 10000.00,
      "iso_currency_code": "USD",
      "institution_name": "American Express",
      "user_id": "usr_abc123",
      "user_name": "Alice"
    }
  ]
}

For credit accounts, balance_current represents the amount owed, not available funds. Do not sum balances across accounts with different iso_currency_code values.

`query_transactions`

Searches transactions using a combination of filters. Results are cursor-paginated with a default page size of 100 and a maximum of 500. Call count_transactions first to understand result size before paginating through a large set. Input parameters

Parameter	Type	Required	Description
`start_date`	string (YYYY-MM-DD)	No	Include transactions on or after this date.
`end_date`	string (YYYY-MM-DD)	No	Include transactions on or before this date.
`account_id`	string	No	Filter to a specific account.
`user_id`	string	No	Filter to accounts owned by this family member.
`category`	string	No	Filter by primary category (e.g., `FOOD_AND_DRINK`). Case-insensitive.
`category_detailed`	string	No	Filter by detailed subcategory (e.g., `FOOD_AND_DRINK_GROCERIES`). Case-sensitive.
`min_amount`	number	No	Minimum transaction amount in USD. Zero is a valid value.
`max_amount`	number	No	Maximum transaction amount in USD. Zero is a valid value.
`pending`	boolean	No	`true` returns only pending transactions; `false` returns only posted. Omit for both.
`search`	string	No	Full-text search over merchant name and description.
`sort_by`	string	No	Sort field: `date` (default), `amount`, or `name`. Cursor pagination requires `date`.
`sort_order`	string	No	Sort direction: `desc` (default) or `asc`.
`limit`	integer	No	Results per page. Default: 100. Maximum: 500.
`cursor`	string	No	Pagination cursor from the previous response. Omit for the first page.

{
  "start_date": "2025-01-01",
  "end_date": "2025-01-31",
  "category": "FOOD_AND_DRINK",
  "limit": 100
}

Example output

{
  "data": [
    {
      "id": "txn_111222333",
      "account_id": "acc_xyz789",
      "account_name": "Chase Checking",
      "user_id": "usr_abc123",
      "user_name": "Alice",
      "amount": 14.50,
      "iso_currency_code": "USD",
      "date": "2025-01-15",
      "authorized_date": "2025-01-14",
      "merchant_name": "Blue Bottle Coffee",
      "name": "BLUE BOTTLE COFFEE #12",
      "category_primary": "FOOD_AND_DRINK",
      "category_detailed": "FOOD_AND_DRINK_COFFEE",
      "payment_channel": "in store",
      "pending": false
    }
  ],
  "next_cursor": "dHhuXzExMTIyMzM0",
  "has_more": true
}

When there are no more pages, the response includes "has_more": false and "next_cursor": null.

Each transaction object is roughly 50 tokens. At the default page size of 100, one call returns approximately 5,000 tokens of content. At the maximum of 500, a single call can reach 25,000 tokens. Use count_transactions first and apply filters to keep result sets manageable.

Page size guidance

Use case	Recommended `limit`
Sampling or spot-checking	25
Single-month analysis	100 (default)
Full dataset processing	200–500
Maximum allowed	500

`count_transactions`

Counts matching transactions without returning any transaction data. Accepts the same filters as query_transactions (excluding cursor and limit). Use this before calling query_transactions to decide whether to narrow your filters or how many pages to expect. Input parameters Same filters as query_transactions, minus cursor, limit, sort_by, and sort_order.

Parameter	Type	Required	Description
`start_date`	string (YYYY-MM-DD)	No	Count transactions on or after this date.
`end_date`	string (YYYY-MM-DD)	No	Count transactions on or before this date.
`account_id`	string	No	Filter to a specific account.
`user_id`	string	No	Filter to accounts owned by this family member.
`category`	string	No	Filter by primary category.
`category_detailed`	string	No	Filter by detailed subcategory.
`min_amount`	number	No	Minimum transaction amount.
`max_amount`	number	No	Maximum transaction amount.
`pending`	boolean	No	Filter by pending status.
`search`	string	No	Full-text search over merchant name and description.

{
  "start_date": "2025-01-01",
  "end_date": "2025-01-31"
}

Example output

{ "count": 347 }

When to use it Call count_transactions before query_transactions whenever the result size is unknown:

If count is under 200, query directly in one or two pages.
If count is 200 or more, add category, account, or user filters and re-count before querying.
If the full dataset is genuinely needed, plan to paginate and process page by page.

Lists all distinct transaction category pairs — primary category and detailed subcategory — that exist in your database. Use this to discover valid category values before filtering transactions. Input parameters None. Pass an empty object.

{}

Example output

{
  "data": [
    { "primary": "FOOD_AND_DRINK", "detailed": "FOOD_AND_DRINK_GROCERIES" },
    { "primary": "FOOD_AND_DRINK", "detailed": "FOOD_AND_DRINK_RESTAURANTS" },
    { "primary": "TRANSPORTATION", "detailed": "TRANSPORTATION_GAS" }
  ]
}

When to use it Call list_categories when you need to filter by category but aren’t sure what values exist in your data. The returned primary values are valid for query_transactions’s category parameter; detailed values are valid for category_detailed.

`list_users`

Lists all family members tracked in Breadbox. Users are labels for account ownership — they are not login accounts. Use the returned IDs to filter accounts and transactions by person. Input parameters None. Pass an empty object.

{}

Example output

{
  "data": [
    {
      "id": "usr_abc123",
      "name": "Alice",
      "email": "alice@example.com"
    },
    {
      "id": "usr_def456",
      "name": "Bob",
      "email": "bob@example.com"
    }
  ]
}

When to use it Call list_users at the start of a session to discover who is in the household and get their IDs. Pass a user_id to list_accounts or query_transactions to scope results to a specific family member.

`get_sync_status`

Returns the health status of all bank connections: whether they are syncing successfully, when they last synced, and whether any connection needs re-authentication. Use this to diagnose why transactions might be missing or out of date. Input parameters None. Pass an empty object.

{}

Example output

{
  "data": [
    {
      "id": "conn_aaa111",
      "institution_name": "Chase",
      "provider": "plaid",
      "status": "active",
      "last_synced_at": "2025-01-20T14:32:00Z",
      "error_message": null,
      "accounts_count": 3
    },
    {
      "id": "conn_bbb222",
      "institution_name": "Bank of America",
      "provider": "plaid",
      "status": "error",
      "last_synced_at": "2025-01-18T09:15:00Z",
      "error_message": "ITEM_LOGIN_REQUIRED: User must re-authenticate via Plaid Link.",
      "accounts_count": 2
    }
  ]
}

Status values

Status	Meaning
`active`	Connection is healthy and syncing normally.
`error`	Last sync failed. Check `error_message` for details.
`pending_reauth`	Connection requires user re-authentication (e.g., bank login changed).
`disconnected`	Connection has been disconnected or removed.

When to use it Call get_sync_status when a user asks why recent transactions are missing, or after calling trigger_sync to check whether the sync completed successfully.

`trigger_sync`

Triggers a manual data sync to fetch the latest transactions and balances from the bank. Syncs all connections by default, or a specific connection if you provide a connection_id. This tool returns immediately after enqueuing the sync — it does not wait for the sync to finish. Call get_sync_status afterward to check progress. Input parameters

Parameter	Type	Required	Description
`connection_id`	string	No	Sync only this connection. Omit to sync all active connections.

{}

Example output

{ "message": "Sync triggered for all connections." }

{
  "connection_id": "conn_aaa111",
  "message": "Sync triggered for connection conn_aaa111 (Chase)."
}

trigger_sync requires a full access API key. It is not available with a read-only key.

When to use it Call trigger_sync when a user wants the latest data before running an analysis, or when get_sync_status shows that a connection’s last_synced_at is stale. After triggering, wait a moment and call get_sync_status to confirm the sync succeeded.

Get Started

Bank Connections

Transactions

AI Integration

Configuration

MCP tools for querying financial data

Recommended agent workflow

`list_accounts`

`query_transactions`

`count_transactions`

`list_users`

`get_sync_status`

`trigger_sync`

Get Started

Bank Connections

Transactions

AI Integration

Configuration

​Recommended agent workflow

​list_accounts

​query_transactions

​count_transactions

​list_categories

​list_users

​get_sync_status

​trigger_sync

Recommended agent workflow

`list_accounts`

`query_transactions`

`count_transactions`

`list_categories`

`list_users`

`get_sync_status`

`trigger_sync`