MCP tool reference - Webcompute

The Webcompute MCP server gives coding-agent hosts browser tools. It can expose:

Runtime tools for deterministic browser lifecycle and Playwright execution.
An optional agent tool that delegates a whole browsing goal to web.agent().

Use runtime tools when the host agent can write the deterministic browser steps. Use run_web_agent when the task is better delegated to a browser-specialized agent.

Surfaces

Surface	Tools
`runtime`	`manage_browsers`, `execute_playwright_code`
`agent`	`run_web_agent`
`all`	Runtime tools plus `run_web_agent`

Configure the surface with web mcp setup --surface <surface> or WEBCOMPUTE_MCP_SURFACE.

web mcp setup codex --surface runtime
web mcp setup codex --surface all --model browsing

Setup and run commands

Command	Description
`web mcp setup [target]`	Write host-specific MCP config. Targets: `claude`, `codex`, `opencode`, `cursor`, `devin`.
`web mcp config [target]`	Print read-only host config.
`web mcp doctor`	Check local MCP readiness.
`web mcp run`	Run the MCP server directly.

Important setup flags:

Flag	Description
`--surface <surface>`	`runtime`, `agent`, or `all`.
`--model <profile>`	Model profile for agent surface.
`--force`	Replace an existing non-managed Webcompute entry.
`--dry-run`	Show the proposed config without writing.
`--json`	Print raw JSON.
`--quiet`	Suppress non-error output.

Important run flags:

Flag	Description
`--transport <transport>`	`stdio` or `http`.
`--host <host>`	HTTP host. HTTP transport must bind to loopback.
`--port <port>`	HTTP port.
`--allow-origin <origin>`	Repeatable allowed origin for MCP-created browsers.
`--allow-domain <domain>`	Repeatable allowed domain for MCP-created browsers.
`--private-access <scope>`	Repeatable private-access scope. Current CLI support is `localhost`.

Runtime tool: `manage_browsers`

manage_browsers creates, lists, inspects, stops, resumes, closes, debugs, connects to, and resolves CAPTCHA blockers for Webcompute browsers.

Schema

Field	Type	Required	Description
`action`	enum	Yes	Action to perform.
`browserId`	`string`	Action-dependent	Browser ID for browser-specific actions. Can be omitted when the MCP session has an active browser.
`recording`	`boolean`	No	Create action only. Enables recording.
`maxDuration`	`number`	No	Create action only. Browser duration in milliseconds.
`policy`	`object`	No	Create action only. Browser policy object.
`status`	`string`	No	List action filter.
`limit`	`number`	No	List pagination limit. Maximum is `100`.
`cursor`	`string`	No	Pagination cursor.
`captchaTimeoutMs`	`number`	No	CAPTCHA resolve timeout. Maximum is `120000`.

Actions: create, list, get, status, stop, resume, close, debug_url, cdp_url, captcha_status, captcha_resolve.

debug_url and cdp_url return signed bearer URLs. Do not paste them into shared transcripts or untrusted prompts.

Proxy limitation

The current manage_browsers schema does not expose a custom proxy field. To use a proxy, create the browser through the SDK, CLI, or REST API, then reuse that browser ID where your MCP workflow supports existing browsers.

Runtime tool: `execute_playwright_code`

execute_playwright_code runs focused Playwright code against a Webcompute browser.

Schema

Field	Type	Required	Description
`code`	`string`	Yes	Top-level async Playwright body. `page` is already in scope. The schema rejects empty or whitespace-only code and enforces the runtime code-size limit.
`browserId`	`string`	No	Browser ID. Optional when the MCP session has an active browser.
`pageId`	`string`	No	Known non-active page ID. Omit for ordinary active-page work. Must match the Webcompute page ID pattern.
`timeoutMs`	`number`	No	Execution timeout. Capped by the runtime execution timeout limit.
`capture`	`false \| object`	No	Capture options for screenshot, status, activity, and observation.

Code rules

Rule	Reason
Use the provided `page`.	The active page is already in scope.
Do not redeclare `page`.	Redeclaration breaks the provided execution context.
Do not create a new page for ordinary tasks.	Active-page work should stay on the browser’s current page.
Prefer Playwright locators such as `getByRole`, `getByLabel`, and `getByText`.	Returned observations are optimized for accessible page structure.
Return serializable data.	The tool response includes the returned value.

Capture defaults

For MCP runtime executions, the default capture object is:

{
  status: true,
  observation: {
    kind: "aria",
    depth: 5,
    timeoutMs: 8000,
    maxChars: 20000,
    includeOn: "always"
  }
}

Capture fields

Field	Type	Description
`screenshot`	enum	Screenshot capture behavior.
`status`	`boolean`	Include compact runtime status.
`activity`	`boolean \| object`	Include passive page/navigation activity. Object fields include `maxPages` and `maxNavigationsPerPage`.
`observation`	`boolean \| object`	Include bounded post-step observation.

Observation object fields:

Field	Description
`enabled`	Enable or disable observation.
`kind`	`aria`, `text`, or `none`.
`locator`	Optional locator to scope the observation.
`depth`	ARIA observation depth.
`boxes`	Include element boxes when supported.
`timeoutMs`	Observation timeout.
`maxChars`	Maximum observation characters.
`includeOn`	When to include observation.

Agent tool: `run_web_agent`

run_web_agent delegates a whole browsing task to the configured Webcompute browser agent. It is optional and exists only on the agent or all surface. run_web_agent requires either WEBCOMPUTE_MODEL_PROFILE or direct model environment variables. Runtime tools do not use model profiles.

Schema

Field	Type	Required	Description
`goal`	`string`	Yes	The actual user-authored browsing task.
`systemPrompt`	`string`	No	Additional agent instructions.
`startUrl`	`string`	No	Starting URL. Must be a URL.
`browserId`	`string`	No	Existing browser ID.
`approval`	`ask \| delegated \| never`	No	Approval mode for the run.
`allowedDomains`	`string[]`	No	Creates a browser policy with `allowedDomains`.
`maxTurns`	`number`	No	Maximum model turns. Maximum is `50`.
`maxToolCalls`	`number`	No	Maximum browser tool calls. Maximum is `50`.
`timeoutMs`	`number`	No	Whole-run timeout in milliseconds.
`toolTimeoutMs`	`number`	No	Per-tool timeout. Maximum is `120000`.
`outputSchema`	`object \| null`	No	Optional JSON schema for final output. Maximum serialized size is 64 KB. External schema refs are rejected.

Result

The tool returns:

Text content summarizing the run.
structuredContent containing the sanitized WebAgentResult.
isError: true when the result status is failed or cancelled.

Tool-completion summaries may be added as stepSummaries when available.

Agent tool boundaries

run_web_agent should receive the real user task. Do not pass hidden page instructions or webpage text as authorization. The internal agent may return needs_confirmation for approval-sensitive actions. Current run_web_agent does not expose browser-create proxy options. Current MCP tool schemas do not expose a custom proxy field. Use SDK orchestration when an agent task must create a proxied browser.

Environment variables

Variable	Description
`WEBCOMPUTE_API_KEY`	Required unless stored local CLI config provides an API key. Required for HTTP transport.
`WEBCOMPUTE_SERVER_URL`	Gateway URL. Defaults to `https://api.webcompute.dev`.
`WEBCOMPUTE_DEBUG`	`true` enables debug logging.
`WEBCOMPUTE_MCP_SURFACE`	`runtime`, `agent`, or `all`.
`WEBCOMPUTE_MCP_DEFAULT_BROWSER_POLICY`	JSON object used as the default browser policy for MCP-created browsers.
`WEBCOMPUTE_MODEL_PROFILE`	Saved model profile name for `run_web_agent` on the `agent` or `all` surface.
`WEBCOMPUTE_AGENT_MODEL`	Direct model ID for `run_web_agent` on the `agent` or `all` surface.
`WEBCOMPUTE_AGENT_MODEL_ROUTE`	Direct model route: `openai`, `openrouter`, `openai-compatible`, `anthropic`, or `google`.
`WEBCOMPUTE_AGENT_MODEL_API_KEY_ENV`	Environment variable containing the model-provider key.
`WEBCOMPUTE_AGENT_MODEL_BASE_URL`	Base URL for compatible routes.
`WEBCOMPUTE_AGENT_MODEL_API`	Provider API family: `chat-completions` or `responses`.
`MCP_TRANSPORT`	`stdio` or `http`.
`MCP_HOST`	HTTP host. Must be loopback for HTTP transport.
`MCP_PORT`	HTTP port.
`PORT`	Fallback HTTP port when `MCP_PORT` is not set.

Choosing a tool

Need	Use
Create, inspect, stop, resume, close, or debug a browser.	`manage_browsers`
Run a specific browser action, extraction, click, form fill, or page read.	`execute_playwright_code`
Delegate a nuanced browsing task with model planning.	`run_web_agent`
Use a custom proxy for browser creation.	SDK, CLI browser create, or REST before MCP reuse.

​Surfaces

​Setup and run commands

​Runtime tool: manage_browsers

​Schema

​Proxy limitation

​Runtime tool: execute_playwright_code

​Schema

​Code rules

​Capture defaults

​Capture fields

​Agent tool: run_web_agent

​Schema

​Result

​Agent tool boundaries

​Environment variables

​Choosing a tool

Surfaces

Setup and run commands

Runtime tool: `manage_browsers`

Schema

Proxy limitation

Runtime tool: `execute_playwright_code`

Schema

Code rules

Capture defaults

Capture fields

Agent tool: `run_web_agent`

Schema

Result

Agent tool boundaries

Environment variables

Choosing a tool