WebMCP Documentation

@mcp-b/webmcp-types emits TypeScript declarations only. It defines the standard browser surface separately from MCP-B and Chromium extensions. The WebMCP draft is authoritative for the browser API.

Installation

npm install --save-dev @mcp-b/webmcp-types

Use a production dependency when a published library exposes these types in its declarations.

Global activation

Choose one activation method:

tsconfig.json
Triple-slash reference
Type-only import

{
  "compilerOptions": {
    "types": ["@mcp-b/webmcp-types"]
  }
}

/// <reference types="@mcp-b/webmcp-types" />

import type {} from '@mcp-b/webmcp-types';

Activation adds these globals:

Property	Type	Status
`document.modelContext`	`ModelContext`	Canonical
`navigator.modelContext`	`ModelContext \| undefined`	Deprecated compatibility alias
`navigator.modelContextTesting`	`ModelContextTesting \| undefined`	Deprecated testing compatibility surface

Example

Browser contracts

`ModelContext`

ModelContext is the type of document.modelContext.

Member	Type
`registerTool(tool, options?)`	`Promise<void>`
`getTools(options?)`	`Promise<RegisteredTool[]>`
`ontoolchange`	Event handler or `null`
EventTarget methods	Inherited from `EventTarget`

Option type	Field	Type	Meaning
`ModelContextRegisterToolOptions`	`signal`	`AbortSignal?`	Owns the registration lifetime
`ModelContextRegisterToolOptions`	`exposedTo`	`string[]?`	Requests exposure to descendant origins
`ModelContextGetToolOptions`	`fromOrigins`	`string[]?`	Requests tools exposed by descendant origins
`ChromeModelContextExecuteToolOptions`	`signal`	`AbortSignal?`	Aborts a Chromium descriptor execution

Aborting the registration signal removes that registration. RegisteredTool contains name, optional title, description, optional serialized inputSchema, window, origin, and optional standard annotations.

`ChromeModelContext`

ChromeModelContextExtensions declares the optional Chromium executeTool() method. ChromeModelContext combines that extension with ModelContext. Feature-detect the method before calling it.

import type { ChromeModelContext } from '@mcp-b/webmcp-types';

const modelContext = document.modelContext as ChromeModelContext;
const tool = (await modelContext.getTools()).find(({ name }) => name === 'search');

if (tool && modelContext.executeTool) {
  await modelContext.executeTool(tool, '{"query":"webmcp"}');
}

`ModelContextExtensions`

The MCP-B extension surface provides schema-aware registerTool() overloads and listTools(). It does not add removed name-based unregistration. ModelContextWithExtensions keeps the standard event and discovery members while replacing standard registration with the MCP-B descriptor overloads.

Tool contracts

`ModelContextTool<TArgs, TResult, TName>`

The standard tool dictionary.

Property	Type	Required
`name`	`TName`	Yes
`description`	`string`	Yes
`title`	`string`	No
`inputSchema`	`InputSchema`	No
`annotations`	`WebMcpToolAnnotations`	No
`execute`	`(input: TArgs) => MaybePromise<TResult>`	Yes

`ToolDescriptor<TArgs, TResult, TName>`

The MCP-B descriptor adds outputSchema and MCP annotations.

Property	Type	Required
`name`	`TName`	Yes
`description`	`string`	Yes
`title`	`string`	No
`inputSchema`	`InputSchema`	No
`outputSchema`	`JsonSchemaForInference`	No
`annotations`	`ToolAnnotations`	No
`execute`	`(args: TArgs) => MaybePromise<TResult>`	Yes

ToolDescriptorFromSchema<TInput, TOutput, TName> infers callback input and output from literal schemas. ToolListItem<TName> describes the metadata returned by listTools().

Annotation types

WebMcpToolAnnotations contains the standard readOnlyHint and untrustedContentHint fields. ToolAnnotations combines those fields with the annotation contract from @modelcontextprotocol/server for MCP-B descriptors.

Result types

CallToolResult, ContentBlock, and TextContent come from the official MCP TypeScript SDK. ToolResultFromOutputSchema<T> replaces structuredContent with the type inferred from T.

Schema inference

`JsonSchemaForInference`

JsonSchemaForInference is the JsonSchemaType owned by @modelcontextprotocol/server. Use as const satisfies JsonSchemaForInference to preserve literal information.

`InferJsonSchema<T>`

Schema keyword	Inference
`type`	Primitive, object, array, or multi-type union
`properties`	Named object fields
`required`	Required named fields when the key list is literal
`additionalProperties`	Closed object, unknown extras, or map values
`items`	Array element type
`enum`	Literal union
`const`	Literal value
Boolean schema	`false` becomes `never`; `true` becomes `unknown`

Typeless properties, required, or additionalProperties imply an object. Unsupported compositions such as $ref and oneOf remain unknown. Use type: ['string', 'null'] for nullable values.

`InferArgsFromInputSchema<T>`

Tool callbacks accept object or array inputs. The helper keeps an inferred object or array and otherwise falls back to WebMcpToolInput:

type WebMcpToolInput = Record<string, unknown> | unknown[];

That fallback applies to widened InputSchema, unknown compositions, and scalar-only schemas.

Deprecated testing contracts

ModelContextTesting retains the optional older Chromium testing shape used by compatibility runtimes:

Member	Type
`listTools()`	`ModelContextTestingToolInfo[]`
`executeTool(name, inputJson, options?)`	`Promise<string \| null>`
`ontoolchange`	Event handler or `null`

New native integrations use document.modelContext.getTools() and feature-detect Chromium executeTool(). ModelContextTestingToolInfo contains name, description, and an optional serialized inputSchema.

Public utility types

Export	Description
`InputSchema`	Broad runtime JSON Schema boundary
`WebMcpToolInput`	Object or array callback input
`MaybePromise<T>`	`T \| Promise<T>`
`RegistrationHandle`	Prompt/resource registration handle
`JsonObject`, `JsonValue`	Canonical MCP JSON values

Packages

WebMCP standard

Core runtime

React

Tooling

@mcp-b/webmcp-types

Installation

Global activation

Example

Browser contracts

`ModelContext`

`ChromeModelContext`

`ModelContextExtensions`

Tool contracts

`ModelContextTool<TArgs, TResult, TName>`

`ToolDescriptor<TArgs, TResult, TName>`

Annotation types

Result types

Schema inference

`JsonSchemaForInference`

`InferJsonSchema<T>`

`InferArgsFromInputSchema<T>`

Deprecated testing contracts

Public utility types

​Installation

​Global activation

​Example

​Browser contracts

​ModelContext

​ChromeModelContext

​ModelContextExtensions

​Tool contracts

​ModelContextTool<TArgs, TResult, TName>

​ToolDescriptor<TArgs, TResult, TName>

​Annotation types

​Result types

​Schema inference

​JsonSchemaForInference

​InferJsonSchema<T>

​InferArgsFromInputSchema<T>

​Deprecated testing contracts

​Public utility types

​Related pages

Installation

Global activation

Example

Browser contracts

`ModelContext`

`ChromeModelContext`

`ModelContextExtensions`

Tool contracts

`ModelContextTool<TArgs, TResult, TName>`

`ToolDescriptor<TArgs, TResult, TName>`

Annotation types

Result types

Schema inference

`JsonSchemaForInference`

`InferJsonSchema<T>`

`InferArgsFromInputSchema<T>`

Deprecated testing contracts

Public utility types

Related pages