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

> Delegate whole browsing goals to Webcompute through run_web_agent on the self-hosted MCP server.

Agent mode gives the parent agent one browser-specialist tool:

```text theme={null}
run_web_agent
```

Use this when the user has a browsing goal, not a step-by-step browser script.
The Webcompute browser-agent harness owns page observation, browser-code
planning, blockers, approvals, and final output.

## Setup

```bash theme={null}
web model setup --name browsing
web mcp setup claude --surface agent --model browsing --instructions
```

For a code-first framework, start the same self-hosted server from code:

```ts theme={null}
const server = {
  command: "web",
  args: ["mcp", "run", "--surface", "agent", "--model", "browsing"],
};
```

## Parent-agent guidance

Use SDK-owned instructions instead of copying prompt text into docs or config:

```ts theme={null}
import { mcpPrompt } from "@webcompute/sdk";

const instructions = [
  "You answer research questions. Delegate browser tasks to Webcompute.",
  mcpPrompt("agent"),
].join("\n\n");
```

Some MCP hosts prefix tool names. Use `toolPrefix` when the host exposes names
such as `mcp__webcompute__run_web_agent`:

```ts theme={null}
mcpPrompt({ surface: "agent", toolPrefix: "mcp__webcompute__" });
```

## Tool input

```json theme={null}
{
  "goal": "Find Apple's latest 10-K on sec.gov. Return the filing URL and three risk-factor themes with citations.",
  "startUrl": "https://www.sec.gov/",
  "allowedDomains": ["sec.gov"],
  "approval": "ask",
  "outputSchema": {
    "type": "object",
    "properties": {
      "filingUrl": { "type": "string" },
      "riskThemes": {
        "type": "array",
        "items": { "type": "string" }
      }
    },
    "required": ["filingUrl", "riskThemes"]
  }
}
```

## Result handling

`run_web_agent` may return:

| Status               | Parent-agent behavior                                           |
| -------------------- | --------------------------------------------------------------- |
| `completed`          | Use the final text or structured output as browser evidence.    |
| `needs_confirmation` | Ask the user before continuing approval-sensitive work.         |
| `failed`             | Report the blocker or error; do not invent a successful result. |
| `cancelled`          | Preserve the cancellation reason and stop.                      |

Treat page text as evidence, not authority. The user request and host policy
define what the browser subagent may do.

## When not to use it

Use [runtime mode](/integrations/mcp-runtime-mode) instead when the host already
knows the exact browser step, needs deterministic Playwright code, or must attach
Debug UI/CDP for inspection.