Tool catalog

The MCP server turns FirstFlow into a set of tools a coding agent (Claude Code, Cursor, Claude Desktop) can call to read your workspace, build experiences, and edit their flows. This page is the canonical list of those tools, grouped exactly as the server groups them, with the scope each one requires. The catalog is server-authoritative. It lives in mcp/policy/mcp-tool-catalog.ts, the dashboard renders it verbatim, and on startup the server asserts every name here maps to a real registered tool so the list below cannot silently drift from reality. The Discovery group is always on; every other group is gated by scope, and the gating happens before the tool ever appears to your agent.

How tool gating works

Tool visibility is decided per request, server-side, and you never see a tool you can’t use. When your agent calls /mcp, the controller authenticates the OAuth bearer token, resolves your scopes from your organization role, then builds a fresh McpServer for that one request. During build, server.registerTool is wrapped: a tool that your organization has disabled, or that your scopes don’t cover, is skipped at registration. It is absent from tools/list, and a tools/call against it returns the SDK’s native “method not found”. That is why a missing tool and a 403 mean the same thing the caller lacks the scope, not that the feature is gone. Read with the role you have; to gain a tool, get the scope it needs. Each tool body also re-asserts its scope at call time and records a metering event, so quota counts against the call, not the listing. Connecting and authenticating the endpoint is covered in Connect an agent; the role-to-scope mapping is in Scopes & roles.

Calling a tool

You rarely invoke tools by hand your agent reads the descriptions and picks them. The interaction is plain natural language once the server is connected:

Call list_agents and tell me which agents exist, then create a 3-step
onboarding tour on the first one that shows when chat opens.

The agent will call list_agents (no arguments), then create_tour with a structured payload. The tool arguments are exactly the JSON schema the server registers. A create_tour call, for example, looks like this on the wire:

{
  "name": "create_tour",
  "arguments": {
    "agentId": "agt_…",
    "name": "New-user onboarding",
    "description": "Three steps shown when chat first opens",
    "steps": [
      { "title": "Welcome", "body": "Let's get you set up in under a minute." },
      { "title": "Connect your data", "body": "Add a source so dashboards populate." },
      { "title": "You're ready", "body": "Explore on your own we're here if you need us.", "ctaLabel": "Got it" }
    ],
    "config": { "trigger": "chat_open", "frequency": "once" }
  }
}

Most write tools return the new entity’s ID plus a dashboard link so the agent can suggest a review before you publish. Read tools return JSON text content. A failed call returns isError: true with a JSON error message rather than throwing for example get_agent on an unknown ID returns {"error":"Agent not found"}.

Discovery (always on)

The Discovery group is alwaysOn it is registered for every caller so an agent can bootstrap context (list agents, read settings) before it has any other permission. Note that “always on” means the tool is always registered; the scopes below are still enforced at call time, so a member without org:admin calling get_organization_settings still gets a scope error.

Tool	Required scope	What it does
`list_integrations_catalog`	none	Browse the integrations catalog.
`get_organization_settings`	`org:admin`	Read workspace settings.
`list_agents`	`agents:list`	List all agents in your workspace.
`get_agent`	`agents:read`	Get an agent’s details and config.

Agents

Manage the agent workspace containers themselves read their public SDK config, create, rename, or delete them.

Tool	Required scope	What it does
`get_agent_sdk_config`	`agents:read`	Get the public SDK config for an agent (experiences, widget UI, settings).
`create_agent`	`agents:create`	Create a new AI agent.
`update_agent`	`agents:update`	Update an agent’s name or description.
`delete_agent`	`agents:delete`	Permanently delete an agent.

Build experiences

Compose a new experience from a high-level intent. Each builder tool returns the new experience ID; publish_experience flips its status to active. Widget composition is handled server-side, so the agent describes the content and FirstFlow renders it.

Tool	Required scope	What it does
`create_tour`	`experiences:create`	Build a multi-step onboarding tour.
`create_announcement`	`experiences:create`	Create a single-card announcement.
`create_survey`	`experiences:create`	Build an NPS / scale / multi-choice / open-text survey.
`create_guide`	`experiences:create`	Create a dynamic AI-filled guide widget.
`publish_experience`	`experiences:publish`	Publish an experience (status → active).

A guide is the one widget whose content is filled by AI at runtime; the others are static steps the agent authors directly. See Experiences for the distinction.

Flow editing

Edit the flow graph behind an experience its steps, branching, and logic nodes. The step tools operate on linear experiences by index; the node tools operate on the underlying graph and require you to wire edges yourself with connect_nodes. All of these require experiences:update.

Tool	What it does
`add_step`	Add a step / question / card to an experience.
`update_step`	Edit a step at a specific index.
`delete_step`	Remove a step from an experience.
`reorder_steps`	Move a step to a new position.
`update_guide_widget`	Regenerate or refine a guide’s widget frame.
`add_classifier`	Add an LLM intent-branching (classify) node to a guide flow.
`add_classify_node`	Insert a bare classify (branching) node into any flow; wire branches with `connect_nodes`.
`add_flow_node`	Insert a logic node (`api_call` / `slack_message` / `webhook` / `assign_segment`) into a guide flow.
`remove_flow_node`	Remove a node from a guide flow and re-stitch it.
`connect_nodes`	Add or re-point an edge between two nodes in a guide flow.

The classify and logic nodes execute server-side at runtime branching decisions and flow navigation (flow.next / flow.back) never run in the browser. A classify node is how a guide chooses a branch based on user intent; a logic node is how it calls out to Slack, a webhook, or an API, or assigns an audience segment.

Manage experiences

List, read, configure, and delete existing experiences, plus read their flow as a graph and trigger logic webhooks.

Tool	Required scope	What it does
`list_experiences`	`experiences:list`	List all experiences for an agent.
`get_experience`	`experiences:read`	Get a single experience by ID.
`get_flow_graph`	`experiences:read`	Read an experience flow as a node/edge graph.
`update_experience`	`experiences:update`	Update name, description, or status.
`configure_experience`	`experiences:update`	Configure START-point settings: trigger, frequency, presentation, audience, priority.
`delete_experience`	`experiences:delete`	Permanently delete an experience.
`trigger_experience_logic_webhook`	`experiences:update`	Enqueue a logic-webhook run for an experience.

configure_experience is where eligibility is set trigger, frequency, presentation, audience, and priority all live on the experience’s START point and are evaluated server-side. The builder tools accept the same settings inline via an optional config block, so you can set them at creation time too.

Audience

Read audience segments and membership for targeting.

Tool	Required scope	What it does
`list_segments`	`audience:list`	List audience segments (id, name) for targeting.
`list_audience_members`	`audience:list`	List audience members for an agent.
`get_audience_membership`	`audience:read`	Get an end-user’s membership and segments.

Organization

Tool	Required scope	What it does
`update_organization_settings`	`org:admin`	Update workspace settings (admin).

Parameters

The two parameters you will pass most often are an agentId and an optional config block. The rest are tool-specific and your agent fills them from the registered JSON schema; the descriptions above are the source of truth your agent reads.

agentId

string

required

The agent a tool acts on (agt_…). Most write and read-by-agent tools take it as the first argument. The recommended flow is to call list_agents first if exactly one agent exists, use its ID; if several exist, ask which one. Every agent-scoped tool re-verifies that this agent belongs to your organization before doing any work, so an ID outside your workspace returns an access error.

config

StartConfig

Optional START-point settings accepted by the builder tools (create_tour, create_announcement, create_survey, create_guide) and set directly by configure_experience. It controls eligibility trigger, frequency, presentation, audience, and priority. Omit it and the experience defaults to “when chat opens”, shown once.

{
  "config": {
    "trigger": "chat_open",
    "frequency": "once",
    "priority": 10
  }
}

steps

Step[]

Ordered step list for create_tour (and similar shapes for surveys). Each step has a title and body, with optional ctaLabel, ctaUrl, and widget-chrome overrides (headerTitle, headerIcon, skipLabel). At least one step is required.

Notes

Authentication is OAuth-only. The /mcp endpoint accepts OAuth-issued tokens; static keys from Settings → API Keys are explicitly rejected there and a compliant client is told to start the OAuth flow via the WWW-Authenticate header. Those static keys still work on the REST API. See API keys & OAuth.
Scopes come from your organization role. Admins (org:admin) get the full catalog; members get read and list tools only (agents:list, agents:read, experiences:list, experiences:read, audience:list, audience:read). Legacy coarse scopes on older keys (experiences:write, agents:write, analytics:read) are expanded to their granular equivalents. Full mapping in Scopes & roles.
Errors are returned, not thrown. A tool that can’t complete returns isError: true with a JSON error payload (e.g. {"error":"Agent not found"}). A scope failure surfaces as a missing tool or a 403.
Every call is metered. The /mcp endpoint is rate-limited and metered per organization; in the self-hosted community edition, quotas are unlimited.
The list is exact. This catalog mirrors mcp/policy/mcp-tool-catalog.ts one-to-one. If a tool name here doesn’t appear to your agent, it’s gated by scope or disabled for your organization not missing.

Resolve a missing tool in Scopes & roles, connect a client in Connect an agent, or understand the entities these tools manipulate in Experiences and Flows & nodes.

Get Started

Features

Core Concepts

AI Connect (MCP)

Integrations

Help

How tool gating works

Calling a tool

Discovery (always on)

Agents

Build experiences

Flow editing

Manage experiences

Audience

Organization

Parameters

Notes

Next

​How tool gating works

​Calling a tool

​Discovery (always on)

​Agents

​Build experiences

​Flow editing

​Manage experiences

​Audience

​Organization

​Parameters

​Notes

​Next

How tool gating works

Calling a tool

Discovery (always on)

Agents

Build experiences

Flow editing

Manage experiences

Audience

Organization

Parameters

Notes

Next