Installing

Installing

Connecting a client. For running the server itself, see Deployment.

Everything below needs two things: the server's URL and, if auth is on, its token. Where that token comes from is in Administration.

The URL, and what you can put on it

https://selenium.example.com/mcp

Three query parameters change how the server treats you. All are optional, and each has a header form that wins over it, so an administrator can pin a setting inside a credential and a caller cannot override it.

Parameter	Header	Does
?session=<name>	X-Session-Key	Names your saved session, so session_id becomes optional. See Sessions
?resources=off	X-MCP-Resources	Declares that you cannot read MCP resources, so the mirroring tools appear
?width=, ?height=, ?page_load_timeout=, ?script_timeout=	X-Window-Width, X-Window-Height, X-Page-Load-Timeout, X-Script-Timeout	Per-client defaults for new sessions

Prefer the query parameter when one credential is shared between callers: each names itself in its own URL. Use the header when one credential should mean one browser no matter who holds it.

Claude Code

Add it to .mcp.json in the project, or use claude mcp add:

{
  "mcpServers": {
    "selenium-flow": {
      "type": "http",
      "url": "https://selenium.example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${SELENIUM_FLOW_TOKEN}"
      }
    }
  }
}

Claude Code reads MCP resources, so session://current, session://files and the embedded skill all arrive without a tool call, and the mirroring tools stay hidden. It also renders images returned by a tool, so screenshot is directly useful there.

It does not implement MCP Apps, so session_files renders as JSON rather than a thumbnail grid. Use the signed URLs in that JSON, or the admin UI.

Claude Desktop

Same shape, in claude_desktop_config.json. Claude Desktop does implement MCP Apps, so a session_files call draws the file grid inline — though inside a collapsed tool-result panel you may need to expand.

VS Code — Copilot Chat

.vscode/mcp.json, with the token as a prompted input so it never lands in the file:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "selenium_flow_token",
      "description": "Bearer token for selenium-flow",
      "password": true
    }
  ],
  "servers": {
    "selenium-flow": {
      "type": "http",
      "url": "https://selenium.example.com/mcp",
      "headers": { "Authorization": "Bearer ${input:selenium_flow_token}" }
    }
  }
}

VS Code 1.109 and later implement MCP Apps, so the components render inline. For that to work the server needs PUBLIC_BASE_URL set — an app's iframe gets a deny-by-default CSP, and that variable is what admits the server's own images to it.

n8n

Use an MCP Client Tool node attached to an AI Agent, with an httpBearerAuth credential. Two things about n8n specifically:

• It has no notion of MCP resources. Add ?resources=off so the mirroring tools appear; without it the agent is told to read resources it cannot fetch.
• It opens a new MCP transport for every tool call. The negotiated session id is therefore never the same twice, so a saved session keyed on it can never be found. Name the session in the URL: ?session=my-agent.

http://selenium-flow.flow.svc.cluster.local:8000/mcp?resources=off&session=my-agent

Put the name in the URL, not the credential, when that credential is shared with anything else — a session key in the credential silently binds every consumer of it to one browser.

n8n cannot display an image returned by a tool, and its agent cannot see one either. Use screenshot(save=true) and put the returned link in the reply: n8n's chat renders markdown images, so ![shot](url) works.

Cursor, Goose, and other HTTP clients

Anything speaking MCP Streamable HTTP works with the URL and a bearer token. If a client cannot read resources, add ?resources=off.

No MCP at all

Every action is also a plain endpoint. See Actions for each one, and GET /openapi.yaml on a running server for the machine-readable contract — both are unauthenticated, so a client can read the contract before presenting a token.

curl -X POST https://selenium.example.com/browser/extract \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"session_id": "…", "xpath": "//h1"}'

The HTTP surface also accepts the bare token as the whole Authorization value, for clients that cannot express a scheme.

Checking it worked

curl https://selenium.example.com/health

/health needs no credentials and reports the Grid as well as the process — a server that cannot see a Grid is not actually ready, and says so with a 503.