MCP reference

Reflow exposes its agent surface as one OAuth 2.1 streamable-HTTP endpoint:

https://mcp.reflow.io/mcp

The client opens browser consent when it first needs authorization. Sign in, review the requested access, and return to the client. There is no API token to copy into the MCP configuration.

Connect

Claude Code

claude mcp add --transport http reflow https://mcp.reflow.io/mcp

Cursor

Add a remote server in Cursor’s MCP settings, or put the same URL in .cursor/mcp.json:

{
  "mcpServers": {
    "reflow": {
      "url": "https://mcp.reflow.io/mcp"
    }
  }
}

VS Code

Add the remote server from MCP: Add Server, or use the command line:

code --add-mcp "{\"name\":\"reflow\",\"type\":\"http\",\"url\":\"https://mcp.reflow.io/mcp\"}"

Codex

codex mcp add reflow --url https://mcp.reflow.io/mcp

Windsurf

Add the URL under Windsurf Settings → Cascade → MCP Servers. The equivalent entry in mcp_config.json is:

{
  "mcpServers": {
    "reflow": {
      "serverUrl": "https://mcp.reflow.io/mcp"
    }
  }
}

After consent, call get_me. It returns the current user, team, and granted scopes and confirms that the connection is ready.

The agent loop

1. Load the authoring context

Call get_context with no arguments to list the built-in guides. Load building-a-suite before authoring a suite and rfl-language for the statement reference. The registry also covers the flow format, run verdicts, email journeys, live sessions, and custom harnesses.

These guides ship with the MCP server. The agent does not need a separate prompt pack or a checked-in context directory.

2. Author a flow

create_flow accepts a name and the complete markdown flow document. Step names state the intent in plain language; non-empty bodies can use readable, deterministic RFL:

---
name: Login screen loads
url: /
---

```ts step="open the login screen"
open /
click "sign in"
expect "welcome"
```

Use save_flow_content to create a new version of an existing flow. See the flow format for the complete document contract and the RFL reference for statements and target syntax.

3. Run it in a browser

Use create_run for a repeatable run against a target URL, then call tail_run until the run reaches a terminal status. A registered flow is addressed by its slug and either a tag or an exact version id.

Use open_session when the agent needs to inspect or drive a live browser before writing the repeatable flow. Poll get_session until ready=true, use snapshot to read the current page and act to execute one RFL line, then always call close_session. A session transcript is a record; rewrite it into the fenced flow format before passing it to create_flow.

4. Interpret the evidence

tail_run returns step events and the terminal verdict. get_run_screenshot returns a short-lived URL for a stored step screenshot.

A snapshot <name> statement creates an explicit visual checkpoint. The first green run establishes its approved baseline for that browser. A later visual difference beyond the checkpoint threshold fails the step and stores the diff for review in the dashboard.

Self-heal is enabled by default. When a scripted step fails, the agent can take over from the failed page state and try to satisfy the named step intent. A successful recovery attaches proposed RFL lines to the run; it does not rewrite the source flow automatically. Set self_heal: false in the flow frontmatter to disable recovery.

The tool surface

The registry in services/mcp/src/tools.ts contains 38 MCP tools. The first five groups account for all 38; settings and keys remain a dashboard boundary and expose 0 MCP tools.

Group	Count	What it does	Representative tools
Identity & guidance	3	Confirms the signed-in identity, loads the built-in guides, and reports MCP friction.	get_me, get_context, give_feedback
Flows & DAGs	8	Creates and versions flows, inspects tags, follows dependencies, and reads upstream outputs.	list_flows, create_flow, save_flow_content, get_flow_graph, get_flow_memory
Runs & results	10	Starts and tails runs, returns step evidence and screenshots, and reads per-run mailboxes.	create_run, tail_run, get_run_screenshot, get_mailbox, wait_for_message
Live-browser sessions	9	Opens a cloud browser, reads its state, drives it with RFL, and captures the viewport.	open_session, get_session, snapshot, act, screenshot, close_session
Harness & containers	8	Boots approved team images, runs commands, streams output, and inspects containers.	list_images, run_image, exec, tail_exec, get_container
Settings & keys	0	Keeps provider keys and API-token creation in the dashboard rather than MCP.	dashboard only

Every tool schema and description is hand-written. The shipped cold-agent canary gives a fresh agent only those descriptions—no examples or hints—and asks it to author a flow, run it, and report the result. It completed the task in 19 tool calls for $0.44; the harness then verified the reported run as succeeded in the database rather than trusting the transcript.

Continue with getting started for the activation path, or add the GitHub Action once the first deterministic run is green.