WebMCP Documentation

@mcp-b/webmcp-ts-sdk exports BrowserMcpServer, a WebMCP adapter that composes the official MCP TypeScript SDK v2 McpServer.

pnpm add @mcp-b/webmcp-ts-sdk @mcp-b/transports

Most applications should use @mcp-b/global, which creates and installs the adapter on document.modelContext.

`BrowserMcpServer`

Constructor

new BrowserMcpServer(serverInfo: Implementation, options?: BrowserMcpServerOptions)

BrowserMcpServerOptions extends the upstream ServerOptions type.

Property	Type	Description
`native`	`ModelContext?`	Context that receives mirrored WebMCP tool registrations

The constructor passes the remaining options to McpServer and enables list-change support for tools, resources, and prompts.

`mcpServer`

readonly mcpServer: McpServer

The composed official server. Use it for upstream registration APIs and other MCP SDK v2 features that BrowserMcpServer does not wrap. Protocol-owned sampling and elicitation APIs are not direct BrowserMcpServer methods. Legacy push-style calls live on browserServer.mcpServer.server and depend on the negotiated protocol revision. WebMCP descriptor callbacks are single-round over MCP. An input_required result becomes a tool error. Register multi-round tools directly with browserServer.mcpServer.registerTool() so the official handler context owns the interaction.

WebMCP tool surface

The WebMCP specification is authoritative for the standard browser API.

`registerTool(tool, options?)`

registerTool(
  tool: ToolDescriptor,
  options?: ModelContextRegisterToolOptions
): Promise<void>

Registers a WebMCP descriptor and its MCP representation. When native is set, registration succeeds only after the native mirror accepts the tool.

Option	Type	Description
`signal`	`AbortSignal?`	Removes the MCP registration and native mirror when aborted
`exposedTo`	`string[]?`	Requests cross-document exposure from the native browser context

A non-empty exposedTo array requires native WebMCP. Invalid descriptors, duplicate names, blocked Permissions Policy, and pre-aborted signals reject the returned promise.

`getTools(options?)`

getTools(options?: ModelContextGetToolOptions): Promise<RegisteredTool[]>

Returns browser descriptors. With native, the call delegates to native.getTools(). Without native, a non-empty fromOrigins array rejects because local code cannot perform cross-document discovery.

`executeTool(tool, inputArgsJson, options?)`

executeTool(
  tool: RegisteredTool,
  inputArgsJson: string,
  options?: ChromeModelContextExecuteToolOptions
): Promise<string | null>

Executes a descriptor returned by getTools(). This optional Chrome imperative API extension is outside the strict WebMCP core. The optional signal aborts the call.

Tool change events

BrowserMcpServer extends EventTarget and exposes ontoolchange. Local registry changes queue a toolchange event. Native toolchange events trigger reconciliation before the adapter dispatches its event.

MCP-B extensions

`isBrowserMcpServer(context)`

isBrowserMcpServer(context: unknown): context is BrowserMcpServer

Narrows an installed document.modelContext without changing the strict global declaration or creating a second runtime handle.

`listTools()`

listTools(): ToolListItem[]

Returns a clone of the adapter’s MCP-B tool metadata, including outputSchema when registered.

`syncNativeTools()`

syncNativeTools(): Promise<void>

Reconciles the adapter with tools already visible through native.getTools(). Backfill requires the native context’s optional descriptor-based executeTool() extension. Later native toolchange events reconcile additions, metadata changes, and removals. Use the Model Context Tool Inspector recommended by Chrome’s WebMCP documentation to inspect native and mirrored tools.

`registerResource(descriptor)`

registerResource(descriptor: ResourceDescriptor): RegistrationHandle

Registers a fixed URI or URI template with the composed McpServer. The returned handle removes the registration through unregister().

Field	Type	Required
`uri`	`string`	Yes
`name`	`string`	Yes
`description`	`string`	No
`mimeType`	`string`	No
`read`	`(uri: URL, params?: Variables) => Promise<ReadResourceResult>`	Yes

A URI containing { registers a ResourceTemplate; its variables are passed to read as params. Other URIs register fixed resources.

`registerPrompt(descriptor)`

registerPrompt(descriptor: PromptDescriptor): RegistrationHandle

Registers a prompt with the composed McpServer. The returned handle removes the registration through unregister().

Field	Type	Required
`name`	`string`	Yes
`description`	`string`	No
`argsSchema`	`InputSchema`	No
`get`	`(args: Record<string, string>) => Promise<GetPromptResult>`	Yes

Prompt and resource discovery and invocation use MCP. Connect an MCP client; BrowserMcpServer does not duplicate the official list, read, or get methods. See Register prompts and resources for usage.

Transport lifecycle

`connect(transport)`

connect(transport: Transport): Promise<void>

Connects the composed server. Custom tab and iframe transports use SDK v2’s legacy 2025-era route; see the upstream protocol revision guide.

`close()`

close(): Promise<void>

Stops native reconciliation, aborts native mirrors, removes registrations, and closes mcpServer. Repeated calls return the same promise.

Schema boundary

The browser-facing tool API accepts JSON Schema and Standard Schema inputs. The adapter converts tool input schemas to the MCP v2 contract, while McpServer owns MCP-call validation. PromptDescriptor.argsSchema accepts InputSchema. Direct upstream registrations support Zod 4.2 or newer and the official fromJsonSchema helper; Zod 3 is unsupported. MCP requires object-root tool input schemas. An array-root WebMCP tool remains available through WebMCP but is omitted from MCP discovery with a warning.

Exports

The package exports only its adapter surface:

BrowserMcpServer
BrowserMcpServerOptions
isBrowserMcpServer
PromptDescriptor
ResourceDescriptor

Import MCP clients, protocol schemas, transports, validators, and upstream server types from their official @modelcontextprotocol/* packages. The @mcp-b/transports reference documents browser transports. Strict core and MCP-B extensions defines the boundary between WebMCP and this adapter.

Packages

WebMCP standard

Core runtime

React

Tooling

@mcp-b/webmcp-ts-sdk

`BrowserMcpServer`

Constructor

`mcpServer`

WebMCP tool surface

`registerTool(tool, options?)`

`getTools(options?)`

`executeTool(tool, inputArgsJson, options?)`

Tool change events

MCP-B extensions

`isBrowserMcpServer(context)`

`listTools()`

`syncNativeTools()`

`registerResource(descriptor)`

`registerPrompt(descriptor)`

Transport lifecycle

`connect(transport)`

`close()`

Schema boundary

Exports

​BrowserMcpServer

​Constructor

​mcpServer

​WebMCP tool surface

​registerTool(tool, options?)

​getTools(options?)

​executeTool(tool, inputArgsJson, options?)

​Tool change events

​MCP-B extensions

​isBrowserMcpServer(context)

​listTools()

​syncNativeTools()

​registerResource(descriptor)

​registerPrompt(descriptor)

​Transport lifecycle

​connect(transport)

​close()

​Schema boundary

​Exports

`BrowserMcpServer`

Constructor

`mcpServer`

WebMCP tool surface

`registerTool(tool, options?)`

`getTools(options?)`

`executeTool(tool, inputArgsJson, options?)`

Tool change events

MCP-B extensions

`isBrowserMcpServer(context)`

`listTools()`

`syncNativeTools()`

`registerResource(descriptor)`

`registerPrompt(descriptor)`

Transport lifecycle

`connect(transport)`

`close()`

Schema boundary

Exports