MCP tool reference

The Webcompute MCP server is self-hosted. Agent hosts start a local stdio process or loopback HTTP process under your credentials and configuration. Recommended product path: use agent mode as a browser subagent through run_web_agent. Technical default: web mcp run exposes runtime tools for model-free browser control.

Surfaces

Surface	Tools	Use it for
`agent`	`run_web_agent`	Delegating a whole browsing goal to Webcompute.
`runtime`	`manage_browsers`, `execute_playwright_code`	Exact browser lifecycle and browser-code control.
`all`	All three tools	Expert escape hatch for debugging and migration.

web mcp run
web mcp run --surface agent --model browsing
web mcp run --surface all --model browsing

--agent is not a supported shorthand. Use --surface agent --model <profile>.

Setup and config commands

Command	Description
`web mcp setup [target]`	Write host-specific MCP config. Targets: `claude`, `codex`, `opencode`, `cursor`, `devin`, `openclaw`, and `hermes`.
`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
`--scope <scope>`	Host-specific scope such as `user` or `project`.
`--surface <surface>`	`runtime`, `agent`, or `all`.
`--model <profile>`	Model profile for `agent` or `all` surfaces. Requires `--surface agent` or `--surface all`.
`--instructions`	Install a host-native Webcompute instruction artifact where safe.
`--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.
`--surface <surface>`	`runtime`, `agent`, or `all`; flags override env.
`--model <profile>`	Model profile for `agent` or `all`; requires `--surface agent` or `--surface all`; flags override env.
`--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`.

Generated host configs prefer visible args:

{
  "mcpServers": {
    "webcompute": {
      "command": "web",
      "args": ["mcp", "run", "--surface", "agent", "--model", "browsing"]
    }
  }
}

Instructions and prompts

Server-level MCP initialize instructions are absent or tiny to avoid prompt pollution. Use one of these explicit prompt surfaces instead:

Prompt	Purpose
`browser_agent`	Parent-agent guidance for `run_web_agent`.
`browser_runtime`	Browser lifecycle and browser-code guidance.
`browser_all`	Routing guidance when all tools are exposed.

The read-only resource webcompute://instructions/mcp is a small index, not a large prompt blob. Application code should use the SDK-owned prompt text:

import { mcpPrompt } from "@webcompute/sdk";

mcpPrompt("agent");
mcpPrompt({ surface: "agent", toolPrefix: "mcp__webcompute__" });

mcpPrompt() equals mcpPrompt("runtime").

Agent tool: `run_web_agent`

run_web_agent delegates a whole browsing task to the configured Webcompute browser-agent harness. It is exposed only on the agent or all surface. It requires a saved model profile or direct model environment variables.

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.
`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 concrete JSON Schema with a root `type`; omit it instead of sending `{}`. Maximum serialized size is `64 KiB`; external 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.

Respect needs_confirmation results. Do not ask Webcompute to handle CAPTCHA through browser code.

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. Treat them like credentials.

Runtime tool: `execute_playwright_code`

execute_playwright_code runs focused browser code against a Webcompute browser. The page variable is already in scope and points at the active page.

Schema

Field	Type	Required	Description
`code`	`string`	Yes	Top-level async browser-code body. 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.
`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 execution context.
Do not create a new page for ordinary tasks.	Active-page work should stay on the browser’s current page.
Prefer accessible 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.

Proxy limitation

MCP tool schemas do 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.

Environment variables

CLI flags are preferred for visible generated config. Environment variables remain supported for secrets, process defaults, and backward compatibility.

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`. Overridden by `web mcp run --surface`.
`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`. Overridden by `web mcp run --model`.
`WEBCOMPUTE_AGENT_MODEL`	Direct model ID for `run_web_agent`.
`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.

Get started

Build agent workflows

Observe and debug

Runtime concepts

Examples

Integrations

Production

Reference

API reference

Surfaces

Setup and config commands

Instructions and prompts

Agent tool: `run_web_agent`

Schema

Result

Runtime tool: `manage_browsers`

Schema

Runtime tool: `execute_playwright_code`

Schema

Code rules

Proxy limitation

Environment variables

​Surfaces

​Setup and config commands

​Instructions and prompts

​Agent tool: run_web_agent

​Schema

​Result

​Runtime tool: manage_browsers

​Schema

​Runtime tool: execute_playwright_code

​Schema

​Code rules

​Proxy limitation

​Environment variables

Surfaces

Setup and config commands

Instructions and prompts

Agent tool: `run_web_agent`

Schema

Result

Runtime tool: `manage_browsers`

Schema

Runtime tool: `execute_playwright_code`

Schema

Code rules

Proxy limitation

Environment variables