WebMCP Documentation

@mcp-b/global is the MCP-B runtime entry point layered on top of WebMCP. It orchestrates the polyfill, creates a BrowserMcpServer, sets up transport, and replaces document.modelContext with the server instance. After initialization, document.modelContext still supports the strict WebMCP surface, but it also exposes MCP-B extension methods such as prompts, resources, sampling, elicitation, and transport-facing helpers.

npm install @mcp-b/global

Package selection

Package	Use When
`@mcp-b/webmcp-types`	You need compile-time types only
`@mcp-b/webmcp-polyfill`	You want the WebMCP standard path without extensions
`@mcp-b/global`	You want the MCP-B runtime with transport, prompts, resources, and extension APIs

For the reasoning behind this split, see Strict Core vs. MCP-B Extensions.

Installation

npm install @mcp-b/global

pnpm add @mcp-b/global

<script src="https://unpkg.com/@mcp-b/global@latest/dist/index.iife.js"></script>

<script type="module">
  import '@mcp-b/global';
</script>

Minimal example

Format	Size	Dependencies
IIFE	~285KB minified	All bundled
ESM	~16KB	External dependencies required

Auto-initialization

Importing @mcp-b/global in a browser environment auto-initializes document.modelContext. This behavior is controlled by window.__webModelContextOptions.

<script>
  window.__webModelContextOptions = {
    autoInitialize: true,
    transport: {
      tabServer: { allowedOrigins: ['https://myapp.com'] },
    },
  };
</script>
<script src="https://unpkg.com/@mcp-b/global@latest/dist/index.iife.js"></script>

To prevent auto-initialization:

<script>
  window.__webModelContextOptions = { autoInitialize: false };
</script>
<script src="https://unpkg.com/@mcp-b/global@latest/dist/index.iife.js"></script>
<script>
  MCPB.initializeWebModelContext();
</script>

Functions

`initializeWebModelContext(options?)`

Initializes the global adapter. Replaces document.modelContext with a BrowserMcpServer instance.

import { initializeWebModelContext } from '@mcp-b/global';

initializeWebModelContext({
  transport: {
    tabServer: { allowedOrigins: ['https://example.com'] },
  },
});

Behavior:

No-op in non-browser environments (SSR safe).
Idempotent: calling multiple times after first initialization is a no-op.
Skipped if document.modelContext is already a BrowserMcpServer (cross-bundle guard).

Initialization sequence:

Calls initializeWebMCPPolyfill() to install document.modelContext and navigator.modelContextTesting (skipped if native API exists).
Saves a reference to the current document.modelContext as native.
Creates a BrowserMcpServer with { native } so core operations mirror to the underlying context.
Syncs existing tools from the native/polyfill context into the server.
Replaces document.modelContext with the BrowserMcpServer instance.
Creates and connects the transport.

`cleanupWebModelContext()`

Tears down the adapter, closes transport, and restores document.modelContext to its pre-initialization state.

import { cleanupWebModelContext } from '@mcp-b/global';

cleanupWebModelContext();

After cleanup, initializeWebModelContext() can be called again to re-initialize.

Configuration

`WebModelContextInitOptions`

Option	Type	Default	Description
`transport`	`TransportConfiguration`	Auto-detect	Transport layer configuration
`autoInitialize`	`boolean`	`true`	Whether to auto-initialize on import
`nativeModelContextBehavior`	`'preserve' \| 'patch'`	`'preserve'`	How to handle an existing native `modelContext`. Both modes wrap with `BrowserMcpServer`.
`installTestingShim`	`boolean \| 'always' \| 'if-missing'`	`'if-missing'`	Controls `navigator.modelContextTesting` installation

`TransportConfiguration`

Option	Type	Default	Description
`tabServer`	`Partial<TabServerTransportOptions> \| false`	Auto	Tab transport options, or `false` to disable
`iframeServer`	`Partial<IframeChildTransportOptions> \| false`	Auto	Iframe transport options, or `false` to disable

Transport is auto-selected based on context:

Context	Transport Used
Inside an iframe	`IframeChildTransport`
Main window	`TabServerTransport`

// Restrict to specific origins
initializeWebModelContext({
  transport: {
    tabServer: { allowedOrigins: ['https://myapp.com'] },
  },
});

// Disable tab transport (iframe only)
initializeWebModelContext({
  transport: { tabServer: false },
});

Methods on `document.modelContext`

After initialization, document.modelContext is a BrowserMcpServer instance. It exposes: Strict WebMCP methods (mirrored to native/polyfill):

Method	Description
`registerTool(tool, options?)`	Add a single tool
`getTools()`	List producer tool descriptors
`executeTool(tool, inputArgsJson)`	Execute a producer tool descriptor

Extension methods (MCP-B only):

Method	Description
`listTools()`	List registered tools
`callTool(params)`	Deprecated compatibility execution helper
`unregisterTool(name)`	Deprecated compatibility removal helper
`registerResource(descriptor)`	Register an MCP resource
`registerPrompt(descriptor)`	Register an MCP prompt
`createMessage(params)`	Request LLM sampling
`elicitInput(params)`	Request user input

For the MCP-B-only methods on document.modelContext, see @mcp-b/webmcp-ts-sdk reference. For the standard-owned browser surface, see WebMCP standard API.

Tool routing

@mcp-b/global mirrors the strict tool lifecycle down to the underlying native or polyfill context so browser-facing tooling can still see registered tools. During initialization it can also backfill existing tools from navigator.modelContextTesting when that shim is available.

Type exports

import type {
  CallToolResult,
  InputSchema,
  ModelContext,
  ModelContextCore,
  ModelContextOptions,
  NativeModelContextBehavior,
  ToolAnnotations,
  ToolDescriptor,
  ToolListItem,
  ToolResponse,
  TransportConfiguration,
  WebModelContextInitOptions,
} from '@mcp-b/global';

@mcp-b/webmcp-polyfill — Strict core polyfill (used internally)
@mcp-b/webmcp-ts-sdk — BrowserMcpServer (used internally)
@mcp-b/transports — Tab and iframe transports (used internally)
@mcp-b/webmcp-types — Type definitions

Packages

WebMCP standard

Core runtime

React

Tooling

@mcp-b/global

Package selection

Installation

Minimal example

Auto-initialization

Functions

`initializeWebModelContext(options?)`

`cleanupWebModelContext()`

Configuration

`WebModelContextInitOptions`

`TransportConfiguration`

Methods on `document.modelContext`

Tool routing

Type exports

​Package selection

​Installation

​Minimal example

​Auto-initialization

​Functions

​initializeWebModelContext(options?)

​cleanupWebModelContext()

​Configuration

​WebModelContextInitOptions

​TransportConfiguration

​Methods on document.modelContext

​Tool routing

​Type exports

​Related packages

Package selection

Installation

Minimal example

Auto-initialization

Functions

`initializeWebModelContext(options?)`

`cleanupWebModelContext()`

Configuration

`WebModelContextInitOptions`

`TransportConfiguration`

Methods on `document.modelContext`

Tool routing

Type exports

Related packages