@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@6/dist/index.iife.js"></script>

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

Minimal example

import '@mcp-b/global';

if (!document.modelContext) throw new Error('WebMCP is unavailable');

await document.modelContext.registerTool({
  name: 'get_page_title',
  description: 'Get the current page title',
  inputSchema: { type: 'object', properties: {} },
  async execute() {
    return {
      content: [{ type: 'text', text: document.title }],
    };
  },
});

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@6/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@6/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. Closing the adapter aborts every registration made through document.modelContext while it was installed, and re-initializing does not restore them; tools registered directly on the underlying context, including declarative tools, survive. It does not uninstall @mcp-b/webmcp-polyfill or its temporary declarative layer; both remain for the document lifetime.

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

`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

WebMCP execution:

Method	Description
`executeTool(tool, inputObject, 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() and object-input executeTool(). Later toolchange events trigger another reconciliation.

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)
Upstream webmcp-types — Core browser declarations

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