Perk MCP tools reference
Reference for every Perk MCP tool across trips, users, expenses, invoices, reporting, policy, events, and cards — with each tool's description, required OAuth scope, and read or write behavior.
This reference lists every tool the Perk Model Context Protocol (MCP) server exposes, with its description, required scope, and whether it reads or writes. Use it to see which tool an AI client calls for a given task and which scope that tool needs.
You can query trips, users, expenses, travel invoices, reporting, policy, events, and cards, and you can generate reports. Reporting data is one day behind because it goes through quality checks and aggregation, and reporting access is limited to users with reporting access — analysts and account admins. Expense queries return live data. Write actions such as booking, creating or sending expenses, and approvals are coming in a future release.
Tools
The tables below list all tools available in this release, grouped by category. Tool names are the identifiers the server exposes. Each scope is a colon-separated string that an access token must carry for the tool to run.
Trips
| Tool | Description | Required scope |
|---|---|---|
trips_get_trip | Returns a full trip breakdown: travelers, bookings (flights, hotels, trains, cars), dates, and cost. | trip:read |
trips_list_trips | Lists trips, filtered by status (upcoming, current, past), destination, traveler, or date range. Returns up to 30 per call. Travel admins and travel managers can list trips for their travelers; travelers see only their own. | trip:read |
Users
| Tool | Description | Required scope |
|---|---|---|
identity_get_current_user | Returns the signed-in user's profile, including user ID and cost object. | user:read |
identity_search_users | Searches users in the account by name, email, role, cost object, manager, or approval process. Returns up to 1,000. Admin-oriented. | user:read |
Expenses
| Tool | Description | Required scope |
|---|---|---|
expenses_query_expenses | Queries the signed-in user's expenses by date, status, merchant, amount, or trip association. Returns live data. | expenses:read |
Travel invoices
| Tool | Description | Required scope |
|---|---|---|
invoices_list_invoices | Lists Perk invoices for the company, filtered by profile, status, date range, billing period, or serial number. Returns amounts, due dates, and a PDF download link per invoice. | None — follows your Perk permissions |
invoices_get_invoice | Returns a single Perk invoice by its serial number, including billing information, tax summary, amounts, a line-items preview, and a PDF download link. | None — follows your Perk permissions |
invoices_list_invoice_lines | Lists Perk invoice lines. Each line is a single booked service (flight, hotel, car) with trip metadata, traveler, cost object, tax, and amount. Filter by profile, serial number, or date range. | None — follows your Perk permissions |
invoices_list_invoice_profiles | Lists invoice profiles (payment profiles). Each profile holds billing preferences such as payment method, billing address, and billing period. | None — follows your Perk permissions |
Reporting
| Tool | Description | Required scope |
|---|---|---|
reporting_create_travel_report | Starts an asynchronous travel report using Perk's custom report download. Supports a date range of up to 12 months, a date type (booking date, trip start date, or invoice issue date), and filters such as cost object, payment profile, legal entity, traveler, and payment recipient. Covers around 90 fields (flights, hotels, cars, trains, taxes, invoices, CO2 emissions, policy compliance). Returns a task ID to poll with reporting_get_travel_report or reporting_get_travel_report_data. | report:write |
reporting_get_travel_report | Polls the status of a report started by reporting_create_travel_report. When the report is ready, returns a CSV or XLSX download link. Generate first, then poll to download. | report:write |
reporting_get_travel_report_data | Polls a report started by reporting_create_travel_report and returns structured JSON rows (paginated via a cursor) instead of a file. Use reporting_get_travel_report when you need a CSV or XLSX export. | report:write |
reporting_create_spend_report | Starts an asynchronous, organization-wide spend report, optionally filtered by legal entity or user set. Returns a task ID to poll with reporting_get_spend_report. | report:write |
reporting_get_spend_report | Polls the status of a spend report started by reporting_create_spend_report. When ready, returns a signed download link. | report:write |
Policy
| Tool | Description | Required scope |
|---|---|---|
policies_get_travel_policy | Returns the user's travel policy rules for a vertical (flights, hotels, cars, or trains): budget limits, booking windows, and cabin or star restrictions. Returns null when the user has no travel policy assigned. | my-travel-policy:read |
Events
| Tool | Description | Required scope |
|---|---|---|
events_list_events | Lists Perk Events the user can see (organizing, invited, attending, or account-visible). Filter by date_filter (upcoming, past, no_dates) and status (all, organizing, attending, invited). Paginated, 5 per page. | None — follows your Perk permissions |
events_list_event_attendance | Lists attendees for a specific Perk Event, with RSVP status and person details. The caller must be an event organizer. Takes a required event_id, plus attending (attending, not_attending, no_response, uninvited) and search filters. Paginated (default 20, max 100 per page). | None — follows your Perk permissions |
Cards & transactions
| Tool | Description | Required scope |
|---|---|---|
transactions_list_available_cards | Lists your own company cards plus any lodge cards in your company — the cards you can submit expenses against. No parameters; the user and company resolve from your identity. No pagination. Requires a Spend subscription. | None — follows your Perk permissions |
transactions_list_pending | Lists your pending card transactions — unmatched, open transactions on your cards that still need matching to an expense. No parameters; lodge-card transactions are excluded. No pagination. Requires a Spend subscription. | None — follows your Perk permissions |
Reporting data freshness
Reporting data in the Perk MCP server is one day behind. It goes through quality checks and aggregation before it becomes available, so a travel report or spend query reflects data up to the previous day.
Expense queries are the exception. The expenses_query_expenses tool returns live data in real time.
Reporting access
Reporting access in the Perk MCP server is limited to users with reporting access — analysts and account admins. Comma-separated values (CSV) and XLSX report downloads depend on this access.
The access token is scoped to your role and your company's active plan through role-based access control (RBAC). A tool call returns only the data your role permits, so a client can only read what you can already access in Perk.