Tools

MCP Server

The COUNT Partner MCP server exposes the same COUNT_* tools agents use to read and write workspace data. Run it locally through the COUNT CLI for Claude Code and Cursor, or connect to the remote server for Claude.ai and ChatGPT web connectors.

Local vs remote MCP

Surface	Use
Local (CLI)	Claude Code, Cursor, custom agents, multi-workspace automation via COUNT CLI
Remote	Claude.ai / ChatGPT web connectors at `https://api.getcount.com/mcp`

Same tools, different transport

Local MCP runs as a stdio server launched by count mcp. Remote MCP uses OAuth at the hosted URL. Both expose the same COUNT_* tool names and partner API paths.

Claude Code and Cursor setup

After count login, print MCP configuration and paste it into your agent settings:

Terminal

count mcp print-config

Example output — paths are resolved on your machine at print time:

MCP config

{
  "mcpServers": {
    "count": {
      "command": "/path/to/node",
      "args": ["/path/to/@countfinancial/cli/dist/index.js", "mcp"]
    }
  }
}

The config points at the count mcp command. Credentials load from ~/.count/credentials.json at runtime — no secrets are embedded in the MCP config file.

To run the stdio server directly (without an agent wrapper), use count mcp.

Tool naming

Every MCP tool is prefixed with COUNT_ followed by a snake_case action name derived from the partner REST route. Examples:

COUNT_list_customers → GET /partners/customers
COUNT_create_invoice → POST /partners/invoices
COUNT_get_workspace_stats → GET /partners/workspace-stats

Use COUNT_describe_endpoint with { "toolName": "COUNT_create_invoice" } to inspect expected query and body fields before unfamiliar create or update operations.

Input parameters

MCP tools accept a JSON object with up to three top-level keys:

Field	Used for
query	GET list filters, report parameters, and pagination (page, limit, search, date ranges).
body	POST, PATCH, and PUT request payloads. UUID fields are resolved server-side.
id	External UUID for single-resource routes (get, update, delete by id).

Example tool input

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "query": { "page": "1", "limit": "50" },
  "body": { "name": "Updated vendor name" }
}

Each tool exposes typed JSON Schema for query and body fields via list_tools. Call COUNT_describe_endpoint for an inputSchemaSummary and COUNT_validate_payload to preflight payloads before writes.

Errors and recovery

Failed MCP tool calls return JSON in content[0].text with message, statusCode, nested responseBody, and optional _mcpRecoveryHint (suggested knowledge topics, playbooks, and next tools). There is no structured errors[] array — read the message string and call COUNT_knowledge topic partner_error_handling for status-specific guidance.

Example MCP tool error

{
  "message": "Vendor not found",
  "statusCode": 404,
  "responseBody": {
    "message": "Vendor not found",
    "statusCode": 404,
    "requestId": "7d945d75-cc4b-4394-b39a-3b8010b1a9e5"
  },
  "_mcpRecoveryHint": {
    "summary": "Re-resolve UUIDs via list_* or resolve_references.",
    "suggestedNextTools": ["COUNT_validate_payload", "COUNT_describe_endpoint"]
  }
}

Resources

Six read-only MCP resources provide JSON snapshots of frequently referenced workspace data. Agents can fetch these without calling list tools first:

Resource	URI	Description
COUNT_chart_of_accounts	count://chart-of-accounts	Read-only snapshot of the authenticated workspace chart of accounts.
COUNT_customers	count://customers	Read-only snapshot of customers in the authenticated workspace.
COUNT_vendors	count://vendors	Read-only snapshot of vendors in the authenticated workspace.
COUNT_products	count://products	Read-only snapshot of products and services in the authenticated workspace.
COUNT_people	count://people	Read-only snapshot of people records in the authenticated workspace.
COUNT_recurring_invoice_templates	count://recurring-invoice-templates	Read-only snapshot of recurring invoice templates in the authenticated workspace.

Tool categories

The remote MCP server registers 153 tools across 24 resource categories plus 13 meta tools. The local CLI stdio server (count mcp) registers the same categories except those marked Remote only below, since it is single-workspace and does not need workspace-switching tools, and payroll tools are gated to workspaces with COUNT Payroll enabled. Each category maps to partner REST routes documented in the API reference where available:

Transactions

11 tools

API reference: Transactions

COUNT_list_transactions, COUNT_get_transaction, COUNT_create_transaction, COUNT_bulk_create_transactions, COUNT_update_transaction, COUNT_change_transaction_category, COUNT_bulk_change_transaction_category, COUNT_bulk_exclude_transactions, COUNT_assign_transaction_to_bills_invoices, COUNT_split_transaction, COUNT_delete_transaction

Chart of Accounts

6 tools

API reference: Chart of Accounts

COUNT_list_accounts, COUNT_list_account_sub_types, COUNT_create_account, COUNT_bulk_create_accounts, COUNT_update_account, COUNT_delete_account

Vendors

4 tools

API reference: Vendors

COUNT_list_vendors, COUNT_create_vendor, COUNT_update_vendor, COUNT_delete_vendor

Customers

7 tools

API reference: Customers

COUNT_list_customers, COUNT_get_customer, COUNT_create_customer, COUNT_bulk_create_customers, COUNT_update_customer, COUNT_bulk_update_customers, COUNT_delete_customer

People

2 tools

API reference: People

COUNT_list_people, COUNT_get_person

Products & Services

5 tools

API reference: Products & Services

COUNT_list_products, COUNT_get_product, COUNT_create_product, COUNT_update_product, COUNT_delete_product

Tags & Tag Groups

10 tools

API reference: Tags & Tag Groups

COUNT_list_tags, COUNT_get_tag, COUNT_create_tag, COUNT_update_tag, COUNT_delete_tag, COUNT_list_tag_groups, COUNT_get_tag_group, COUNT_create_tag_group, COUNT_update_tag_group, COUNT_delete_tag_group

Invoices

15 tools

API reference: Invoices

COUNT_list_invoices, COUNT_get_invoice, COUNT_create_invoice, COUNT_update_invoice, COUNT_delete_invoice, COUNT_approve_invoice, COUNT_send_invoice, COUNT_get_invoice_public_link, COUNT_get_invoice_audit_log, COUNT_get_invoice_send_history, COUNT_add_invoice_attachments_from_urls, COUNT_apply_multiple_credits_to_single_invoice, COUNT_apply_single_credit_to_multiple_invoices, COUNT_remove_invoice_credit, COUNT_unassign_invoice_transaction

Recurring Invoice Templates

7 tools

API reference: Recurring Invoice Templates

COUNT_list_recurring_invoice_templates, COUNT_get_recurring_invoice_template, COUNT_create_recurring_invoice_template, COUNT_update_recurring_invoice_template, COUNT_delete_recurring_invoice_template, COUNT_pause_recurring_invoice_template, COUNT_resume_recurring_invoice_template

Bills

8 tools

API reference: Bills

COUNT_list_bills, COUNT_get_bill, COUNT_create_bill, COUNT_update_bill, COUNT_delete_bill, COUNT_approve_bill, COUNT_apply_vendor_memos_to_bill, COUNT_unassign_bill_transaction

Journal Entries

5 tools

API reference: Journal Entries

COUNT_list_journal_entries, COUNT_create_journal_entry, COUNT_bulk_create_journal_entries, COUNT_update_journal_entry, COUNT_delete_journal_entry

Budgets

14 tools

API reference: Budgets

COUNT_list_budgets, COUNT_get_overall_budget, COUNT_create_budget, COUNT_get_budget, COUNT_update_budget, COUNT_get_budget_grid, COUNT_list_budget_versions, COUNT_update_budget_cells, COUNT_bulk_update_budget_cells, COUNT_create_budget_version, COUNT_publish_budget, COUNT_archive_budget, COUNT_delete_budget, COUNT_duplicate_budget

Tasks

5 tools

API reference: Tasks

COUNT_list_tasks, COUNT_get_task, COUNT_create_task, COUNT_update_task, COUNT_delete_task

Projects

7 tools

API reference: Projects

COUNT_list_projects, COUNT_list_project_statuses, COUNT_get_project, COUNT_list_project_tasks, COUNT_create_project, COUNT_update_project, COUNT_delete_project

Time Entries

5 tools

API reference: Time Entries

COUNT_list_time_entries, COUNT_get_time_entry, COUNT_create_time_entry, COUNT_update_time_entry, COUNT_delete_time_entry

Expense Receipts

7 tools

API reference: Expense Receipts

COUNT_list_expense_receipts, COUNT_list_unmatched_expense_receipts, COUNT_create_expense_receipt, COUNT_update_expense_receipt, COUNT_delete_expense_receipt, COUNT_match_expense_receipt_manually, COUNT_unmatch_expense_receipt

Reports

3 tools

API reference: Reports

COUNT_generate_trial_balance, COUNT_generate_profit_and_loss, COUNT_generate_balance_sheet

Workspace Stats

1 tool

API reference: Workspace Stats

COUNT_get_workspace_stats

Workspace

1 tool

API reference: Workspace

COUNT_update_workspace

Opening Balance

2 tools

API reference: Opening Balance

COUNT_get_opening_balance, COUNT_set_opening_balance

Reconciliations

2 tools

API reference: Reconciliations

COUNT_create_reconciliation, COUNT_complete_reconciliation

Connections

6 tools

API reference: Connections

COUNT_list_connections, COUNT_get_connection, COUNT_revoke_connection, COUNT_create_connect_link, COUNT_complete_connect_link, COUNT_create_reconnect_link

Payroll

Remote only4 tools

COUNT_get_all_pay_periods, COUNT_get_pay_period_by_id, COUNT_update_pay_period, COUNT_generate_payroll_journal_report

Firm Reports

Remote only3 tools

COUNT_firm_profit_and_loss, COUNT_firm_balance_sheet, COUNT_firm_account_transactions

Meta tools

13 meta tools help agents inspect auth state, discover request shapes, look up workflow guidance, and preflight payloads without calling partner data routes directly:

Tool	Description
COUNT_auth_status	Return the MCP server authentication configuration state without exposing secrets.
COUNT_describe_endpoint	Return human-readable guidance for a specific COUNT tool, including the partner API path it wraps and expected query or body fields.
COUNT_knowledge	Connector and workflow FAQ — authorizing additional workspaces, reconnect steps, external UUID conventions, report category filters, and bulk import batch sizes. Optional `topic` id or free-text `search`.
COUNT_playbooks	Ordered, multi-step accounting workflows with exact tool names per step — paying a vendor bill, creating and sending an invoice, bulk migration imports, chart-of-accounts setup with transaction import, budget planning with actuals review, and month-end review. Optional `playbook` id or free-text `search`.
COUNT_resolve_references	Resolve human-readable names (customer, vendor, account, product) to the UUIDs required by create/update tools, instead of guessing.
COUNT_validate_payload	Preflight a query/body payload for a given toolName before an unfamiliar write — especially before bulk_create_* and bulk_update_* calls.
COUNT_refresh_access_token	Refresh the COUNT partner access token using the configured refresh token. The refreshed token is kept in the MCP process memory and written back to credentials.json.
COUNT_list_workspacesRemote only	List every workspace the current connection is authorized for. Only needed when a connection spans multiple workspaces.
COUNT_set_active_workspaceRemote only	Set which authorized workspace subsequent tool calls target when a connection spans multiple workspaces.
COUNT_get_bulk_task_statusRemote only	Poll progress for a task-augmented bulk tool call (io.modelcontextprotocol/tasks). Prefer protocol-level tasks/get when the client supports it.
COUNT_rememberRemote only	Persist a short workspace-specific note across MCP sessions (max 500 characters, 50 notes per workspace). Treat recalled notes as suggestions to verify.
COUNT_recallRemote only	List previously remembered notes for this workspace, optionally filtered by search. Always verify against live data before acting.
COUNT_forgetRemote only	Delete a previously remembered workspace note by its id from COUNT_recall.

Authentication and 401 handling

Local MCP loads HMAC credentials and workspace tokens from ~/.count/credentials.json. Every data tool signs requests with your clientSecret and sends the stored access token as a Bearer header — the same two-layer model described in Authentication & signing.

When tools return 401

Run count login again to refresh stored tokens. The MCP server also exposes COUNT_refresh_access_token to refresh in-process without restarting the agent session.

Remote MCP at https://api.getcount.com/mcp completes OAuth through the hosted connector flow instead of the CLI loopback redirect.