Skip to Content
SaaSFlow
DevelopersMCP

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

ToolPurpose
searchFree-text search across customers, vendors, accounts, and transactions in one call. Use it to turn a name into an id.
run_data_batchRun multiple data slices in one round trip.
data_recurring_transactionsRecurring 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_startedOn 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_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: 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_create

Every 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_create creates a company with the person as owner. It is registered only for an OAuth token carrying saasflow: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 with code legal_acceptance_required comes with a link to create the company in the app instead. With type sandbox it creates a test company instead: no trial, deleted after 14 days, and with addSampleData filled with example data.
  • integrations_connect_link returns 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. Then integrations_list shows the integration, with initialSetupComplete false until the first import is done. With an integrationId it links to the reconnect dialog of an integration in status error.
  • integrations_sync pulls new data now (Stripe, Digistore24, PayPal, HubSpot, EBICS). It needs integrations:write, which editors and owners have, and saasflow:write on an OAuth token.
  • billing_link links 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_reimport reads one subscription again from Stripe or HubSpot, say after a plan change at the source. It needs subscriptions:write.
  • integrations_full_sync reads everything from Stripe, Digistore24, PayPal or EBICS again. Rows already there are updated, not duplicated. On a large account it can take hours.
  • integrations_rebuild recomputes what SaaSFlow derived from the provider data: Stripe subscriptions or transactions, HubSpot subscriptions or categorizations.

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_upload takes the CSV as text and a file saying what it is: pleoExport, pleoReimbursements, finwayTransactions, finwayExpenses or datevPayroll. 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 the aiSuggestions as defaults, and send the same file again with plMappingField or mappings. 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 confirmReplace only if they agree. dryRun counts the changes without importing.
  • integrations_upload_history lists 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_list lists the widgets a dashboard can hold, with their default size and the permissions a viewer needs to see them.
  • dashboards_create takes 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_update and dashboards_delete work 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_key and access_requests_delete_company record a request and return a url. 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_get tells the agent how it went: pending, succeeded, failed with the reason, rejected or expired (after an hour).

  • invitations_list and api_keys_list show 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_update

Updates 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_valuation

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:

ToolsAnnotations
Read toolsreadOnlyHint: true, destructiveHint: false
Creates and flag toggles (like, mark as read)readOnlyHint: false, destructiveHint: false
Destructive toolsreadOnlyHint: 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.

On this page