Categorization MCP reference

How to set, reset, and batch-apply transaction categories from MCP using update_transactions and apply_rules.

The individual categorization tools (categorize_transaction, batch_categorize_transactions, bulk_recategorize, reset_transaction_category) were merged into update_transactions during the MCP overhaul. Use update_transactions for all per-row and batch category writes. For retroactive rule application, see apply_rules.

Setting a category

update_transactions handles all category writes — single rows, batches of up to 50, resets, and compound review closures (category + tag removal + comment in one atomic call).

Single transaction

Pass category_slug in one operation:

{
  "operations": [
    {
      "transaction_id": "k7Xm9pQ2",
      "category_slug": "food_and_drink_groceries"
    }
  ]
}

Close a review (compound)

Set category, remove needs-review, and attach a comment in one call:

{
  "operations": [
    {
      "transaction_id": "k7Xm9pQ2",
      "category_slug": "food_and_drink_groceries",
      "tags_to_remove": [{ "slug": "needs-review" }],
      "comment": "Costco run — clearly groceries."
    }
  ]
}

Reset to automatic

Pass reset_category: true to remove a manual override and return to automatic categorization:

{
  "operations": [
    {
      "transaction_id": "k7Xm9pQ2",
      "reset_category": true
    }
  ]
}

Batch (up to 50)

Include multiple operations in one call:

{
  "operations": [
    { "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" }
  ]
}

The response summary carries succeeded, skipped, and failed counts.

Category-override precedence

Category writes follow the precedence user > agent > rule. If a transaction’s category_override is 'user' (set manually in the dashboard), the agent’s write is silently skipped — the human’s choice is preserved. The summary.skipped count in the response surfaces these no-ops so you can account for them.

apply_rules

To categorize in bulk by applying a stored rule to existing transactions, use apply_rules. Pass a rule_id to run one rule in isolation, or omit it to run the full active-rule pipeline in priority order.

See Rules (write) for the other rules write tools (create_transaction_rule — accepts a rules array for batch creation, update_transaction_rule, delete_transaction_rule).