For the complete documentation index, see [llms.txt](https://docs.kick.co/llms.txt). This page is also available as [Markdown](https://docs.kick.co/ai/developer-tools/mcp/tool-reference.md).

Complete technical reference for Kick MCP. The hosted MCP server at `https://use.kick.co/mcp` exposes a consolidated tool list. Some tools handle several actions through an `operation` or `report` parameter.

Every tool executes through the Kick REST API under the same auth, workspace, permission, and audit checks as the web app.

* * *

## Auth & Transport

```
Endpoint:  https://use.kick.co/mcp
Auth:      Authorization: Bearer kick_pat_...
OAuth:     https://use.kick.co/.well-known/oauth-protected-resource
Scopes:    mcp:read · mcp:write
```

Workspace-scoped PATs auto-inject their bound workspace. User-scoped PATs and OAuth tokens must pass `workspaceId` in inputs where required.

* * *

## Conventions

### Confirmation flow (write tools)

All write tools are preview-first.

1. Call the tool **without**`confirmationToken` → receive a `preview` object describing the action and a fresh token

2. Re-call with the **same input** plus the returned `confirmationToken` → mutation executes

```
{
  "preview": {
    "action": "transactions_update",
    "confirmationToken": "...",
    "summary": "Update transaction 12345.",
    "input": { }
  }
}
```

Never invent or reuse a token. Each preview issues a new token bound to the exact input.

### List output

Most read tools return:

```
{
  "operation": "find",
  "rows": [ { } ],
  "fields": ["id", "date", "amount"],
  "total": 123,
  "hasMore": false,
  "nextCursor": null
}
```

`fields` projects which columns appear in `rows`. `nextCursor` is `null` when there is no more data. Some tools use domain-specific keys (for example `counterparties`, `workspaces`) instead of `rows`.

### Pagination

- **Page cursor:** 1-based string (`"1"`, `"2"`...). Used by most list endpoints.
- **Offset cursor:** 0-based string (`"0"`, `"100"`...). Used by accounting, rule transactions, and similar endpoints.
- **Default limit:** 25. **Maximum limit:** 100 unless noted otherwise.

### Common ID types

| Field                                     | Type                                  |
|------------------------------------------|---------------------------------------|
| `workspaceId`                           | UUID v7 string                        |
| `entityId`                              | positive integer (not a UUID)        |
| `transactionId`, `financialAccountId`,  | positive integer                      |
| `financialDocumentId`                   |                                       |
| `ruleId`, `groupId`, `categoryId`,     | UUID v7 string                        |
| `counterpartyId`, `classId`,           |                                       |
| `accountId`, `journalEntryId`,         |                                       |
| `taskId`                                |                                       |

### GL-first workspaces

When `glFirstEnabled` is `true` on a workspace (visible via `context_browse`), classify transactions by GL account using `accounting_query` and `accountOverrides` on `transactions_act`. Do not send `categoryId` in GL-first workspaces; it is rejected. Category taxonomy tools (`categories_act`) are blocked in GL-first workspaces.

### Tool roster

| Toolset                         | Tools                                                                                       | Context                                       |
|---------------------------------|---------------------------------------------------------------------------------------------|-----------------------------------------------|
|  context_browse,                | `financial_accounts_query`                                                                  | Financial accounts                             |
|  context_resolve                | `transactions_query`, `transactions_act`, `transactions_transfer_matches_act`, ...          | Transactions                                   |
|                                 | `categories_query`, `categories_act`                                                         | Categories                                     |
|                                 | `classes_query`, `classes_act`                                                              | Classes                                        |
|                                 | `counterparties_query`, `counterparties_act`                                              | Counterparties                                 |
|                                 | `rules_query`, `rules_act`                                                                  | Rules                                          |
|                                 | `accounting_query`, `accounting_act`, ...                                                 | Accounting                                     |
|                                 | `reports_query`                                                                              | Reports                                       |
|                                 | `documents_query`, `documents_download`, `documents_act`                                   | Documents                                      |
|                                 | `entities_query`, `entities_act`                                                            | Entities                                       |
|                                 | `activity_query`, `activity_undo`                                                            | Activity                                       |
|                                 | `tasks_query`, `tasks_act`                                                                  | Tasks                                          |
|                                 | `organization_clients_create`                                                                | Organization                                    |
|                                 | `invoices_create`, `invoices_update`                                                        | Invoices                                       |
|                                 | `bills_create`, `bills_update`                                                              | Bills                                          |
|                                 | `list_kick_skills`, `load_kick_skill`                                                      | Skills                                        |

The tool list can vary by plan and permissions. `classes_*` requires the Classes plan capability. `invoices_*` and `bills_*` require the Accrual Ledger plan capability. Plan-gated tools appear in `tools/list` but return a plan-capability error at execution. Only feature-flagged tools are omitted from listing.

### Tool selection patterns

| Goal                                                | Reach for                                                        |
|-----------------------------------------------------|------------------------------------------------------------------|
| Orient to available workspaces and entities         | `context_browse`                                                 |
| Resolve a workspace, entity, or ledger by name     | `context_resolve`                                               |
| Resolve a transaction by description/date/amount    | `transactions_query` { `operation`: `"find"` } → `"get"` |
| Find both sides of a transfer                       | `transactions_query` { `operation`: `"suggested_transfers"` } → `transactions_transfer_matches_act` |
| Find accrual match candidates                       | `transactions_query` { `operation`: `"suggested_accrual_*"` }|
| Find a category/class/counterparty by name          | `*_query` { `operation`: `"search"` }                        |
| Run any financial report                             | `reports_query` { `report`: `"..."` }                        |
| Audit what changed and possibly undo                | `activity_query` → `activity_undo`                             |

* * *

## Context

### `context_browse`

**read** · idempotent · `GET /workspaces/list`
Lists accessible workspaces with nested entity summaries. Call this first before workspace-scoped work.

Operation

Required fields

`workspaces` (default)

_(none)_

```
{ "operation": "workspaces", "limit": 25 }
```

### `context_resolve`

**read** · idempotent

Resolves a workspace, entity, or ledger by name to the IDs Kick tools need.

`target`

Required fields

`workspace`
`query`
`entity`
`query`
`ledger`
`entityId`

```
{ "target": "workspace", "query": "Acme" }
```

* * *

## Financial Accounts

### `financial_accounts_query`

**read** · idempotent · `GET /user/workspaces/:workspaceId/entities`
Lists connected bank and payment accounts for a workspace.

Operation

Required fields

`list` (default)
`workspaceId`

```
{ "operation": "list", "workspaceId": "019e2df8-d291-7a06-9958-602ffc4e9b71", "search": "Chase" }
```

* * *

## Transactions

### `transactions_query`

**read** · idempotent
Finds, inspects, summarizes, and discovers match candidates for transactions.

Operation

Required fields

REST
`find`
`workspaceId`
`GET /transactions`
`get`
`transactionId`
`GET /transactions/:id`
`statistics`
`workspaceId`
`GET /transactions/statistics`
`suggested_transfers`
`transactionId`
`GET /transactions/:id/suggested-matches`
`suggested_accrual_transactions`
`transactionId`
`GET /transactions/:id/suggested-accrual-match-transactions`
`suggested_accrual_invoices`
`transactionId`
`GET /transactions/:id/suggested-accrual-match-invoices`
`suggested_accrual_bills`
`transactionId`
`GET /transactions/:id/suggested-accrual-match-bills`
`similar`
`transactionId`
`GET /transactions/:id/similar`
Use top-level `since` / `until` for date ranges, not `filters`. Accrual suggestion operations require the accrual ledger capability.

```
{
  "operation": "find",
  "workspaceId": "019e2df8-d291-7a06-9958-602ffc4e9b71",
  "since": "2026-01-01",
  "until": "2026-01-31",
  "filters": { "search": "Stripe" },
  "fields": ["id", "date", "amount", "counterparty"],
  "limit": 25
}
```

### `transactions_act`

**write** · destructive
Updates, bulk-updates, splits, creates manual transactions, and manages the soft-deletion lifecycle. Permanent hard deletion is not available.

Operation

Required fields

`update`
`transactionId`, `payload`
`bulk_update`
`workspaceId`, `payload`
`update_splits`
`transactionId`, `payload`
`bulk_unsplit`
`workspaceId`, `payload`
`create_manual`
`payload`
`bulk_mark_for_deletion`
`payload` (`transactionIds`)
`cancel_deletion`
`transactionId`
Single-transaction soft deletes use `bulk_mark_for_deletion` with one id in `transactionIds`.

```
{ "operation": "update", "transactionId": 12345, "payload": { "memo": "Owner reviewed" } }
```

### `transactions_transfer_matches_act`

**write** · destructive

Operation

Required fields

`match`
`originTransactionId`, `payload` (`targetTransactionId`)
`unmatch`
`financialTransactionId`

```
{ "operation": "match", "originTransactionId": 12345, "payload": { "targetTransactionId": 12346 } }
```

### `transactions_document_links_act`

**write** · destructive

Operation

Required fields

`link`
`payload` (`financialDocumentId`, `financialTransactionId`)
`detach`
`financialTransactionId`, `matchId`

```
{ "operation": "link", "payload": { "financialDocumentId": 34567, "financialTransactionId": 12345 } }
```

* * *

## Categories

### `categories_query`

**read** · idempotent

Operation

Required fields

`list`
`workspaceId`
`search`
`workspaceId`, `search`
`list_global`
_(none)_

`statistics`
`workspaceId`

```
{ "operation": "search", "workspaceId": "019e2df8-d291-7a06-9958-602ffc4e9b71", "search": "software" }
```

### `categories_act`

**write** · destructive · blocked in GL-first workspaces

Operation

Required fields

`create`
`workspaceId`, `payload`
`update`
`workspaceId`, `categoryId`, `payload`
`delete`
`workspaceId`, `categoryId`

* * *

## Classes

### `classes_query`

**read** · idempotent · requires Classes plan

Operation

Required fields

`list`
`workspaceId`
`search`
`workspaceId`, `search`
`statistics`
`workspaceId`
`transaction_counts`
`workspaceId`

### `classes_act`

**write** · destructive · requires Classes plan

Operation

Required fields

`create`
`workspaceId`, `label`
`update`
`workspaceId`, `classId`, `label`
`delete`
`workspaceId`, `classId`

* * *

## Counterparties

### `counterparties_query`

**read** · idempotent

Operation

Required fields

`list`
`workspaceId`
`search`
`workspaceId`, `search`

```
{ "operation": "search", "workspaceId": "019e2df8-d291-7a06-9958-602ffc4e9b71", "search": "Gusto" }
```

### `counterparties_act`

**write** · destructive

Operation

Required fields

`create`
`workspaceId`, `payload`
`update`
`workspaceId`, `counterpartyId`, `payload`
`delete`
`workspaceId`, `counterpartyId`
`merge`
`workspaceId`, `counterpartyToMergeId`, `counterpartyToKeepId`
`copy_global`
`workspaceId`, `globalCounterpartyId`

* * *

## Rules

### `rules_query`

**read** · idempotent

Operation

Required fields

`groups_list`
`workspaceId`
`accounting_defaults`
`workspaceId`
`normalized_descriptions`
`workspaceId`
`matching_transactions`
`workspaceId`, `payload`
`applied_transactions`
`workspaceId`, `ruleId`
`matching_transfers`
`workspaceId`, `payload`
`applied_transfers`
`workspaceId`, `ruleId`

```
{ "operation": "groups_list", "workspaceId": "019e2df8-d291-7a06-9958-602ffc4e9b71" }
```

### `rules_act`

**write** · destructive

Operation

Required fields

`create`
`workspaceId`, `payload`
`update`
`workspaceId`, `ruleId`, `payload`
`change_order`
`workspaceId`, `ruleId`, `payload`
`update_note`
`workspaceId`, `ruleId`, `payload`
`delete`
`workspaceId`, `ruleId`
`groups_create`
`workspaceId`, `payload`
`groups_update`
`workspaceId`, `groupId`, `payload`
`groups_delete`
`workspaceId`, `groupId`

* * *

## Accounting

### `accounting_query`

**read** · idempotent

Operation

Required fields

`accounts_list`
`entityId`
`accounts_get_workspace`
`workspaceId`
`ledgers_list`
`entityIds`
`ledgers_get`
`entityId`

```
{ "operation": "accounts_list", "entityId": 123 }
```

### `accounting_act`

**write** · destructive

Creates, updates, bulk-updates, enables, disables, or deletes chart-of-accounts entries. Account merge is not available through hosted MCP.

Operation

Required fields

`create`
`workspaceId`, `payload`
`update`
`entityId`, `accountId`, `payload`
`bulk_update`
`payload`
`bulk_disable`
`payload`
`bulk_enable`
`payload`
`bulk_delete`
`payload`

### `account_groups_act`

**write** · destructive

Operation

Required fields

`create`
`workspaceId`, `payload`
`update`
`workspaceId`, `groupId`, `payload`
`delete`
`workspaceId`, `groupId`

### `opening_balances_query`

**read** · idempotent

Operation

Required fields

`list`
`entityId`
`get`
`entityId`, `accountId`

### `opening_balances_act`

**write** · destructive

Operation

Required fields

`upsert`
`entityId`, `accountId`, `payload`
`bulk_set`
`entityId`, `payload`
`remove`
`entityId`, `accountId`

### `journals_query`

**read** · idempotent

Operation

Required fields

`list`
`entityId`
`get`
`entityId`, `journalEntryId`

### `journals_act`

**write** · destructive

Operation

Required fields

`create`
`entityId`, `payload`
`bulk_create`
`entityId`, `payload`
`update`
`entityId`, `journalEntryId`, `payload`
`delete`
`entityId`, `journalEntryId`, `payload`

```
{
  "operation": "create",
  "entityId": 123,
  "payload": {
    "ledgerBasis": "cash",
    "date": "2026-03-31",
    "memo": "Accrue rent",
    "lines": [
      { "accountId": "019e2df9-07fe-748d-a5c2-03ba571bda2d", "debit": 5000 },
      { "accountId": "019e2df9-07fe-7108-845b-405355baa1e7", "credit": 5000 }
    ]
  }
}
```

* * *

## Reports

### `reports_query`

**read** · idempotent

Multiplexes nine financial reports through the `report` parameter.

`report` value

Required `params`

`profit_loss`
`entityId`, `ledgerId`, `startDate`, `endDate`
`balance_sheet`
`entityId`, `ledgerId`, `startDate`, `endDate`
`trial_balance`
`entityId`, `ledgerId`, `startDate`, `endDate`
`cash_flow_statement`
`entityId`, `ledgerId`, `startDate`, `endDate`
`expenses_by_vendor`
`entityId`, `ledgerId`, `startDate`, `endDate`
`account_transactions`
`entityId`, `ledgerId`
`chart_of_accounts`
`workspaceId`
`owner_cash_flow`
`entityIds`
`top_transactions`
`entityIds`, `startDate`, `endDate`, `categoryIdentifier`

Resolve `ledgerId` via `accounting_query` { `operation`: `"ledgers_get"` } or `context_resolve` { `target`: `"ledger"` }.

```
{
  "report": "profit_loss",
  "params": {
    "entityId": 123,
    "ledgerId": "019e6a38-683c-7050-af2b-72978a5a3a46",
    "startDate": "2026-01-01",
    "endDate": "2026-03-31",
    "cycle": "month"
  }
}
```

* * *

## Documents

### `documents_query`

**read** · idempotent

Operation

Required fields

`search`
`workspaceId`
`get_metadata`
`financialDocumentId`

### `documents_download`

**read** · idempotent · `POST /financial-document/mcp-download`
Returns a presigned download URL. Requires `documentId`.

```
{ "documentId": 12345 }
```

### `documents_act`

**write**

Two-step upload flow.

Operation

Required fields

`request_upload`
`workspaceId`, `fileName`
`confirm_upload`
`uploadToken`

```
{ "operation": "request_upload", "workspaceId": "019e2df8-d291-7a06-9958-602ffc4e9b71", "fileName": "receipt-jan-2026.pdf" }
```

* * *

## Entities

### `entities_query`

**read** · idempotent

Operation

Required fields

`list`
_(none)_
`search`
`search`
`get_address`
`entityId`
`get_metadata`
`workspaceId`, `entityId`

```
{ "operation": "list", "workspaceId": "019e2df8-d291-7a06-9958-602ffc4e9b71", "limit": 25 }
```

### `entities_act`

**write** · destructive

Operation

Required fields

`create`
`payload`
`update`
`entityId`, `payload`
`update_address`
`payload` (includes `entityId`)
`save_tax_locations`
`payload` (includes `entityId`)

* * *

## Activity

### `activity_query`

**read** · idempotent

Operation

Required fields

`list`
`workspaceId`
`logs_list`
`workspaceId`
`details_get`
`workspaceId`, `date`, `sourceType`

```
{ "operation": "list", "workspaceId": "019e2df8-d291-7a06-9958-602ffc4e9b71", "filters": { "resourceTypes": ["transaction"] } }
```

### `activity_undo`

**write** · destructive · `POST /history/:workspaceId/history/revert`
Reverts a prior change. Requires `workspaceId`, `date`, `sourceType`, `resourceType`, `fields`, and `changeTypes`.

* * *

## Tasks

### `tasks_query`

**read** · idempotent

Operation

Required fields

`list` (default)
`workspaceId`

### `tasks_act`

**write** · destructive

Operation

Required fields

`create`
`workspaceId`, `payload`
`update`
`workspaceId`, `taskId`, `payload`
`delete`
`workspaceId`, `taskId`
New tasks are always type `question`.

* * *

## Organization Clients

### `organization_clients_create`

**write** · firm-admin only · `POST /organization-client/:organizationId`
Creates a new client organization workspace. Requires `organizationId` and `payload` (`workspaceName`, `entity`, `bookkeepingStartDate`, `servicesOffered`, `plan`, etc.). Listed only for organization-scoped or all-scoped credential grants.

* * *

## Skills

### `list_kick_skills`

**read** · idempotent

Lists available Kick skill guides. Skills document step-by-step workflows, query syntax, and pitfalls for related tools.

Parameter

Description

`query`
Optional ranked fuzzy search across skill names and descriptions

`includeHeader`
When true, include each skill's summary and covered tools

```
{ "query": "close the books", "includeHeader": true }
```

### `load_kick_skill`

**read** · idempotent

Loads a Kick skill guide by name. Call `list_kick_skills` first if you are not certain of the exact skill name.

Parameter

Description

`name`
Exact skill name from `list_kick_skills` (for example `kick/transaction-review-and-categorization`)

`headerOnly`
When true, return only the summary and covered tools without the full guide body

```
{ "name": "kick/transaction-review-and-categorization" }
```

* * *

## Invoices

Requires Accrual Ledger plan capability.

### `invoices_create`

**write** · `POST /invoices/:workspaceId/mcp`

Requires `workspaceId` and `payload.invoices[]` (each with `entityId`, `invoiceNumber`, `status`, `currency`, `lines`).

### `invoices_update`

**write** · destructive · `PUT /invoices/:workspaceId/mcp`

Batch edit or remove MCP-sourced invoices via `payload.upserts` and `payload.idsToRemove`. Only invoices with source `mcp` can be changed.

* * *

## Bills

Requires Accrual Ledger plan capability.

### `bills_create`

**write** · `POST /bills/:workspaceId/mcp`

Requires `workspaceId` and `payload.bills[]` (each with `entityId`, `invoiceNumber`, `status`, `currency`, `lines`).

### `bills_update`

**write** · destructive · `PUT /bills/:workspaceId/mcp`

Batch edit or remove MCP-sourced bills via `payload.upserts` and `payload.idsToRemove`. Only bills with source `mcp` can be changed.

* * *

## Common workflows

### Recategorize a transaction

1. `context_browse` or `context_resolve` → confirm workspace

2. `transactions_query` { `operation`: `