---
title: "Invoke a WebMCP tool"
method: POST
path: "/api/session/{id}/webmcp/invoke"
---

# Invoke a WebMCP tool

`POST /api/session/{id}/webmcp/invoke`

## Request

- Base URL: `https://api.hyperbrowser.ai`
- URL: `https://api.hyperbrowser.ai/api/session/{id}/webmcp/invoke`
- Auth: API key in header `x-api-key`
- TypeScript: <https://skmtc.dev/hyperbrowser/apis/hyperbrowser-api/docs/api/session/:id/webmcp/invoke/post.ts> (a function with typed inputs; its response is checked against the schema)

Invoke once and wait for the result. A form may return awaiting_submission with an invocationId. Do not blindly retry if the response is lost; the tool may already have acted. Requires an active session created with enableWebMcp: true and an API key with browser.sessions.update permission.

## Path parameters

- `id` string, uuid, required

## Request body

- WebMCPInvokeParams
  - `toolRef` string, required
  - `input` object: Arguments matching the tool inputSchema. At most 1 MiB when JSON encoded. Keys are passed through unchanged.
  - `timeoutSeconds` integer: Tool execution budget in seconds. Expiration requests cancellation; it does not guarantee rollback.

## Response `200`

Success

- WebMCPInvokeResult
  - `invocationId` string: Handle for subsequent result reads or cancellation, when provided.
  - `status` 'completed' | 'error' | 'canceled' | 'awaiting_submission', required
  - `output` unknown
  - `errorText` string
  - `outputBytes` integer, required: Byte length of the original JSON output.
  - `outputTruncated` boolean: True when output exceeds 1 MiB. Full output is withheld.
  - `outputPreview` string: At most 4096 UTF-8 bytes of the oversized output; may be incomplete JSON.
  - `untrustedContent` boolean, required
  - `durationMs` integer, required

## Other responses

- `400`: Invalid request or tool reference.
- `401`: Authentication required.
- `403`: Insufficient API key permission.
- `404`: Session, tool, or invocation not found. Expired handles return invocation_not_found.
- `409`: Session is stopped, unavailable, or was not created with WebMCP enabled.
- `413`: Tool input exceeds 1 MiB (input_too_large).
- `429`: Rate limit reached; too_many_invocations indicates 16 active invocations.
- `500`: Internal server error.
- `502`: WebMCP service unavailable.
- `504`: Request timed out. For invocation requests, outcome_unknown means the tool may have acted.

## Changes

- **2026-10-11** `6bf1269eede9`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/hyperbrowser/apis/hyperbrowser-api/changes/api/session/:id/webmcp/invoke/post.md)

---

[API](https://skmtc.dev/hyperbrowser/apis/hyperbrowser-api.md) - [All operations](https://skmtc.dev/hyperbrowser/apis/hyperbrowser-api/llms.txt) - [OpenAPI document](https://skmtc.dev/hyperbrowser/apis/hyperbrowser-api/revisions/ef089024c533?raw)