Browser Session MCP

Overview Schema Source Related Servers Discussions Admin

upload_file

Attach a file to a file input or drop zone in the browser session's active tab, simulating a real user pick with input and change events. Send it by server path or base64 content.

Instructions

Attach a file in the session's active tab, as if picked in the file dialog (which can't be driven): the page gets a real File with input and change events. selector is the file input, or what stands for it on the page: an "Attach" or "Upload" button, its label or the box around it, whose hidden file input is used. An element with no file input behind it is treated as a drop zone and receives the drag and drop a person dropping the file would make. Give the file as a path the server can read, or as content (base64) with its name. Prefer path: content passes the whole file through your context. path is on the machine the server runs on, which may be a container that doesn't see your files; send content then. Up to 25 MB. Returns what received the file and whether the page then shows its name, with where the page is as for click; warns when the input's accept list doesn't take the file.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "sessionId": "<sessionId>",
      "selector": "<selector>"
    },
    "name": "upload_file"
  }
}

Input Schema

Name	Required	Description
`name`	No	The file name the page sees, such as resume.pdf. Defaults to the name in `path`.
`path`	No	A file on the machine the server runs on, instead of `content`.
`content`	No	The file's bytes as base64. Needs `name`.
`timeout`	No	Milliseconds to wait for `selector` to appear. Default 5000.
`mimeType`	No	The file's type. Default from the name's extension (application/pdf for .pdf).
`selector`	Yes	The file input, an Attach/Upload button or label for it, or a drop zone. CSS, or plain words as for click.
`sessionId`	Yes	The id returned by open_browser_session. Errors if no open session has it.

Output Schema

Name	Required	Description
`hit`	No	What was at the clicked or tapped point.
`how`	Yes	"input" when set on a file input, "drop" when dropped on an element.
`url`	Yes	The page's URL after the action.
`into`	Yes	The file input or drop zone that received it.
`name`	Yes	The file name the page received.
`bytes`	Yes
`title`	Yes	The page's title after the action.
`dialog`	No	An open dialog's text, if one is showing.
`changed`	No	A field `type` filled that the page changed once focus left it (a date that reformats or reverts on blur), with both texts.
`focused`	Yes	The element with keyboard focus, or "nothing".
`options`	No	The options of a dropdown or list open after the action (the one the focused field controls, else any showing), up to 50: pick one with select_option or click.
`answered`	No	The page's own dialogs (alert, confirm, prompt, "Leave site?") answered since the last action, each accepted.
`mimeType`	Yes
`rejected`	No	Fields the page rejected during the action, each with its message: the browser's own form check (a required field left empty), or the page marking them invalid. The form wasn't sent while any remain.
`navigated`	Yes	Whether the URL changed.
`focusTrail`	No	With press_key's `repeat`: the focused element after each press.
`pageShowsName`	Yes	Whether the file's name appears on the page after.

Schema Changelog

Changes observed during successful MCP inspections.

Addedv0.1.23Nov 13, 2026

TDQS

A4.6/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Goes well beyond the annotations: it discloses that the page receives a real File with input and change events, that an element without a backing file input is treated as a drop zone with drag-and-drop semantics, the 25 MB cap, the accept-list warning, and that it returns what received the file plus whether the page shows the name. The openWorldHint/non-idempotent annotations are consistent with this and the description adds substantive operational context on top.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Dense but front-loaded: the core action comes first, then selector resolution, then file-source choice, then limits and returns. It is a single long run-on paragraph, so a reader has to work harder than necessary, but nearly every clause carries decision-relevant information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 7-parameter mutation tool with an output schema, this covers the ambiguous cases (selector resolution, drop-zone fallback, path vs content locality, size limit, accept mismatch) that would otherwise cause failed calls. Return values are briefly summarized and the rest is left to the output schema, which is the right division of labor.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is already 100%, so the baseline is 3, but the description adds real meaning the schema lacks: `path` resolves on the server's machine (possibly a container that cannot see your files), `content` routes the whole file through the agent's context and therefore should be avoided when possible, and `name` defaults from `path`. These are the trade-offs an agent actually needs to choose between the two file sources.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a specific verb and resource ("Attach a file in the session's active tab") and immediately situates it against the native file dialog that cannot be driven, so an agent knows this is the only way to get bytes into a page. It is clearly differentiated from sibling tools like click and act.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives concrete guidance on what `selector` may be (file input, Attach/Upload button, its label, surrounding box, or bare drop zone) and how each is handled, plus an explicit preference for `path` over `content`. It does not explicitly state when to reach for this instead of e.g. click or evaluate on a file input, but the framing of the undrivable dialog covers the essential case.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.