> ## Documentation Index > Fetch the complete documentation index at: https://docs-preview.webcompute.dev/llms.txt > Use this file to discover all available pages before exploring further. # MCP tool reference > Reference Webcompute MCP surfaces, tools, prompts, CLI flags, environment fallback, and limitations. 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. | ```bash theme={null} 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 `. ## 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 ` | Host-specific scope such as `user` or `project`. | | `--surface ` | `runtime`, `agent`, or `all`. | | `--model ` | 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 ` | `stdio` or `http`. | | `--host ` | HTTP host. HTTP transport must bind to loopback. | | `--port ` | HTTP port. | | `--surface ` | `runtime`, `agent`, or `all`; flags override env. | | `--model ` | Model profile for `agent` or `all`; requires `--surface agent` or `--surface all`; flags override env. | | `--allow-origin ` | Repeatable allowed origin for MCP-created browsers. | | `--allow-domain ` | Repeatable allowed domain for MCP-created browsers. | | `--private-access ` | Repeatable private-access scope. Current CLI support is `localhost`. | Generated host configs prefer visible args: ```json theme={null} { "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: ```ts theme={null} 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. |