AutoFlow agent server (autoflow-agent)

Lets an AI agent on your computer — Claude Code, Codex, Antigravity, Cursor, Claude Desktop or any other MCP client — drive the AutoFlow Chrome extensions:

• Queue Manager: add queues of prompts (with reference images and Flow characters), change settings, run, pause, stop, retry, and read the results.
• Studio: build workflows from a plan, open templates and saved workflows, edit nodes, run, retry, stop, and read every node's result.

The agent asks; the extension does the work with the same code as its own buttons. So an agent's run is checked against your plan's limits, charged the same way, and shows up in the panel as it happens.

How it fits together

 Claude Code / Codex / Antigravity            your browser
 ───────────────────────────────              ───────────────────────────────
 agent ──stdio (MCP)──► autoflow-agent ◄──ws://127.0.0.1:8124── Queue Manager
                                       ◄───────────────────── Studio

The server listens on 127.0.0.1 only. The extensions connect to it; it accepts only AutoFlow's own extensions (by the Origin a browser sets and a web page cannot change), so no website can use it. Several agent sessions can run at once: the first holds the port and the others relay through it.

1. Switch it on in the extension

Agent control is off until you turn it on, in each extension:

• Queue Manager: Settings → AI agents → Let AI agents control AutoFlow
• Studio: side panel → Let AI agents control AutoFlow

The line under the switch says Waiting for the agent server until step 2 is done, then Connected.

2. Add the server to your agent

Claude Code

claude mcp add autoflow -s user -- npx -y autoflow-agent

Codex (CLI or IDE extension)

codex mcp add autoflow -- npx -y autoflow-agent

or in ~/.codex/config.toml:

[mcp_servers.autoflow]
command = "npx"
args = ["-y", "autoflow-agent"]

Antigravity: Agent panel → ⋯ → MCP Servers → Manage MCP Servers → View raw config, and add:

{
  "mcpServers": {
    "autoflow": { "command": "npx", "args": ["-y", "autoflow-agent"] }
  }
}

Cursor / Claude Desktop: the same mcpServers entry, in .cursor/mcp.json or claude_desktop_config.json.

On Windows, if the agent cannot start npx, use "command": "cmd", "args": ["/c", "npx", "-y", "autoflow-agent"].

Then ask your agent something like "Check AutoFlow is connected, then queue these five prompts in portrait on Veo 3.1 Fast and run them."

Tools

| Tool | What it does | |---|---| | autoflow_status | Which extensions are connected. Call first. | | autoflow_use | Pick a browser when two run the same extension (e.g. two Multilogin profiles). | | queue_status | Signed in?, today's allowance, open Flow tabs, the running queue. | | queue_get_settings / queue_update_settings | Read or change the saved settings; lists every allowed value. | | queue_list / queue_get | Queues and their prompts, statuses, errors, output files; a refused prompt carries lastFailure (reason, kind, what to do). | | queue_add | New queue from prompts (text, image files, characters). Each queue runs in its own new Flow project. | | queue_run | Spends credits. Start a queue on Google Flow. | | queue_control | Pause, resume, stop, skip, retry_failed. | | queue_replace | New words for failed prompts in the same prompt numbers (the panel's Replace), then runs them. Spends credits unless run: false. | | queue_wait | Wait until a queue stops running. | | queue_delete, queue_logs | | | queue_character_list | The Character maker's characters, Flow's 30 voices, the image models. | | queue_character_write | An AI writes a character from a short idea (needs a Gemini key in the panel). | | queue_character_create | Spends credits (one portrait). Save and make a character in one call: name, look, voice. | | queue_character_save | Create or change a character: name, look, personality, voice, custom voice. | | queue_character_make | Spends credits (one portrait). Makes the character in Flow, once; every queue borrows it. | | queue_character_import, queue_character_delete | Bring in the open Flow project's characters; remove one. | | studio_status | The open workflow, run state, node counts. | | studio_plan_guide | The brief for writing a plan. Read before studio_build. | | studio_check_plan / studio_build | Check a plan; build it onto the canvas. | | studio_get_workflow, studio_list_workflows, studio_open_workflow | | | studio_list_templates, studio_open_template | | | studio_set_node | Change a node's fields (prompt text, model, enabled…). | | studio_run / studio_retry | Spends credits. Run the workflow; retry failed nodes. | | studio_control, studio_wait, studio_outputs, studio_logs | |

Tools that start generations say Spends in their description, so your agent — and you, approving its tool calls — can see which calls cost credits.

Watching what it does

While an agent is connected, the Queue Manager's panel and Studio's canvas show a bar naming it (Claude Code is controlling AutoFlow) with a Stop button that switches agent control off. Each extension's Agent page (the link under the switch) shows which agents are connected, this server's version and port, the settings or workflow the agent works with, marking what it changed, and every call it made with what it asked and the answer.

The agent's name is the one its MCP client gives at startup; servers before 3.0.1 do not pass it on, and the extensions say An AI agent.

Troubleshooting

• "… is not connected": switch on Let AI agents control AutoFlow in that extension. It connects within a minute (seconds if the browser is active).

• Multilogin, AdsPower or another proxied profile: add 127.0.0.1 to the profile's proxy bypass list.

• "Port 8124 is taken by something that is not an AutoFlow agent hub": an older AutoFlow MCP server is still running. Close it.

• Another port: set AUTOFLOW_AGENT_PORT for the server, and the same number as autoflow_agent_port in the extension's storage.

• An unpacked (developer) build of an extension: its id is not a store id, so the server refuses it, and autoflow_status says so with the id. Allow it in your agent's MCP config, then restart the agent:

  "autoflow": { "command": "npx", "args": ["-y", "autoflow-agent"], "env": { "AUTOFLOW_EXTENSION_IDS": "<the id autoflow_status shows>" } }

  The server never accepts an extension on its own say-so: whatever connects as AutoFlow receives your agent's prompts and the image files it sends.

Develop

npm install
npm test        # builds, then runs the hub, relay and MCP tests

Source: src/protocol.ts (the wire), src/hub.ts (the port and who may use it), src/link.ts (hub or relay), src/tools.ts (what agents see).