@mcp-b/webmcp-polyfill

Reference for the strict WebMCP core polyfill that installs navigator.modelContext.

@mcp-b/webmcp-polyfill installs the strict WebMCP runtime on navigator.modelContext when no native implementation exists. It is the package to use when you want the browser standard in browsers today without MCP-B extensions.

npm install @mcp-b/webmcp-polyfill

Package selection

Package	Use When
@mcp-b/webmcp-types	You need compile-time types only (no runtime)
@mcp-b/webmcp-polyfill	You want the WebMCP standard path in browsers today
@mcp-b/global	You want the MCP-B runtime layer on top of that path

---

Minimal example

Functions

initializeWebMCPPolyfill(options?)

Installs the strict core polyfill on navigator.modelContext.

import { initializeWebMCPPolyfill } from '@mcp-b/webmcp-polyfill';

initializeWebMCPPolyfill();

Behavior:

• No-op in non-browser environments.
• Non-destructive: if navigator.modelContext already exists (native or from a previous install), initialization is skipped.
• Safe to call repeatedly.

Options

Option	Type	Default	Description
autoInitialize	boolean	true	Set false to disable auto-init from IIFE/import side effect.
installTestingShim	boolean | 'always' | 'if-missing'	'if-missing'	Controls whether navigator.modelContextTesting is installed.
disableIframeTransportByDefault	boolean	-	Deprecated no-op, kept for backward compatibility.

installTestingShim values

Value	Behavior
true or 'if-missing'	Install only when modelContextTesting is not already present
'always'	Install even when modelContextTesting already exists
false	Do not install

initializeWebModelContextPolyfill(options?)

Alias for initializeWebMCPPolyfill.

cleanupWebMCPPolyfill()

Restores previous navigator.modelContext and navigator.modelContextTesting property descriptors and resets the polyfill install state.

import { cleanupWebMCPPolyfill } from '@mcp-b/webmcp-polyfill';

cleanupWebMCPPolyfill();

---

IIFE / script tag

The IIFE build auto-initializes on load. Configure via window.__webMCPPolyfillOptions:

<script>
  window.__webMCPPolyfillOptions = {
    installTestingShim: 'if-missing',
  };
</script>
<script src="https://unpkg.com/@mcp-b/webmcp-polyfill@latest/dist/index.iife.js"></script>

---

Methods on navigator.modelContext

After initialization, navigator.modelContext exposes these methods:

registerTool(tool)

Adds a single tool to the registry.

• Requires a non-empty name, non-empty description, and execute function.
• Throws on duplicate tool names.
• If inputSchema is omitted, defaults to { type: "object", properties: {} }.

unregisterTool(name)

Removes a tool by name. Unknown names are a no-op.

The polyfill does not provide listTools() or callTool() on navigator.modelContext. For tool listing and execution, use navigator.modelContextTesting (when the testing shim is enabled) or switch to @mcp-b/global.

---

Testing shim

When installTestingShim is enabled, the polyfill installs navigator.modelContextTesting with the standard testing API:

Method	Returns
listTools()	ModelContextTestingToolInfo[]
executeTool(toolName, inputArgsJson, options?)	Promise<string | null>
registerToolsChangedCallback(callback)	void
getCrossDocumentScriptToolResult()	Promise<string> (always "[]" in polyfill)

initializeWebMCPPolyfill({ installTestingShim: true });

const tools = navigator.modelContextTesting?.listTools();
const result = await navigator.modelContextTesting?.executeTool(
  'search',
  JSON.stringify({ query: 'webmcp' })
);

For full details on the testing API, see WebMCP standard API.

---

Input schema support

The polyfill accepts three formats for inputSchema:

Format	Description
Plain JSON Schema	InputSchema object
Standard Schema v1 validator	Object with ~standard.validate() (e.g., Zod 4)
Standard JSON Schema v1	Object with ~standard.jsonSchema.input()

Standard JSON Schema conversion is attempted with targets draft-2020-12 first, then draft-07. When both Standard validator and Standard JSON Schema are present on the same object, JSON conversion is preferred.

---

Validation

The polyfill validates tool descriptors on registration:

Condition	Error
tool is not an object	TypeError: registerTool(tool) requires a tool object
name is empty or not a string	TypeError: Tool "name" must be a non-empty string
description is empty or not a string	TypeError: Tool "description" must be a non-empty string
execute is not a function	TypeError: Tool "execute" must be a function
Duplicate tool name	Error: Tool already registered: <name>
Invalid JSON Schema structure	Error: Invalid JSON Schema at <path>: <details>
Schema not JSON-serializable	Error: Invalid JSON Schema at <path>: schema must be JSON-serializable

Input arguments are validated at execution time using JSON Schema validation (via @cfworker/json-schema). Standard Schema validators are used when available.

---

Type inference

For compile-time type inference, pair the polyfill with @mcp-b/webmcp-types:

import type { JsonSchemaForInference } from '@mcp-b/webmcp-types';
import { initializeWebMCPPolyfill } from '@mcp-b/webmcp-polyfill';

initializeWebMCPPolyfill();

const inputSchema = {
  type: 'object',
  properties: {
    query: { type: 'string' },
    limit: { type: 'integer', minimum: 1, maximum: 50 },
  },
  required: ['query'],
  additionalProperties: false,
} as const satisfies JsonSchemaForInference;

navigator.modelContext.registerTool({
  name: 'search',
  description: 'Search indexed docs',
  inputSchema,
  async execute(args) {
    // args inferred as: { query: string; limit?: number }
    return { content: [{ type: 'text', text: `Searching for ${args.query}` }] };
  },
});

For full inference documentation, see @mcp-b/webmcp-types.

---

Interop with @mcp-b/global

If the polyfill is installed first, @mcp-b/global wraps the existing context with BrowserMcpServer to add MCP-B extension APIs without replacing the core object identity. Use @mcp-b/global directly when you need callTool, resources, prompts, or transport. For guidance on choosing between them, see Choose a Runtime. For the layering rationale, see Native vs Polyfill vs Global.