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.

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

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) 
{ "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_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
}

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

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