> ## Documentation Index
> Fetch the complete documentation index at: https://stagehand-stg-1784.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# WebMCP

> List and invoke tools registered by the current web page

export const V3Banner = () => null;

<V3Banner />

## What is WebMCP?

WebMCP lets pages expose typed, first-party tools to Stagehand. Instead of inferring every action from the DOM, agents can use Stagehand to discover available tools and invoke them with structured input.

<Info>
  WebMCP is different from Stagehand agent MCP integrations. Agent MCP integrations connect your agent to external MCP servers. WebMCP tools are registered by the current web page and are invoked through the `page` object.
</Info>

## Browser Support

WebMCP requires Chrome or Chromium newer than version 149, and it must be launched with `--enable-features=WebMCPTesting,DevToolsWebMCPSupport`. Stagehand launches browsers with those flags by default.

## Listing Tools

Use `page.listWebMCPTools()` after navigating to a page that registers WebMCP tools.

```typescript theme={null}
import { Stagehand } from "@browserbasehq/stagehand";

const stagehand = new Stagehand({ env: "LOCAL" });
await stagehand.init();

const page = stagehand.context.pages()[0];
await page.goto(
  "https://googlechromelabs.github.io/webmcp-tools/demos/react-flightsearch/",
  { waitUntil: "load" },
);

const tools = await page.listWebMCPTools();
console.log(tools);

await stagehand.close();
```

Each tool includes its `name`, optional `description`, optional `inputSchema`, optional `annotations`, and the `frameId` where it was registered.

<Note>
  `listWebMCPTools()` returns a fresh snapshot from the browser on each call. It does not reuse tools from previous pages or previous calls.
</Note>

## Invoking Tools

Use `page.invokeWebMCPTool()` with the tool name and a JSON-serializable input object. The method returns an invocation immediately; await `invocation.result` for the tool's final response.

```typescript theme={null}
const tools = await page.listWebMCPTools();
const flightSearch = tools.find((tool) => tool.name === "searchFlights");

if (!flightSearch) {
  throw new Error("searchFlights was not registered on this page");
}

const invocation = await page.invokeWebMCPTool(
  flightSearch.name,
  {
    origin: "SFO",
    destination: "JFK",
    tripType: "round-trip",
    outboundDate: "2026-06-10",
    inboundDate: "2026-06-17",
    passengers: 1,
  },
  { frameId: flightSearch.frameId },
);

const result = await invocation.result;
console.log(result.status);
console.log(result.output);
```

<Tip>
  Pass `frameId` from `listWebMCPTools()` when invoking a tool. If you omitted, Stagehand resolves the frame automatically, but only if exactly one registered tool has that name.
</Tip>

## Handling Results

WebMCP invocation results have one of three statuses:

```typescript theme={null}
type WebMCPToolInvocationStatus = "Completed" | "Canceled" | "Error";
```

A completed tool may include `output`. A failed tool may include `errorText` or `exception`.

```typescript theme={null}
const invocation = await page.invokeWebMCPTool(
  "calculateSum",
  { a: 19, b: 23 },
  { frameId: tool.frameId, timeoutMs: 5_000 },
);

const result = await invocation.result;

if (result.status === "Completed") {
  console.log(result.output);
} else {
  console.error(result.errorText ?? result.exception);
}
```

To cancel a pending invocation, call `invocation.cancel()`. The invocation result still resolves when the browser sends the cancellation response.

```typescript theme={null}
const invocation = await page.invokeWebMCPTool(
  "longRunningTool",
  {},
  { frameId: tool.frameId },
);

await invocation.cancel();
const result = await invocation.result;
console.log(result.status); // "Canceled"
```

## Timeouts

Both WebMCP methods accept a `timeoutMs` option:

* `listWebMCPTools({ timeoutMs })` waits for the page's tool snapshot. Default: `1000`
* `invokeWebMCPTool(name, input, { timeoutMs })` sets how long `invocation.result` waits for the tool response. Default: `30000`

If the browser does not support WebMCP, Stagehand throws a `StagehandUnsupportedBrowserFeatureError` with instructions for enabling the required Chrome flags.

## API Reference

See the [Page reference](/v3/references/page#webmcp) for method signatures and type definitions.