Categorization MCP reference

Tools for overriding a transaction’s category or applying categorization rules after the fact. These tools set category_override = 'agent' on affected transactions, which prevents rules from reassigning the category on future syncs. A transaction whose category_override is 'user' (set by a human in the dashboard) is skipped — the write is a no-op and the human’s choice is preserved. To restore a transaction to automatic categorization, use reset_transaction_category.

Prefer compound ops for review-driven categorization. When you’re closing a review (set category + remove needs-review + leave a note) reach for update_transactions instead. It writes one linked annotation per transaction covering the whole edit, where categorize_transaction only writes the category set.

All tools on this page are Write scope and require session_id + reason.

categorize_transaction

Manually overrides one transaction’s category. Pass transaction_id plus either category_id or category_slug — slug is resolved automatically. Mirrors: PATCH /api/v1/transactions/{id}/category

Parameters

transaction_id

string

required

Transaction UUID or short ID.

category_slug

string

Category slug (e.g. food_and_drink_groceries). Alternative to category_id.

category_id

string

Category UUID or short ID. Takes precedence if both are supplied.

session_id

string

required

From create_session.

reason

string

required

Brief rationale.

Example input

{
  "session_id": "s9Xm2pQk",
  "reason": "correcting miscategorized grocery run",
  "transaction_id": "k7Xm9pQ2",
  "category_slug": "food_and_drink_groceries"
}

Example output

{ "text": "Transaction k7Xm9pQ2 categorized successfully." }

batch_categorize_transactions

Categorize multiple transactions at once. Each item is a {transaction_id, category_slug} pair. Max 500 items per request. Sets category_override = 'agent' on every affected transaction (skips any transaction already at 'user'). Mirrors: POST /api/v1/transactions/batch-categorize

Parameters

items

array of objects

required

Array of {transaction_id, category_slug} pairs. Max 500.

session_id

string

required

reason

string

required

Example input

{
  "session_id": "s9Xm2pQk",
  "reason": "assigning coffee runs flagged during review",
  "items": [
    { "transaction_id": "k7Xm9pQ2", "category_slug": "food_and_drink_coffee" },
    { "transaction_id": "k8Yn0qR3", "category_slug": "food_and_drink_coffee" },
    { "transaction_id": "k9Zo1rS4", "category_slug": "food_and_drink_coffee" }
  ]
}

Example output

{
  "succeeded": 3,
  "failed": 0,
  "errors": []
}

bulk_recategorize

Moves every transaction matching from_category (plus any other filters) to to_category. Requires to_category and at least one filter as a safety requirement. Sets category_override = 'agent' on affected rows (skips any at 'user'). Typical use: “move everything currently in general_merchandise for March to groceries”. Mirrors: POST /api/v1/transactions/bulk-recategorize

Parameters

to_category

string

required

Destination category slug.

from_category

string

Only transactions currently in this category are matched.

start_date

string (YYYY-MM-DD)

end_date

string (YYYY-MM-DD)

account_id

string

user_id

string

min_amount

number

max_amount

number

pending

boolean

string

name_contains

string

Filter transactions whose name contains this string.

session_id

string

required

reason

string

required

The legacy parameter names target_category_slug (for to_category) and category_slug (for from_category) are still accepted but deprecated. Prefer the new names.

Example input

{
  "session_id": "s9Xm2pQk",
  "reason": "NETFLIX charges were misfiled under general",
  "from_category": "general_merchandise",
  "to_category": "entertainment_streaming_services",
  "search": "NETFLIX",
  "start_date": "2026-01-01",
  "end_date": "2026-04-01"
}

Example output

{
  "matched_count": 14,
  "updated_count": 14
}

reset_transaction_category

Removes a manual category override from one transaction and re-resolves its category from the automatic mapping + rule pipeline. Use this to undo a categorize_transaction action. Mirrors: DELETE /api/v1/transactions/{id}/category

Parameters

transaction_id

string

required

session_id

string

required

reason

string

required

Example input

{
  "session_id": "s9Xm2pQk",
  "reason": "undoing accidental override",
  "transaction_id": "k7Xm9pQ2"
}

Example output

{ "text": "Transaction k7Xm9pQ2 category reset to automatic." }

apply_rules

Applies rules retroactively to existing transactions. Pass rule_id to run one rule in isolation, or omit to run the full active-rule pipeline in priority-ASC order. Materializes set_category, add_tag, and remove_tag actions; add_comment is sync-only and does not fire here. Hit counts increment per condition match, matching sync-time semantics.

Use sparingly. This is for initial setup and explicit back-fills — not routine reviews. During normal work, create the rule and let it match future syncs naturally. Running the full pipeline across thousands of historical transactions can take time.

Parameters

rule_id

string

UUID or short ID of a specific rule to apply. Omit to apply every active rule.

session_id

string

required

reason

string

required

Examples

Single rule
All rules

Apply one specific rule retroactively. Pass its rule_id.Input:

{
  "session_id": "s9Xm2pQk",
  "reason": "backfilling new Starbucks rule to existing transactions",
  "rule_id": "r9Xm2pQr"
}

Output:

{
  "rule_id": "r9Xm2pQr",
  "affected_count": 47
}

Apply every active rule in priority-ASC order. Omit rule_id.Input:

{
  "session_id": "s9Xm2pQk",
  "reason": "initial setup — apply every rule to historical data"
}

Output:

{
  "rules_applied": {
    "r9Xm2pQr": 47,
    "rAYn0qR3": 128,
    "rBZo1rS4": 12
  },
  "total_affected": 187
}

​categorize_transaction

​Parameters

​Example input

​Example output

​batch_categorize_transactions

​Parameters

​Example input

​Example output

​bulk_recategorize

​Parameters

​Example input

​Example output

​reset_transaction_category

​Parameters

​Example input

​Example output

​apply_rules

​Parameters

​Examples

categorize_transaction

Parameters

Example input

Example output

batch_categorize_transactions

Parameters

Example input

Example output

bulk_recategorize

Parameters

Example input

Example output

reset_transaction_category

Parameters

Example input

Example output

apply_rules

Parameters

Examples