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

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

### 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_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
}
```

### 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" }
```

### Classes

### `classes_query`

**read** · idempotent · requires Classes plan

| Operation            | Required fields         |
| -------------------- | ----------------------- |
| `list`               | `workspaceId`           |
| `search`             | `workspaceId`, `search` |
| `statistics`         | `workspaceId`           |
| `transaction_counts` | `workspaceId`           |

### Invoices

### `invoices_create`

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

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

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