Driving the tool with MCP

Flowline speaks MCP, so an AI assistant — Claude Desktop, Cursor, Copilot CLI, or any MCP client — can do almost everything in this wiki by conversation: create projects, author flows, define scenarios, build suites, run them, record results, file bugs, and read analytics.

You connect an AI assistant to Flowline over MCP. Two routes, and one config entry can carry both. The usual one is your team's hosted Flowline at its public URL — sign in, create a token, point your assistant at it. The other is a folder on your own computer, with no account and no server at all. If you never use an AI assistant, you can skip this chapter.

After this chapter you can connect your assistant to the MCP server and drive the Bramble Toys demo by talking to it.

Full reference for every tool and argument: MCP setup & tool reference. Step-by-step walkthrough: MCP tutorial.

How it works

MCP drives Flowline's REST API — the same data the web app shows. An open editor on the same server merges what an agent writes as soon as the write is announced to it, and any other at its next check (08). There are two ways to connect:

• Hosted (the usual path). Point your assistant at your team's public Flowline URL — https://<your-host>/mcp — with a personal access token. Nothing to install. Each session picks its own workspace.
• A folder on your own computer. Point the small flowline-mcp helper at one or more folders — no account, no server. It can also reach your hosted account from the same connection, so one entry covers both.

Every write reads the project, applies one change, and writes only the files that changed — and only if nobody changed them since the read. If someone did, the tool reads again and tries again, 3 attempts in all, then fails with The project kept changing while saving; try again. Unknown ids fail with a clear error instead of silently succeeding.

Connect to a hosted Flowline (recommended)

When the app runs behind a public URL — a hosted domain or an ngrok tunnel — it exposes an MCP endpoint at /mcp. You need an account and a token; you don't run anything locally.

1. Sign in to the web app at its public URL.

2. Create a token. Open the MCP access tokens panel in your profile, create a named token, and copy it — it's shown once.

3. Add the endpoint to your assistant, sending the token as a bearer header.

   Claude Desktop (claude_desktop_config.json):

   {
     "mcpServers": {
       "flowline": {
         "url": "https://<your-host>/mcp",
         "headers": { "Authorization": "Bearer fl_pat_…" }
       }
     }
   }
   

   Cursor (.cursor/mcp.json), Copilot CLI, and other MCP clients take the same url and headers.

4. Choose a workspace. Each session is isolated to your account. Ask your assistant to "list my workspaces and select the one" — it runs list_workspaces then select_workspace, and the rest of the session reads and writes there.

Connect to a folder on your computer

No account, no server, nothing left running. Point your assistant at the flowline-mcp helper and it works on folders on your own machine — your assistant starts the helper itself.

Add one entry to your assistant's MCP config, listing the folders it may work on:

{
  "mcpServers": {
    "flowline": {
      "command": "npx",
      "args": ["-y", "flowline-mcp", "mcp", "/Users/you/my-flows"]
    }
  }
}

The same entry can also reach your hosted account, so one connection covers both your folders and your team's server. Edit a folder on your computer has that combined config, how to add folders and check the connection, and how to edit those same folders in the browser.

Running Flowline from a checkout? You can instead point a stdio process at your own instance with npm run mcp and FLOW_API_URL. That is a developer path; the steps are in MCP setup & tool reference.

What you can do — the tool groups

64 tools, grouped by area — the registerTool calls under server/mcp/ are the source of truth. projectId and flowId are required by every flow-scoped tool unless noted.

start_suite_run gives each scenario to its owner, else to the suite's owner. set_suite_result takes assignee as an email or a name; "" clears it. list_suite_run_results returns every result of a run, newest first, with recordedBy, recordedAt and latest, which marks each scenario's current result.

create_flow takes a spec that references nodes by author keys; the server assigns ids, wires edges (fromHandle = branch), lays out the graph, and returns warnings for issues like a dangling branch or an unreachable node.

Whose name an agent writes

file_bug, start_suite_run, set_suite_result and finish_suite_run record who did it, marked "agent": true (99). The name is, in order:

1. the account the token belongs to, when the backend has sign-in on;
2. on a backend without sign-in, FLOWLINE_USER_NAME and FLOWLINE_USER_EMAIL, set where the MCP server runs — in the env of your assistant's MCP config for flowline-mcp or npm run mcp;
3. otherwise Agent.

If the server can't answer who the token belongs to, that one call falls back to step 2 and the next call asks again. Agents never appear in owner lists (08).

What MCP does not do

Git and auth management; full card-by-card player-run recording; project export/import and session PDF reports; and template instances or QA test sessions stay UI-only. The agent records manual suite outcomes with set_suite_result; it never fabricates a player run. Bug export is the exception — export_bugs gives an agent the same zip the Bugs tab produces (04).

One editor feature has no tool behind it: a scenario's pinned path, set by pinning a branch in the Table or by Update path / Save as new in the Player. create_scenario makes a scenario with no path.

Canvas modes, group selection, duplicate, and Arrange are ways of driving the editor by hand; move_node is the agent's equivalent, and create_flow lays a new flow out on its own.

MCP cannot reach a workspace kept only in your browser. Those store their bytes in your browser, so a hosted or self-hosted server has nothing to serve an agent — list_workspaces on that connection returns only Drive and server-folder workspaces. Move a project with Move this project to a folder or Drive in the Sync panel to bring it into reach.

A folder on your own computer is different: it never appears in that picker's list, but pointing the flowline-mcp helper at it (see Edit a folder on your computer) makes it reachable over its own MCP connection — no server round-trip, no account needed.

Card images and notes are in reach: an agent can attach screenshots, choose backgrounds, and write notes with the tools above. delete_node drops the notes pinned to the card it removes, so an agent never orphans one. The bundled demo already includes its screens when the server starts.

Worked example — extend the demo

With the demo loaded and its workspace active, you can ask your assistant to add a regression cycle. The assistant carries the real ids returned by each call into the next, so you never copy ids by hand.

You: "In Bramble Toys, find the Sign in flow and start a Staging run of the Authentication regression suite for build 2.4.1-rc1. Mark the two valid-sign-in scenarios as pass and Desktop · wrong password as fail, then file a high-severity bug for the failure and show me the pass-rate."

The assistant chains: get_project → get_flow → list_suites → start_suite_run → set_suite_result (×3) → file_bug → get_suite_analytics, then reports the new cycle's pass-rate. The new cycle appears on Suites → Dashboard once the editor merges the change.

Safety notes

• Pick the right workspace — call select_workspace at the start of every session, on any connection. It never changes the web app's active workspace. Until a session selects one, its tools follow the active workspace, and activating another workspace mid-task redirects its writes. If a workspace you expect is missing from list_workspaces, it's either kept only in your browser (out of MCP's reach entirely) or a folder on your computer reachable only through its own flowline-mcp connection, not this one.
• Deletes are permanent — delete_project, delete_flow, delete_suite, delete_scenario, delete_bug, delete_run, and delete_suite_run cannot be undone via MCP. Recover from your storage backend (e.g. git).
• API must be running — otherwise calls fail with Could not reach the Flowline API at … Is it running?
• Same item, two writers — if you and an agent change different fields of the same card, scenario or suite, both changes stay; where you both changed one field, the later save wins, and when yours lands on top, the editor header names the field (08). An agent's write reaches open editors when it is saved, as a merged file, not as a live edit.
• Restart MCP after switching the live relay on — the MCP server asks the backend once whether the relay runs and keeps a no until it restarts (admin guide). Until then an agent's writes reach open editors at their next check.