MCP tools reference
Every tool the SaaSFlow MCP server exposes, what it returns, and when an LLM should use it.
Nearly every tool is generated from an OpenAPI operation or a data slice, so the MCP surface and the REST API never drift apart. Only two tools are hand-written, because no single route backs them.
Read tools are always registered; write tools only when writes are
enabled. Every tool accepts an optional companyId. Connect with an API key and it
falls back to that key's company; with an OAuth token, pass it per call.
The agent_definitions_list and agent_runs_* tools are only listed when you connect
with an API key. An agent run is a server-side agent that calls tools of its own, so
assistants connected over OAuth (Claude, ChatGPT) do that work with the other tools
instead. The agent runs API stays
available to OAuth clients.
Server instructions
On connect, the server returns instructions covering the conventions that span the
whole catalogue: start from companies_list to get a companyId, use data_* tools
for any metric rather than summing transactions, amounts are signed decimal strings,
and subscription events are deltas rather than levels. Most clients surface this to
the model automatically.
Hand-written tools
| Tool | Purpose |
|---|---|
search | Free-text search across customers, vendors, accounts, and transactions in one call. Use it to turn a name into an id. |
run_data_batch | Run multiple data slices in one round trip. |
data_recurring_transactions | Recurring charges detected across the whole transaction history, one row per series (vendor, amount, frequency, active or ended). Filter by vendor or status; includeItems adds every charge. Needs transactions:read. |
get_started | On https://mcp.saasflow.com only. Reports which sign-in options the connection holds, which it lacks and what each unlocks, and how to add one. See Sign in. |
Read tools
One tool per OpenAPI GET operation, named <resource>_<verb>, plus the four POST
routes that only read (their input is a filter or selection object too structured for
a query string). Those four are available to read-only connections:
account_groups_get account_groups_list
accounts_balances accounts_daily_balance accounts_get
accounts_initial_balance accounts_list
accounts_remove_history_preview
agent_definitions_list agent_runs_get agent_runs_list
agent_runs_messages_list agent_runs_transcript
background_tasks_get background_tasks_list
billing_link
categories_get categories_list
comments_get comments_list
companies_get companies_list
counterparties_search
customers_external_ids customers_get customers_list
files_download files_get files_list
integrations_connect_link integrations_get
integrations_list
notifications_list
plan_items_get plan_items_list
planned_transaction_occurrences_list
planned_transactions_get planned_transactions_list
product_groups_get product_groups_list
products_external_ids products_get products_list
reports_get reports_list reports_versions_get
reports_versions_list
subscription_events_list
subscriptions_get subscriptions_list
transactions_categorization_status transactions_get
transactions_list transactions_search transactions_selection_summary
transactions_transfer_chain
vendors_apply_default_categorization_preview
vendors_external_ids vendors_get vendors_listtransactions_search is the one to reach for when transactions_list is not enough:
it takes a composable filter array with sorting, where the list endpoint only filters
by account and categorization status.
The data and search resources are skipped here because the hand-written tools and
the data_* tools cover them.
Write tools
Registered only when writes are enabled: the caller authenticated with an API key, or
with an OAuth token carrying the saasflow:write scope.
Every write runs through the same permission checks as the REST API. The API key's permission set, or the granting user's permissions, bound what a tool can touch.
These add data or flip a per-user flag, and carry destructiveHint: false:
account_groups_create
accounts_create
agent_runs_create agent_runs_messages_create
categories_create
categorization_suggestions_apply
comments_create comments_like comments_unlike
customers_create
files_upload
integrations_full_sync integrations_sync
notifications_create notifications_mark_all_read
notifications_mark_read notifications_mark_unread
plan_items_create
planned_transactions_create
product_groups_create
products_create
reports_create
subscription_events_create
subscriptions_create subscriptions_reimport
transactions_create transactions_create_counter_transaction
transactions_import
vendors_createEvery other write tool is listed under Destructive tools.
Setting up a company
An agent can take a person from an empty account to a company with data:
companies_createcreates a company with the person as owner. It is registered only for an OAuth token carryingsaasflow:create_companies: the person ticked Create companies for you on the consent screen and accepted the Terms of Service and the Data Processing Agreement for those companies there. API keys cannot create companies. A 403 withcodelegal_acceptance_requiredcomes with a link to create the company in the app instead. Withtypesandboxit creates a test company instead: no trial, deleted after 14 days, and withaddSampleDatafilled with example data.integrations_connect_linkreturns a link to the connect dialog for one provider, or for a bank. The person signs in with the provider there; the agent never sees provider credentials. Thenintegrations_listshows the integration, withinitialSetupCompletefalse until the first import is done. With anintegrationIdit links to the reconnect dialog of an integration instatuserror.integrations_syncpulls new data now (Stripe, Digistore24, PayPal, HubSpot, EBICS). It needsintegrations:write, which editors and owners have, andsaasflow:writeon an OAuth token.billing_linklinks to the billing page, where an owner picks a plan.
Keeping integrations right
integrations_sync covers most days. When numbers still look wrong, these do what the
integration menu in the app does:
subscriptions_reimportreads one subscription again from Stripe or HubSpot, say after a plan change at the source. It needssubscriptions:write.integrations_full_syncreads everything from Stripe, Digistore24, PayPal or EBICS again. Rows already there are updated, not duplicated. On a large account it can take hours.integrations_rebuildrecomputes what SaaSFlow derived from the provider data: Stripesubscriptionsortransactions, HubSpotsubscriptionsorcategorizations.
The last two need a company role that manages integrations, and saasflow:admin on an
OAuth token. Follow them in background_tasks_list.
File uploads
Pleo, Finway and DATEV payroll don't have an API SaaSFlow can pull from: the person exports a CSV and uploads it. An agent can do the upload when the person hands it the file:
integrations_uploadtakes the CSV as text and afilesaying what it is:pleoExport,pleoReimbursements,finwayTransactions,finwayExpensesordatevPayroll. The first account export sets up the integration and its account. Later uploads import into it, and sending a file twice doesn't duplicate rows.- Some uploads come back with questions, the same ones the app's dialog asks: which Pleo
column decides the category (
needsMappingField), which category each new Pleo value, Finway cost center or DATEV employee gets (needsMappings,needsDefaults). Nothing is imported yet. Ask the person, using theaiSuggestions as defaults, and send the same file again withplMappingFieldormappings. SaaSFlow keeps the answers for the next upload. - A Finway month that would change or remove rows already there answers 409 with a summary.
Show it to the person and resend with
confirmReplaceonly if they agree.dryRuncounts the changes without importing. integrations_upload_historylists the last 20 Pleo or Finway files with what each import did.
Both need a company role that manages integrations and an OAuth token with saasflow:admin.
Uploads are made by a person, so API keys get 403. Requests are capped at 20 MB.
Dashboards
An agent can build a custom dashboard the person then opens in the app, for a board meeting say, or a weekly cash review:
dashboard_widgets_listlists the widgets a dashboard can hold, with their default size and the permissions a viewer needs to see them.dashboards_createtakes a name and a list of widget ids and section headlines. Leave out the positions and SaaSFlow lays them out on the 12-column grid at their default sizes. The person owns the new dashboard, and the response has the link to open it.dashboards_list,dashboards_get,dashboards_updateanddashboards_deletework on the dashboards shared with the person: viewers read, editors change name and layout, owners delete.
Dashboards belong to people, so these tools need an OAuth connection (an API key gets
403), and changes need saasflow:write. Only dashboards shared with the person count,
even when they own the company. Sharing a dashboard with teammates or by public link stays
in the app. Every widget loads its data with the permissions of whoever opens it.
Admin tools
companies_update, integrations_delete and accounts_switch_to_manual change company
settings or integrations. They are registered only for an OAuth token carrying
saasflow:admin, or an API key whose permission list includes company:manage
(companies_update) or integrations:manage (the other two). accounts_switch_to_manual
also changes an account, so it needs accounts:write too: saasflow:write on an OAuth
token. The granting user's role still applies, so in practice that means an owner. All
three are destructive and listed below.
integrations_upload, integrations_upload_history, integrations_full_sync and
integrations_rebuild are registered the same way as the two integration tools. An API key
gets 403 from the upload tools, though: an import is always made by a person.
Members, API keys and deleting the company
An agent never makes these changes itself. It asks, and the person approves the exact change in the app:
-
access_requests_invite,access_requests_change_role,access_requests_remove_member,access_requests_revoke_invitation,access_requests_create_api_key,access_requests_revoke_api_keyandaccess_requests_delete_companyrecord a request and return aurl. Nothing changes yet. -
The person opens the link, signed in to SaaSFlow, and approves or declines. Approving makes the change right away with their own role, so the usual rules apply: nobody grants a permission they don't hold, changes their own membership, or removes the last member who manages users. Deleting the company also asks them to type its name.
-
access_requests_gettells the agent how it went:pending,succeeded,failedwith the reason,rejectedorexpired(after an hour). -
invitations_listandapi_keys_listshow the open invitations and the company's API keys (never their secrets), to pick what to withdraw or revoke.
These tools need an OAuth token with saasflow:admin, and the person's role must allow the
change (users:manage, api_keys:manage or company:manage). Only the person the token
belongs to can approve. A new API key is shown to them once, on the approval page; the agent
only learns its id. API keys can't ask for any of this.
Destructive tools
These delete or overwrite data. They carry destructiveHint: true, which is what
hosted clients gate a confirmation prompt on:
account_groups_delete account_groups_reorder account_groups_update
accounts_archive accounts_change_group accounts_delete
accounts_remove_history accounts_remove_history_bulk
accounts_reorder accounts_set_initial_balance
accounts_switch_to_manual accounts_unarchive accounts_update
categories_batch_delete categories_delete categories_merge
categories_reorder categories_update
comments_delete comments_update
companies_update
customers_batch_delete customers_delete customers_merge
customers_set_external_ids customers_update
dashboards_delete dashboards_update
files_batch_delete files_delete files_update
integrations_delete integrations_rebuild integrations_upload
notifications_batch_delete
plan_items_delete plan_items_update
planned_transactions_delete
planned_transactions_update
product_groups_delete product_groups_reorder product_groups_update
products_change_group products_delete products_reorder
products_set_external_ids products_update
reports_delete reports_patch
subscription_events_delete subscription_events_update
subscriptions_delete subscriptions_update
transactions_batch_delete transactions_batch_edit transactions_delete
transactions_link_stripe_invoices transactions_link_transfer
transactions_uncategorize transactions_unlink_transfer
transactions_update
vendors_apply_default_categorization vendors_batch_delete
vendors_delete vendors_merge vendors_set_external_ids
vendors_updateUpdates are on the list because they overwrite the previous values. Deletes go
further and are not reversible: a merge deletes the records it merged,
*_batch_delete removes up to 10,000 rows at a time, and accounts_remove_history
permanently drops transactions before a cut-off date. Where
a preview exists (accounts_remove_history_preview,
vendors_apply_default_categorization_preview,
transactions_selection_summary), run it first to show the user what will be affected.
Data-slice tools
One data_* tool per slice. The tool's input schema mirrors the slice's params, so an
LLM can fill them correctly without guessing.
data_mrrData data_mrrAtDate
data_mrrByProduct data_mrrChangeEvents
data_customerMrr data_customerChanges
data_customerMonthlyData data_monthlyData
data_cohorts data_retentionCohortDetail
data_cashFlowTimeSeries data_cashFlowByCategory
data_forecastCashFlowTimeSeries
data_balanceTimeSeries data_accountBalanceByAccount
data_accountBalanceKpis data_balanceByCashType
data_profitLossData data_revenueExpenses
data_revenueExpensesBar data_revenueExpensesByCategory
data_topExpenseVendors data_periodDetails
data_analytics data_metricDefinitions
data_metricExplanation
data_benchmarks data_valuationFor details on what each slice returns, see Data slices.
Behavioural hints
Every tool sets the three MCP annotations hosted clients use for confirmation prompts:
| Tools | Annotations |
|---|---|
| Read tools | readOnlyHint: true, destructiveHint: false |
| Creates and flag toggles (like, mark as read) | readOnlyHint: false, destructiveHint: false |
| Destructive tools | readOnlyHint: false, destructiveHint: true |
Each tool's title is repeated as annotations.title.
openWorldHint is false everywhere, because every tool is scoped to the caller's
own company. Classification is per route rather than per HTTP method, so a POST that
deletes in bulk or edits existing records is marked destructive, and a POST that only
reads is available to read-only connections.