> ## 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 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, `document.modelContext` still supports the [strict WebMCP surface](/reference/webmcp/standard-api), but it also exposes [MCP-B extension methods](/packages/webmcp-ts-sdk/reference) 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](/explanation/strict-core-vs-mcp-b-extensions).

***

## Installation

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

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

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

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

## Minimal example

<Snippet file="snippets/packages/global-quickstart.ts" />

| 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`.

```html theme={null}
<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:

```html theme={null}
<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.

```ts theme={null}
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:**

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

### `cleanupWebModelContext()`

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

```ts 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                                                      |
| `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`   |

```ts theme={null}
// 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](/packages/webmcp-ts-sdk/reference). For the standard-owned browser surface, see [WebMCP standard API](/reference/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

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

***

## Related packages

* [`@mcp-b/webmcp-polyfill`](/packages/webmcp-polyfill/reference) -- Strict core 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)
* [`@mcp-b/webmcp-types`](/packages/webmcp-types/reference) -- Type definitions