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.
See MCP overview for how to connect, and the per-client guides (ChatGPT, Claude, Claude Code, Cursor, 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.
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.
