Payhawk MCP tool reference

Under the hood, the Payhawk MCP exposes a set of structured tools grouped by area. The list of tools you will see is filtered to your role and account setup.

Every tool is one of two kinds:

Read tools look up and return information (for example, fetching an expense or listing your cards). They never change anything, and they scope to your permissions automatically.
Write tools act on your behalf to make a change (for example, update category field on an expense). They always show a preview and need your confirmation.

Your AI Assistant picks the right tool automatically and you never need to name the tools. This Payhawk MCP tool reference is intended for IT and security reviewers, and the technically curious.

Handy tools to know

The following tools do something genuinely useful that’s worth having on your radar. They also appear in the full list of Payhawk MCP tools.

Tool	What it does	Who it’s for	When to use and when not
`submit_feedback`	Sends your feedback about the Payhawk assistant experience to Payhawk, in your own words, with one confirmation and no forms.	Everyone using the assistant - praise, frustration, a suggestion, or a bug gripe: any reaction to the MCP experience itself.	Use: The moment you express an opinion about the experience, the assistant offers, in one short sentence, to send it. Not for: Product questions or support requests (a different route) - this is feedback about the MCP, not a ticket.
`product_help`	Answers “How do I” and “Is X available to us” questions about Payhawk, tailored to what your account actually has switched on, grounded in help articles it can cite.	Everyone. Especially anyone who would otherwise open a support ticket for something an article answers: an employee stuck on a submission, a Payhawk Administrator checking whether a feature is in their plan.	Use: Product questions. How something works, whether you have it, how to switch it on. Not for: Diagnosing a specific payment, transaction or reimbursement from your own account (needs the live-data route), or feedback about the assistant (its own channel).
`list_card_acceptance_opportunities`	Lists the vendors you pay by bank transfer that are known to accept card payments, with the bank spend that could move to a Payhawk card and earn rewards.	Financial controllers and finance administrators looking for rewards on spend the company already has. This is the tool behind the cashback question.	Use: “Which vendors could we pay by card instead?” Not for: switching a payment method (done in each vendor’s own billing settings, never in Payhawk); it will never tell you a cashback amount, because reward rates are not Payhawk data.
`needs_my_attention`	Your Payhawk inbox in one call: everything waiting on you, such as pending approvals, requests, to-dos, missing receipts, plus finance and administrators signals where your role carries them.	Everyone, with role-shaped content: employees see their own items and failed card payments; finance sees uncoded and unexported counts; Payhawk Administrators see card signals.	Use: any “What needs me?” moment, from a morning catch-up to a pre-holiday sweep. Not for: a plain count of pending approvals (a lighter summary exists); it surfaces some items it cannot act on (for example, travel reviews, four-eyes approvals), which it flags for the app.
`insights_query_async`	Analysis over time - company/account/team/person totals and breakdowns. Monthly available balance trends use one closing snapshot per balance and month, never a sum of repeated snapshots.	—	—

Full list of supported tools

The following table lists the full set of tools supported as part of the Payhawk MCP.

Area	Tools
Expenses and documents	`list_expenses`, `get_expense`, `get_expense_approval_status`, `list_expense_payments`, `list_documents`, `upload_document`, `ingest_and_auto_match_receipt`, `create_expense`, `get_invoice_inbox`, `submit_expense`, `recode_expense`, `list_close_blockers`, `list_expense_reports`, `get_expense_report`, `list_expense_subscriptions`, `confirm_expense_subscription`, `manage_expense_subscription`, `list_mileage_claims`
Cards, funds, and transactions	`list_cards`, `get_card`, `update_card_status` (freeze, unfreeze, close), `list_card_requests`, `get_card_request`, `create_card_request`, `list_fund_accounts`, `get_fund_account`, `list_balances`, `list_fund_account_activity`, `get_upcoming_payments`, `get_transaction`, `get_fx_rate`
Approvals and review	`review_queue`, `needs_my_attention`, `get_approval_request`, `approve_or_return`, `complete_expense_review`, `return_expense_for_review`, `list_audit_logs`, `out_of_office_delegate`
Suppliers, purchase orders, and merchants	`list_suppliers`, `get_supplier`, `manage_supplier`, `list_purchase_orders`, `get_purchase_order`, `manage_purchase_order`, `list_purchase_order_types`, `list_merchants`, `get_merchant`, `list_card_acceptance_opportunities`
Accounting, export, and budgets	`list_export_history`, `list_failed_exports`, `list_export_templates`, `run_export`, `list_account_codes`, `list_tax_rates`, `list_custom_fields`, `list_expense_categories`, `get_expense_category`, `budgets`
People, teams, and policies	`list_accounts`, `list_users`, `get_user`, `list_teams`, `list_team_members`, `list_spend_policies`, `get_spend_policy`, `manage_spend_policy`
Comments	`add_comment`, `list_comments`
Payhawk agents and insights	`insights_query_async`, `get_job_status` (checks on background work), `travel_agent` , `procurement_agent`, `payments_agent`, `dispatch_widget_action` (used only when you click a button inside an interactive card, such as choosing a flight), `get_agent_job_status` (checks on agent and widget-continuation jobs)
Feedback	`submit_feedback`
Guidance	`product_help`, `list_playbooks`, `get_playbook`, `draft_playbook`, `manage_playbook`