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

# WebMCP

> Inspect and invoke page-provided WebMCP tools

`page.tools()` returns page-bound `WebMCPTool` objects. Invoking a tool returns a
`WebMCPInvocation`, which can wait for Chrome's terminal response or request cancellation. See the
[Page reference](/v4/reference/page) for tool discovery options.

<Tabs>
  <Tab title="TypeScript">
    ## WebMCPTool

    ### Properties

    | Property        | Type                                   | Description                                                      |
    | --------------- | -------------------------------------- | ---------------------------------------------------------------- |
    | `name`          | `string`                               | Tool name used for invocation.                                   |
    | `description`   | `string`                               | Human-readable tool description.                                 |
    | `inputSchema`   | `Record<string, unknown> \| undefined` | Optional JSON input schema.                                      |
    | `annotations`   | `WebMCPAnnotation \| undefined`        | Optional `readOnly`, `untrustedContent`, and `autosubmit` flags. |
    | `frameId`       | `string`                               | Frame that published the tool.                                   |
    | `backendNodeId` | `number \| undefined`                  | Optional non-negative backend node identifier.                   |

    ### invoke()

    ```typescript theme={null}
    invoke(options?: WebMCPInvokeOptions): Promise<WebMCPInvocation>
    ```

    `options.input` is a JSON-compatible object and defaults to `{}`. The helper supplies its own page,
    frame, and tool name.

    ## WebMCPInvocation

    ### Properties

    | Property       | Type                      | Description                    |
    | -------------- | ------------------------- | ------------------------------ |
    | `invocationId` | `string`                  | Stable invocation identifier.  |
    | `toolName`     | `string`                  | Name of the invoked tool.      |
    | `frameId`      | `string`                  | Frame handling the invocation. |
    | `input`        | `Record<string, unknown>` | JSON input sent to the tool.   |

    ### result()

    ```typescript theme={null}
    result(options?: WebMCPResultOptions): Promise<WebMCPToolResponse>
    ```

    `options.timeout` is an optional non-negative timeout in milliseconds. A successful terminal
    response is cached on the invocation; timeout and transport failures are not cached and can be
    retried.

    | Response field | Type                                   | Description                            |
    | -------------- | -------------------------------------- | -------------------------------------- |
    | `invocationId` | `string`                               | Invocation that produced the response. |
    | `status`       | `"Completed" \| "Canceled" \| "Error"` | Terminal status.                       |
    | `output`       | `unknown`                              | Optional JSON output.                  |
    | `errorText`    | `string \| undefined`                  | Optional error message.                |
    | `exception`    | `WebMCPRemoteObject \| undefined`      | Optional structured exception data.    |

    ### cancel()

    ```typescript theme={null}
    cancel(): Promise<void>
    ```

    Requests cancellation from Chrome. It does not synthesize or overwrite a terminal response; call
    `result()` for the authoritative final status.
  </Tab>

  <Tab title="Python">
    ## WebMCPTool

    ### Properties

    | Property          | Type                           | Description                                                        |
    | ----------------- | ------------------------------ | ------------------------------------------------------------------ |
    | `name`            | `str`                          | Tool name used for invocation.                                     |
    | `description`     | `str`                          | Human-readable tool description.                                   |
    | `input_schema`    | `dict[str, JsonValue] \| None` | Optional JSON input schema.                                        |
    | `annotations`     | `WebMCPAnnotation \| None`     | Optional `read_only`, `untrusted_content`, and `autosubmit` flags. |
    | `frame_id`        | `str`                          | Frame that published the tool.                                     |
    | `backend_node_id` | `int \| None`                  | Optional non-negative backend node identifier.                     |

    ### invoke()

    ```python theme={null}
    async def invoke(
        *,
        input: Mapping[str, JsonValue] | None = None,
    ) -> WebMCPInvocation
    ```

    `input` defaults to an empty dictionary. The helper supplies its own page, frame, and tool name.

    ## WebMCPInvocation

    ### Properties

    | Property        | Type                   | Description                    |
    | --------------- | ---------------------- | ------------------------------ |
    | `invocation_id` | `str`                  | Stable invocation identifier.  |
    | `tool_name`     | `str`                  | Name of the invoked tool.      |
    | `frame_id`      | `str`                  | Frame handling the invocation. |
    | `input`         | `dict[str, JsonValue]` | JSON input sent to the tool.   |

    ### result()

    ```python theme={null}
    async def result(*, timeout: float | None = None) -> WebMCPToolResponse
    ```

    `timeout` is an optional non-negative timeout in milliseconds. A successful terminal response is
    cached; timeout and transport failures are not cached and can be retried.

    | Response field  | Type                                        | Description                            |
    | --------------- | ------------------------------------------- | -------------------------------------- |
    | `invocation_id` | `str`                                       | Invocation that produced the response. |
    | `status`        | `Literal["Completed", "Canceled", "Error"]` | Terminal status.                       |
    | `output`        | `JsonValue \| None`                         | Optional JSON output.                  |
    | `error_text`    | `str \| None`                               | Optional error message.                |
    | `exception`     | `dict[str, JsonValue] \| None`              | Optional structured exception data.    |

    ### cancel()

    ```python theme={null}
    async def cancel() -> None
    ```

    Requests cancellation from Chrome. It does not synthesize or overwrite a terminal response; call
    `result()` for the authoritative final status.
  </Tab>

  <Tab title="Go">
    ## WebMCPTool

    Go exposes descriptor data through a method rather than properties.

    ### Descriptor()

    ```go theme={null}
    func (t *WebMCPTool) Descriptor() WebMCPToolDescriptor
    ```

    The returned descriptor contains `Name`, `Description`, `InputSchema`, `Annotations`, `FrameID`,
    and optional `BackendNodeID`. `Annotations` may contain `ReadOnly`, `UntrustedContent`, and
    `Autosubmit` pointers.

    ### Invoke()

    ```go theme={null}
    func (t *WebMCPTool) Invoke(
        ctx context.Context,
        input WebMCPInput,
    ) (*WebMCPInvocation, error)
    ```

    `WebMCPInput` is a `map[string]any`; `nil` is sent as an empty JSON object. Values must be JSON
    encodable. The helper supplies its own page, frame, and tool name.

    ## WebMCPInvocation

    ### Descriptor()

    ```go theme={null}
    func (i *WebMCPInvocation) Descriptor() WebMCPInvocationDescriptor
    ```

    The descriptor contains `InvocationID`, `ToolName`, `FrameID`, and the JSON `Input` map.

    ### Result()

    ```go theme={null}
    func (i *WebMCPInvocation) Result(
        ctx context.Context,
        options *WebMCPResultOptions,
    ) (WebMCPToolResponse, error)
    ```

    Pass `nil` for default waiting behavior. `options.Timeout` is an optional non-negative timeout in
    milliseconds. A successful terminal response is cached; context and RPC failures are not cached
    and can be retried.

    | Response field | Type                     | Description                                                                                            |
    | -------------- | ------------------------ | ------------------------------------------------------------------------------------------------------ |
    | `InvocationID` | `string`                 | Invocation that produced the response.                                                                 |
    | `Status`       | `WebMCPInvocationStatus` | `WebMCPInvocationStatusCompleted`, `WebMCPInvocationStatusCanceled`, or `WebMCPInvocationStatusError`. |
    | `Output`       | `json.RawMessage`        | Optional JSON output.                                                                                  |
    | `ErrorText`    | `*string`                | Optional error message.                                                                                |
    | `Exception`    | `WebMCPRemoteObject`     | Optional structured exception data.                                                                    |

    Use `WebMCPOutputAs[T](response)` to decode a non-empty JSON output into a caller-selected type.

    ### Cancel()

    ```go theme={null}
    func (i *WebMCPInvocation) Cancel(ctx context.Context) error
    ```

    Requests cancellation from Chrome. It does not synthesize or overwrite a terminal response; call
    `Result()` for the authoritative final status.
  </Tab>
</Tabs>