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; on the stdio server it falls back to SAASFLOW_COMPANY_ID. On the hosted server it must be specified per call.

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.

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
ai_consents_list
background_tasks_get   background_tasks_list
categories_get         categories_list
comments_get           comments_list
companies_get          companies_list              company_users_list
counterparties_search
customers_external_ids customers_get               customers_list
files_download         files_get                   files_list
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_list

transactions_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:

Mode	Writes are enabled when
Stdio	`SAASFLOW_MCP_WRITES=1` is set in the server's environment.
Remote	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.

account_groups_create      account_groups_reorder     account_groups_update
accounts_archive           accounts_change_group      accounts_create
accounts_reorder           accounts_set_initial_balance
accounts_switch_to_manual  accounts_unarchive         accounts_update
agent_runs_create          agent_runs_messages_create ai_consents_create
categories_create          categories_reorder         categories_update
categorization_suggestions_apply
comments_create            comments_like              comments_unlike
comments_update
companies_update           company_users_set_role
customers_create           customers_set_external_ids customers_update
files_update               files_upload
notifications_create       notifications_mark_all_read
notifications_mark_read    notifications_mark_unread
plan_items_create          plan_items_update
planned_transactions_create                           planned_transactions_update
product_groups_create      product_groups_reorder     product_groups_update
products_change_group      products_create            products_reorder
products_set_external_ids  products_update
reports_create             reports_patch
subscription_events_create subscription_events_update
subscriptions_create       subscriptions_update
transactions_batch_edit    transactions_create
transactions_create_counter_transaction
transactions_import        transactions_link_transfer transactions_update
vendors_apply_default_categorization                  vendors_create
vendors_set_external_ids   vendors_update

Destructive tools

These delete data and are not reversible. They carry destructiveHint: true, which is what hosted clients gate a confirmation prompt on:

account_groups_delete      accounts_delete            accounts_remove_history
accounts_remove_history_bulk                          ai_consents_delete
categories_batch_delete    categories_delete          categories_merge
comments_delete            company_users_remove
customers_batch_delete     customers_delete           customers_merge
files_batch_delete         files_delete               integrations_delete
notifications_batch_delete
plan_items_delete          planned_transactions_delete
product_groups_delete      products_delete            reports_delete
subscription_events_delete subscriptions_delete
transactions_batch_delete  transactions_delete        transactions_uncategorize
transactions_unlink_transfer
vendors_batch_delete       vendors_delete             vendors_merge

Note that the list is not just the delete endpoints. 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

For 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`
Create, update, and other non-destructive writes	`readOnlyHint: false`, `destructiveHint: false`
Destructive tools	`readOnlyHint: false`, `destructiveHint: true`

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 is correctly marked destructive, and a POST that only reads is available to read-only connections.