> ## Documentation Index > Fetch the complete documentation index at: https://docs.kualia.com/llms.txt > Use this file to discover all available pages before exploring further. # MCP Tool Reference > Every tool exposed by the Kualia MCP server, grouped by category These are the tools your MCP client can call once you've connected to `https://api.kualia.com/mcp`. Names and parameters match exactly what the server registers. The same catalog powers the in-app [AI Assistant](/features/ai-assistant). See [MCP overview](/mcp/overview) for how to connect, and the per-client guides ([ChatGPT](/mcp/chatgpt), [Claude](/mcp/claude), [Claude Code](/mcp/claude-code), [Cursor](/mcp/cursor), [Perplexity](/mcp/perplexity)) for client-specific setup. ## Workspaces & accounts | Tool | What it does | Key params | | ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | | `kualia_list_workspaces` | Lists the workspaces the authenticated user can access. Call this only when switching workspaces explicitly. | *none* | | `kualia_list_bank_accounts` | Lists every bank account with name, type, on-budget flag, currency, current balance, and closed flag. | `workspaceId?`, `includeClosed?` | | `kualia_create_bank_account` | Creates a manual (unlinked) account from a `name` and `accountType`. `banking_*`/`credit_*` are on-budget; `investment_*`/`loan_*` are off-budget. Optionally seeds an opening balance. | `name` *(required)*, `accountType` *(required)*, `initialBalance?` + `initialBalanceDate?`, `workspaceId?` | | `kualia_close_bank_account` | Closes an account non-destructively: reconciles it, marks it closed, disconnects any link, and keeps all transactions for history. Use instead of delete when the account has activity. | `bankAccountId` *(required)*, `workspaceId?` | | `kualia_delete_bank_account` | Deletes an account. Only succeeds when the account has no transactions; otherwise it refuses and you should close it instead. Also removes a credit account's linked category. | `bankAccountId` *(required)*, `workspaceId?` | ## Transactions | Tool | What it does | Key params | | ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | | `kualia_list_transactions` | Lists transactions for a single month, with splits expanded to one row per movement. Each row carries a `url` linking to the transaction in the web app. | `yearMonth` *(required)*, `workspaceId?`, `accountId?`, `categoryId?`, `type?`, `limit?` (default 500, max 1000) | | `kualia_create_transactions` | Batch-creates regular or transfer rows (mix freely). Regular rows can be categorized, uncategorized, or sent directly to Ready to Assign. They are deduped against existing transactions on the same account and land as **Needs Review**. Up to 200 per call. | `transactions[]` *(required)*, `bankAccountId?`, `forceInsert?`, `workspaceId?` | | `kualia_update_transactions` | Batch-updates existing transactions: date, amount, category, movements, merchant, notes, account, status, review status, even type conversion. Up to 200 per call. | `updates[]` *(required)*, `workspaceId?` | | `kualia_delete_transactions` | Soft-deletes by id, reversing balance and budget side effects. Transfer pairs are deleted together. Up to 200 per call. | `transactionIds[]` *(required)*, `workspaceId?` | | `kualia_restore_transactions` | Undeletes soft-deleted transactions, re-applying balance and budget side effects. Transfer pairs are restored together. Up to 200 per call. | `transactionIds[]` *(required)*, `workspaceId?` | | `kualia_list_recurring_transactions` | Lists subscription, bill, and recurring-income templates with merchant, expected amount, and calculated next due date. | `status?` (`active` \| `inactive`, default `active`), `workspaceId?` | ### Creating transactions For a regular, single-movement transaction, pass `amount` and choose one of: * `categoryId` to categorize it. * `readyToAssign: true` to treat it as income for Ready to Assign. This creates a movement with no category. * Neither field to leave it uncategorized or let Kualia apply rules and suggestions. ```json theme={null} { "bankAccountId": "bank_account_checking", "transactions": [ { "merchantName": "Payroll", "amount": "1200.00", "date": "2026-06-15", "readyToAssign": true, "notes": "June paycheck" } ] } ``` Do not combine `readyToAssign: true` with `categoryId` on the same transaction or movement. For split transactions, pass `movements` and put `readyToAssign: true` on the specific movement that should go to Ready to Assign. ## Categories & groups | Tool | What it does | Key params | | -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | | `kualia_list_category_groups` | Lists category groups with their nested categories. | `workspaceId?` | | `kualia_create_categories` | Batch-creates categories inside an existing group. Up to 50 per call. Per-row failures (duplicate names, unknown group) don't abort the batch. | `categories[]` *(required, with `name` + `categoryGroupId`)*, `workspaceId?` | | `kualia_update_categories` | Batch-updates category `name`, `categoryGroupId`, or `iconName`. Up to 50 per call. | `updates[]` *(required, with `categoryId`)*, `workspaceId?` | | `kualia_archive_categories` | Archive (`isArchived: true`) or unarchive (`false`) categories in bulk. System and credit-card categories are rejected. All-or-nothing per call. Up to 50. | `categoryIds[]` *(required)*, `isArchived` *(required)*, `workspaceId?` | | `kualia_reorder_categories` | Custom rearrangement. Places categories at exact top-to-bottom positions, including cross-group moves. Use only for arbitrary orderings. | `groups[]` *(required, with `categoryGroupId` + `orderedCategoryIds`)*, `workspaceId?` | | `kualia_sort_categories` | Server-side sort by `name_asc`/`name_desc`, `target_due_date_asc`/`_desc`, or `created_asc`/`_desc`. Sorts one group or every group. | `sortBy` *(required)*, `categoryGroupId?`, `workspaceId?` | | `kualia_create_category_groups` | Batch-creates groups (`type: 'expense'`). Up to 10 per call. | `groups[]` *(required, with `name` + `type`)*, `workspaceId?` | | `kualia_update_category_groups` | Batch-updates group `name` (and `type` back to `expense` if needed). Credit-card groups cannot be converted. Up to 10 per call. | `updates[]` *(required, with `categoryGroupId`)*, `workspaceId?` | | `kualia_archive_category_groups` | Archive (soft-delete) or restore groups in bulk. Group must be empty to archive. Credit-card groups can't be archived. Up to 10 per call. | `categoryGroupIds[]` *(required)*, `isArchived` *(required)*, `workspaceId?` | | `kualia_reorder_category_groups` | Custom rearrangement. Sets the top-to-bottom order of groups in the workspace. | `orderedCategoryGroupIds[]` *(required)*, `workspaceId?` | | `kualia_sort_category_groups` | Server-side sort by `name_asc`/`name_desc` or `created_asc`/`created_desc`. | `sortBy` *(required)*, `workspaceId?` | ## Budgets & targets | Tool | What it does | Key params | | ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `kualia_set_category_assigned_amount` | Sets the **absolute** assigned amount for one category-month (single mode) or many (bulk mode). Overwrites the existing assignment; it's not a delta. Positive funds the category, negative pulls money back to Ready to Assign. | Single: `categoryId` + `yearMonth` + `assignedAmount`. Bulk: `updates[]`. Plus `workspaceId?`. | | `kualia_get_envelope_month_status` | Returns one month of envelope status (assigned, activity, available) with assignment guidance (`remainingToAssign`, `underfundedAmount`, `assignmentNeeded`). Filter to a single category or group by id or name. | `yearMonth` *(required)*, `currentDate` *(required, YYYY-MM-DD)*, `categoryId?` \| `categoryName?` \| `groupId?` \| `groupName?`, `workspaceId?` | | `kualia_list_category_targets` | Lists every category's target definition (type, amount, frequency, due date, etc.) for categories that have targets enabled. | `workspaceId?` | | `kualia_create_category_target` | Creates a target on a category that doesn't have one. Types: `recurring`, `recurring_rollover`, `maintain_balance`, `one_time`. Credit-card categories are rejected. | `categoryId`, `targetType`, `amount` *(all required)*; plus `frequency?`, `frequencyInterval?`, `dayOfWeek?`, `dueDay?`, `firstDueDate?`, `targetDate?`, `monthlyContribution?`, `targetBalance?`, `workspaceId?` | | `kualia_update_category_target` | Updates an existing target. Nullable fields accept `null` to clear (`monthlyContribution`, `targetBalance`, `targetDate`, `dayOfWeek`, `dueDay`). | `categoryId` *(required)*; same target fields as `create_category_target`, all optional; plus `workspaceId?` | | `kualia_delete_category_target` | Disables the target on a category. Preserves the underlying settings so it can be re-enabled later. Idempotent. | `categoryId` *(required)*, `workspaceId?` | ## Reports | Tool | What it does | Key params | | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | `kualia_get_monthly_summary` | The canonical "how much did I spend, save, or earn" report. Per-month `income`, `spending`, `savings`, `savingsRate`, plus `byCategory` and `byGroup` spending breakdowns. Already excludes credit-card and loan transfer mechanics; use this instead of summing other reports. | `yearMonth?` *xor* `monthsBack?` (default 6, max 24); `currentYearMonth?`, `workspaceId?` | | `kualia_get_spending_report` | Spending breakdown by category for a single month or a range. Exposes net-of-internal-flow numbers; prefer `get_monthly_summary` for totals. | `yearMonth?` *xor* `monthsBack?`; `currentYearMonth?`, `workspaceId?` | | `kualia_get_income_summary` | Income and inflow summary for a month or range, sourced from pre-aggregated workspace data. | `yearMonth?` *xor* `monthsBack?` (default 1); `currentYearMonth?`, `workspaceId?` | | `kualia_get_category_rollup` | Multi-month per-category totals: total assigned, total inflow, total outflow. | `monthsBack?` (default 6, max 24), `currentYearMonth?`, `workspaceId?` | | `kualia_get_account_balances_report` | Monthly account balance history across every account, with multi-currency support. | `monthsBack?`, `currentYearMonth?`, `workspaceId?` | ## Common parameters * **`workspaceId`** is optional on every tool and defaults to the user's active workspace. Pass it explicitly only when the user has multiple workspaces and you need a non-default one. Get ids from `kualia_list_workspaces`. * **`yearMonth`** is `YYYYMM` (e.g. `202604` for April 2026). **`currentDate`** is `YYYY-MM-DD`. * **Batch limits:** transactions up to **200** per call; categories up to **50**; category groups up to **10**. * **Money** is encoded as a signed decimal string in the workspace currency, with at most `minorUnit` fractional digits (USD = 2 → `"51.08"`; JPY = 0 → `"5108"`; KWD = 3 → `"5.108"`). Each money-bearing response carries `currencyCode`, `minorUnit`, and `amountEncoding: 'decimal_string'`. Don't scale by 100. All tools respect per-workspace permissions. The server only returns and modifies data your account can access. Agent-driven updates also preserve a transaction's `reviewStatus`: rows created or edited through MCP stay as **Needs Review** until you mark them reviewed in the app yourself.