MCP reference

Local author connection

Install the public CLI and configure your agent to launch reflow mcp over stdio. Follow agent setup for installation, hosted sign-in, target selection and client configuration. The CLI manages the local execution service as needed.

Use the full author profile for flow edits, execution, knowledge maintenance and comment export. Use the same private profile and connection settings as the CLI. After reflow login, hosted connection settings are automatic. Launch the MCP host from your application checkout; Reflow infers its Git root. Hosts that start outside the project can set REFLOW_LOCAL_REPO explicitly; see the setup appendix. reflow mcp discovers or starts the service for that profile; no port lookup is needed.

Representative author tools

Job	Tools	Contract
Product documentation	get_product_docs	List, search and read bounded excerpts of the packaged product docs.
Packaged guidance	load_skill	Load reflow to start, then plugin-execution, flow-authoring, knowledge-corpus or storyboard.
Plugins	list_plugins, init_plugins	Inspect the installed schemas and exact source pins; explicitly initialize selected plugins.
Local execution	manage_execution	Select a target, plan, apply, inspect runs, taint, cancel or unlock using the same controller as the CLI.
Saved flows	get_reflow_context, manage_flows, get_flow_source	Read exact originals; create/save through shared state and resolve canonical versions after acceptance.
Device execution	manage_device_jobs	Start an exact flow version, inspect job results and originals, prepare and publish selected evidence.
Knowledge	search_kb, get_kb_page, manage_knowledge_uploads, manage_knowledge_drafts	Read pinned revisions; maintain complete current-state knowledge with explicit publication and root decisions.
Source changes	prepare_knowledge_refresh	Return a bounded task for a fresh host-managed knowledge maintainer; planning makes no model call or product write.
Comparisons	review_changes	Publish/read exact comparisons, inspect originals, add advisory notes and prepare/export a PR comment.
Live browser	open_session, get_session, act, snapshot, screenshot, get_session_command, close_session	Use explicit RFL and retain command IDs for recovery.

Tool profiles expose different subsets. Read the connected tool schemas before calling; the remote HTTP registry’s names are not interchangeable with sidecar flow, knowledge and review tools.

Plan and execute with plugins

Read get_reflow_context to select the application collection and its current storage preference. Load flow-authoring and plugin-execution, then inspect list_plugins before authoring. Keep exact plugin requirements in the flow’s frontmatter; private database, shell and container settings belong in device binding files.

Use manage_execution with action: "target" to select the repository, target URL and group once. action: "plan" returns the run/reuse/wait/blocked decisions. For action: "apply", pass the inspected fingerprint, its storage_fingerprint and a fresh request_id UUID. Inspect run and status for completion and evidence. parallelism can overlap independent flows while preserving their dependencies.

After an uncertain response, reconcile the same request_id; do not launch a second apply. For an intentional rerun, taint selects a flow slug or flow#step, followed by a new plan and apply. See getting started for the equivalent CLI loop.

Live session loop

1. Call open_session with target_url and, optionally, browser, device and an idempotency_key retained for this start.
2. Poll get_session with the returned session_id until ready: true.
3. Use snapshot with that session_id to inspect page state. act accepts one deterministic RFL line, not a free-form prose task.
4. Retain a fresh UUID as command_id before each action or screenshot. Recover a pending or uncertain command with get_session_command, using the same session_id and command_id, or an identical retry with that ID.
5. Always call close_session with the session_id when finished.

Example act arguments, after selecting a real session and generating a UUID:

{
  "session_id": "RETURNED_SESSION_ID",
  "command_id": "FRESH_COMMAND_UUID",
  "line": "click role=button name=\"Add to cart\""
}

Use a new command ID for a different action. A screenshot command uses session_id and command_id; completed responses can include an image block and a short-lived original URL. A live session transcript is not a saved flow: author the executable Markdown and explicitly save it.

Prepare a PR for human review

1. Read the selected application’s knowledge with search_kb and get_kb_page, retaining the returned revision. Load load_skill({"name":"knowledge-corpus"}). Knowledge describes the application at the selected revision; replace stale facts rather than appending change logs. Keep rationale and history outside current pages.
2. Use manage_execution to plan and apply the selected collection’s repository and shared flows through the installed plugins, then inspect the original source, step results and captures. Keep the controller’s run and artifact links for review. For an execution produced by the separate manage_device_jobs path, its prepare_review and publish_review actions can prepare portable evidence; follow their returned selections and hashes. Do not rerun a controller test through another tool just to produce an export.
3. When committed source changes, prepare_knowledge_refresh accepts base_ref, candidate_ref and a selected knowledge revision/hash (or explicit uninitialized state). The author host chooses a fresh maintainer, its budget and any authorized publication. This does not start an autonomous backend authoring agent or approve the candidate knowledge.
4. Use review_changes to publish an exact base/candidate selection and, where relevant, a visual walkthrough. Keep the returned id and selectionHash together. Declared coverage, omissions and original evidence remain inspectable; source code remains in version control.
5. A separate fresh reviewer pages review_packet and examines originals before adding advisory annotations with basis: "fresh_review". Follow patch pages and text_changes offsets when previews are shortened.
6. Call review_changes with action: "prepare_comment", id and selectionHash. Inspect its preparation state. The author can use action: "export_comment" with the same selection and a new absolute outputDirectory on the daemon device to save Markdown, selected media and a receipt. Existing output directories refuse. These actions do not post or upload. After uncertainty inspect the same output and receipt before retrying.

Human links use the configured application origin and require normal team access. Hand over a ready comment through your authorized PR workflow. Missing evidence cannot be waived by an agent’s LGTM. Human acceptance belongs to PR merge; Reflow does not commit accepted changes to the branch automatically.

Visual results and repairs

An explicit snapshot checkpoint with no approved baseline reports new. It requires explicit owner approval before becoming a baseline. A difference above its threshold fails the checkpoint and stores evidence. An advisory base/candidate visual comparison is separate from that contractual result. See Snapshots and review for browser screens, command output and database evidence.

For ordinary repair, the connected coding agent inspects the failure, patches the application or flow, then uses manage_execution to plan and apply the affected work. Changed inputs and dependency outputs automatically select reruns. It preserves the original failure and inspects the candidate’s actual results before claiming a verified repair. This uses the host agent; no additional model provider is required inside Reflow. See Repair and rerun.

The separate in-run selector repair requires the execution path’s configured provider authority and is restricted to eligible element-target failures. It cannot waive assertions or visual mismatches.

Remote HTTP API connection

The separate streamable-HTTP MCP server exposes API flow/run/session/mailbox and container operations. Its configured public endpoint is:

https://mcp.reflow.io/mcp

The hosted endpoint uses OAuth 2.1 browser consent. For example:

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

get_me identifies the authenticated user. The remote registry uses get_context, get_reflow_context, manage_flows, tail_run and get_run_screenshot. It does not replace the local author’s knowledge and comparison preparation tools. Collection tests run through the author device’s manage_execution controller. Hosted manage_flows can save shared tests and return repository drafts; it cannot write local files. The legacy remote create_run interface needs an idempotency_key and a flows array: registered flows use slug plus exactly one of tag or flow_version_id. The browser must be able to reach its target URL; a remote browser’s localhost is not the author’s device.

See API and tokens for the HTTP contract and GitHub Actions for CI progress comments and private visual report delivery.