MCP server — agentic project, flow & QA authoring

The Flowline app ships a local MCP server that lets an AI assistant (Claude Desktop, Cursor, Copilot CLI, or any stdio MCP client) drive almost the entire QA workflow in natural language: create projects, author and refine flows, define scenarios (value sets) with per-field values and expected outcomes, build regression suites, run them against a build, record results, file bugs, and read pass-rate analytics.

New here? Read the hands-on MCP tutorial for an end-to-end walkthrough (natural-language ask → tool call → result) plus a QA management guide. This page is the reference.

How it works

The MCP server is a thin stdio process that calls the tool's existing REST API on http://127.0.0.1:8787 — the same data the web app shows. An open editor merges what it writes (08).

1. Start the app/API first (npm run dev or npm start).
2. Point your assistant at the MCP server (below).
3. Pick the workspace with list_workspaces and select_workspace (which workspace a session uses).

Every write tool reads the project, applies a pure transform, and writes only the changed files, retrying up to 3 times when another save changed them first (how saves resolve). Unknown ids fail fast with a clear error instead of silently succeeding.

Configure your assistant

The server is started with npm run mcp (which runs tsx server/mcp/index.ts). Set FLOW_API_URL if your API is not on the default port. All stdout is reserved for JSON-RPC; logs go to stderr.

Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "flowline": {
      "command": "npx",
      "args": ["tsx", "server/mcp/index.ts"],
      "cwd": "/absolute/path/to/flowline",
      "env": { "FLOW_API_URL": "http://127.0.0.1:8787" }
    }
  }
}

Cursor (.cursor/mcp.json) / Copilot CLI / other MCP clients

Use the same command / args / cwd / env. Any stdio MCP client works.

Remote / hosted MCP (multi-user)

When the app is deployed with authentication enabled, anyone with an account can use the MCP over the public internet — no repo checkout, no local process.

1. Generate a token. Sign in to the web app, open the MCP access tokens panel in your profile, create a named token, and copy it (it is shown once).

2. Point your assistant at the hosted endpoint (https://<your-host>/mcp), sending the token as a bearer header:

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

3. Choose a workspace. Each MCP session is isolated to your account. Call list_workspaces, then select_workspace { workspaceId }. The selection lives in the MCP session and never changes your web-app active workspace. Call current_workspace to see the current target.

Notes

• Tokens are shown once and stored only as a hash; revoke them anytime in the profile panel. Token management itself requires an interactive (cookie) login.
• The endpoint must be served over HTTPS. To enable DNS-rebinding protection, set MCP_ALLOWED_HOSTS to your public host(s) (comma-separated).

Local folders (no server, no account)

You can also point an assistant straight at folders on your own machine — no sign-in, no token, no repo checkout:

{
  "mcpServers": {
    "flowline": {
      "command": "npx",
      "args": ["-y", "flowline-mcp", "mcp", "/absolute/path/to/your/flows"]
    }
  }
}

This boots the folders itself; nothing else needs to be running. Add FLOWLINE_SITE/FLOWLINE_TOKEN to env to reach your hosted account from the same entry:

{
  "mcpServers": {
    "flowline": {
      "command": "npx",
      "args": ["-y", "flowline-mcp", "mcp", "/absolute/path/to/your/flows"],
      "env": {
        "FLOWLINE_SITE": "https://<your-host>",
        "FLOWLINE_TOKEN": "fl_pat_…"
      }
    }
  }
}

list_workspaces then returns both, with ids qualified as hosted:<id> / local:<id> so select_workspace can target either. Full walkthrough: Edit a folder on your computer.

Tool reference

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. Node ids, scenario ids, suite ids, etc. are the real ids returned by the corresponding list_* / get_* / create_* tools.

Workspaces (session-scoped)

Projects

Flows

create_flow spec

Reference nodes by author keys (not UUIDs). The server assigns ids, wires edges (fromHandle = branch), lays out the graph (BFS auto-layout), and returns warnings (dangling_branch, unreachable_node, auto_added_branch).

{
  "projectId": "<id from create_project>",
  "spec": {
    "name": "PIN entry",
    "entry": "idle",
    "points": [
      { "key": "idle", "title": "Idle screen", "branches": ["start"] },
      { "key": "pin",  "title": "Enter PIN",   "branches": ["correct", "wrong"] }
    ],
    "ends": [
      { "key": "ok",     "outcome": "Cell opens" },
      { "key": "locked", "outcome": "Account locked" }
    ],
    "edges": [
      { "from": "idle", "branch": "start",   "to": "pin" },
      { "from": "pin",  "branch": "correct", "to": "ok" },
      { "from": "pin",  "branch": "wrong",   "to": "locked" }
    ]
  }
}

A branch is either a bare name or an object. The object form carries the rest of the branch model:

{ "name": "Sign in", "id": "signin-wrong", "result": "Wrong password",
  "kind": "validation", "staysOnCard": false,
  "expected": [{ "label": "Red text under the password field" }] }

• name is the action; result is what the system answers. The card renders them as Sign in / Wrong password.
• id is what edges[].branch refers to; it defaults to name. Two branches on one card that share a name must each set id, or the edges cannot tell them apart.
• kind is ui, network, or validation.
• staysOnCard: true marks an outcome that records in place — an inline error — and must own no edge.
• expected holds results the tester verifies for that outcome specifically, separate from the card-wide expected.

get_flow returns branches in this same form.

spec.notes carries the canvas notes:

{ "text": "Ask design about the empty state", "position": { "x": 40, "y": 80 },
  "pinnedTo": "pin", "color": "#ffd166" }

• text is the note body; position defaults to 0,0.
• pinnedTo is a spec key — an author key here, a node id in get_flow output, where keys are ids. A key no node claims is an unknown_note_pin error.
• get_flow emits notes in this same form, so a get_flow → create_flow round trip keeps every note and its pin.

Graph (incremental editing)

Operate on a live flow by id. Get node ids from get_flow. Mutations return warnings for non-fatal notes (auto_added_branch, pruned_edges, entry_cleared).

Card images & backgrounds

Attach images to point cards and end nodes, and control how they render. Images may be PNG, JPEG, WebP, GIF, or SVG, up to 8 MB. Supply each image as either image.base64 (a data: URL prefix is accepted) or image.url — exactly one. URL sources are fetched server-side and must resolve to a public host (loopback/private addresses are refused).

Notes

A note is authoring commentary on the canvas. It sits beside the graph, not in it: notes never appear in flow order, scenarios, runs, the table, or the player. Pin a note to a card or end with pinnedTo and it travels with that node and is deleted with it; its position is then relative to that node instead of the canvas. get_flow returns the flow's notes, and create_flow accepts them.

Scenarios

A scenario is a named value set: per-field input/expected values, an optional expected outcome, a background image per card, and a pinned path used for guided runs.

The tools below reach the values, the expected outcome, the per-screen expected notes, and the per-card background overrides. The pinned path is UI-only — set by pinning a branch in the Table or by Update path / Save as new in the Player.

Suites

Suite runs & analytics

Bugs & runs

owner, tester, reportedBy, startedBy and finishedBy are people as the project stores them (see the layout). A summary leaves the field out when the project doesn't record one.

Lifecycle (destructive)

What's intentionally not exposed

These stay UI-only (by design) — the MCP surface is for authoring and QA orchestration, not binary/identity/transport concerns:

• Git / auth management — connecting a workspace to a git remote or Google Drive, and signing in, are UI + server concerns.
• Raw asset bytes & rendering — fetching or streaming stored image bytes is a multipart/transport concern handled in the player/table UI; MCP treats asset ids as opaque. (Attaching images and choosing backgrounds is now supported — see Card images & backgrounds above.)
• Full player-run recording — stepping a flow card-by-card and capturing a Run with steps is the player's job. The agent records manual suite outcomes via set_suite_result; it never fabricates a full player run. (This keeps recordSuiteScenarioRun the single writer of suite-tagged runs.)
• Project export / import & session PDF reports — generated from the UI. (Bug export is available — see export_bugs above.)
• Template instances & QA test sessions — separate features not part of the scenario/suite path.

Safety notes

Which workspace a session uses, permanent deletes, and what happens when you and an agent change the same item: Driving the tool with MCP → Safety notes.