Model Context Protocol (MCP) Server for gflow-cli¶

This document describes the design, configuration, security model, and developer setup for the gflow-cli MCP server.

1. Architecture¶

The gflow-cli MCP server acts as a type-safe JSON-RPC interface, supporting two transport mechanisms: 1. stdio Subprocess Transport (gflow mcp run): Runs over standard input/output (stdio), ideal for direct integration with local desktop agents like Claude Desktop, Cursor, or VS Code. 2. Streamable HTTP Transport (gflow serve): Runs as a background web daemon over HTTP at /mcp, ideal for decoupled web UI dashboards, concurrent scripts, or external clients. The legacy HTTP+SSE transport remains available for one deprecation cycle via gflow serve --transport sse.

Protocol versions¶

The server is built on the mcp>=2 Python SDK and negotiates the protocol per connection, serving both eras from one binary:

Era	Versions	Notes
Handshake (legacy)	`2024-11-05`, `2025-03-26`, `2025-06-18`, `2025-11-25`	`initialize`/`initialized` exchange, `Mcp-Session-Id`
Modern (stateless)	`2026-07-28`	No handshake, no session id; protocol version and client capabilities ride in `_meta` on every request

We write no protocol code for this — the SDK's low-level Server.run drives serve_dual_era_loop, and the client's first request decides the era.

The 2026-07-28 stateless core costs us nothing structurally: the server holds no per-connection state. Cross-call continuity lives in SQLite (gflow.db) and the Chromium profile directory, keyed by the profile argument that every tool already takes — which is exactly the "server-minted handle passed as an ordinary tool argument" pattern the spec now prescribes. ProfileLease is a cross-process file lock, not a session, so it is unaffected. We use none of the features the spec deprecated (Roots, Sampling, Logging).

Dependency bound. pyproject.toml pins mcp>=2.0.0,<3. The upper bound is mandatory, not cosmetic: MCP SDK majors carry breaking protocol-era changes (2.0.0 deleted mcp.server.fastmcp outright, which an unbounded mcp>=1.0.0 happily resolved into — breaking every fresh install of this surface while CI stayed green on the lockfile). The resolve-drift CI job installs from the declared ranges without the lockfile and smoke-imports this surface, so the next such break fails CI instead of reaching users.

Response caching. 2026-07-28 added ttlMs/cacheScope to list results. Our listing surfaces are decided at import time by decorators, so tools/list, prompts/list, and resources/list advertise a one-hour TTL. resources/read gets five minutes because it is not static — the known-issues resource reads KNOWN_ISSUES.md off disk. cacheScope is private throughout: gflow is a local, single-user daemon driving one user's authenticated browser profile, so public would authorize shared caching of user-scoped responses.

┌────────────────────────────────────────────────────────────┐
│      Client AI Agent (Claude / Cursor / Web Dashboard)     │
└─────────────┬───────────────────▲──────────────────────────┘
              │ JSON-RPC          │ JSON-RPC
              │ (stdio / HTTP)    │ (stdout / SSE)
┌─────────────▼───────────────────┴──────────────────────────┐
│        MCP Server Adapter (MCPServer / FastAPI app)         │
│  Exposes: Tools, Prompts, Resources                        │
└─────────────┬──────────────────────────────────────────────┘
              │ internal calls
              ▼
┌────────────────────────────────────────────────────────────┐
│                       gflow-cli Core                       │
│  - FlowApiClient (Playwright / REST requests)               │
│  - SQLite operations catalog (DataStore)                   │
├──────────────────────────────┬─────────────────────────────┤
│   Chromium Profile Lock      │      Direct SQLite Read     │
│   (asyncio & file-based)     │      (Fast read paths)      │
└─────────────┬────────────────┴──────────────┬──────────────┘
              │ writes cookies                │ queries history
              ▼                               ▼
     [profile_<name>/]                  [gflow.db]

Adapters side-by-side¶

Both Click CLI (src/gflow_cli/cli.py) and MCP Server (src/gflow_cli/mcp/) are thin adapter layers that drive the core application services (FlowApiClient and repository.py), ensuring zero duplication of business logic.

2. Tools, Prompts, and Resources¶

The server registers three protocol surfaces:

Tools (Executable actions)¶

gflow_generate_image(prompt, model, aspect, count, reference_images, reference_entities, reference_entity_names, tools, profile, project, project_name, instructions, ui_mode, output, wait): Triggers text-to-image / image-to-image (Imagen / Nano Banana). There is no seed parameter: Flow picks the seed and the image request cannot carry one (removed in #1013, as the CLI's --seed was in v0.8.0). A completed result reports the catalogued seed under seed: the seed Flow chose on the classic image paths, 0 on the agentic / agent-only arms (which observe none), null if none was recorded — the MCP twin of gflow image t2i --json's images[].seed. instructions is an optional list of ephemeral agent-instruction strings (agentic cohort only). reference_images switches to i2i and accepts either a local file path or a generated image's Flow media UUID. A UUID reference is attached by selecting the already-existing asset in Flow's reference picker — no duplicate copy is uploaded (locating the tile by the media id in its thumbnail URL, and searching the recorded display name to surface it when needed); gflow falls back to uploading the asset's on-disk local file only when it can't be located in place (e.g. it lives in a different project's picker). project generates into an existing Flow project id (mirrors CLI --project; when omitted, GFLOW_CLI_PROJECT is used unless project_name asks for a new project, #1039) — pass the reference's project to keep it selectable in place. ui_mode selects the Flow UI arm (auto/classic/agentic, mirroring CLI --ui-mode, matched case-insensitively). Since #595 auto means "no arm was asked for" and resolves to classic — the arm that can satisfy an image request — so an account in Flow's agentic cohort aborts pre-submit (exit-28 equivalent envelope, zero credits) instead of failing mid-run with selector drift or video bytes; the agentic arm is bound only when named. Passing instructions forces agentic automatically, so ui_mode="classic" + instructions is a hard conflict rather than a silent drop. An unknown value returns a 400 problem-details envelope. See CONFIGURATION § GFLOW_CLI_UI_MODE. model is nano2 (Nano Banana 2.1 on flow.google.com; nano2.1 also accepted), nano2-lite (Nano Banana 2 Lite), nano-pro (Nano Banana Pro) or image4 (Imagen 4, no longer in Flow's menu); other aliases are accepted too. On migrated flow.google.com accounts, T2I and local-file I2I are supported with Nano Banana 2.1 (nano2, #958) / 2 Lite / Pro, all five aspects (16:9, 4:3, 1:1, 3:4, 9:16) and count 1–4; the page owns reCAPTCHA and the ogiZ0b submit. @Name character mentions in the prompt are attached through the composer's @ picker and verified as character chips before submit (#723). reference_entities must be paired with reference_entity_names there (an id alone is refused, exit 36); a reference_images UUID is referenced in place when the catalog records it in the same project (#995), and a local reference_images file is uploaded into the project once and mentioned in place on later calls with the same file, like the CLI's --ref (#772); an output path gflow cannot write ends in the exit-11-equivalent envelope, with the image still in the Flow project (#1091); other UUID references, instructions and Imagen 4 remain pre-submit refusals there. An agent-only composer (see below) takes T2I only. The queued (wait=false) and blocking (wait=true) calls use the same typed payload and worker path.
gflow_generate_video(prompt, mode, aspect, initial_frame, end_frame, reference_images, reference_entities, reference_entity_names, model, duration, resolution, count, tools, profile, project, project_name, ui_mode, output, wait): Triggers vertical or landscape video generation (Veo). mode is t2v/i2v/r2v; model (veo_lite/veo_fast/veo_quality/omni_flash, aliases accepted), duration (seconds — 4/6/8 for Veo 3.1 and 4/6/8/10 for omni_flash; 10 is omni_flash-only), resolution ('360p' or '720p', supported on omni_flash; on any other model, or on the labs editor, the job fails pre-submit with the exit-11-equivalent envelope and no credits spent). Whether Flow renders a duration control at all is account/cohort-dependent: on an account that renders none, the job is accepted here and fails in the worker pre-submit (exit 23 equivalent on the labs driver, exit 11 equivalent on the migrated flow.google.com host — now the default t2v route, #650 — no credits spent either way) rather than being rejected up front — see KNOWN_ISSUES (#451/#288/#630), and count mirror the CLI gflow video flags — an omitted model lets the transport apply its i2v veo-lite default (issue #125), and every model — omni_flash included — accepts i2v with a start frame and with an end frame (wire-verified 2026-09-02, issue #626); i2v requires initial_frame, r2v requires reference_images or reference_entities; project generates into an existing Flow project id (mirrors CLI --project; when omitted, GFLOW_CLI_PROJECT is used unless project_name asks for a new project, #1039); on an account Google has moved to flow.google.com (GFLOW_CLI_FLOW_HOST, read from the server/daemon environment, not per call — see CONFIGURATION § GFLOW_CLI_FLOW_HOST) omitting project creates one there first (#864); there, on the classic migrated composer (an agent-only one takes text-to-video only — see below), the ported modes are text-to-video; image-to-video with a local initial_frame, optionally with a local end_frame (start+end interpolation, #639) (the file is uploaded through the editor and bound on the Start chip by display name — it stays in the Flow project like any upload, under a run-unique name: hero.png is listed as hero-a1b2c3d4.png, so a re-run cannot bind an earlier upload — #792); and reference-to-video with local reference_images (each file is uploaded the same way — run-unique name included — and attached as an @ mention of that name in the prompt; duration there accepts only 8 and is pinned when omitted — Flow offers r2v at its base tier alone, and at 4 or 6 it silently drops the references and bills a text-to-video clip, so any other value returns the exit-11-equivalent envelope). A Flow media UUID as initial_frame or end_frame, and r2v by reference_entity_names or reference_entities, return the exit-36-equivalent envelope; a local-file end_frame is ported (#639). initial_frame, end_frame, and reference_images each accept either a local file path or the Flow image UUID of a generated asset — pass a generated image's id straight in to chain image→video, and gflow attaches it for you. Since v0.58.0 (#529) the CLI and MCP surfaces are unified for i2v frames: the UUID keeps its identity and is enriched with the catalog's recorded display name plus an integrity-verified local fallback, so the transport prefers selecting the exact asset in the project's media picker (no duplicate upload) and re-uploads the recorded local file only when the tile is unreachable — and only if its byte count/SHA-256 still match. A UUID that isn't in your local asset catalog is rejected up front with a clear "Reference Not Found" error; a catalogued asset with neither a display name nor a verified local file gives a "Reference Not Usable" error (re-generate it or pass a local path). r2v UUID refs are resolved to the recorded local file for upload. ui_mode selects the Flow UI arm (#299 PR-A, mirroring CLI --ui-mode) and applies to every mode of this tool, including r2v — unlike the CLI, where video r2v/chain have no flag and follow the env-only path. On labs and the classic migrated composer, video generation has only a classic driver, so auto ≡ classic: both verify the classic editor pre-submit and abort before spending credits if it is unreachable. ui_mode="agentic" is rejected with a 400 problem-details envelope, because no agentic video driver exists yet. (An agent-only migrated composer is routed before this check: text-to-video runs through its chat agent under ui_mode auto or classic — "agentic" is still rejected with the 400 above, before any browser work — and other video forms return the exit-36-equivalent envelope before anything is clicked.) Values are matched case-insensitively. (MCP tools return envelopes, never process exit codes — the CLI equivalents of these aborts are exit 28 and exit 2 respectively.) See CONFIGURATION § GFLOW_CLI_UI_MODE.

Attaching a saved character (the identity axis). Three routes reach Flow's referenceEntities wire and they dedupe against each other: an @Name mention inside the prompt, reference_entities by entity id, and reference_entity_names as the optional display names paired with those ids. Prefer the id when a display name could be ambiguous — Flow does not enforce unique names. reference_images is a different axis entirely: it buys a look, not an identity. Use gflow_character_list to discover ids. See REFERENCE_STRATEGIES.

wait and long generations (#481, #1097). Both generation tools take wait (default true), and its schema description in tools/list says what follows. With wait=true the tool runs the job inside the call, so the call stays open for the whole generation — minutes for a video — which can outlast an MCP client's tool timeout. Raise the client's tool timeout, or use wait=false. With wait=false the tool returns {"status": "pending", "task_id": ...} at once and runs the job in the background of the same server process, one job at a time per profile within that server. Read it back with the SEP-2663 Tasks extension (io.modelcontextprotocol/tasks): tasks/get gives its status, tasks/result gives the same reply wait=true returns (files, project id, seed) once it has finished, and tasks/cancel stops it (tasks/get then answers cancelled). A job cancelled after its submit fired is stored as indeterminate, not failed: a credit may have been spent, so check the Flow project before you retry. The job lives only as long as the server: when the client closes a stdio server, or gflow serve stops, running jobs are cancelled and recorded the same way. A server killed outright leaves its row processing — see Known issues.

gflow_auth_status(profile): Credit-free, non-interactive Flow session probe (#497) — wraps the same fail-closed verify_flow_profile check as gflow auth status. Returns {"status": "authenticated", "profile", "user_email"} or a problem-details error with a remediation_hint; a verification_error outcome (HTTP 503, retryable: true) means a network/endpoint problem, which re-login does not fix, and a profile_marker_missing outcome (HTTP 409, retryable: false, #796) means the profile lost its .gflow_browser_strategy marker so its cookies cannot be read — a retry does not help, and neither does a plain gflow auth login; re-run gflow auth login --browser chrome for that profile. A cookie_store_unreadable outcome (HTTP 409, retryable: false, #796) means the profile's Chrome cookie database is corrupt or unreadable — a local file fault, not the network; close any Chrome window using that profile, then re-run gflow auth login for it. Any other unauthenticated outcome is a dead session (HTTP 401). Call it before a generation tool to fail fast on dead auth, before a long blocking generation call. Login/logout remain CLI-only (genuinely interactive).
gflow_get_credits(profile, all_profiles, refresh): Current Flow balance query; spends no credits. With all_profiles=true, inspects every saved profile sequentially and preserves successful balances plus total_credits when another profile fails. The balance is read from flow.google.com in the profile's browser: the number the app itself loads, which is the one Flow's account menu shows (#795). That is one browser launch per profile, and the tier fields (sku, service_tier, user_paygate_tier, subscription_credits) are always null. With refresh=true, a profile that lands on a sign-in page is renewed in a headless browser and read again: one more Chrome launch per such profile, no credits. This is the MCP twin of gflow credits user|list --refresh. It runs the same renewal as gflow auth renew, but only for a profile whose credits read lands on a sign-in page. auth renew itself has no MCP tool; see the exemption in tests/mcp/test_cli_parity.py. Without refresh the call is read-only; with it, an expired profile's saved cookies are rewritten. This tool spends no credits and returns no cookies, bearer tokens, or browser API keys. The balance funds Veo video generation; image generation uses separate per-model daily quotas. A page that loads but never fetches the balance is a FlowAppError (exit 31), never an auth error.
gflow_character_list(project, profile): Lists a project's saved Flow CHARACTER entities with their entity ids — read-only, spends no credits, drives a browser session. This is how an agent discovers what it can attach: an entity_id goes to reference_entities, a display_name can be used as an @Name mention. An empty list means the project genuinely has none.
gflow_character_show(project, entity_id, name, profile): Shows one character by id or exact display name (exactly one selector required). An ambiguous name is refused rather than resolved arbitrarily — which is the reason to prefer the id. Read-only; drives a browser session.
gflow_character_voices(): Lists the preset voices available for Character TTS (name, description, sample URL). A static in-process lookup — no network, no browser, no profile, no cost. Call it to pick a valid voice name.
gflow_list_projects(profile, limit, offset): Queries the SQLite catalog for recent generation folders, paginated — the response carries count (rows in this page), offset, has_more, and next_offset (pass it back as offset for the next page; null on the last page).
gflow_download_media(media_id, out_dir, profile): Fetches an already-generated asset from Flow by its media ID and writes it to disk — the recovery path for a generation that was billed but whose download failed. Spends no credits. The bytes are verified against the size Flow reports before the file is written, and the catalog's local_files row is updated. Returns path, bytes, media_id, workflow_id, project_id and profile. The transfer retries a dropped connection internally (#895), so a failure marked retryable means pause and call again — not immediately, and not in a tight loop: each call opens a browser under a per-profile lease, and a second concurrent call fails on that lease instead (exit 11).
gflow_upscale_image(media_id, scale, project, out_dir, profile): Upscales an already-generated image to 2K or 4K. scale is 2k or 4k (4K requires Ultra; Pro accounts support 2K). Spends no credits.
gflow_upscale_video(media_id, scale, project, out_dir, profile): Upscales or exports an already-generated video to 1080p Full HD, downloads the original 720p, or exports a 270p animated GIF. scale is 1080p, 720p, or 270p. Driven on flow.google.com only; measured free (1 observation, 2026-10-07).
gflow_list_tools(): Lists the prompt tools (name/title/description/category) accepted by the generate tools' tools param.
gflow_list_models(): The image and video model catalog, the same object as gflow models --json (#883): per model name, label (image: Flow's menu name), the CLI's --model aliases (the generate tools accept each of them as model, plus wider spellings such as narwhal or veo_lite), ref_cap, default (image) and max_duration (video), plus aspects and video tiers. Built from the same enums the generate tools use, so every alias it lists is accepted back. Static: no profile, no browser, no spend.
gflow_instructions_list(project, profile): Lists a project's persistent Agent-Mode instruction cards (live server brief; credits-free).
gflow_instructions_add(project, title, text, refs, enabled, profile): Adds a persistent instruction card. Each ref is classified automatically — local image path → uploaded image reference, asset UUID → image reference, anything else → character id/name (mirrors CLI instructions add --ref).
gflow_instructions_set_enabled(project, enabled, title|card_id, profile): Enables/disables one card selected by title or stable card id (covers CLI instructions enable/disable).
gflow_instructions_rm(project, title|card_id, profile): Removes one card from the brief.
gflow_instructions_toggle_mode(project, enabled, profile): Flips the brief-level master switch; cards are left untouched.
gflow_instructions_apply(project, cards, profile): Declarative full-sync — REPLACES all cards with the given set (destructive; same entry shape as the CLI instructions apply file).

CLI↔MCP parity is enforced programmatically: tests/mcp/test_cli_parity.py walks every CLI leaf command and fails when one has neither a mapped MCP tool nor an explicit exemption with a stated reason. Note the deliberate asymmetry: gflow_generate_video has no instructions param (unlike gflow_generate_image) because the video pipeline (GenerateVideoRequest / the worker) has no instructions support — agentic-video is a typed divergence, and a dead parameter would be silently dropped. Both gflow_generate_image and gflow_generate_video support an output parameter mirroring the CLI -o/--output flag (#414, #415), decoding explicit output destinations in the worker path. gflow update is a considered exemption, not a backlog item: the package manager would replace the venv under a live gflow mcp run and write its output onto the JSON-RPC stdout channel — the operator runs it and restarts the server. A read-only twin of gflow update --check would be harmless; it is the upgrade path if agents ever need version awareness beyond the initialize handshake.

Prompts (Orchestration templates)¶

expand_prompt: Helps the agent structure simple ideas into Google's official 5-component prompt formula (Subject + Action + Location + Composition + Style) before sending them to the generation tools.
create_character: Assists agents in defining face, body, and voice parameters for consistent subject generation.

Resources (Context feeds)¶

gflow://docs/mcp-guide: A specialized, agent-targeted guide instructing the LLM to use the registered MCP tools (rather than running raw shell wrapper commands).
gflow://docs/known-issues: Bounded index of KNOWN_ISSUES.md (titles + status, a few KB — #501); read gflow://docs/known-issues/{slug} for one issue's full text (capped at 16 KB). The old behavior injected the whole ~70 KB file per fetch.
gflow://db/schema: Exposes SQLite schema definitions, allowing agents to understand project and media tables.

3. The Dilemma: Why we need the MCP Server (vs. Pure Skill)¶

We analyzed whether a terminal-driven CLI guided by a text skill (e.g., skills/gflow-cli/SKILL.md) is sufficient. The LLM Council concluded that the MCP server is fully justified for these reasons:

Dimension	Direct CLI via Terminal Execution	Native MCP Server Daemon
Output Fragility	Ephemeral `stdout`/`stderr` log outputs are fragile to format adjustments, progress bars, and ANSI colors.	Strictly structured JSON payloads containing explicit metadata and absolute output file URIs.
Process Lifecycle	High process startup overhead (Python import latency) on every individual execution.	Warm daemon process. Retains active caching of database metadata.
Concurrency	A second concurrent process against the same profile is rejected immediately by the cross-process `ProfileLease` with `ProfileLockedError` (exit code 11) — a clean fail-fast, never a crash, never a wait. Different profiles run fully in parallel.	Calls on one profile inside one server run one at a time — a second call waits for the first instead of failing. A profile held by a different process (a CLI run, another server) is waited out for up to 180 s (`GFLOW_CLI_LEASE_WAIT_SECONDS`, which a value you set yourself overrides) before `ProfileLockedError`; different profiles still run fully in parallel.
Error Handling	Agent must scan logs for strings or parse exit codes to check status.	Strongly-typed JSON-RPC errors with mapped codes and clear remediation.
Transport Safety	Volatile console printing.	Stdout is strictly isolated for JSON-RPC; all logs and warnings route to stderr.

Error envelope¶

MCP tool failures return a structured error object built from the same RFC 9457 Problem Details as the CLI, plus a retryable boolean. retryable: true marks a transient failure a scheduler can re-run without operator intervention — WAF/reCAPTCHA bounce (WafRejectionError), rate-limit (RateLimitError), transport timeout (TransportTimeoutError — but one raised after a submit click is false, see below), network blip (NetworkError — but not a failed download of media Flow already made, see below), a dropped browser session (BrowserSessionClosedError), a Flow web-app crash (FlowAppError), an agentic-cohort flap (FlowAgentUiError — but see the agent-only exception in § 6.1, which overrides it to false), an unreachable UI arm (UiModeUnavailableError), and a partially-completed sync (SyncPartialError). That list is errors.RETRYABLE_ERRORS, but it is no longer the whole answer: errors.is_retryable consults the instance first, so a raise site can override its class. Among them, Flow's /about redirect raises FlowAppError with retryable: false, and since 2026-09-11 that is a measurement, not a preserved default: caught during a live occurrence, 5/5 consecutive attempts over ~3 minutes landed on /about again, on the account's own project with a healthy session — so a retry is doomed and costs ~35 s each (#756). The second is the migrated agent-only composer (#799), which gflow drives through its chat agent: there FlowAgentUiError carries retryable: false because it means the agent did something other than what was asked — a second credit confirmation, more results than requested, or an image turn that made nothing (a video turn that makes nothing ends in TransportTimeoutError, also retryable: false there, since the request was already sent) — and a blind re-run repeats the ask. Its detail may include the agent's last reply. The cause, and whether it ever clears, remain unmeasured. The same holds on the classic flow.google.com composer for any TransportTimeoutError raised after the submit click (#1010): an unreadable or missing submit reply, or a generation that is not terminal in time, is retryable: false, because Flow may already have made and billed it. Likewise a failed download of a finished generation (MediaDownloadError, exit 6, type …/errors/media-download) is retryable: false (#941): the clip exists and was billed, so the recovery is gflow_download_media with its media_id, which spends nothing and stays retryable: true. The override also runs the other way: a reCAPTCHA mint failure (type …/errors/recaptcha-mint, exit 1, no request sent, no credit spent) is retryable: true when a navigation raced the mint or the page was a Flow page whose script had not loaded yet, and false on a page that is not a web page — each measured live (#915). Read the flag off the envelope; never re-derive it from the class list. Everything else (auth, content-policy, configuration, security) is terminal (retryable: false): retrying the identical request fails the same way. This flag is the same shared classification the CLI --json payload and the worker-queue error record use (errors.is_retryable) — the three surfaces cannot drift. On a captured failure the envelope also carries a remote-safe incident object ({id, capture_status} only — never a local path); see DEBUGGING § Automatic incident bundles.

Every tool routes through one error funnel. Unexpected (non-gflow) exceptions are masked: the client sees only the exception class name ("Unexpected RuntimeError; details were logged server-side.", status: 500, retryable: false) — raw exception text can embed filesystem paths, profile names, or token material and never leaves the server; the full message and traceback go to the server-side structured log (mcp.tool.unexpected_error).

A failed generation task can still name its media. When Flow generated the media and only the download failed (a video whose transfer dropped, #895; an image whose local write failed, #1035), the status: "failed" reply of gflow_generate_image / gflow_generate_video also carries flow_media_id and, when the catalog knows it, flow_project_id. Both keys are absent when the task failed before Flow named any media. With count > 1, flow_media_id is the first image's id only; every image's id is in the catalog (gflow data list images; there is no MCP twin for that listing). A video is then recoverable with gflow_download_media; an image is not (that tool is video-only, #877), so open the project in Flow. The catalog keeps the image's asset row, with no local copy, under one FAILED operation.

4. Setup Instructions¶

Claude Code — the plugin (one step)¶

/plugin marketplace add ffroliva/gflow-cli
/plugin install gflow@gflow-cli

This installs the gflow-cli and video-production skills and registers this MCP server, so there is nothing further to configure.

It ships disabled on purpose. Claude Code starts a plugin's MCP servers automatically when the plugin is enabled — there is no separate prompt for the server itself. This server drives your own signed-in Google account, and Veo video generation bills your credits. So the plugin sets defaultEnabled: false: installing it does not start anything, and enabling it is a deliberate act. Images and composition cost nothing; only video spends.

The plugin also declares a required userConfig acknowledgement, which Claude Code prompts for when you enable it in the UI. Be aware that it is a prompt, not an enforcement gate — claude plugin enable on the command line succeeds without it. defaultEnabled: false is the control that actually holds.

The hard guarantee, if you want one, is --no-spend. It is not a policy the model is asked to respect: the credit-spending tools are never registered, so they do not appear in tools/list at all. Register the server yourself with gflow mcp run --no-spend (see the manual setup below) instead of using the bundled entry.

The plugin runs gflow mcp run, so gflow must be on your PATH (uv tool install gflow-cli) and you must have authenticated once with gflow auth login --browser chrome.

Which revision you get. /plugin marketplace add ffroliva/gflow-cli reads the marketplace from the repository's default branch, which in this project is develop — the integration branch, not the last release. So the plugin you install tracks develop, while the version string in its manifest and the documentation links inside its skills both point at the last released state. If you want a released revision, install from a tag instead of the default branch, or use the manual MCP setup below and a pinned gflow-cli from PyPI.

Claude Desktop Integration¶

Run the configuration helper command in your terminal:

gflow mcp setup

This merges the server entry into your Claude Desktop configuration file — existing content is preserved, and a pre-existing file is backed up as <name>.gflow-backup first. A corrupt config fails loud (exit 11) and is never overwritten: * Windows: %APPDATA%\Claude\claude_desktop_config.json * macOS: ~/Library/Application Support/Claude/claude_desktop_config.json * Linux: ~/.config/Claude/claude_desktop_config.json

Other targets: gflow mcp setup --target cursor (~/.cursor/mcp.json) and --target vscode (the user-profile mcp.json, written with VS Code's servers + "type": "stdio" schema).

Existing entries are preserved: if your config already has a gflow or gflow-cli server entry (including the local-clone uv --directory variant below), gflow mcp setup leaves it completely untouched and reports "Already configured" — it only ever adds a missing entry.

Manual Configuration¶

Depending on how you installed gflow-cli, add one of the following configuration blocks under the mcpServers key of your claude_desktop_config.json:

Option A: Global Installation (Recommended)¶

Use this if you installed gflow-cli globally (e.g. via uv tool install gflow-cli or pip install gflow-cli):

{
  "mcpServers": {
    "gflow-cli": {
      "command": "gflow",
      "args": [
        "mcp",
        "run"
      ]
    }
  }
}

Option A2: Read-only server¶

Use this when the agent must never be able to spend credits (#496). The two credit-spending tools (gflow_generate_image, gflow_generate_video) are then never registered, so they do not appear in tools/list at all — invisible rather than refused. Every read-only tool stays available.

{
  "mcpServers": {
    "gflow-cli": {
      "command": "gflow",
      "args": [
        "mcp",
        "run",
        "--no-spend"
      ]
    }
  }
}

Setting GFLOW_MCP_NO_SPEND=1 in the environment does the same thing and also covers gflow serve. gflow mcp setup writes the plain (spending) block above — add the flag or the env var yourself if you want the read-only server.

Option B: Local Clone (Development)¶

Use this if you cloned the repository locally and run it via uv:

{
  "mcpServers": {
    "gflow-cli": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/gflow-cli",
        "run",
        "gflow",
        "mcp",
        "run"
      ]
    }
  }
}

Cursor Setup¶

Open Cursor Settings -> Features -> MCP.
Click + Add New MCP Server.
Configure depending on your installation:
Global Installation:
- Name: gflow-cli
- Type: command
- Command: gflow mcp run
Local Clone (Development):
- Name: gflow-cli
- Type: command
- Command: uv --directory /path/to/gflow-cli run gflow mcp run

HTTP Daemon Setup (`gflow serve`)¶

For decoupled clients, local web interfaces, or multi-process frontends, run the daemon as an HTTP service:

gflow serve --port 8000 --host 127.0.0.1 --profile default

# Read-only daemon — the two credit-spending tools are never registered (#496):
gflow serve --port 8000 --host 127.0.0.1 --profile default --no-spend

This serves the MCP server over Streamable HTTP, the current spec transport: * Endpoint: http://127.0.0.1:8000/mcp

The legacy HTTP+SSE transport is still available for one deprecation cycle:

gflow serve --transport sse --port 8000   # deprecated; logs a warning

* Connection endpoint (SSE stream): http://127.0.0.1:8000/sse * Command posting endpoint: http://127.0.0.1:8000/messages/

Deprecated: the MCP 2026-07-28 spec reclassified HTTP+SSE as deprecated. Prefer the default --transport http. The spec's lifecycle policy guarantees a minimum twelve months between deprecation and removal.

stateless_http is deliberately not enabled. The stateless core exists so servers can scale out across interchangeable instances; gflow's value is the opposite — a warm daemon holding one live Chromium profile, serialized by ProfileLease. The protocol is stateless either way; that flag only governs transport bookkeeping we want to keep.

Authentication¶

Set GFLOW_DAEMON_TOKEN (alias GFLOW_CLI_DAEMON_TOKEN) and every request to the daemon must present it:

Authorization: Bearer <token>

A missing header, a non-Bearer scheme, or a wrong token is answered 401 with WWW-Authenticate: Bearer — on /mcp and on both halves of the deprecated SSE surface (/sse, /messages/). The comparison is constant-time (hmac.compare_digest), and auth is the outermost layer, so an unauthenticated caller learns nothing about the transport's DNS-rebinding allow-list.

Non-loopback binds (e.g. --host 0.0.0.0) require the token — gflow serve refuses to start without one (exit 11). A loopback bind with no token stays unauthenticated, which is the local single-user default.

Note: the background FlowWorker queue manager and the REST /api/v1 surface are built as internal foundation but are not yet wired into gflow serve — it currently runs the MCP/SSE server only. See the CHANGELOG for the roadmap.

Settings reach the server through its environment, not your shell's .env. An MCP client starts gflow mcp run in a directory of its own choosing, so a .env beside your shell is not read. Put settings such as GFLOW_CLI_BROWSER_PROXY in $GFLOW_CLI_HOME/.env or in the client's env block, and restart the server after changing them.

However you register it, that server then gates your upgrades. Every client above starts a long-lived gflow mcp run — one per session — and on Windows it holds the install open, so a package manager can abort part-way through gflow update and leave the environment broken. Stop the servers first: USAGE § gflow update.

5. Security & Anti-Bot Mitigations¶

Because the MCP server runs locally, inheriting the host user's permissions and access to their authenticated browser cookies, the following security constraints are enforced:

Profile Pre-flight: Before enqueuing work, each tool resolves and validates the target profile directory (_resolve_and_validate_profile — existence and home-boundary checks). There is no session-validity probe before launching Chromium: expired cookies surface as a typed AuthExpiredError from the generation run itself, with the remediation Run 'gflow auth login' in your local terminal.
Channel Isolation: All internal structlog configurations are forced to write to sys.stderr. The standard output stream (sys.stdout) is globally captured and redirected to sys.stderr for any unexpected prints, preserving the integrity of the stdio JSON-RPC pipe.
Windows Stdio Encoding: During startup, stdio streams are explicitly reconfigured:
```
sys.stdout.reconfigure(encoding='utf-8')
sys.stdin.reconfigure(encoding='utf-8')
```
This prevents crashes caused by non-ASCII prompt strings on Windows.
Local Rate-Limiting: Enforces a token-bucket rate limiter with a capacity of 8 tokens and a refill rate of 1 token every 20 seconds (allowing burst filmmaking tasks without timeouts). This is the only spend brake — there is no credit-budget accounting or per-session/daily cap (#495; a registration-time --no-spend gate is tracked in #496).
CLI-MCP Parameter Symmetry: Two CI layers guard the surfaces against drift: tests/mcp/test_cli_parity.py forces an explicit MCP decision (mapped tool or stated exemption) for every CLI leaf command, and tests/mcp/test_server.py::TestCliMcpParameterSymmetry compares CLI Click parameters against registered tool signatures for the two generate tools. Parameter-level comparison does not yet cover the other tools.
No-Spend Mode (#496): gflow mcp run --no-spend (or GFLOW_MCP_NO_SPEND=1, which also covers gflow serve) never registers the credit-spending generate tools — gflow_generate_image and gflow_generate_video are absent from tools/list entirely, rather than present-but-refusing. Both are gated because image generation is only empirically free and no-spend is a hard guarantee. Listing, instructions, and other read-only tools remain available.

6. Troubleshooting a failed tool call¶

A failing MCP tool call gives an agent much less to go on than a CLI run gives a human: there is no --help to re-read, no stderr to scroll, and the envelope is deliberately narrow (no local paths, no raw exception text — see § Error envelope). This section is the decoder.

Read the envelope in this order: retryable → status → title → detail. Never re-derive retryable from the class name; a raise site can override its class, and one does today.

6.1 First question: what state is this account's Flow in?¶

Google has moved Flow from labs.google/fx/tools/flow onto flow.google.com, and the move is not one step. Measured 2026-09-14 (3 accounts x 2 entry points x 2 runs): the old labs URL answers HTTP 308 Permanent Redirect on every account tested, yet those same accounts differ in which capabilities work. So the host you are served does not tell you what works — several capability states coexist behind one frontend, they change without notice, and most confusing failures here are really "this account is in a different state than the one the message assumes". Establish the state before diagnosing anything else — it is a $0, read-only check:

gflow auth status          # which host minted the session, and for whom
gflow credits user         # reads the balance from flow.google.com (#795)

History. The credits user column describes builds before the #795 fix, when the balance came from a labs.google token. Since that fix, credits user reads the balance from flow.google.com (#795), so it no longer tells these rows apart. The table is kept for the auth status column.

`auth status`	`credits user`	What you are on	Consequence
verified	a balance	labs session alive	Everything documented works
verified	fails, `"the labs.google session returned no access token"`	migrated; labs authenticates but never mints the `ya29` Bearer	`credits` cannot work. Since v0.73.2 the remediation says so (#795)
verified	fails, `"credits endpoint returned 401"`	a token exists but aisandbox-pa rejects it — most often labs' token has lapsed (`ACCESS_TOKEN_REFRESH_NEEDED`)	Until 2026-10-22, usually fixable (labs' session URL is gone now, see the note above): `gflow_get_credits(refresh=true)` (CLI: `--refresh` or `gflow auth renew`) renews it headlessly and reads again. Measured 2026-10-14: 7 of 10 such profiles, all served `flow.google.com`, recovered. The rest were held at Flow's public `/about` page, which renewal reports and cannot clear (#795)
"Signed in to Google, but not to the Flow app" forever	—	migrated; labs no longer mints a Flow session at all	Login cannot complete on the released build. Tracked in #791
"Signed in to Google, but not to the Flow app"	—	or the account has no Flow access at all	Same sentence, second cause. The session endpoint answers 200 with an empty `user` for an abandoned sign-in and for an account with no Google AI Plus/Pro/Ultra (or qualifying Workspace) plan, so `auth status` cannot tell them apart. Open `https://flow.google.com` in a browser on that account: a landing on `/unavailable` means this row. A generation command says so directly — exit 39, `FlowAccessUnavailableError`

In every migrated row above except the no-Flow-access one, generation over the migrated composer still works — only the aisandbox REST reads fail (credits no longer is one, #795). On the agent-only composer described below that holds for text-to-image and text-to-video only.

A credits failure names its cause. Since #795 the balance is read from flow.google.com's own reply, not from a labs.google token. A sign-in landing is exit 3 (AuthExpiredError, renewable with refresh=true / --refresh). Flow's public /about page, or an app that loads without a readable balance reply, is exit 31 (FlowAppError). An account with no Flow access is exit 39. A balance reply in an unexpected shape is exit 7 (WireFormatError), and a profile another gflow process holds is exit 11 (ProfileLockedError). Only exit 3 is about your session. The other codes do not mean "re-run gflow auth login". If the profile has no browser-strategy marker yet, a re-login can make things worse, because a failed first login rolls that marker back. History: before #795, two raise sites in the since-deleted api/credits.py (labs issuing no token, aisandbox-pa rejecting the token) produced every credits failure. Through v0.73.2 the second one carried the class-default SAPISID advice; see the CHANGELOG.

The migrated composer itself also comes in more than one shape. An account whose composer is agent-only — no classic composer at all — is driven through its chat agent for gflow_generate_image (text-to-image) and gflow_generate_video (text-to-video): aspect, count and model are set in Agent settings for the run and restored afterwards, and "Confirm before generating" follows the server's GFLOW_CLI_AGENT_CONFIRM. Other forms on that composer (references, image-to-video, instructions, more than one video) return an exit-36-equivalent envelope before anything is clicked (#799). Through v0.73.2 such an account got a generic selector-drift envelope (exit 23); v0.74.0 and v0.75.0 named it with exit 25.

The distinction that matters, because the DOM is identical either way: a pressed chip means the classic arm exists and gflow turns it back on itself (#749); no chip at all means there is no classic arm to return to, aspect / model / count are Agent-settings defaults rather than per-request controls, and no flag or profile change helps. Generating from the Flow web UI still works.

6.2 Envelope → cause → what to do¶

What you see	Almost always	Do this
`retryable: true`, WAF / rate-limit / timeout	Transient	Re-run once. If it repeats immediately, stop — it is not transient
selector drift, "the frame picker stayed open … and stayed open after its confirm was clicked"	Flow changed the Frames picker again	File it with the verbatim `detail`; the raise sites are textually distinct and the string identifies which one
selector drift, "… and carries no confirm"	A cohort whose picker neither commits nor offers a confirm	As above — this is a new shape, not #792
"the Start chip did not bind"	The search and the click both landed; the chip still did not take the thumbnail	Not retryable (`retryable: false`) — gflow refuses to submit rather than let it go out as text-to-video. File it with the verbatim detail. (Late server-side indexing is a different failure — "lists no asset named …" — and that path already retries internally)
exit-27-equivalent, upload rejected, a dialog opened and no request left the page	Flow's one-time "rights to use this image" confirmation	Open the project on flow.google.com, upload any image by hand, accept it. gflow will not click it for you: it affirms that you hold the rights. Once per account, then uploads run unattended
exit-39-equivalent, "This Google account cannot reach Flow"	The account has no Flow access — it needs a Google AI Plus/Pro/Ultra or qualifying Workspace plan, an age-verified account and a supported region	Stop. Do not retry, and do not call `gflow_auth_status` or suggest a re-login — this is the one envelope where a retry is guaranteed futile, because the editor does not exist for this account. Relay the `remediation_hint` and its link verbatim; only the human can fix it. Note `auth status` will separately claim the Flow sign-in was not completed, which is the same sentence with a second cause
exit-36-equivalent	The capability is not ported to the migrated host	See CONFIGURATION § GFLOW_CLI_FLOW_HOST for exactly what is served there
"Profile is missing its browser-strategy marker" (409, `retryable: false`, from `gflow_auth_status`)	The profile's browser-strategy marker is gone — typically after a failed first login	`gflow auth login --browser chrome`. It is not a network problem, whatever an older build told you
`"Unexpected <Class>; details were logged server-side."` (500)	A non-gflow exception; the text is masked on purpose	Read the server's structured log for `mcp.tool.unexpected_error` — the traceback is there, not in the envelope

6.3 Getting evidence an agent can actually send¶

The envelope carries an incident object ({id, capture_status} only — never a path). Resolve it on the machine running the server:

<GFLOW_CLI_HOME>/incidents/<YYYY-MM-DD>/<stamp>-<incident-id>-<rand>/

Layout and what triggers a capture are in DEBUGGING § Automatic incident bundles.

Judge the bundle before you trust it. A bundle whose ui.json has all tag counts at 0 and a blank white screenshot photographed an about:blank page, not your failure — that was a real defect in gflow (fixed in v0.73.2), so a bundle with that signature from an older build carries no information about what went wrong. It is not evidence that the page was blank.

For a run you can reproduce, raise the log level on the server process (GFLOW_CLI_LOG_LEVEL=DEBUG) and capture stderr — MCP writes every structured log line there, never to the stdio pipe.

6.4 Before filing¶

Include the verbatim detail string, the retryable/status pair, the two cohort commands from §6.1, and gflow --version. Redact account identifiers, cookie and token values, and signed media URLs before pasting anything into an issue. If you have an incident bundle, say so — but do not paste it: it contains prompts and can contain identity-bearing attributes.