Skip to content

protocol

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

Protocol

The server is an MCP server first: a client reaches every browser action, resource, prompt and app through it. The area files say what each tool and resource does. This area holds what they share: which generations of the protocol the server speaks and how it tells them apart, the stack it is built on and why its versions are held, how a call that waits runs as a task, how tools are annotated, how the instructions a client reads at connect are built, what the MCP App is, and which facts about a client change what the server shows it.

Use cases

  • A client that opens with initialize and a client that opens with server/discover both connect to /mcp, each gets instructions fitted to it, and each reads the same tools.
  • A client that supports tasks calls await_control and polls it, while one that does not gets a call that returns after a cap and says to call again.
  • A client reads readOnlyHint and destructiveHint to decide whether to ask its user first.
  • A host that renders MCP Apps is offered show; any other client never sees it.
  • An engineer moves the server to a new FastMCP major and a contract test names the assumption that broke.

Neighbours

PROT-1. How tools, resources and prompts are listed and shaped per caller, the headers and parameters that name a workspace or switch resources off, and the show result are in surfaces.md (SURF-8 to SURF-30). The skill, the prompts and the Skills and agents extensions are in plugin.md. The wait itself, await_control, is in live-view-and-control.md (LIVE-28 to LIVE-34). Failures and their wording are in errors-and-logging.md. Startup, shutdown and the concurrency map are in runtime.md, and the Grid contract is in grid.md.

Two generations of the protocol

PROT-2. The server answers two generations of MCP on one endpoint, {prefix}/mcp. A client of the older generation (the 2025 revisions) opens with initialize, and the server holds what the client said in the transport session. A client of the 2026-07-28 generation opens with server/discover, has no handshake, and puts its identity in the _meta of every request. The server does not pick a mode: it reads the places each generation uses.

PROT-3. A client's name is its clientInfo.name. It is read first from the request's _meta key io.modelcontextprotocol/clientInfo, and when that is absent from the initialize record the transport session holds. It is the empty string when neither says, and the lookup never raises: a client that cannot be named is in no table.

PROT-4. The two handshake messages, initialize and server/discover, are answered before a session can hold a name. The name for those two is read from the message itself: params.clientInfo for initialize, _meta for server/discover.

PROT-5. The extensions in play, each named by its identifier:

Identifier Declared by Where it is specified
io.modelcontextprotocol/skills The server, with skills/list and skills/get PLG-17
io.modelcontextprotocol/agents The server, with agents/list and agents/get PLG-31
io.modelcontextprotocol/tasks The tasks extension, which carries long calls PROT-11 to PROT-20
io.modelcontextprotocol/ui The client, when it renders MCP Apps PROT-32 to PROT-35

PROT-6. FastMCP declares a registered extension in the server/discover result and leaves it out of the initialize result. The server adds the skills and agents extensions to initialize in middleware, so a client of the older generation learns the methods exist. The two methods of each answer any caller.

PROT-7. Over stdio the same server answers, no request headers exist, and the caller is named stdio (SURF-15).

The stack

PROT-8. The server is one FastMCP application named Selenium, built on FastMCP 4 with its tasks extra and on the mcp package 2. Both are declared with an upper bound below the next major: fastmcp[tasks]>=4.1.4,<5 and mcp>=2.0,<3.

PROT-9. The bounds are held because the server rests on behaviour the libraries do not document. What it takes from FastMCP:

It relies on Used for
Middleware hooks for a tool call, a resource read, a tool listing, initialize and server/discover Instructions per client, the workspace carried to a task, control notices, failure wording, the scrub of reads, the hidden tools
Extensions registered on the server Skills, agents and tasks
A tool's annotations, app and task options PROT-21 to PROT-27, PROT-32, PROT-11
A context that says whether the client supports an extension, whether the call is a background task, and reports progress PROT-33, PROT-13, PROT-15
A failed tool call raised as a ToolError and a failed read as a ResourceError or NotFoundError, wrapping the original as the cause ERR-13

PROT-10. tests/test_tasks_contract.py states each assumption about tasks against a toy server, so an upgrade that changes one fails there by name: a tasked call returns the task stub to middleware; a client of the older generation runs the tool inline; the worker has the submission's headers and no request; the worker runs on the server's loop; the tool's result survives tasks/get; the poll interval is one second; cancelling reaches the waiting tool; a task on a sync function is refused.

Long-running calls as tasks

PROT-11. One tool may run as an MCP task: await_control. run_flow is not a task. It stays a single call and reports progress while it runs (SURF-24).

PROT-12. The tool's task mode is optional with a poll interval of one second, which a client that submits a task is told in the task's creation result.

PROT-13. A call runs as a task only when the client asks for one. A client of the older generation never does, and a client of the newer generation that does not ask gets the same blocking call. A client that asks gets a task and polls it with tasks/get.

PROT-14. The blocking call ends by itself after live.await_cap seconds and says to call again (LIVE-34). In a task there is no cap: the work answers when the person hands back, when the workspace's browser ends, when the server stops, or when the task is cancelled.

PROT-15. A waiting call sends a progress notification at once and every 15 seconds after, each with a value strictly greater than the one before. The message is the tool's own sentence. In a task it is the status message tasks/get reads. A client that sent no progressToken gets none, and a notification that fails to send is logged at DEBUG and does not fail the call.

PROT-16. A tool that may run as a task is declared async, because FastMCP refuses a task on a sync function when the tool is registered. The browser actions, open_session, end_browser, keep_file and delete_flow are sync. save_flow, run_flow, show, list_resources, read_resource and await_control are async.

PROT-17. A task's worker has no request, only a snapshot of the submission's headers, so ?workspace= never reaches it. The Carry middleware writes the caller's workspace into the private header sf-carried-workspace as the call is submitted, for a tool whose own task config allows tasks. The worker names the workspace from that header alone.

PROT-18. On every HTTP call, a sf-carried-workspace header the client sent is removed. A task's worker ignores the snapshot's Sf-Workspace and X-Workspace. A request that names no workspace, or names it twice or in a malformed way, is refused at submission in the words the tool would use (Error calling tool '<name>': <message>), because the worker could not say why.

PROT-19. Tasks run on Docket, which the server pins to memory:// in code. A stray FASTMCP_DOCKET_URL cannot move it. A task lives in process memory and is lost with the process.

PROT-20. Docket's worker waits for the tasks it runs when it stops. A waiter nobody releases would hold that stop for ever. FastMCP enters the server's lifespan first and the extensions' after, so it leaves the extensions first. The server's tasks extension therefore calls the controls' stop, which releases every pending grant and every waiter, before its worker stops. The server's own lifespan calls it again and finds nothing. The rest of shutdown is in runtime.md.

Tool annotations

PROT-21. Every tool the server lists declares a display title and the four hints read_only_hint, destructive_hint, idempotent_hint and open_world_hint. MCP's defaults are read-only false and destructive true, so a tool without annotations is presented as the most dangerous on the server. test_surfaces checks every listed tool, with resources on and off, because the switch changes the list.

PROT-22. The hints are advisory: a client uses them to decide how to present a tool and whether to ask its user. They are never a security boundary, and each is declared honestly.

PROT-23. A tool is read-only only when it changes nothing and hands the page no instruction. The tools are extract, outline, network_body, await_control, list_resources, read_resource and show. screenshot and print are not, because each writes a file into the workspace. A tool cannot be read-only only sometimes.

PROT-24. A tool is destructive wherever it hands the page an instruction the page is free to interpret, because a click or a keypress can place an order and the server cannot tell which. These are interact, drag, press_key, dialog, execute_script and assert. Four more are destructive for what they do to the server's own state: open_session, end_browser, keep_file and delete_flow. run_flow is destructive because its steps are.

PROT-25. A tool is idempotent when repeating the same call leaves the same state: navigate, frame, resize, save_site_data, save_flow, delete_flow, end_browser, the read-only tools above, and no other.

PROT-26. A tool is open-world when it reaches a browser or the Grid. Every tool is, except list_resources, which answers from the server's own registry.

PROT-27. The exact hints of every tool are in tests/golden/tools-on.json and tools-off.json. A capability row may also declare a visibility: network_body is visible to the model and to an app, so an MCP App can call it.

The instructions

PROT-28. The handshake result carries an instructions string. The server builds it from a fixed text and up to two further paragraphs. The fixed text says:

  • what the server is: a real Chrome or Firefox browser on a Selenium Grid that stays alive between calls;
  • to name the workspace first, with ?workspace=<name> or an Sf-Workspace header, and that no call takes a session id;
  • the lifecycle: open_session first, then the other tools, then end_browser, including after a failure;
  • that a selector is {"xpath": ...} or {"css": ...}, one and never both;
  • that url is optional on most actions and navigates first when the browser is elsewhere;
  • to prefer extract to read a page and use execute_script for what the tools do not cover.

PROT-29. A client whose model cannot read resources (SURF-13) gets a paragraph saying that everything the server has to read is a URI, how read_resource(uri) reads one and that list_resources lists them. When the skill is served, a paragraph points at skill://selenium-flow/SKILL.md and asks the client to read it before its first call, "with read_resource" for the client that cannot read resources (PLG-58, PLG-59).

PROT-30. The text is chosen for each initialize and each server/discover, from the client that message names (PROT-4), because one server object serves every client. The object itself starts with the text for a client it cannot tell, which is the text for a client that reads resources.

PROT-31. The instructions name only what exists. With the skill off or not loaded they carry no pointer, so no URI a client cannot read is offered. They do not mention the prompts, the agents or an extension, and they name the workspace header only as Sf-Workspace (SURF-14).

The MCP App

PROT-32. show(uri) draws one resource inside a client that can show UI (SURF-26 to SURF-30). The client draws it from the shell resource ui://selenium-flow/component, a single HTML page built from ui/ that every view shares. The server sets no media type on that resource, because FastMCP stamps ui:// resources text/html;profile=mcp-app and a plain text/html is ignored by the host.

PROT-33. show is listed only to a client that declares io.modelcontextprotocol/ui, as SURF-15 says. The ui:// resource is registered only when mcp.apps is on and the shell is built.

PROT-34. The model reads a resource with read_resource to think. show is for when it means a person to see the resource, so only show carries the app declaration.

PROT-35. An app's links are absolute and signed, because the host draws it on a sandbox origin that is not this server. public_base_url makes them resolvable, and its origin is the one the shell's policy allows for resources, connections and frames (SURF-26).

What the server asks of a client

PROT-36. The server changes its answer for a client in four ways, and in each an unknown client gets the assumption in the last column:

It asks The answer decides Assumed when it cannot tell
Whether the model reads resources (SURF-13) The mirror tools in the listing and the instructions' paragraph Yes
Whether the client declares io.modelcontextprotocol/ui show in the listing No
Whether the call asked to be a task A task or the blocking call The blocking call
Whether the call carries a progressToken Progress notifications None sent

PROT-37. The short list names only clients known not to reach a resource. Every other client is assumed complete, and one that is not says so.

PROT-38. None of these checks fails a call. A check that cannot run leaves the client with the data and costs it at most a plainer rendering.

PROT-39. The listing is filtered for each request and not at registration, so one server object is right for every client at once. A tool left out of a listing stays callable.

Failures at the protocol

PROT-40. A failed tools/call is a tool error result carrying one sentence, and a failed resources/read is the MCP error of ERR-13. skills/get answers -32602 for a URI it does not serve (PLG-21), and agents/get for an unknown agent (plugin.md).

Clone this wiki locally