Repository navigation
surfaces
An action is reached three ways: as an MCP tool on /mcp, as a JSON route, and as a step of a
flow. This area holds what a client can rely on at that edge: the table every action is declared
in, the headers and parameters the server reads, how tools and resources are listed for the caller,
the HTTP routes and the OpenAPI document, show, and how one request gets one answer.
- A script drives a browser over HTTP with a tool's arguments and gets its answer.
- A client that cannot read resources is given two tools that read them; one that renders MCP Apps
is given
show. - A Claude.ai connector, limited to allowlisted headers, names its workspace with
X-Workspace.
SURF-1. Naming a workspace, workspace://, session:// and moved URIs are in
workspaces-and-sessions.md. The credential a route accepts is in
auth-and-roles.md. What an action does is in
browser-actions.md, the flow document in saved-flows.md,
the scrub in secrets-and-scope.md, the admin API and the app shell's
drawing in admin-ui.md, the skill and prompts in plugin.md.
SURF-2. Every browser action is one row of core.capabilities.CAPABILITIES: its name (the
tool, a flow step's tool and the OpenAPI operationId), the Actions method that does it, its
route and http_method, its MCP annotations, its response schema, and the flags in_path,
reshapes, library_arg, visibility, closed, under_control and waits. A duplicate name,
or route and method, stops the import.
SURF-3. The rows are open_session, end_browser, navigate, interact, drag, write,
press_key, extract, execute_script, assert, outline, screenshot, frame, resize,
dialog, upload_file, print, save_site_data, network_body and await_control.
SURF-4. A row declares its route and method, never derived from its name:
press_key is POST /browser/press-key, execute_script is POST /browser/script and
upload_file is POST /browser/upload. Every row is a POST except end_browser, which is
DELETE /browser; open_session is POST /browser. interact takes its gesture in the path,
/browser/interact/{action}.
SURF-5. mcp/tools.py declares one tool per row, which supplies its name, annotations and
body; a row with no declaration stops the server at registration. A tool's signature is its input
schema, which forbids additional properties, and its docstring is its description.
SURF-6. extract, outline, screenshot, print, network_body and await_control have
under_control answers; every other row is refused, a 409 while a person holds the browser
(live-view-and-control.md). Workspaces.act asks a row's closed
method first when the workspace has no session: network_body uses it, so a body that went with
the browser is a 404, not a "no session" 400.
SURF-7. Every tool carries a title and the four hints, built by core.annotations.hints or
reads. Which tool carries which is PROT-23 to PROT-26.
SURF-8. The MCP and REST edges read these, and the server sets no CORS headers.
| Header | Query | Read for |
|---|---|---|
Sf-Workspace, X-Workspace
|
workspace |
The workspace (SURF-9) |
Sf-Browser, Sf-Version
|
browser, version
|
Default browser and version |
Sf-Window-Width, Sf-Window-Height
|
width, height
|
Default window |
Sf-Page-Load-Timeout, Sf-Script-Timeout
|
page_load_timeout, script_timeout
|
Default timeouts |
X-MCP-Resources |
resources |
Whether the caller reads resources (SURF-13) |
Authorization |
The credential (auth-and-roles.md) | |
Content-Type, Content-Length
|
Reading a body (SURF-35) |
A header name is matched in any case, a query name exactly. Caller.from_request reads them once
at the edge.
SURF-9. X-Workspace is an alias of Sf-Workspace, kept because some clients cannot send
the Sf- name. WS-1 and WS-2 say how it is read.
SURF-10. No other X- name is an alias. Six X- names are retired: X-Browser,
X-Version, X-Window-Width, X-Window-Height, X-Page-Load-Timeout and X-Script-Timeout. A
request carrying one with a non-blank value is refused, even beside the new name, and the refusal
replaces the workspace name. It reads "X-Browser is now Sf-Browser: rename the header", one
clause per header, joined with "; ".
SURF-11. The refusals of naming (SURF-10, BOTH, an unnamed request, a malformed name) are
raised when something asks for the name, as WS-2 says. X-Session-Key and ?session= are read
nowhere (WS-4).
SURF-12. The six defaults follow SET-3 to SET-6: the header wins over its query parameter, and a value that cannot be used is ignored with a log warning, never refused. What a default does at an open is in session-settings.md.
SURF-13. The header X-MCP-Resources (or ?resources= when the header is absent or empty)
says whether the caller reads resources: off for a value (trimmed, any case) of off, false,
0, no or none, on for any other (clients.reads_resources). With neither sent, a client whose
clientInfo.name starts with "Visual Studio Code" is off and every other client, including one
that cannot be identified, is on. The name comes from initialize, or from the request's _meta
key io.modelcontextprotocol/clientInfo.
SURF-14. Every sentence the server writes that names a workspace header names Sf-Workspace
(UNNAMED, BOTH, the instructions, the OpenAPI parameter). That parameter and workspace are on
every operation but the probes; X-Workspace appears only in Sf-Workspace's description.
SURF-15. MCP is served at {prefix}/mcp over HTTP and over stdio, where the caller is named
stdio. The tools are the twenty rows of SURF-3 plus keep_file, save_flow, run_flow,
delete_flow, show, list_resources and read_resource. The list varies by caller in two
ways, in mirror.HideMirrors: the last two are listed only to a client that does not read
resources (SURF-13), and show only to a client that declares the MCP Apps extension when
mcp.apps is on and the shell is built. A hidden tool stays callable.
SURF-16. Resources, templates and prompts are listed the same to every caller. A section
that is switched off still lists its resources and answers a read with the reason. The schemes:
workspace:// (current, site-data and its {site}, console, network and its {id} with
the ?level, ?filter and ?pages forms, files with its folders and items), session://
(downloads), flow:// (flows, flows/{name}, schema), secret://secrets,
skill://selenium-flow/... and ui://selenium-flow/component, which is listed only when apps are
on. Each is specified in the area that owns its data.
SURF-17. list_resources returns a row per resource (uri, name, description,
mime_type) and per template (uri_template, name, description), without ui://.
read_resource(uri) refuses a moved URI with its new spelling and refuses ui://; for a URI with
no resource it names every template. It reads through FastMCP.read_resource, so the scrub applies
as it does to a client's own reads.
SURF-18. read_resource returns text as text, and a binary body as text when its type is
text/* or SVG and it decodes as UTF-8. PNG, JPEG, GIF and WebP come back as an image block. Any
other binary is described as {uri, mime_type, bytes, binary: true, read}, where read points at
the folder listing that holds the file's link.
SURF-19. The handshake's instructions are fitted to the client and described in PROT-28 to PROT-31.
SURF-20. A closed set in a tool's schema (mouse, dialog and frame actions, print format,
browser) is an enum accepted in any case, and a blank browser means unset. A call refused for its
arguments is answered <tool> refused its arguments: <problem>, with a bullet per problem when
there are several. The problems come from flows.document.argument_problems, so a flow step and a
call are refused in the same words.
SURF-21. A failed call is answered Error calling tool '<name>': <message>, and a failed
read Error reading resource '<uri>': <message>. How the message is made, the MCP error codes of
a read and what is logged are ERR-13, ERR-14 and ERR-31.
SURF-22. A screenshot over MCP is an image block with a structured part holding what the
screenshot's response declares beside the capture (file, file_error, site_data, reopened,
page, flows_here), each only when present. Over HTTP the capture is base64 in image.
SURF-23. The middleware runs outermost first: HideMirrors, InstructionsFor, Carry,
control.Notices, failures.Explained, the resource scrub. A control notice follows the sentence
Explained wrote, and a scrub failure's fixed sentence passes through Explained unchanged.
SURF-24. run_flow sends notifications/progress to a client that put a progressToken on the
call, so a long run stays alive: when the step changes (looked at every 0.5 s) and every 15 s
within a step, with a rising value and the message step n/total: summary. A client without a
token gets none, a lost notification does not fail the run, and cancelling the call stops it.
POST /flows/{name}/runs answers once.
SURF-25. completion/complete answers for the {name} of flow://flows/{name},
workspace://files/{name}, workspace://files/screenshots/{name} and session://downloads/{name},
and for the flow argument of the repair_flow prompt. Candidates are the names in the matching
listing as the caller reads it, filtered by a case-insensitive substring.
SURF-26. show(uri) draws one resource in a client that renders MCP Apps, and has no HTTP
route. Its description names the workspace://, session://, flow://, secret:// and
skill:// schemes. It carries the app declaration with resource_uri
ui://selenium-flow/component, visibility model and app (so the app can call it to drill
down), and a policy allowing the origin of public_base_url for resources, connections and
frames. With apps off, or no built shell, it is not listed and answers with the same data.
SURF-27. mcp.show.VIEWS ties each URI form to the component that draws it. A URI is matched
whole and the first row wins, so a folder precedes its {name} row. Every URI form the server
serves has a row except ui://: context, sites, site, files, folder, file, flows,
flow, document (the flow schema and the skill's files), console, network, request and
secrets. A URI with no row, or one that has moved, is refused with "<uri> has no view; show
draws" and every form.
SURF-28. The result is structured content {component, uri, data} and one line for the model,
Showing <uri> to the person (<component>)., or Showing <uri> to the person: <n> <noun>. for
files, folder, flows, secrets, console and network. data is the resource as
FastMCP.read_resource returns it: markdown as its text, JSON parsed, any other UTF-8 text as one
fenced block so a YAML comment is not a heading. A body that is not UTF-8 is refused ("is not a
resource show can draw"), as is a URI with no resource.
SURF-29. A single file (workspace://files/{name}, a screenshot or recording item, a download
item) is drawn from its folder's listing entry, found by the unquoted last segment, never from its
bytes. A name the listing lacks is refused naming the listing. For console and network data
keeps the newest rows that fit, at most 200, and count is unchanged.
SURF-30. A result whose content and structured part together pass 100,000 characters is
refused: "<uri> is too large to draw here (n characters); read it with the resource instead".
show never opens a browser.
SURF-31. ROUTE_PREFIX is trimmed of slashes and becomes one path segment, or nothing for /
or empty. Every route hangs under it: /mcp, /browser, /flows, /schemas/flow, /files,
/secrets, /site-data, /admin, the signed file routes and /openapi.*. Only the four probes
also answer at the root.
SURF-32. The routes and the rule that governs each. The route-by-route reference is the OpenAPI document (SURF-36).
| Routes | Rule |
|---|---|
POST, DELETE, GET /browser; /browser/<route> per row |
One browser resource, addressed by naming yourself; GET /browser/downloads lists the session's downloads |
GET /flows, GET/PUT/DELETE /flows/{name}, POST /flows/{name}/runs, GET /schemas/flow
|
An unnamed caller reads the shared library |
GET /files, /files/screenshots, /files/recordings, PUT /files/{folder}/{name}/kept, GET /site-data[/{site}]
|
A workspace's files and saved sites, scrubbed |
GET /secrets |
The catalogue, never a value |
/health, /started, /ready, /info, /openapi.yaml, /openapi.json
|
Open to anyone |
/admin/*, /, the signed file routes |
admin-ui.md, workspace-files.md |
The console and network listings are MCP resources and admin routes, with no route of their own.
SURF-33. A workspace is never a path segment or a body field outside /admin. A browser
action's route drops unknown body fields rather than refusing them, session_id and the argument a
row marks library_arg among them (only a flow run sets that one). secret is accepted on write
alone, through secrets.perform_write; read_back never. GET /browser answers the data of
workspace://current with named_by request, and principal admin when a token is set.
SURF-34. The four probes, /health, /started, /ready and /info, are RUN-7.
SURF-35. A body is JSON or multipart/form-data. A JSON body over 1 MiB, or an upload over 64
MiB, is a 413 naming the cap, counted as it arrives. A file part becomes content and filename,
and an explicit filename field wins. An absent or unparseable JSON body reads as {}. A body
that is not an object is a 400, "body must be a JSON object".
SURF-36. /openapi.yaml and /openapi.json are OpenAPI 3.1, need no token, and are built
once on first request by spec.build_spec. The committed snapshot is tests/golden/openapi.json,
and scripts/generate_openapi.py writes the untracked openapi.yaml in the repository root.
- The document is built from
get_tool, not a listing, so it describes the surface and not one client's view. - Its
serversare/, the server the document was fetched from, thenhttp://localhost:8000. Every path carries the mount prefix. - An operation's summary and description are its tool's description, its request schema is the tool's input schema with nested models hoisted into components, and its response is the row's.
- Each operation carries
x-mcp-toolorx-mcp-resourcenaming its MCP counterpart, and error responses by what the caller should do (ERR-2). - With a token every operation but the probes declares
bearerAuth. - Tags are
browser,flows,files,secretsandops.
SURF-37. http.answer.answer answers the browser, flows, files and site-data trees. In order it
checks the token (401 {"error": "unauthorized"}), reads the body, reads the caller (the admin
principal when a token is set), requires a name unless the tree is flows, and runs the call: a
synchronous one in a worker thread so a long wait stalls nothing else, a coroutine on the loop.
GET /secrets repeats these steps by hand without reading a body.
SURF-38. Starlette's trailing-slash redirect is made relative, so a path behind an ingress that strips a prefix still resolves; only a 307 to the same path with one slash added or removed is rewritten. The access log is ERR-29.
SURF-39. Every capability is a tool and a route from one row. A call on any surface goes through
Workspaces.act with its surface (mcp, http or flow), so resolving the browser, reopening
a reaped one, the turn, the scrub and the record update are one code path
(workspaces-and-sessions.md, WS-19).
SURF-40. A failure's text is made by faults.message (ERR-14). Only the reopen note and the
page note follow it (ERR-16).
SURF-41. errors.status_for is the one decision of what a failure means, for every surface.
The statuses, the causes and the order are ERR-2, ERR-3, ERR-5 and ERR-7.
SURF-42. Over HTTP a failure is {"error": <text>} with its status (ERR-11). What is logged
at which status is ERR-31.
SURF-43. The surfaces differ in these ways only: the screenshot's result (SURF-22); an HTTP
body drops unknown fields where a tool refuses them (SURF-33); show, the mirror tools, the
instructions, progress and completions exist over MCP only; the probes, the OpenAPI document and
the admin API exist over HTTP only.
SURF-44. test_surfaces holds that every row is a tool and a route, test_openapi and
test_routes that the document describes the routes served, test_show_inventory that every
resource has a view, and test_golden the shapes under tests/golden/ and that a tool and its
endpoint answer alike. A golden changes only with the contract.
Not built. The reasoning, and the questions still open, are in the multiplayer design.
SURF-45. (proposed) SURF-8's table gains the header and the query parameter that pin a
connection to a session (WS-50). If the parameter is ?session=, this replaces SURF-11's
"?session= is read nowhere".
SURF-46. (proposed) A tool or route that acts on a session takes session, the loose name of
WS-50, on every call: a request carries nothing else that tells two callers on one connection
apart.
Not built. The reasoning, and the questions still open, are in the ownership design.
SURF-47. (proposed) tools/list leaves out every tool the caller's roles do not allow
(AUTH-54), and such a tool is refused when called. Replaces, when built, SURF-15's "The list varies
by caller in two ways" and, for a tool left out by role, "A hidden tool stays callable".
The action pages are generated from the server's tool schemas, so they describe the version that shipped.
selenium-flow · MIT
Start here
Guides
Lifecycle
Going places
Doing things
Getting things out
Site data
Console and network