> ## Documentation Index > Fetch the complete documentation index at: https://tbd-6fc993ce-hypeship-search-api-docs.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Add custom WebMCP tools > Add a namespaced batch of custom tools. A custom tool can be page-backed or CDP-backed. Page-backed tools execute in the page via JavaScript. CDP-backed tools execute via CDP and can use all browser REPL tools (see `/repl`). The source must evaluate to a non-empty array of definitions with URL matchers, tool metadata (including an optional output schema), and execute functions. The batch is added atomically. Matchers apply to top-level documents and nested frames, including out-of-process iframes; each matching tool is exposed once on the tab's top-level document and appears in the WebMCP tool snapshot. To update one tool, list the tools, delete its ID, and add its replacement. Set force_overwrite_namespace to replace every existing tool in the namespace atomically; omitted or false adds tools without replacing existing ones. Existing invocations continue. ## OpenAPI ````yaml https://api.onkernel.com/spec.json post /browsers/{id_or_name}/webmcp/custom-tools openapi: 3.1.0 info: description: Developer tools and cloud infrastructure for AI agents to use web browsers title: Kernel API version: 0.1.0 servers: - description: API Server url: https://api.onkernel.com security: - bearerAuth: [] tags: - description: Search the web and retrieve content for selected results. name: Search - description: Create and manage browser sessions. name: Browsers - description: Control mouse, keyboard, and screen on the browser instance. name: Browser Computer Controls - description: Execute Playwright code against the browser instance. name: Browser Playwright - description: Execute JavaScript in the browser instance's persistent Browser REPL. name: Browser REPL - description: Discover and invoke native page tools across the browser instance. name: Browser WebMCP - description: Read, write, and manage files on the browser instance. name: Browser Filesystem - description: Execute and manage processes on the browser instance. name: Browser Processes - description: Record and manage browser session video replays. name: Browser Replays - description: Stream logs from the browser instance. name: Browser Logs - description: >- Stream live telemetry events from a browser session, and manage the destinations sessions export them to. name: Browser Telemetry - description: Create, list, retrieve, and delete browser profiles. name: Profiles - description: Create and manage proxy configurations for routing browser traffic. name: Proxies - description: Create, list, retrieve, and delete browser extensions. name: Extensions - description: Create and manage browser pools for acquiring and releasing browsers. name: Browser Pools - description: Inspect the identity and authorization context for the current request. name: Authentication - description: >- Create and manage auth connections for automated credential capture and login. name: Managed Auth - description: Create and manage credentials for authentication. name: Credentials - description: Configure external credential providers like 1Password. name: Credential Providers - description: List applications and versions. name: Apps - description: Create and manage app deployments and stream deployment events. name: Deployments - description: Invoke actions and stream or query invocation status and events. name: Invocations - description: Read and manage organization-level limits. name: Organization - description: | Create and manage projects for resource isolation within an organization. When projects are disabled for the organization, project operations return `404` with code `projects_disabled`. name: Projects - description: Create and manage API keys for organization and project-scoped access. name: API Keys - description: Read audit log records for the authenticated organization. name: Audit Logs - description: Resolve browser and proxy recommendations for bot-protected sites. name: Config Registry paths: /browsers/{id_or_name}/webmcp/custom-tools: parameters: - description: Browser session ID or name in: path name: id_or_name required: true schema: type: string post: tags: - Browser WebMCP summary: Add custom WebMCP tools description: > Add a namespaced batch of custom tools. A custom tool can be page-backed or CDP-backed. Page-backed tools execute in the page via JavaScript. CDP-backed tools execute via CDP and can use all browser REPL tools (see `/repl`). The source must evaluate to a non-empty array of definitions with URL matchers, tool metadata (including an optional output schema), and execute functions. The batch is added atomically. Matchers apply to top-level documents and nested frames, including out-of-process iframes; each matching tool is exposed once on the tab's top-level document and appears in the WebMCP tool snapshot. To update one tool, list the tools, delete its ID, and add its replacement. Set force_overwrite_namespace to replace every existing tool in the namespace atomically; omitted or false adds tools without replacing existing ones. Existing invocations continue. operationId: addCustomWebMCPTools requestBody: content: application/json: schema: $ref: '#/components/schemas/AddCustomWebMCPToolsRequest' description: >- Source is limited to 8000000 UTF-8 bytes; the raw JSON body is limited to 8000000 bytes plus 4 KiB before decoding. required: true responses: '201': content: application/json: schema: $ref: '#/components/schemas/CustomWebMCPToolsResponse' description: Custom tools added. Contains only the newly added tools. '400': $ref: '#/components/responses/BadRequest' '409': $ref: '#/components/responses/Conflict' '500': $ref: '#/components/responses/InternalError' default: $ref: '#/components/responses/BrowserProxyError' security: - bearerAuth: [] components: schemas: AddCustomWebMCPToolsRequest: additionalProperties: false properties: force_overwrite_namespace: default: false description: >- Atomically replace all existing tools in this namespace with this batch when true. type: boolean namespace: pattern: ^[A-Za-z0-9_.-]{1,128}$ type: string source: description: >- JavaScript expression that evaluates to a non-empty array of custom tool definitions. Limited to 8,000,000 bytes when UTF-8 encoded, so multi-byte characters reduce the allowed character count. maxLength: 8000000 type: string required: - namespace - source type: object CustomWebMCPToolsResponse: additionalProperties: false properties: tools: items: $ref: '#/components/schemas/CustomWebMCPDefinition' type: array required: - tools type: object CustomWebMCPDefinition: additionalProperties: false properties: id: pattern: ^ct_[a-z][a-z0-9]{23}$ type: string kind: pattern: ^(page|cdp)$ type: string match: $ref: '#/components/schemas/CustomWebMCPMatch' namespace: type: string tool: $ref: '#/components/schemas/WebMCPToolMetadata' required: - id - namespace - kind - match - tool type: object Error: properties: code: description: Application-specific error code (machine-readable) example: bad_request type: string details: description: Additional error details (for multiple errors) items: $ref: '#/components/schemas/ErrorDetail' type: array inner_error: $ref: '#/components/schemas/ErrorDetail' message: description: Human-readable error description for debugging example: 'Missing required field: app_name' type: string required: - code - message type: object InstanceProxyError: properties: code: $ref: '#/components/schemas/InstanceProxyErrorCode' message: description: Human-readable error description for debugging type: string required: - code - message type: object CustomWebMCPMatch: additionalProperties: false properties: url_patterns: items: type: string minItems: 1 type: array required: - url_patterns type: object WebMCPToolMetadata: additionalProperties: false description: > Tool metadata follows the [MCP Tool definition](https://modelcontextprotocol.io/specification/2025-11-25/server/tools#tool) and the [WebMCP RegisteredTool definition](https://webmachinelearning.github.io/webmcp/#dictdef-registeredtool). outputSchema is optional for page and custom tools. properties: annotations: $ref: '#/components/schemas/WebMCPToolAnnotations' description: type: string inputSchema: additionalProperties: true type: object name: type: string outputSchema: additionalProperties: true type: object title: type: string required: - name - description - inputSchema type: object ErrorDetail: properties: code: description: Lower-level error code providing more specific detail example: invalid_input type: string message: description: Further detail about the error example: Provided version string is not semver compliant type: string type: object InstanceProxyErrorCode: description: Canonical error code returned by browser instance API proxy routes enum: - invalid_request - unauthorized - forbidden - session_not_leased - not_found - conflict - session_gone - rate_limit_exceeded - internal_error - browser_unavailable type: string WebMCPToolAnnotations: additionalProperties: false description: > Tool-provided behavioral hints from the [MCP tool specification](https://modelcontextprotocol.io/specification/2025-11-25/server/tools#tool) and the [WebMCP ToolAnnotations definition](https://webmachinelearning.github.io/webmcp/#dictdef-toolannotations). These hints are untrusted and are not enforced by Kernel. properties: autosubmit: type: boolean consequentialHint: type: boolean destructiveHint: type: boolean idempotentHint: type: boolean openWorldHint: type: boolean readOnlyHint: type: boolean untrustedContentHint: type: boolean type: object responses: BadRequest: content: application/json: schema: $ref: '#/components/schemas/Error' description: Bad Request – invalid input Conflict: content: application/json: schema: $ref: '#/components/schemas/Error' description: Conflict – resource already exists InternalError: content: application/json: schema: $ref: '#/components/schemas/Error' description: Internal Server Error BrowserProxyError: content: application/json: schema: $ref: '#/components/schemas/InstanceProxyError' description: Error returned by the browser or its proxy securitySchemes: bearerAuth: scheme: bearer type: http ````