Skip to content

surfaces

Dr K edited this page Nov 14, 2026 · 3 revisions

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.

Use cases

  • 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.

Neighbours

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.

The capability table

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.

Headers and parameters

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.

The MCP surface

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.

show

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.

The HTTP surface

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 servers are /, the server the document was fetched from, then http://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-tool or x-mcp-resource naming 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, secrets and ops.

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.

One answer on every surface

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.

Proposed: several sessions in a workspace

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.

Proposed: ownership and roles

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".

Clone this wiki locally