> For the complete documentation index, see [llms.txt](https://docs.kick.co/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kick.co/ai/developer-tools/mcp/tool-reference.md).

# Tool Reference

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.

For a user-facing capability summary, see → [Kick Tool List](/ai/mcp/available-tools.md).

***

## 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

```json
{
  "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:

```json
{
  "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`, `financialDocumentId`                                            | positive integer              |
| `ruleId`, `groupId`, `categoryId`, `counterpartyId`, `classId`, `accountId`, `journalEntryId`, `taskId` | UUID v7 string                |

### 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`, `context_resolve`                                                                                                            |
| Financial accounts | `financial_accounts_query`                                                                                                                     |
| Transactions       | `transactions_query`, `transactions_act`, `transactions_transfer_matches_act`, `transactions_document_links_act`                               |
| Categories         | `categories_query`, `categories_act`                                                                                                           |
| Classes            | `classes_query`, `classes_act`                                                                                                                 |
| Counterparties     | `counterparties_query`, `counterparties_act`                                                                                                   |
| Rules              | `rules_query`, `rules_act`                                                                                                                     |
| Accounting         | `accounting_query`, `accounting_act`, `account_groups_act`, `opening_balances_query`, `opening_balances_act`, `journals_query`, `journals_act` |
| Reports            | `reports_query`                                                                                                                                |
| Documents          | `documents_query`, `documents_download`, `documents_act`                                                                                       |
| Entities           | `entities_query`, `entities_act`                                                                                                               |
| Activity           | `activity_query`, `activity_undo`                                                                                                              |
| Tasks              | `tasks_query`, `tasks_act`                                                                                                                     |
| Organization       | `organization_clients_create`                                                                                                                  |
| Invoices           | `invoices_create`, `invoices_update`                                                                                                           |
| Bills              | `bills_create`, `bills_update`                                                                                                                 |
| Skills             | `list_kick_skills`, `load_kick_skill`                                                                                                          |

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)*        |

```json
{ "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`      |

```json
{ "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`   |

```json
{ "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.

```json
{
  "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`.

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

### `transactions_transfer_matches_act`

**write** · destructive

| Operation | Required fields                                          |
| --------- | -------------------------------------------------------- |
| `match`   | `originTransactionId`, `payload` (`targetTransactionId`) |
| `unmatch` | `financialTransactionId`                                 |

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

### `transactions_document_links_act`

**write** · destructive

| Operation | Required fields                                             |
| --------- | ----------------------------------------------------------- |
| `link`    | `payload` (`financialDocumentId`, `financialTransactionId`) |
| `detach`  | `financialTransactionId`, `matchId`                         |

```json
{ "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`           |

```json
{ "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` |

```json
{ "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`  |

```json
{ "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`      |

```json
{ "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` |

```json
{
  "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"` }.

```json
{
  "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`.

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

### `documents_act`

**write**

Two-step upload flow.

| Operation        | Required fields           |
| ---------------- | ------------------------- |
| `request_upload` | `workspaceId`, `fileName` |
| `confirm_upload` | `uploadToken`             |

```json
{ "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` |

```json
{ "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` |

```json
{ "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        |

```json
{ "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                    |

```json
{ "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`: `"find"`, filters/search } → resolve `transactionId`
3. `categories_query` { `operation`: `"search"` } → resolve `categoryId`
4. `transactions_act` { `operation`: `"update"`, `transactionId`, `payload` } → preview → confirm

### Match a transfer

1. `transactions_query` { `operation`: `"find"` } → resolve origin `transactionId`
2. `transactions_query` { `operation`: `"suggested_transfers"` } → pick counterpart
3. `transactions_transfer_matches_act` { `operation`: `"match"` } → preview → confirm

### Run a P\&L

1. `context_resolve` { `target`: `"entity"` } → `entityId`
2. `accounting_query` { `operation`: `"ledgers_get"`, `entityId` } → `ledgerId`
3. `reports_query` { `report`: `"profit_loss"`, `params`: { dates, `entityId`, `ledgerId` } }

***

{% hint style="info" %}
For a user-facing summary of available capabilities, see → [Kick Tool List](/ai/mcp/available-tools.md).
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.kick.co/ai/developer-tools/mcp/tool-reference.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.