> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mcp-b.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# @mcp-b/global reference

> Reference for the full MCP-B runtime entry point: initialization, cleanup, transport, and configuration.

`@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](/reference/webmcp/standard-api). The installed runtime object also supports [MCP-B extensions](/packages/webmcp-ts-sdk/reference), but the global TypeScript declaration stays limited to the package's browser contracts. Narrow `document.modelContext` explicitly when you opt into those extensions.

## Installation

<CodeGroup>
  ```bash npm theme={null}
  npm install @mcp-b/global
  ```

  ```bash pnpm theme={null}
  pnpm add @mcp-b/global
  ```

  ```html title="Script tag (IIFE)" theme={null}
  <script src="https://unpkg.com/@mcp-b/global@6/dist/index.iife.js"></script>
  ```

  ```html title="ES module" theme={null}
  <script type="module">
    import '@mcp-b/global';
  </script>
  ```
</CodeGroup>

## Minimal example

```ts title="Register a tool" theme={null}
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`.

```html title="Configure before the IIFE" theme={null}
<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:

```html title="Disable auto-initialization" theme={null}
<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`.

```ts title="Initializer signature" theme={null}
initializeWebModelContext(options?: WebModelContextInitOptions): void
```

```ts title="Manual initialization" theme={null}
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](/explanation/architecture/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.

```ts title="Cleanup" theme={null}
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.

```ts title="Manual transport configuration" theme={null}
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:

```ts title="Narrow MCP-B extensions" theme={null}
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](/packages/webmcp-ts-sdk/reference). For the proposed browser surface, see [WebMCP API sources](/reference/webmcp/standard-api).

***

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

```ts title="Type imports" theme={null}
import type { TransportConfiguration, WebModelContextInitOptions } from '@mcp-b/global';
```

***

## Related packages

* [`@mcp-b/webmcp-polyfill`](/packages/webmcp-polyfill/reference) -- Tool registration and discovery polyfill (used internally)
* [`@mcp-b/webmcp-ts-sdk`](/packages/webmcp-ts-sdk/reference) -- BrowserMcpServer (used internally)
* [`@mcp-b/transports`](/packages/transports/reference) -- Tab and iframe transports (used internally)
* [Upstream `webmcp-types`](https://github.com/webmachinelearning/webmcp-types) -- Core browser declarations


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.