@mcp-b/webmcp-types reference

@mcp-b/webmcp-types emits TypeScript declarations only. It defines the browser contracts implemented by MCP-B packages separately from MCP-B extensions and serialized-JSON execution compatibility. The WebMCP draft is authoritative for the browser API. For ambient declarations that track that proposal directly, use the Community Group’s webmcp-types package. Use @mcp-b/webmcp-types when you need MCP-B package contracts or schema inference.

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. Every one is optional, so feature-detect before use. Check WebMCP resources and status for current browser and declarative API support.

Property	Type	Status
`document.modelContext`	`ModelContext?`	Canonical
`navigator.modelContext`	`ModelContext \| undefined`	Deprecated compatibility alias
`navigator.modelContextTesting`	`ModelContextTesting \| undefined`	Deprecated testing compatibility surface
`SubmitEvent.agentInvoked`	`boolean?`	Declarative forms
`SubmitEvent.respondWith`	`((agentResponse: Promise<unknown>) => void)?`	Declarative forms
`ModelContext`	interface object or `undefined`	Branding and `instanceof`

The optional members are bare optionals (?: T, not ?: T | undefined). Where WebMCP is absent the property is genuinely missing, so 'modelContext' in document is false. ModelContext is | undefined instead, because a var declaration cannot be optional; guard it with typeof ModelContext !== 'undefined'.

const modelContext = document.modelContext;
if (!modelContext) return;
await modelContext.registerTool(tool);

Install @mcp-b/webmcp-polyfill when you want the surface installed rather than detected.

Example

Browser contracts

`ModelContext`

ModelContext is the package-supported registration and discovery type for document.modelContext. The live proposal may contain additional or changed members.

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 listed origins in the active frame tree
`ModelContextGetToolOptions`	`fromOrigins`	`string[]?`	Requests tools from listed origins in the active frame tree
`ChromeModelContextExecuteToolOptions`	`signal`	`AbortSignal?`	Aborts a Chromium descriptor execution

Aborting the registration signal removes that registration. RegisteredTool contains name, optional title, description, optional inputSchema, window, origin, and optional WebMCP annotations. The compatibility type accepts either a JSON Schema object or serialized JSON string. Branch on typeof and follow the Chrome imperative API for current browser behavior.

`ChromeModelContext`

ChromeModelContextExtensions declares the serialized-JSON executeTool() signature supported by MCP-B and current Chrome builds. ChromeModelContext combines that compatibility shape 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 package’s event and discovery members while replacing registration with the MCP-B descriptor overloads.

Tool contracts

`ModelContextTool<TArgs, TResult, TName>`

The generic tool dictionary used by the package’s browser registration contracts.

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 proposal’s 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 executeTool(). Follow the Chrome imperative API for the browser’s current serialized-JSON signature. 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 platforms and agents

Core runtime

React

Tooling

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