@mcp-b/global reference

@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, application code continues through the package-supported document.modelContext surface. The installed runtime object also supports MCP-B extensions, but the global TypeScript declaration stays limited to the package’s browser contracts. Narrow document.modelContext explicitly when you opt into those 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

Auto-initialization

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

Configure before the IIFE

<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:

Disable auto-initialization

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

Functions

`initializeWebModelContext(options?)`

Initializes the global adapter and installs it on document.modelContext.

Initializer signature

initializeWebModelContext(options?: WebModelContextInitOptions): void

Manual initialization

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

initializeWebModelContext();

Behavior:

Returns nothing in every environment.
Does nothing outside a secure browser environment (SSR safe).
Repeated calls and calls after another bundle initialized the runtime are no-ops.
Returns before native-tool synchronization and transport connection finish.
Continues to transport connection when initial native-tool synchronization fails.
Logs a transport connection failure, starts closing the adapter, and restores the previous context.

Initialization captures the current document context, wraps it with a BrowserMcpServer, replaces document.modelContext, then starts native-tool reconciliation and transport connection asynchronously. See Runtime layering for why the wrapper is installed without changing application usage.

`cleanupWebModelContext()`

Restores the native or polyfilled context immediately and starts closing the adapter and transport. It does not uninstall @mcp-b/webmcp-polyfill; the polyfill owns its lifecycle separately.

Cleanup

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
`installTestingShim`	`boolean`	`true`	Installs the MCP-B `navigator.modelContextTesting` shim when no implementation exists

`TransportConfiguration`

Option	Type	Default	Description
`tabServer`	`TabServerTransportOptions \| false`	Auto	Tab transport options, or `false` to disable
`iframeServer`	`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`

When omitted, allowedOrigins defaults to ['*'] on the selected transport. Disabling both eligible transports makes initialization throw before document.modelContext is replaced.

Manual transport configuration

window.__webModelContextOptions = { autoInitialize: false };

const { initializeWebModelContext } = await import('@mcp-b/global');
initializeWebModelContext({
  transport: {
    tabServer: { allowedOrigins: ['https://myapp.com'] },
  },
});

Set autoInitialize before importing the package. Static imports run package initialization before the importing module’s body.

Canonical document surface

After initialization, use document.modelContext for browser-facing WebMCP registration, discovery, and events. The installed runtime exposes: WebMCP tool members (mirrored to native/polyfill):

Member	Description
`registerTool(tool, options?)`	Add a tool and return `Promise<void>`
`getTools(options?)`	Resolve registered producer descriptors
`ontoolchange`	Observe changes to the available tool list

Serialized execution compatibility:

Method	Description
`executeTool(tool, inputArgsJson, options?)`	Execute a descriptor returned by `getTools()`

Extension methods (MCP-B only):

Member	Description
`listTools()`	List locally registered tools
`registerResource(descriptor)`	Register an MCP resource
`registerPrompt(descriptor)`	Register an MCP prompt
`mcpServer`	Access the official high-level MCP server object

TypeScript users can narrow the canonical surface without widening the global declaration:

Narrow MCP-B extensions

import '@mcp-b/global';
import { isBrowserMcpServer } from '@mcp-b/webmcp-ts-sdk';

const modelContext = document.modelContext;
if (!isBrowserMcpServer(modelContext)) {
  throw new Error('MCP-B extensions are unavailable');
}

const mcpTools = modelContext.listTools();

Add @mcp-b/webmcp-ts-sdk as a direct dependency when importing its guard or extension types. Sampling and elicitation are not direct BrowserMcpServer methods. Legacy push-style SDK APIs live on modelContext.mcpServer.server after narrowing. They remain sensitive to the negotiated protocol revision. For the MCP-B-only server members, see @mcp-b/webmcp-ts-sdk reference. For the proposed browser surface, see WebMCP API sources.

Tool routing

@mcp-b/global mirrors registrations down to the underlying native or polyfill context so browser-facing tooling can still see them. Initial reconciliation uses the underlying context’s asynchronous getTools() method and requires its descriptor-based, serialized-JSON executeTool() signature. Later toolchange events trigger another reconciliation. The MCP-B testing shim is not a native-tool discovery source. The live WebMCP proposal currently specifies an object-input executeTool() signature. This reference describes the package behavior.

Type exports

Type imports

import type { TransportConfiguration, WebModelContextInitOptions } from '@mcp-b/global';

@mcp-b/webmcp-polyfill — Tool registration and discovery 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 platforms and agents

Core runtime

React

Tooling

Installation

Minimal example

Auto-initialization

Functions

`initializeWebModelContext(options?)`

`cleanupWebModelContext()`

Configuration

`WebModelContextInitOptions`

`TransportConfiguration`

Canonical document surface

Tool routing

Type exports

​Installation

​Minimal example

​Auto-initialization

​Functions

​initializeWebModelContext(options?)

​cleanupWebModelContext()

​Configuration

​WebModelContextInitOptions

​TransportConfiguration

​Canonical document surface

​Tool routing

​Type exports

​Related packages

Installation

Minimal example

Auto-initialization

Functions

`initializeWebModelContext(options?)`

`cleanupWebModelContext()`

Configuration

`WebModelContextInitOptions`

`TransportConfiguration`

Canonical document surface

Tool routing

Type exports

Related packages