Transaction write MCP reference

Compound writes for category, tags, and comments on transactions. Categorization lives on its own page.

Write tools for editing transactions. update_transactions is the single primitive — it covers category, tags, and a comment in one atomic op per row, for up to 50 transactions per call.

All tools on this page are Write scope. See Categorization for category-only writes.

---

update_transactions

Compound write for up to 50 transactions at once. Each operation can set a category (category_slug), add tags (tags_to_add), remove tags (tags_to_remove), and attach a comment — all atomically per transaction. This is the tool for closing review work (set category + remove needs-review + explain) in one call.

Every change lands as a single linked annotation per operation, so the activity timeline reads as one event per transaction rather than a separate entry for each change.

Compound op semantics

What “compound” means here. Each element in the operations array is a bundle of mutations targeting one transaction. Within a single operation:

• The category, tag additions, tag removals, and comment are applied atomically — either all land or none do.
• The annotations written for those changes are linked so the activity timeline reads as one event, not four.
• Tag note fields are preserved on both tag_added and tag_removed annotations.

on_error behavior

• continue (default) — each operation runs in its own DB transaction. A failure on row 17 doesn’t roll back rows 1–16. The response returns per-row status so you can retry the failed ones.
• abort — the whole batch runs in one DB transaction. The first error rolls back every operation and the response includes aborted: true.

Parameters

operations · array of objects · required

Array of per-transaction operations. Max 50. See the operation shape below.

on_error · string · default: "continue"

continue or abort.

Operation shape

transaction_id · string · required

UUID or short ID.

category_slug · string

Category slug to set. Sets category_override = 'agent' (skips the row if a user has already set it to 'user'). Omit to leave the category unchanged.

tags_to_add · array

List of {slug, note?} entries. Auto-creates persistent tags if the slug is unknown.

tags_to_remove · array

List of {slug, note?} entries. note is recommended for workflow tags like needs-review.

comment · string

Free-form comment written as an annotation. Max 10000 chars. Markdown supported.

Example input

{
  "on_error": "continue",
  "operations": [
    {
      "transaction_id": "k7Xm9pQ2",
      "category_slug": "food_and_drink_groceries",
      "tags_to_remove": [
        { "slug": "needs-review", "note": "clearly groceries (Whole Foods)" }
      ]
    },
    {
      "transaction_id": "k8Yn0qR3",
      "category_slug": "transportation_ride_share",
      "tags_to_remove": [
        { "slug": "needs-review", "note": "Uber to airport" }
      ],
      "comment": "Work trip — filed to expense tracker 2026-04-20."
    }
  ]
}

Example output

{
  "results": [
    { "transaction_id": "k7Xm9pQ2", "status": "ok" },
    { "transaction_id": "k8Yn0qR3", "status": "ok" }
  ],
  "succeeded": 2,
  "failed": 0
}