Available MCP Tools
FunnelStory exposes the following tools through the MCP server, grouped by what they work with. Some tools are admin-only — noted below — because they configure workspace-wide settings rather than reading or acting on individual records.
Semantic DB and data connections
| Tool | What it does |
|---|---|
query_semantic_db | Run SQL queries against your workspace data |
get_data_connection_schema | (Admin) List tables, or inspect a table's columns and sample rows, on a connected data source |
preview_data_connection | (Admin) Run a query directly against a data connection and preview the results |
Flows
| Tool | What it does |
|---|---|
get_flows | List flows or retrieve a specific flow's configuration |
save_flow | (Admin) Create a flow, or replace one wholesale |
edit_flow | (Admin) Apply targeted edits to an existing flow |
debug_flow_step | (Admin) Run a single flow step in isolation to debug it |
run_flow | Execute a flow and return its output |
preview_flow_triggers | (Admin) Preview real trigger payloads for a flow, for testing against run_flow |
Data models
| Tool | What it does |
|---|---|
configure_data_model | (Admin) Create or update a data model configuration |
preview_data_model | (Admin) Preview query results and validate a data model before saving |
Tasks and projects
| Tool | What it does |
|---|---|
create_task | Create a task, optionally linked to a project and/or an account |
add_task_note | Add a note to a task |
create_project | (Admin) Create a project and link it to one or more accounts |
update_project | (Admin) Update a project's title, description, state, due date, or assignee |
Templates and presentations
| Tool | What it does |
|---|---|
list_templates | (Admin) List workspace templates (email, Slack, generic, or pptx) |
read_template | (Admin) Read a template's content or, for pptx, its slide layouts |
read_presentation | (Admin) Download a generated .pptx from Google Drive and inspect its slide XML |
google_sheets_read | (Admin) Read a Google Sheet by ID as normalized JSON |
Resources and identity
| Tool | What it does |
|---|---|
read_resource | Read a resource document by URI (guides, schema, workspace profile) |
who_am_i | Return the current user's identity for this MCP connection |
query_semantic_db
Runs a SQL query against FunnelStory's semantic database — a structured view of your workspace data including accounts, metrics, predictions, activities, meetings, notes, tasks, projects, tickets, and needle movers.
Your AI assistant can read the schema first (available as the file://semantic/schema.sql resource) to understand what tables and columns are available before querying.
Input:
| Field | Type | Description |
|---|---|---|
query | string | SQL query to run |
Two tables have dedicated guidance resources worth reading before you query them: account_profiles (file://semantic/account_profiles.md) and relationship_map_history (file://semantic/relationship_map_history.md). The relationship-map guide in particular explains why risk labels like Single-Threaded or Gone dark should come from the live GET /api/accounts/{id}/relationship_map API rather than be inferred from the raw weekly snapshot counts — your workspace's configured thresholds (see Relationship Risk Configuration) can't be reconstructed from the numbers alone. Projects and tasks have their own guide too — see file://projects/guide.md under read_resource.
get_data_connection_schema
Admin only. Returns schema information for a data connection — omit table_name to list all available tables, or provide it to get that table's columns and a sample of rows. Only available for queryable connections (Postgres, BigQuery, Snowflake, Salesforce, HubSpot, and similar).
Input:
| Field | Type | Description |
|---|---|---|
data_connection_id | string | UUID of the data connection |
table_name | string | (Optional) Table to inspect (use schema.table format when applicable). Omit to list all tables |
preview_data_connection
Admin only. Runs a query directly against a data connection (SQL, SOQL, HubSpot query syntax, etc., depending on connection type) and returns a sample of the results. Use this to validate a query before configuring a data model with it.
Input:
| Field | Type | Description |
|---|---|---|
data_connection_id | string | UUID of the data connection to query |
query | string | Query to run |
limit | integer | (Optional) Maximum rows to return. Defaults to 25, capped at 100 |
get_flows
Returns flow metadata for the workspace. Pass a flow_id to get the full configuration of a specific flow — including its trigger, input schema, and graph. Omit it to get a summary list of all flows.
Input:
| Field | Type | Description |
|---|---|---|
flow_id | string | (Optional) ID of the flow to retrieve |
save_flow
Admin only. Creates a flow, or replaces one wholesale. Omit flow_id to create a new flow; pass flow_id to replace an existing one completely — any field you don't include is cleared, not left as-is. Use this for a flow's birth or a full rewrite; for any smaller change, use edit_flow instead so you don't have to resend the whole flow.
Read the file://flow/guide.md resource for the complete flow authoring reference.
Input:
| Field | Type | Description |
|---|---|---|
flow_id | string | (Optional) Flow to replace; omit to create |
name | string | Display name |
draft | boolean | If true, saves without publishing (recommended until the flow is ready) |
trigger_config | object | When and how the flow runs — see Triggers |
input_schema | array | Input fields the flow accepts |
config | object | Flow graph with entrypoint and steps |
edit_flow
Admin only. Applies targeted edits to an existing flow in one all-or-nothing call — the tool validates and saves once all edits succeed, or none of them apply. Pass flow_id and an ordered edits array; each edit has an op:
| Op | Fields | What it does |
|---|---|---|
set_step | step_id, step | Replaces one whole step (the step must already exist) |
merge_patch | patch | A JSON Merge Patch for metadata and structure — rename the flow, toggle draft, change step fields, add a step, remove a step (set it to null), or rewire next/entrypoint |
replace_text | path, old_string, new_string, replace_all | An exact-substring edit inside a long string field — a script.js source, an AGENT prompt, or SQL — addressed by JSON Pointer (for example /config/steps/build_files/call/args/source). old_string must match exactly once unless replace_all is true |
Edits apply in order. Call get_flows first to read current step IDs and field values before editing.
Input:
| Field | Type | Description |
|---|---|---|
flow_id | string | Flow to edit |
edits | array | Ordered list of edit operations (see above) |
debug_flow_step
Admin only. Runs a single flow step in isolation so you can debug it without triggering the whole flow. Only CALL and AGENT steps are supported — other step types (WAIT, LOOP, BRANCH, CONDITION, etc.) aren't. Runs in test mode by default, which never persists write actions.
Input:
| Field | Type | Description |
|---|---|---|
flow_id | string | Flow that owns the step |
step_id | string | Step to run in isolation |
variables | object | (Optional) Global @.* state to seed before the step runs — typically captured from a prior test run |
trigger | object | (Optional) Trigger payload to expose as @.trigger.* for the debug run |
test | boolean | (Optional) Defaults to true. Set to false to allow write actions to persist |
run_flow
Executes a flow by ID and waits for it to complete. If the flow sets a response variable, that value is returned to the caller.
Input:
| Field | Type | Description |
|---|---|---|
flow_id | string | ID of the flow to run |
input | object | (Optional) Input values, merged with flow defaults |
preview_flow_triggers
Admin only. Previews real trigger payloads for a flow based on its trigger config and current workspace data. Each returned payload can be passed to run_flow as the trigger argument to test the flow against real data without waiting for the trigger to fire naturally.
Input:
| Field | Type | Description |
|---|---|---|
flow_id | string | Flow to preview triggers for |
limit | number | (Optional) Maximum number of trigger candidates to return. Defaults to 5 |
configure_data_model
Admin only. Creates or updates a data model in your workspace configuration. Use preview_data_model first to validate the query before saving.
Always read file://data_model/guide.md before calling this tool — it contains the full reference for supported model types, required mappings, and source-specific query patterns (HubSpot, Salesforce, databases).
For HubSpot, always configure models in this order: accounts → users → conversations/notes/activities. The user model must exist before engagement models can resolve account IDs.
Input:
| Field | Type | Description |
|---|---|---|
id | string | (Optional) ID of the model to update. Omit to create a new model. |
name | string | Display name for the model |
type | string | Model type: account, user, conversation, note, support_ticket, non_product_activity, product_activity, etc. |
draft | boolean | If true, saves but does not activate. Defaults to true for new models. |
data_source | object | Query configuration — either data_connection_id + query, or dataset with name and query |
mappings | array | Column-to-property mappings: [{"column": "...", "property": "..."}] |
refresh | object | (Optional) Refresh schedule, e.g. {"interval": "6h"} |
preview_data_model
Admin only. Validates a data model configuration by running the query and returning a sample of rows with resolved column types. Use this before configure_data_model to confirm the query returns the expected shape and that account_id values match your accounts model.
Input: Same shape as configure_data_model (without id).
create_task
Creates a task, optionally linked to a project and/or an account. Tasks created this way are marked as agent-created — see Action Cards for how these can surface as recommended actions in the product.
Input:
| Field | Type | Description |
|---|---|---|
title | string | Task title |
body | string | (Optional) Task description |
project_id | string | (Optional) UUID of a project to link this task to — when every task in a project is done, the project auto-completes |
account_id | string | (Optional) External account_id to associate with this task |
add_task_note
Adds a note to an existing task, linking it as an association on that task.
Input:
| Field | Type | Description |
|---|---|---|
task_id | string | UUID of the task |
title | string | Note title |
content | string | Note content / body |
create_project
Admin only. Creates a project and links it to one or more accounts. account_ids must be external account identifiers, not internal fs_id values.
Read file://projects/guide.md first — it explains the distinction between template projects (blueprints, no linked accounts) and instance projects (created per account from a template), and why source_project_id matters: funnel stage conditions that gate on project completion match by source_project_id, not by title, so omitting it when provisioning from a template makes the project invisible to those conditions. Find a template's ID with query_semantic_db (SELECT id, title FROM projects WHERE json_array_length(account_ids) = 0).
Input:
| Field | Type | Description |
|---|---|---|
title | string | Project title |
description | string | (Optional) Project description |
account_ids | array of string | External account IDs to link (at least one required) |
source_project_id | string | (Optional) UUID of the template project this instance was created from — set this so funnel conditions keep working even if the project is renamed |
update_project
Admin only. Updates an existing project's title, description, state, due date, or assignee. Only the fields you provide are changed.
Input:
| Field | Type | Description |
|---|---|---|
project_id | string | UUID of the project to update |
title | string | (Optional) New title |
description | string | (Optional) New description |
state | string | (Optional) One of open, in_progress, completed, expired |
due_at | string | (Optional) Due date in RFC3339 format. Omit to leave unchanged |
assigned_to | string | (Optional) User ID to assign the project to; pass an empty string to unassign |
list_templates
Admin only. Lists workspace templates (id, name, type, whether a file is uploaded), optionally filtered by type. Use this to find a template_id to pass to read_template.
Input:
| Field | Type | Description |
|---|---|---|
type | string | (Optional) Filter by email, slack, generic, or pptx |
read_template
Admin only. Reads a workspace template by ID. Text templates (email, slack, generic) return their raw subject and content. pptx templates return the deck's slide size, slide count, and the layouts it ships, so an AI assistant can bind a generated slide to a layout and inherit its positioning and formatting.
Input:
| Field | Type | Description |
|---|---|---|
template_id | string | ID of the template to read |
read_presentation
Admin only. Downloads a .pptx file from Google Drive by file ID and returns the XML content of each slide, so an AI assistant can inspect or validate a presentation it generated. Requires Google Drive credentials to be configured for the workspace.
Input:
| Field | Type | Description |
|---|---|---|
file_id | string | Google Drive file ID of the .pptx to read |
google_sheets_read
Admin only. Reads a Google spreadsheet by ID and returns normalized JSON for all sheets. The spreadsheet must be shared with the FunnelStory managed service account (viewer access), and the account's domain must be in the workspace's drive_domains allowlist.
Input:
| Field | Type | Description |
|---|---|---|
spreadsheet_id | string | Google spreadsheet ID |
read_resource
Reads a reference document by URI and returns its content. Use this to look up guides and schemas before configuring models, flows, or projects.
Available resources:
| URI | Contents |
|---|---|
file://data_model/guide.md | Complete guide for configuring data models — model types, required mappings, HubSpot and Salesforce query patterns, configuration order |
file://flow/guide.md | Entry-point guide for creating and editing flows |
file://flow/ops.md | Reference for flow step operation types (CALL, AGENT, LOOP, and others) |
file://flow/functions.md | Reference for CALL function IDs, their arguments, and return values |
file://flow/patterns.md | Composable flow graph patterns and use-case examples |
file://flow/pptx.md | Workflow for generating PowerPoint decks from workspace templates inside a flow |
file://projects/guide.md | Guide to the projects and tasks tools — templates vs. instances, funnel conditions, and role access |
file://semantic/schema.sql | Live schema of your workspace's semantic database |
file://semantic/usage.md | How to interpret semantic database tables and values |
file://semantic/account_profiles.md | Guide to the account_profiles table — recent and long-term account context, stakeholder contacts, and citations |
file://semantic/relationship_map_history.md | Guide to the relationship_map_history table — weekly relationship-map snapshots, engagement signals, and why the AI should compute risk labels from the live API rather than infer them from raw counts |
file://workspace/profile.json | Your workspace's connected data sources and active models |
Input:
| Field | Type | Description |
|---|---|---|
uri | string | URI of the resource to read |
who_am_i
Returns the identity behind the current MCP connection — user ID, name, email, and role. Useful for an AI assistant to confirm who it's acting as before taking a role-gated action.
Input: None.
Next Steps
- Examples — example prompts using these tools
- Getting Started — connect your MCP client
- Configure HubSpot models with Claude — step-by-step walkthrough for HubSpot configuration via MCP
- AI Agents — product concepts, triggers, and examples