Tool Reference

Complete technical reference for Kick MCP tools, endpoints, auth, conventions, inputs, and tool details.

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.

---

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

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

---

For a user-facing summary of available capabilities, see → Kick Tool List.