Skip to main content
TaxChad
Sign InRequest Early Access

MCP Tool Reference

Drive TaxChad from any AI assistant.

TaxChad exposes an OAuth-secured MCP server at https://taxchad.com/mcp. Every tool below is callable from Claude, ChatGPT, Cursor or any MCP-compatible client - as the signed-in user, subject to Row Level Security.

Quick start

  1. Add the MCP URL to your assistant: https://taxchad.com/mcp
  2. Sign in with your TaxChad account when the OAuth window pops up.
  3. First message: "Call whoami and list my companies."
  4. Then use the client_id it returns for company-scoped calls.

Signed in to TaxChad? See your AI Access audit log

Identity

Start here. Confirms who you are and which companies you can act on.

whoami- Who am I

Returns the signed-in user and the list of companies (client_ids) they can act on. Call this first.

No arguments.

Try saying

  • "Who am I connected as in TaxChad, and what companies can you see?"

Read-only

Query your books, payments, customers and statements. Safe to call any time.

get_merchant_summary- Company summary

Headline numbers for a company: balances, VAT status, unreconciled counts.

Arguments

  • client_iduuidOmit if you only have one company.

Try saying

  • "Give me a quick summary of my TaxChad company."
  • "How many unreconciled bank transactions do I have?"
list_recent_transactions- List recent bank transactions

Latest bank feed rows for a company.

Arguments

  • client_iduuid
    required
  • limitinteger 1-100Default 25.

Try saying

  • "Show me my last 25 bank transactions."
  • "Any big outgoings this week?"
list_transactions- List payments

Filter TaxChad Payments by date, direction, status, customer or amount.

Arguments

  • client_iduuid
  • fromISO date
  • toISO date
  • direction'in' | 'out'
  • statuspending | completed | failed | refunded
  • customer_iduuid
  • min_amountnumber
  • max_amountnumber
  • limit1-200Default 50.

Try saying

  • "List completed payments in from customers this month over £500."
  • "Show me failed payments in the last 30 days."
get_payment- Get payment

Full detail for one payment by id.

Arguments

  • client_iduuid
  • payment_iduuid
    required

Try saying

  • "What's the status of payment <id>?"
list_payment_links- List payment links

Pay-by-bank links, newest first.

Arguments

  • client_iduuid
  • statusactive | expired | paid | cancelled
  • limit1-200Default 50.

Try saying

  • "Which of my payment links are still active but unpaid?"
list_customers- List payments customers

Saved payers/beneficiaries for a company.

Arguments

  • client_iduuid
  • searchstringSubstring match on name/email.
  • limit1-200Default 50.

Try saying

  • "Find the customer record for Acme Ltd."
get_fee_ledger- Fees owed to TaxChad

Accrued, billed and unbilled TaxChad Payments fees.

Arguments

  • client_iduuid
  • fromISO date
  • toISO date

Try saying

  • "How much do I owe TaxChad in fees this quarter?"
get_statement- Get TaxChad statement

Fetch one statement by id, or list recent statements.

Arguments

  • client_iduuid
  • statement_iduuid
  • limit1-50Default 12.

Try saying

  • "Show me my last three TaxChad statements."
verify_account- Verify a UK bank account (AIS)

Confirmation-of-Payee style check via Finexer.

Arguments

  • client_iduuid
  • sort_codestring
  • account_numberstring
  • ibanstring
  • bicstring
  • account_namestring

Try saying

  • "Check that sort code 20-00-00 / account 12345678 belongs to Acme Ltd."

Note: Currently returns provider_unavailable until Finexer is live.

For accountants

Firm staff only. Triage, review, coding and practice management across every client of your firm. Reads are instant. Book-changing writes are two-step - preview first, then commit with the returned confirmation_token (15 minutes, single use); task and note updates are single step and write the same history events as the app. Callers without a firm membership get not_a_firm_member.

firm_overview- Firm overview

Cross-client snapshot: active clients, open alerts by severity, uncategorised transactions, tasks due and overdue, stale bank feeds.

No arguments.

Try saying

  • "Give me a triage overview of my firm this morning."
firm_list_clients- List firm clients

Every active client with VAT and deadline fields plus triage counts. Source of client_id for the other firm_ tools.

Arguments

  • searchstring
  • needs_attentionboolean
  • vat_registeredboolean
  • entity_typestring
  • limit1-200Default 100.

Try saying

  • "Which of my clients need attention right now?"
firm_client_status- Client status

One client in full: bank accounts with masked identifiers, open alerts, upcoming tasks, open queries, current and last VAT periods.

Arguments

  • client_iduuid
    required

Try saying

  • "Give me the full status of client <id>."
firm_ledger_health- Ledger health

Run the ledger invariant checks live, or return stored open alerts.

Arguments

  • client_iduuid
    required
  • livebooleanDefault true.

Try saying

  • "Run the ledger health checks for client <id>."
firm_list_exceptions- List exceptions

Uncategorised and suspense transactions for a client, grouped by normalised payee for bulk triage.

Arguments

  • client_iduuid
    required
  • bank_account_iduuid
  • fromISO date
  • toISO date
  • limit1-500Default 200.

Try saying

  • "Show the uncategorised transactions for client <id>, grouped by payee."
firm_statement_coverage- Statement coverage

Per bank account: first and last transaction dates, month gaps, months since last, and whether coverage reaches period end.

Arguments

  • client_iduuid
    required

Try saying

  • "Are there any statement gaps for client <id>?"
firm_vat_summary- VAT summary

Recent VAT periods with boxes, adjustments, filing due dates and movements versus the previous period.

Arguments

  • client_iduuid
    required
  • limit1-8Default 5.

Try saying

  • "Summarise the last four VAT returns for client <id>."
firm_vat_return- VAT return (live compute)

Computes the full nine-box return with the same engine as the app's VAT Return screen: all schemes, late claims, splits, journals, margin scheme and adjustments. Read only.

Arguments

  • client_iduuid
    required
  • vat_period_iduuidDefault: the period the app's VAT Return screen opens.

Try saying

  • "Compute the current VAT return for client <id> and explain each box."
firm_list_jobs- List tasks

Practice tasks across the firm with client and assignee names.

Arguments

  • statusstring
  • categorystring
  • client_iduuid
  • assignee'me' | 'unassigned' | uuid
  • due_within_days1-365
  • overdue_onlyboolean
  • limit1-500Default 200.

Try saying

  • "What tasks are overdue across the firm?"
  • "List my tasks due this month."
firm_job_detail- Task detail

One task in full: record, client, checklist, events and notes.

Arguments

  • job_iduuid
    required

Try saying

  • "Show me task <id> with its checklist."
firm_list_client_notes- Client notes

Internal notes on a client, pinned first.

Arguments

  • client_iduuid
    required
  • limit1-200Default 50.

Try saying

  • "What notes do we hold on client <id>?"
firm_chart_of_accounts- Chart of accounts

Compact nominal list: code, name, type, VAT treatment, active flag.

Arguments

  • client_iduuid
    required
  • include_inactiveboolean

Try saying

  • "List the active nominals for client <id>."
firm_list_rules- Coding rules

Allocation rules, description cleanup rules and firm payee-rule settings for a client.

Arguments

  • client_iduuid
    required

Try saying

  • "What coding rules are set up for client <id>?"
firm_preview_rule- Preview a coding rule

Dry-run a proposed rule: which uncategorised rows it would code, which coded rows conflict, which existing rules overlap. Returns the confirmation_token for firm_create_rule.

Arguments

  • client_iduuid
    required
  • match_textstring
    required
  • match_typecontains | word | all_words | starts_with | regexDefault all_words.
  • directionboth | money_in | money_outDefault both.
  • currencyISO 4217
  • category_codenominal code
    required
  • vat_rateS | R | Z | E | N | DR20 | DR5 | RC20 | OS | PVA | FRS
    required

Try saying

  • "Preview a rule coding everything containing 'tesco' to 7500 for client <id>."
firm_create_rule- Create a coding rule

Create an allocation rule. With apply_to_existing=true it also codes the previewed uncategorised rows - that needs the confirmation_token from firm_preview_rule for the identical rule.

Arguments

  • client_iduuid
    required
  • match_textstring
    required
  • match_typesee firm_preview_rule
  • directionsee firm_preview_rule
  • currencyISO 4217
  • category_codenominal code
    required
  • vat_ratesee firm_preview_rule
    required
  • apply_to_existingbooleanDefault false.
  • confirmation_tokenstringRequired with apply_to_existing.

Try saying

  • "Create that rule and apply it to the existing transactions."
firm_delete_rule- Delete a coding rule

Remove one allocation rule. Transactions already coded are never touched.

Arguments

  • client_iduuid
    required
  • rule_iduuid
    required

Try saying

  • "Delete rule <id> for client <id>."
firm_rule_hygiene- Rule hygiene report

Rules matching nothing, duplicate pairs, rules pointing at archived nominals, and same match text mapping to different categories or VAT rates.

Arguments

  • client_iduuid
    required

Try saying

  • "Check the coding rules for client <id> for problems."
firm_categorise_transactions- Code bank transactions

Two-step manual coding of 1-100 uncategorised transactions. First call returns a per-item preview and confirmation_token; second call commits exactly the previewed items.

Arguments

  • client_iduuid
    required
  • items[]array
    required
    transaction_id, category_code, vat_rate.
  • confirmation_tokenstringSecond call only.

Try saying

  • "Code these five transactions to 7500 standard-rated for client <id>."
firm_update_job- Update a task

Change one task's stage, assignee, reviewer, internal deadline or internal notes. Writes the same history events as the app. Setting status to filed is refused - use firm_mark_job_filed.

Arguments

  • job_iduuid
    required
  • statusstageAny stage except filed.
  • assigneeuuid | 'me' | null
  • revieweruuid | 'me' | null
  • internal_deadlineISO date | null
  • internal_notesstring

Try saying

  • "Move the Bakeaway VAT task to review and assign it to me."
firm_mark_job_filed- Mark a task filed

Mark one task filed with the mandatory filing reference and an optional filing date (defaults to today).

Arguments

  • job_iduuid
    required
  • filed_referencestring
    required
  • filed_atISO dateDefault today.

Try saying

  • "Mark task <id> filed with reference ABC-123."
firm_create_job- Create a task

Create a task for one client, from a template (by id or code, with the app's deadline derivation and checklist seeding) or ad hoc with an explicit statutory deadline.

Arguments

  • client_iduuid
    required
  • template_iduuidOr template_code.
  • template_codestringOr template_id.
  • titlestring
  • statutory_deadlineISO dateRequired for ad hoc jobs.
  • assigneeuuid | 'me'

Try saying

  • "Create the annual accounts task for client <id> and assign it to me."
firm_add_client_note- Add a client note

Add an internal practice note to a client's record, optionally pinned. Never client visible.

Arguments

  • client_iduuid
    required
  • bodystring
    required
  • pinnedboolean

Try saying

  • "Note on client <id>: waiting for their March statements."
firm_log_chase- Log a client chase

Record that the client was chased about a task, by email or WhatsApp, with an optional note. Writes the history line only - sends nothing.

Arguments

  • job_iduuid
    required
  • channelemail | whatsapp
    required
  • notestring

Try saying

  • "Log that I chased the client by email about task <id>."
firm_list_staff- List firm staff

Members of your firms with name, role and access scope - the source of assignee and reviewer ids.

No arguments.

Try saying

  • "Who can I assign tasks to?"
firm_create_transaction_query- Query the client about transactions

Ask a client what 1-100 uncategorised transactions were for, via the client portal. Without send: creates the query and returns the portal link (single step). With send=true: two-step preview then commit, emailing the portal link.

Arguments

  • client_iduuid
    required
  • transaction_ids[]uuid array
    required
  • messagestringOptional message to the client.
  • sendbooleantrue = email flow (two-step).
  • confirmation_tokenstringSecond call of the send flow.

Try saying

  • "Ask Cooking It what these six transactions were for."
firm_preview_statement_import- Preview a statement import (step 1 of 2)

Parse a CSV or PDF bank statement for one client account and preview the import: duplicates already in the ledger, new rows, date range, gap since the last transaction and opening balance tie. Nothing is written; returns a confirmation_token.

Arguments

  • client_iduuid
    required
  • bank_account_iduuid
    required
  • format_idstringOmit to auto-detect by header signature.
  • csv_textstringRaw CSV contents (or pdf_base64).
  • pdf_base64stringBase64 PDF. Automated text extraction - rows need review.
  • filenamestring
    required

Try saying

  • "Here is the January statement CSV for client <id> - preview the import."
firm_import_statement- Import a previewed statement (step 2 of 2)

Consumes the preview's confirmation_token (15 minutes, single use) and posts exactly the stored rows through the same dedupe, fingerprints, GBP stamping and opening balance anchoring as the in-app importers.

Arguments

  • client_iduuid
    required
  • bank_account_iduuid
    required
  • confirmation_tokenstring
    required

Try saying

  • "The preview looks right - import it."

Create

Draft new records. No money moves.

create_payment_link- Create pay-by-bank link

Generate a pay-by-bank link (single, multiple-use or variable).

Arguments

  • client_iduuid
  • amountnumberRequired unless type='variable'.
  • currencyISO 4217Default GBP.
  • referencestring
    required
  • descriptionstring
  • typesingle | multiple | variableDefault single.
  • customer_iduuid
  • expires_atISO datetime
  • settlement_account_iduuid
  • idempotency_keystring
    required

Try saying

  • "Create a £250 pay-by-bank link for invoice INV-1042."
  • "Give Acme Ltd a reusable variable-amount payment link."
create_customer- Create payments customer

Add a saved customer/beneficiary.

Arguments

  • client_iduuid
  • namestring
    required
  • emailemail

Try saying

  • "Add a new customer called Acme Ltd, email ap@acme.co.uk."
request_ais_consent- Request AIS consent link

Ask a customer for account-info consent (Finexer).

Arguments

  • client_iduuid
  • customer_iduuid
    required
  • callback_urlurl

Try saying

  • "Send an AIS consent request to my customer <id>."

Note: Returns provider_unavailable until Finexer is live.

Money-movement

Two-step: preview first, then execute with the returned confirmation_token. Requires platform kill-switch off + per-company opt-in.

create_payout- Send a payout

Send a payout to a verified beneficiary.

Arguments

  • client_iduuid
  • beneficiary_account_refstring
    required
  • amountnumber
    required
  • currencyISO 4217Default GBP.
  • referencestring
    required
  • idempotency_keystring
    required
  • confirmation_tokenstringSecond call only.

Try saying

  • "Pay £1,200 to my supplier beneficiary <ref> with reference 'INV-882'."

Note: Returns compliance_gate until TaxChad Payments launches.

create_bulk_payout- Send a batch of payouts

Batch of up to 100 payouts. Same two-step confirmation.

Arguments

  • client_iduuid
  • idempotency_keystring
    required
  • items[]array
    required
    beneficiary_account_ref, amount, currency, reference.
  • confirmation_tokenstring

Try saying

  • "Run this week's payroll: pay these 8 staff their net amounts."

Note: Returns compliance_gate until TaxChad Payments launches.

create_vrp_mandate- Create VRP mandate (Beta)

Variable Recurring Payment mandate for a customer.

Arguments

  • client_iduuid
  • customer_iduuid
    required
  • max_per_paymentnumber
    required
  • max_per_periodnumber
    required
  • periodday | week | month | year
    required
  • referencestring
    required

Try saying

  • "Set up a monthly VRP for customer <id>, max £500/payment, £2000/month."

Note: Returns compliance_gate until TaxChad Payments launches.

execute_vrp_collection- Execute VRP collection (Beta)

Pull a payment under an active VRP mandate.

Arguments

  • client_iduuid
  • mandate_iduuid
    required
  • amountnumber
    required
  • currencyISO 4217Default GBP.
  • referencestring
    required
  • idempotency_keystring
    required

Try saying

  • "Collect £199 under mandate <id> for this month's subscription."

Note: Returns compliance_gate until TaxChad Payments launches.

Admin

TaxChad staff only. Rejected for non-admin callers.

admin_platform_summary- Admin: platform summary

Rolling platform-wide totals across all merchants.

Arguments

  • days1-365Default 30.

Try saying

  • "Give me a 30-day TaxChad platform summary."

Works with Claude, in early access. Not technical? See the plain-English guide to bookkeeping with Claude.

AI bookkeeping with Claude