Skip to main content
Glama

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 public url (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:true gives a short-TTL signed scratch URL (screenshots[].scratch_url, never durable project storage). No-actions inspect includes the bounded clickable-element map. An explicit include list 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. actions clicks / fills / asserts a flow, and auth:{ "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 — a url must 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 explicit include list selects optional sections: include:["network","dom"] retains the map and adds the full per-request network table + 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:false skips 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_id call 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 steps remain accepted for older callers; new flows use the shared actions shape above.

  • url with NO project_id → capture/inspection of ANY public third-party page (e.g. { "url": "https://example.com" }), not just your own app. (When you DO pass project_id, url is scoped to that project's origin.) The screenshot comes back inline by default; store:true instead 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 when storage is set. This is render_screenshot's html niche, folded in.

  • extract:"markdown" (or include:["markdown"]) → the page as clean MARKDOWN (headings, links, lists, main content) in the markdown field, instead of vision-parsing the screenshot. The cheapest way to actually read a page's content. (The plain rendered text is always in rendered_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 returns session_id + session_expires_at; a reconnect skips the initial navigation (the page is where you left it — a goto step 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

NameRequiredDescriptionDefault
urlNoPublic 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.
authNoDrive 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.
helpNoTrue returns the full action reference, including action fields, frame targeting, and wait/eval semantics, without running a browser.
htmlNoRaw 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.
closeNoTrue 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.
stepsNoOrdered 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.
storeNoExternal 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.
widthNoFlat alias for viewport width (prefer `viewport: { width, height }`). With `html`, the snippet viewport width (default 1280).
heightNoFlat alias for viewport height (prefer `viewport: { width, height }`). With `html`, the snippet viewport height (default 800).
inlineNoInline 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.
actionsNoConcise 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.
captureNoCapture 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.
cookiesNoArray of { name, value } cookies set on the target origin before load. Same origin scoping and size cap as local_storage.
extractNoStructured 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.
headersNoFlat object of extra request headers (e.g. Authorization) sent with page requests. Same origin scoping and size cap as local_storage.
includeNoOpt-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.
storageNoProject-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/.
viewportNoLayout 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_forNoA 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_msNoExecution 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_idNoOwned 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.
screenshotNoAlternative spelling of `capture` (same fields; `format` is accepted as an alias of `as`). `capture` is the canonical name.
session_idNoOpt-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_onlyNoWhen true, dom_outline omits hidden controls. Every returned node still carries visible, plus disabled when applicable.
local_storageNoKey/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_requestsNoExpected 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_failureNoTrue continues after failed steps; false (default) aborts at the first failure while preserving captured signals.
require_existing_sessionNoWith 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.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.7/5.0
Behavior5/5

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

Beyond the annotations, the description discloses signals-first reporting, that passed reflects only step outcomes while console/page/network errors still matter, audited 1-hour impersonation, origin locking, session idle and hard caps, inline downscaling, storage behavior, and first-failure abort semantics. These are substantial behavioral details that an agent needs before invoking a non-read-only, open-world browser tool.

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

Conciseness3/5

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

The description is front-loaded and well structured with mode headings and examples, which helps for a 28-parameter tool. However, it is very long and repetitive, with marketing-style capitalization and repeated explanations of inline/storage, aliases, and actions that make it harder to scan than necessary.

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?

Given the tool's complexity, 28 parameters, and lack of an output schema, the description is complete: it explains return signals, inline versus stored artifacts, session behavior, failure reporting, and mode-specific outputs. An agent has enough context to call it correctly across inspection, capture, and action-driving scenarios.

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 100%, so the schema already documents all 28 parameters, setting a baseline of 3. The description still adds useful meaning through examples and mode interactions, such as capture as an output format, frames contact-sheet semantics, include section behavior, and the actions array shape, though some of this repeats schema text.

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?

The description states specific verbs and resources: "SEE, inspect, DRIVE and CAPTURE any web page," and explicitly positions the tool as the single capture surface replacing render_screenshot and render_pdf. It also distinguishes browser UI verification from run_code backend proof, so an agent can identify its role without opening the schema.

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

Usage Guidelines5/5

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

It gives explicit mode-based guidance: EYES without project_id for public pages, VERIFY with project_id for deployed app QA, actions for driving flows, html for isolated rendering, extract:"markdown" for reading content, and session_id for cross-call state. It also names when alternatives like run_code or the CLI are relevant, leaving little to inference.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources