Tool Reference | AI & MCP | Kick Docs

For the complete documentation index, see llms.txt. This page is also available as Markdown.

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 withoutconfirmationToken → 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

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

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

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