agent entry point

this page is for the agent reading it.

Reflow proves an AI's PR works in a real browser before merge. Connect one endpoint; browser sign-in handles OAuth 2.1 on first use, with no API token to paste.

mcp.reflow.io/mcp · streamable HTTPOAuth 2.1

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

browser sign-in opens on first useno token to paste

/llms.txt is the source map.

The public, plain-text summary of the endpoint, workflow, evidence, and canonical docs.

open raw file MCP reference

reflow.io/llms.txt · text/plain canonical machine-readable entry point

# Reflow

> Reflow proves an AI's PR works in a real browser before merge. It is built for coding agents such as Claude Code, Cursor, and Codex, and for the developers driving them.

Reflow's agent surface is one streamable-HTTP MCP endpoint: https://mcp.reflow.io/mcp. It uses OAuth 2.1 with browser sign-in on first use, so there is no API token to paste.

The endpoint exposes 38 hand-written tools for identity and guidance, flows and DAGs, runs and results, live browser sessions, and harnesses and containers. Provider keys and API tokens stay in the dashboard, not MCP.

Flows are markdown files with YAML frontmatter, plain-language intent, and named ```ts step="..." fences. Step bodies contain deterministic RFL, Playwright TypeScript, or remain empty for agent-driven execution. Runs use a real cloud browser and the team's own model key: customers pay their model provider, never a token markup.

Evidence returns through the same MCP surface: tail_run streams step events and the terminal verdict, get_run_screenshot returns short-lived signed URLs, named snapshot checkpoints are perceptually diffed against approved baselines, and per-run virtual mailboxes support magic-link and OTP journeys.

Self-heal is enabled by default. If a scripted step fails, the agent takes control from the failed page state; a successful recovery attaches proposed RFL to the run and never rewrites the source flow. Set self_heal: false to disable it.

The GitHub Action runs selected flows against a pull-request preview and posts one merge-blocking check per flow with screenshots and visual diffs.

A cold-agent canary gave a fresh agent only the tool descriptions. It authored login-screen-loads, ran it, and reported PASS in 19 tool calls for $0.44; the harness verified runs.status='succeeded' in the database rather than trusting the transcript.

## Connect

- [MCP endpoint](https://mcp.reflow.io/mcp) — Connect any streamable-HTTP MCP client with OAuth 2.1 browser sign-in.
- [MCP reference](https://reflow.io/docs/mcp) — Connection commands, the agent loop, evidence, recovery, and all five tool groups.

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

Cursor, Windsurf, Claude Desktop, and Codex take the endpoint URL. VS Code: `code --add-mcp "{\"name\":\"reflow\",\"type\":\"http\",\"url\":\"https://mcp.reflow.io/mcp\"}"`

## Start

- [Getting started](https://reflow.io/docs/getting-started) — Connect an agent, author a first flow, and run it in a browser.
- [Flow format](https://reflow.io/docs/flow-format) — Structure YAML frontmatter, intent, and named step fences.
- [Reflow language](https://reflow.io/docs/reflow-language) — Write readable deterministic RFL statements and targets.
- [Guiding the agent](https://reflow.io/docs/guiding-the-agent) — Give an agent the context it needs to author and interpret flows.
- [Test accounts](https://reflow.io/docs/test-accounts) — Cover sign-in, magic-link, and OTP journeys with per-run mailboxes.
- [GitHub Action](https://reflow.io/docs/github-action) — Run selected flows against PR previews and return merge-blocking evidence.
- [Playground](https://reflow.io/docs/playground) — Record flows against a live cloud browser with validated selectors.
- [Self-target](https://reflow.io/docs/self-target) — Execute flows directly on the browser image with inline CLI steps.
- [Autoheal](https://reflow.io/docs/autoheal) — How Reflow repairs a bounded class of selector failures and returns the change for review.
- [Visual testing](https://reflow.io/docs/visual-testing) — Snapshot checkpoints, baselines, and the perceptual compare loop.
- [API and tokens](https://reflow.io/docs/api) — The /v1 API, PAT scopes, and team binding.
- [Docs index](https://reflow.io/docs) — Full documentation map.

## Optional

- [Pricing](https://reflow.io/pricing) — Reflow plans.
- [Features](https://reflow.io/features) — Product capabilities.
- [For agents](https://reflow.io/agents) — The machine-facing overview, tool surface, and cold-agent proof.
- [Blog](https://reflow.io/blog) — Product and engineering notes.

why an agent uses reflow.

browser truth

Prove the pull request in a real cloud browser before merge, not from code inspection or a transcript alone.

durable replay

Store intent and named steps in markdown. RFL replays deterministically; self-heal retakes control after failure and attaches proposed RFL without rewriting the source flow.

readable evidence

Read step events and the terminal verdict with tail_run, fetch signed screenshot URLs, inspect visual checkpoints, and complete email journeys through per-run mailboxes.

described by hand

All 38 tool descriptions are hand-written. A cold agent using only those descriptions authored a flow, ran it, and returned a result within its tool-call and spend caps.

author → run → interpret.

The same MCP surface carries the agent from a live page state to a repeatable flow and back to a terminal verdict with evidence.

agent transcript · author → run → interpret streamable HTTP · OAuth 2.1

inspect reflow:open_session → reflow:snapshot → heading='Welcome back' · textbox='Email'

author reflow:create_flow name='Login screen loads' → login-screen-loads

run reflow:create_run flow=login-screen-loads@latest → run_id=f41b5dc9…

interpret reflow:tail_run → status=succeeded · summary='intent satisfied'

evidence reflow:get_run_screenshot → signed URL · agent report: PASS

38 tools. one endpoint.

Five tool-bearing groups cover the whole agent loop. Settings and keys remain an explicit dashboard boundary.

Identity & guidance

3 tools

Confirm the signed-in user, load the authoring guides, and report tool friction.

get_me · get_context · give_feedback

Flows & DAGs

8 tools

Create and version flows, inspect tags, follow dependencies, and reuse upstream output.

list_flows · create_flow · get_flow_graph · get_flow_memory · save_flow_content

Runs & results

10 tools

Run flows, tail step events, retrieve screenshots, and complete email-based journeys.

create_run · tail_run · get_run_screenshot · get_mailbox · wait_for_message

Live browser sessions

9 tools

Open a cloud browser, read its state, drive it with RFL, and capture the viewport.

open_session · snapshot · act · screenshot · close_session

Harness & containers

8 tools

Boot approved team images, run shell commands, stream output, and inspect containers.

list_images · run_image · exec · tail_exec · get_container

Settings & keys

dashboard boundary

Provider keys and API tokens stay in the dashboard. MCP OAuth never asks for a token to paste.

OAuth 2.1 · provider keys · API tokens

we test this the way a stranger would.

A fresh agent received only the tool descriptions—no examples or hints—and had to author a flow, run it, and report the result. The harness verified the reported run directly in the database, not from the transcript.

cold-agent canary · login-screen-loads database-verified

“Using only the tools available, author a flow that verifies the Reflow login screen, run it, and report PASS/FAIL with the run id.”

flow: login-screen-loads
tool calls: 19 / 30
provider spend: $0.44 / $0.90 cap
agent report: PASS
runs.status: succeeded

continue from source.

getting started MCP reference llms.txt

The GitHub Action runs selected flows against the PR preview and posts one merge-blocking check per flow with screenshots and visual diffs.