@mcp-b/webmcp-ts-sdk reference

@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 Community Group draft is authoritative for the proposed 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[]?`	Restricts the tool to the listed embedder origins

A tool registered with a non-empty exposedTo is advertised only while the connected peer’s origin appears in that list. BrowserMcpServer reads the origin from transports that report one, such as IframeChildTransport. Restricted tools fail closed: they stay hidden before the first peer origin arrives, and on transports that never report one. exposedTo only narrows. The child transport’s allowedOrigins still decides who may connect, and enforcement is the page’s own JavaScript rather than the user agent. See Bridge tools across iframes for the end-to-end setup. 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() using the package’s serialized-JSON compatibility signature. The optional signal aborts the call. The live proposal currently specifies object input, while the Chrome imperative API documents serialized JSON.

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 package’s 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 descriptor-based, serialized-JSON executeTool() signature. 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. WebMCP and MCP-B extensions defines the boundary between the proposal and this adapter.

Packages

WebMCP platforms and agents

Core runtime

React

Tooling

`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