🌊 Selenium Flow

One browser, many calls. Drive a real Chrome or Firefox on Selenium Grid from an agent over MCP — or from anything else over plain HTTP. Same actions, same server, one browser that stays exactly where you left it. 🧭

---

The whole idea, in one breath

Open a browser once. It stays alive — same page, same cookies, same scroll position — while an agent works a task one call at a time, or an n8n workflow steps node to node. Nothing relaunches, nothing logs in twice.

   agent  ──── MCP  /mcp ─────▶  ┌───────────────┐        ┌───────────────┐
                                 │ selenium-flow │ ─────▶ │ Selenium Grid │ ──▶ 🌐
workflow  ──── HTTP /browser ──▶ └───────────────┘        └───────────────┘
                                  holds no browser          the browser
                                                            lives here

This server holds no browser. The browser lives on the Grid, and with WORKSPACE_STORE=redis the record naming it does too — so the server can restart or scale to zero without anyone losing a tab. With the default in-memory store, a restart forgets which browser was whose. 🪄

---

🔀 Two surfaces, one implementation

| Surface | For | Path | |---|---|---| | MCP over Streamable HTTP | agents and MCP clients | /mcp | | JSON over HTTP | n8n HTTP nodes, curl, scripts, anything | /browser/* |

Every action is a tool and an endpoint, one to one, and a test fails the build if that stops being true. They differ in one place: screenshot hands MCP an image block a vision model can see, and HTTP a base64 payload.

GET /health and GET /openapi.yaml need no credentials.

---

🧰 Every action, both ways

Twenty actions, each a tool and an endpoint: a request body is the tool's schema, nothing added, nothing taken away.

Name your workspace on either surface: ?workspace=<name> or an Sf-Workspace header. There is no session id anywhere. See Workspaces.

| Action | Endpoint | | |---|---|---| | open_session | POST /browser | Start a browser — chrome or firefox 🚀 | | navigate | POST /browser/navigate | Go to a URL 🧭 | | interact | POST /browser/interact/{action} | Click, double-click, right-click, hover, scroll to 🖱️ | | drag | POST /browser/drag | Drag an element onto another, or by an offset 🤏 | | write | POST /browser/write | Type into a field ⌨️ | | press_key | POST /browser/press-key | Press a named key — tab, enter, arrows 🎹 | | extract | POST /browser/extract | Read text and HTML off the page 📖 | | outline | POST /browser/outline | What is on the page: a checked selector each, and what works 🗺️ | | assert | POST /browser/assert | JavaScript that must come back true, or the call fails ✅ | | screenshot | POST /browser/screenshot | Capture a PNG, viewport or full page 📸 | | print | POST /browser/print | Keep the page as a PDF or as HTML 📄 | | execute_script | POST /browser/script | Run JavaScript — the escape hatch 🧪 | | frame | POST /browser/frame | Enter and leave an iframe 🖼️ | | dialog | POST /browser/dialog | Answer a native alert, confirm or prompt 💬 | | resize | POST /browser/resize | Change the window at any time 📐 | | upload_file | POST /browser/upload | Attach a file to a file input 📎 | | save_site_data | POST /browser/save-site-data | Keep cookies and storage to restore 🍪 | | network_body | POST /browser/network-body | One captured response body 📦 | | await_control | POST /browser/await-control | Wait for a person to hand back ✋ | | end_browser | DELETE /browser | Give the slot back, keep the workspace 🧹 |

Every parameter, return field and trap worth knowing is one page per action in the wiki — generated from the live tool schemas. The same schemas are served at GET /openapi.yaml.

🦊 Chrome or Firefox

open_session(browser="firefox") and you are on Firefox; leave it out and you are on Chrome. Every other action behaves identically on both (plain W3C WebDriver), so only session creation differs.

🧠 A workspace is not a browser

The workspace outlives the sessions it holds — a session is the live browser open in it, one at a time. When the Grid reaps an idle one, or an operator ends one, the workspace keeps the page it was on and the settings its caller passed — so recovery is one call with no arguments:

open_session()      # back where you were, with the settings you chose

Workspaces expire on WORKSPACE_TTL, slid forward on every use; nothing else removes one. More in the wiki.

🧭 About that url parameter

click, write, press_key, extract, screenshot and execute_script all take an optional url, which is not an assertion: if the browser is elsewhere it goes there first, so you can jump straight to a page instead of clicking a path to it.

---

🍪 Workspaces

Every workspace is named by whoever calls, on both surfaces. Say who you are and you get the browser that belongs to that name — there is no session id in the contract, so nothing to keep or pass.

| How to name it | Looks like | Use it when | |---|---|---| | A URL parameter | …/mcp?workspace=research-bot | the usual case: one credential, each caller named in its own URL | | A header | Sf-Workspace: research-bot | an operator pins one workspace to one credential | | stdio | nothing to do | one process serves one client, and it is named stdio |

The old X- headers (X-Workspace, X-Browser, …) are refused with a 400 naming the new spelling.

Sending both is a 400: two names is two ideas about who is calling. Naming nothing is a 400 too, with a message saying how — except on the flow library, which falls back to the shared global one that everyone reads and nobody writes.

open_session always comes first. Nothing opens a browser implicitly, because that is the only place its browser, window size and timeouts are chosen.

Call again with the same name — after a reconnect, a restart, a week later — and you are back on the same browser at the same page.

⚠️ n8n opens a new MCP transport per tool call, so nothing the transport negotiates is ever the same twice. Name the workspace in the URL and it simply works.

🔑 A workspace name is an address, not a secret: the bearer token is the credential, so anyone holding it who knows your workspace's name can drive your browser.

Browser lifetime is the Grid's (SE_NODE_SESSION_TIMEOUT, 300s here); how long a workspace is remembered is WORKSPACE_TTL, slid forward on every call. Nothing runs a cleanup loop.

📍 Where am I?

workspace://current reports the workspace name, which browser it is running, the page it is on, whether a session is open at all, whether you are inside a frame, and the window size. Reading it never opens a browser.

Everything there is to read is a resource like this one, and a client whose model cannot read resources — VS Code Copilot, or anything declaring ?resources=off — gets two tools instead: list_resources and read_resource(uri).

📖 It teaches you how to use it

The server ships an Agent Skill: the strategic half tool descriptions cannot hold — how to name a workspace, why extract beats screenshot by orders of magnitude, how to reach a page in one call, and what a timeout usually means.

SKILL.md is a thin index; each reference is its own resource, so an agent loads only what its task needs:

| Resource | Holds | |---|---| | skill://selenium-flow/SKILL.md | the index: naming your workspace, the three rules, where next | | .../references/WORKSPACES.md | naming a workspace, sharing one, recovering a dead browser | | .../references/READING_PAGES.md | extract vs script vs screenshot, and durable XPath | | .../references/INTERACTION.md | forms, clicks, keys, scrolling, waiting | | .../references/TROUBLESHOOTING.md | timeouts, dead sessions, blank captures | | .../references/CONFIGURATION.md | setting the server up, which env var to change | | skill://selenium-flow/_manifest | the file listing, with sizes and hashes |

Those URIs are FastMCP's convention, served by its own SkillProvider, so list_skills and download_skill work here with no special casing.

A client that implements the MCP Skills extension also finds it through skills/list and skills/get, and can verify every file it reads.

A client that cannot read resources reads the same URIs with read_resource. MCP_SKILL=false turns the skill off.

---

🔁 Flows — do it once, run it forever

Drive a form once, save the steps under a name, and every run after that is one call:

run_flow(name="sign-up", params={"email": "a@example.com"})

A step is just a tool call, validated against the live tool schemas when it is saved — so a flow that could not run is refused before it starts. It runs in whatever browser you already hold, which means the same flow checks Chrome and then Firefox without an edit. Each workspace keeps its own library, beside a shared one called global that every workspace can run and none can change. Set DATA_DIR to turn them on; workspaces live under DATA_DIR/workspaces/<name>/.

🔐 Secrets — typed, never shown

Mount credentials as a directory per secret and a file per key — exactly how Kubernetes already mounts a Secret — and point SECRETS_DIRS at it. An agent sees the names and keys, never a value, and binds one where the value would go:

write(selector={"css": "#password"}, secret={"name": "nextcloud", "key": "password"})

The server types it; it never passes through the model, th