Flow Agent Tools

Flow agents are Sapot Chat’s AI conversation agents. Over MCP you operate them at the intent level — list them, inspect their live settings, attach inboxes, and publish. The Flow Designer graph (graph_data, graph_snapshots, designer_history) is stripped server-side before any response reaches an agent key, and there is no build-from-scratch, export, import, or restore tool. Design happens in the dashboard’s Flow Designer; you drive the outcome here.

Two scopes gate this domain: flows:manage for the read + wiring tools, and flows:publish for going live. A key granted flows:manage but not flows:publish can attach inboxes but cannot flip an agent live. See Authentication & Scopes and Safety & Boundaries.

The intent-level view

Every flow-agent tool returns the same agent shape — never the graph:

Field	Meaning
`id`	Flow agent id
`name`, `description`	Human-readable identity
`status`	`draft` or `published`
`conversational_mode`	Whether the agent keeps answering after the flow completes (park mode) vs restarts
`reply_delay_seconds`	Per-agent send delay before each reply
`handoff_pause_duration`	How long the agent stays paused after a hand-off to a human
`inbox_ids`	The inboxes this agent is connected to
`inbox_settings`	Per-inbox runtime rules (see `set_flow_agent_inboxes`)

You will never receive the flow’s internal graph. Don’t ask for or expect raw graph JSON — it’s IP, stripped at the API boundary. To change how an agent behaves node-by-node, open the Flow Designer in the dashboard.

flows:manage

list_flow_agents

List the account’s flow agents. Takes no arguments. Returns a list of agents in the intent-level shape above. The underlying flow graph is intentionally not included.

get_flow_agent

Fetch one flow agent by id (intent-level view, no graph).

Argument	Type	Required	Description
`flow_agent_id`	int	yes	The agent’s id.

Returns the same fields as list_flow_agents, for one agent.

get_flow_agent_metrics

Runtime metrics across the account’s flow agents — conversations handled, hand-offs, and so on.

Argument	Type	Required	Description
`days`	int	no	Look-back window in days. Defaults to the server’s standard window.

Returns the aggregated metrics object.

set_flow_agent_inboxes

Set which inboxes a flow agent is connected to. This REPLACES the current set — it is not additive.

Argument	Type	Required	Description
`flow_agent_id`	int	yes	The agent’s id.
`inbox_ids`	int[]	yes	The complete list of inbox ids the agent should handle. Replaces current membership. Pass `[]` to detach all inboxes.
`inbox_settings`	object	no	Per-inbox rules keyed by inbox id as a string (see below).

Returns the updated agent (intent-level view).

inbox_ids is the full desired set, and an inbox belongs to exactly one flow agent. Adding an inbox here moves it off whatever other agent it was on. To add one inbox without dropping the rest, read the current inbox_ids first and send the union. Sending [] detaches every inbox from this agent.

Per-inbox inbox_settings. Keyed by inbox id as a string, each value carries the runtime rules for that inbox:

Setting	Type	Effect
`ignore_whatsapp_groups`	bool	Skip WhatsApp group chats on this inbox.
`excluded_labels`	string[]	Don’t let the agent act on conversations carrying any of these labels.
`pause_on_human_reply`	bool	Pause the agent when a human agent replies.

{
  "12": {
    "ignore_whatsapp_groups": true,
    "excluded_labels": ["vip"],
    "pause_on_human_reply": true
  }
}

flows:publish

publish_flow_agent

Publish a flow agent so it goes live on its connected inboxes.

Argument	Type	Required	Description
`flow_agent_id`	int	yes	The agent’s id.

The graph is validated server-side first. If it’s invalid, the call fails and the error is opaque — it tells you the graph didn’t pass, not which node is broken (the graph itself stays private). On success, returns the published agent (intent-level view).

If publish reports the graph is invalid, there’s nothing to fix from the MCP side — open the agent in the Flow Designer, resolve the validation errors there, then call publish_flow_agent again.

Typical flow

Find the agent

list_flow_agents → note the id and current inbox_ids / status.

Attach inboxes

set_flow_agent_inboxes(flow_agent_id, inbox_ids=[…]) with the full desired inbox set, plus any per-inbox inbox_settings.

Go live

publish_flow_agent(flow_agent_id) (needs flows:publish). If it reports an invalid graph, fix it in the Flow Designer and retry.

What’s deliberately absent

There is no create, export, import, or restore_snapshot tool for flow agents. Building a graph is an intent-level path reserved for the dashboard’s Flow Designer. This isn’t a gap in the tool catalog — it’s a locked product boundary. See Safety & Boundaries for the full rationale, and the in-app Help Center for a no-code walkthrough of the Flow Designer.

Connect

claude mcp add --transport http sapot https://mcp.sapot.ai/mcp --header "Authorization: Bearer YOUR_AGENT_KEY" --header "X-Sapot-Account-Id: YOUR_ACCOUNT_ID"

Getting Started

Tool Reference

Reference

The intent-level view

flows:manage

list_flow_agents

get_flow_agent

get_flow_agent_metrics

set_flow_agent_inboxes

flows:publish

publish_flow_agent

Typical flow

What’s deliberately absent

Connect

​The intent-level view

​flows:manage

​list_flow_agents

​get_flow_agent

​get_flow_agent_metrics

​set_flow_agent_inboxes

​flows:publish

​publish_flow_agent

​Typical flow

​What’s deliberately absent

​Connect

The intent-level view

flows:manage

list_flow_agents

get_flow_agent

get_flow_agent_metrics

set_flow_agent_inboxes

flows:publish

publish_flow_agent

Typical flow

What’s deliberately absent

Connect