> ## 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 runtime mode

> Use manage_browsers and execute_playwright_code for advanced self-hosted MCP browser control.

Runtime mode is the technical default for `web mcp run`. It is model-free and
exposes low-level browser tools:

```text theme={null}
manage_browsers
execute_playwright_code
```

Use runtime mode when the parent agent or application should own each browser
step.

MCP tool schemas do not expose custom proxy creation options. Create proxied
browsers through SDK, CLI browser creation, REST, or quick actions before MCP
reuse when proxy routing is required.

## Run

```bash theme={null}
web mcp run
```

Generated configs should use CLI args for visible behavior. Runtime mode needs
no `--surface` flag because it is the default:

```json theme={null}
{
  "mcpServers": {
    "webcompute": {
      "command": "web",
      "args": ["mcp", "run"]
    }
  }
}
```

## Tool loop

```text theme={null}
1. Create or reuse a browser with manage_browsers.
2. Navigate or inspect with execute_playwright_code.
3. Read the returned result, logs, status, artifacts, and observation.
4. Run another focused browser-code snippet when needed.
5. Close browsers created for the task.
```

## Active-page contract

`execute_playwright_code` receives a top-level async browser-code body. The
`page` variable is already in scope and points at the active page.

```json theme={null}
{
  "code": "await page.goto('https://example.com'); return { title: await page.title(), url: page.url() };"
}
```

Follow these rules:

* Use the provided `page`.
* Do not redeclare `page`.
* Do not create new pages for ordinary single-page tasks.
* Omit `pageId` unless targeting a known non-active page.
* Return JSON-compatible evidence.
* Prefer `getByRole`, `getByLabel`, and `getByText` for interaction.

## Browser lifecycle

```json theme={null}
{ "action": "create", "recording": true }
```

`manage_browsers` handles create, list, get, status, stop, resume, close,
Debug UI URL, CDP URL, and CAPTCHA status actions.

<Warning>
  Debug UI and CDP URLs are signed bearer capabilities. Request them only for
  live review or external framework attachment.
</Warning>

## Exact control example

```ts theme={null}
await client.callTool({
  name: "execute_playwright_code",
  arguments: {
    code: [
      "await page.goto('https://example.com');",
      "return { title: await page.title(), url: page.url() };",
    ].join("\n"),
  },
});
```

For a complete direct MCP client example, see
`examples/mcp/runtime-direct-mcp-client.ts`.