browser
SEE, inspect, DRIVE and CAPTURE any web page — your app's EYES for perception, a VERIFY harness for QA, AND the one way to turn a page into a picture or a PDF. One call returns a structured health SIGNAL (console errors, page errors, failed network requests), not a raw image to vision-parse; a bad step or wrong shape hands back a correcting error.
This is the ONE capture surface. render_screenshot and render_pdf are aliases of this tool; everything they do lives here, and things neither could do compose freely: a full-page webp of a logged-in view saved to a path you choose, or a PDF invoice, out of the same call.
One tool, several outputs — capture: { "as": "png" | "jpeg" | "webp" | "pdf" }. Printing is an output format, not a different operation:
{ "project_id": "my-saas", "url": "https://my-saas.somewhere.site/pricing",
"capture": { "as": "webp", "full_page": true }, "storage": "/renders/pricing.webp" }{ "project_id": "my-saas", "html": "<h1>Invoice #1234</h1><p>Total: $49.99</p>",
"capture": { "as": "pdf", "paper": "A4" }, "storage": "/invoices/inv-1234.pdf" }See below the first screen, and watch it move. The default screenshot is the first screen only (the viewport). capture: { "full_page": true } captures the whole scrollable page; the frames action watches a page over a few seconds and returns ONE labelled contact sheet plus measured change:
{ "project_id": "my-saas", "capture": { "full_page": true } }{ "project_id": "my-saas", "actions": [
{ "click": "#open-menu" },
{ "frames": { "count": 6, "interval_ms": 150, "selector": "#menu" } }
] }frames takes 2–12 screenshots at fixed geometry, (count - 1) × interval_ms at most 10000 ms, and reports steps[].value.motion (from_ms, to_ms, changed_ratio between consecutive frames, measured times) and visual_change_detected, worded as "visual change detected in the sampled region" — sampled pixels neither prove an animation runs nor that none does. With selector the region is that element's box at the first frame, held fixed, and element_box reports how the element itself moved; when it moved, visual_change_detected is true and the summary says by how much, even if it left the region before the next capture. Captures in the hosted browser are spaced by their measured times (frames[].at_ms), not the requested interval_ms: each takes a few hundred milliseconds, so a 200 ms request can come back 400–700 ms apart. Directly after a click it samples at once, so a short transition is caught. An incomplete capture (deadline, element gone, navigation) fails the step with complete: false and its captured count; it never reports "no change". The sheet comes back inline (re-encoded to fit) and, with a project, stored like a screenshot.
Modes:
EYES (perception) — NO
project_id, any publicurl(e.g.{ "url": "https://example.com" }): look at / inspect / screenshot ANY page. Ephemeral output — the screenshot returns inline (auto-downscaled to fit) by default;store:truegives a short-TTL signed scratch URL (screenshots[].scratch_url, never durable project storage). No-actions inspect includes the bounded clickable-element map. An explicitincludelist selects sections;include:["network","dom"]adds the full network table and the map. No auth, no origin-lock — any public URL.VERIFY (project QA) —
project_id: drive + assert the deployed app of that project.actionsclicks / fills / asserts a flow, andauth:{ "user_id": "…" }runs it as a logged-in user (1h audited impersonation), and screenshots store durably to the project filesystem (screenshots[].fs_path). Origin-locked — aurlmust be on the project's own origin.
Same engine and the same signals-first report either way. Each completed page run also returns one accessibility_layout line for WCAG AA text contrast, horizontal overflow, and tap targets below the 24×24px WCAG 2.2 AA minimum (24–44px is listed as a note). Those findings are advisory and never change passed.
Without
actions→ a health snapshot by default: console errors, page errors, failed network requests (the 4xx/5xx + dropped calls — the real signal), the rendered page text (rendered_text— grep-able structured text beats a screenshot ~80% of the time),final_url, a small screenshot, and a bounded interactive-element map (dom_outline+ testid handles). An explicitincludelist selects optional sections:include:["network","dom"]retains the map and adds the full per-requestnetworktable + redirect chain;include:[]omits both. This is the quick "what does my app look like and is it healthy" call (it replaces a standalone screenshot). That page screenshot comes back inline as an MCP image content block by default (it renders directly in the conversation) while its file path stays in the output as the durable artifact;inline:falseskips the inline image and keeps only the path. An oversized capture on a tall/heavy page is auto-downscaled to fit inline — a no-project_idcall still returns a real image in one shot.actions→ the same concise action-sequence JSON as the CLI:{click},{fill,value},{upload,file,name?},{select,value},{wait},{expect},{screenshot},{frames},{eval}, and{goto}(a path on the app, e.g.{goto:"/club"}). Every item reports ok/fail with a reason, and the first failure stops the sequence.Existing expanded
stepsremain accepted for older callers; new flows use the sharedactionsshape above.urlwith NOproject_id→ capture/inspection of ANY public third-party page (e.g.{ "url": "https://example.com" }), not just your own app. (When you DO passproject_id,urlis scoped to that project's origin.) The screenshot comes back inline by default;store:trueinstead returns a short-lived, auto-expiring signed URL to the full-res image (screenshots[].scratch_url) — handy for a big external capture you'd rather link than inline. It's kept in an ephemeral scratch store and never touches project storage.html→ a raw HTML snippet rendered straight to an image (e.g. an OG card). No page navigation, no steps; returns the image inline, or the stored file path whenstorageis set. This is render_screenshot's html niche, folded in.extract:"markdown"(orinclude:["markdown"]) → the page as clean MARKDOWN (headings, links, lists, main content) in themarkdownfield, instead of vision-parsing the screenshot. The cheapest way to actually read a page's content. (The plain rendered text is always inrendered_text.)session_id→ ONE live browser page kept alive ACROSS calls (persistent session). Navigate in call 1; in call 2 (same session_id) wait for a 20s stream and screenshot the SAME page — cookies, current URL, and the in-flight stream all survive. The call returnssession_id+session_expires_at; a reconnect skips the initial navigation (the page is where you left it — agotostep moves). Sessions are yours only, capped per developer, and idle out after 5 min (10 min hard cap); a failed step keeps the session, and an expired one restarts signed out and says so (session_note). Omitted, it is the default fresh-per-call browser (cache-safe — a session is only for cross-call state).
With a shell: somewhere browser covers navigation, waits, evaluation, screenshots, and flow steps. This MCP tool covers clients without a shell, and cases where an inline image or result is more useful.
It checks what a UI looks like AND whether it works — clicks land, the form submits, the modal opens — and to catch the 500-ing API call a screenshot alone would hide. (run_code proves a function's backend; browser proves the rendered UI.) Signals come FIRST: passed reflects step outcomes only — console_errors / page_errors / failed_requests matter too (a 500 shows there even when every step "passes").
Elements are targeted by selector rather than pixel coordinates.
Shared action-sequence JSON (preferred; the CLI's --actions file uses this exact array):
"actions": [
{ "fill": "#email", "value": "a@b.co" },
{ "upload": "#avatar", "file": "data:image/png;base64,iVBORw0KGgo=", "name": "avatar.png" },
{ "select": "#plan", "value": "pro" },
{ "click": "button[type=submit]" },
{ "wait": ".dashboard" },
{ "expect": { "selector": ".welcome", "text": "Hi", "visible": true, "count": 1 } },
{ "screenshot": "after" },
{ "eval": "document.title" }
]Files over the 10 MB inline limit come from project files via { "upload": "#video", "fs_path": "/uploads/big.mp4" } (optional name, type; up to 50 MB per call, streamed into the page).
wait is a CSS selector string or a millisecond number. expect requires a selector and at least one of text (substring), visible (boolean), or count (exact non-negative integer); conditions may be combined. A failed action stops the sequence and names its zero-based action index.
Native alert/confirm/prompt/beforeunload dialogs are dismissed by default and listed in the report's dialogs. { "dialog": "accept" } (with "text" for a prompt) right before the action that opens one accepts it; the answer applies to the next dialog only.
Expanded steps remain runtime-compatible for older callers, but are not a
second authoring contract. actions is the form for new flows. A failed action aborts
the run while preserving console, network, and screenshot state.
Examples:
// See + inspect — screenshot, signals, and the clickable-element map, no actions:
{ "project_id": "my-saas" }// Drive a logged-in flow as a specific user (impersonation, 1h, audited):
{ "project_id": "my-saas", "auth": { "user_id": "usr_123" }, "actions": [
{ "wait": "h1" },
{ "expect": { "selector": "h1", "text": "Welcome" } }
] }Tool call template
This tool declares no required parameters. Add optional parameters from the input schema as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {},
"name": "browser"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| url | No | Public HTTP/HTTPS page URL; private networks are refused. Without project_id, external public URLs support inspection and screenshots only. With project_id, navigation and action targets must stay on an authorized origin owned by that project. Normal external assets and API requests made by the owned app remain available under backend policy. A *.somewhere.site URL resolves to the owned project automatically. | |
| auth | No | Drive as a logged-in user: { "user_id": "..." }. Mints a 1-hour impersonation session for that app user (audited) and injects it before navigation. Requires a project. Ignored when `html` is set. | |
| help | No | True returns the full action reference, including action fields, frame targeting, and wait/eval semantics, without running a browser. | |
| html | No | Raw HTML to render straight to an image (up to 1MB), instead of navigating a url. No steps/auth/DOM-map — just the rendered picture (e.g. an OG card). Returns the image inline (base64), or the stored file path when `storage` is set (storage requires project_id). Honours the full `capture` bag — including `as: "pdf"` (an invoice/receipt/certificate from an HTML string), `full_page` and `quality` — plus width/height/wait_for. An html snippet has no origin, so steps, auth and cookies do not apply to it. | |
| close | No | True closes the named session instead of running a browser. For a project session, project_id must match the opening project; url, steps and other options are not accepted. A session opened without a project closes with session_id alone. | |
| steps | No | Ordered step objects requiring project_id and a project-owned navigation origin. Each step has an action plus its fields; `frame` targets an iframe. An omitted or empty array performs inspection without driving. Ignored when html is set. | |
| store | No | External inspection without project_id only. True stores the full-resolution screenshot in ephemeral scratch storage and returns a short-lived signed URL instead of inline base64. It never uses project storage. With project_id this field is ignored because screenshots save to project files. Default false. | |
| width | No | Flat alias for viewport width (prefer `viewport: { width, height }`). With `html`, the snippet viewport width (default 1280). | |
| height | No | Flat alias for viewport height (prefer `viewport: { width, height }`). With `html`, the snippet viewport height (default 800). | |
| inline | No | Inline MCP image output, default true. Page/steps mode inlines the final page shot and each frames contact sheet (re-encoded to fit); step screenshots remain stored paths. Html mode inlines the rendered snippet. The durable file path remains in output. Images above about 750KB are not inlined; false disables inline image output. | |
| actions | No | Concise action sequence requiring project_id and a project-owned navigation origin. Each item has one action key: {click:selector}, {fill:selector,value}, {upload:selector,file:data-url-or-base64,name?} or {upload:selector,fs_path:"/stored/file",name?,type?} (a project file up to 50 MB per call), {select:selector,value}, {wait:selector|ms}, {expect:{selector,text?|value?|visible?|count?}}, {screenshot:label}, {frames:{count:2-12,interval_ms,selector?}} (one contact sheet + measured motion), {eval:js}, or {goto:"/path"} (a path on the app; a continued session_id resumes on the page it left, and goto navigates from there). The CLI additionally resolves a local path in upload.file before calling the hosted API. Execution stops on the first failure, and every result includes ok plus an error reason when false. | |
| capture | No | Capture configuration. `as` is png, jpeg, webp, or pdf; `full_page` covers the scrollable page (the default is the first screen only: { "full_page": true } shows the rest); `width` is output width (default 800) and does not change layout; `quality` is 1–100 for jpeg/webp (default 70). PDF fields are `paper`, `landscape`, and `print_background`. It applies to no-steps capture and screenshot steps. | |
| cookies | No | Array of { name, value } cookies set on the target origin before load. Same origin scoping and size cap as local_storage. | |
| extract | No | Structured extraction shortcut for a no-steps inspect call (same as include:["markdown"]). "markdown" (or true) → return the page as clean MARKDOWN in the `markdown` field — headings, links, lists, emphasis, main content only — the cheapest way to READ a page vs vision-parsing a screenshot or grepping rendered_text. "text" is a no-op (the plain rendered text is already returned as `rendered_text`). Bounded. | |
| headers | No | Flat object of extra request headers (e.g. Authorization) sent with page requests. Same origin scoping and size cap as local_storage. | |
| include | No | Opt-in heavy sections for a no-steps inspect call. Values: "network" (full request table and redirect chain), "dom" (interactive-element outline and testid handles), and "markdown" (clean page structure). Example: ["network","dom","markdown"]. console_errors, page_errors, failed_requests, and rendered_text are always returned. On a steps run, "dom" describes the final page; "network" and "markdown" apply to no-steps inspection. | |
| storage | No | Project-file path for the final capture, requiring project_id, e.g. "/renders/hero.webp" or "/invoices/inv-1234.pdf". It works with URL capture, html rendering, and steps; the response includes the stored path. Without it, the image is inline. Screenshot steps retain their own labelled files under /_browser_tests/. | |
| viewport | No | Layout viewport geometry: 'desktop' (1280×800, default), 'mobile' (390×844), or { "width": 1600, "height": 1200 } within width 100–3840 and height 100–2160. This controls page layout; `capture.width` only shrinks the output image. | |
| wait_for | No | A wait to satisfy BEFORE the capture. A CSS selector string, or ANY wait_for condition object: { "selector": "#status", "contains": "Ready" }, { "text": "All loaded" }, { "text_gone": "Loading…" }, { "settled": true }, { "network_idle": true }, { "url": "/dashboard" }, { "predicate": "window.__ready === true" } — with optional `timeout` / `idle_ms` / `frame`. Same condition engine as a wait_for step, so a rich wait composes with `storage` in one call. It applies to a run without steps; on a `steps` run a wait_for step waits at its position in the sequence. | |
| budget_ms | No | Execution cap for the whole run in milliseconds (10000–180000, default 60000). An action starts only if its own deadline fits in what is left; otherwise the run stops with `incomplete` and the remaining steps are reported `ran: false` (never passed, never retried). | |
| project_id | No | Owned project authority (UUID, subdomain, slug, or 'default'). It opens the deployed root by default and is required for actions, steps, eval, auth, session seeding, persistent sessions, and project-file screenshots. Without it, a public external URL supports inspection and screenshots only; html supports isolated rendering. | |
| screenshot | No | Alternative spelling of `capture` (same fields; `format` is accepted as an alias of `as`). `capture` is the canonical name. | |
| session_id | No | Opt-in persistent-session handle requiring project_id and a project-owned origin (1–64 letters, digits, dots, dashes, or underscores). Reusing it reconnects to one live page with cookies, current URL, and in-flight requests preserved. The first call returns session_id and session_expires_at; reconnect skips initial navigation. Sessions belong to the authenticated account and to the project they were opened for: the same name in another project is a different session. Live sessions count against one plan limit shared by all of the account's projects; they idle out after 5 minutes and have a 10-minute hard cap. A project session closes with { project_id, session_id, close: true }. Omission creates a fresh browser for every call. | |
| visible_only | No | When true, dom_outline omits hidden controls. Every returned node still carries visible, plus disabled when applicable. | |
| local_storage | No | Key/value localStorage session seed requiring url, project_id, and a project-owned origin. The standard auth client uses "sw_auth". Values are never logged. local_storage, cookies, and headers share an 8KB cap. Backend origin policy governs their delivery to owned-app requests and frames. | |
| expect_requests | No | Expected request outcomes. An observed matching path and status is a PASS and is excluded from failed_requests and failed-resource console errors. A different 4xx/5xx or a missing expected request still fails. | |
| continue_on_failure | No | True continues after failed steps; false (default) aborts at the first failure while preserving captured signals. | |
| require_existing_session | No | With session_id: continue ONLY the live session and its recorded page. A missing, expired or lost session is refused with 409 SESSION_EXPIRED / SESSION_TARGET_LOST before anything starts; nothing is launched, seeded or navigated. Not allowed with auth, cookies, local_storage or headers. |