---
description: "Installs a document.modelContext polyfill unless the browser already has one, and returns whichever ModelContext is active."
---

# `installWebMCPPolyfill`

Installs a `document.modelContext` polyfill unless the browser already has one, and returns whichever `ModelContext` is active. [`<WebAgentsProvider>`](/docs/reference/react/web-agents-provider) and [`createWebAgents`](/docs/reference/core/create-web-agents) call it for you, through [`loadWebMCPPolyfill`](/docs/reference/core/load-webmcp-polyfill); call it yourself only on a page that registers tools without them.

## Import

```ts
import { installWebMCPPolyfill } from "@webmcp-agents/core/polyfill";
```

## Example

Call it before any tool registers. Here it also lists the registered tools whenever they change.

```ts title="src/polyfill.ts"
import { installWebMCPPolyfill } from "@webmcp-agents/core/polyfill";

// For a page that registers tools without createWebAgents or the
// provider (they load it themselves). Does nothing where the browser
// already has document.modelContext, and returns the native one.
const modelContext = installWebMCPPolyfill();

modelContext?.addEventListener("toolchange", async () => {
  const tools = await modelContext.getTools();
  console.log(tools.map((tool) => tool.name));
});
```

When you do not need the return value, import [`@webmcp-agents/core/polyfill/auto`](/docs/reference/polyfill/auto) instead.

## Options

None. The function takes no arguments.

## Returns

`ModelContext | undefined`:

- The native `document.modelContext` when the browser has one. Nothing is installed.
- Otherwise a new [`PolyfillModelContext`](/docs/reference/polyfill/polyfill-model-context), defined on `document` as `modelContext` (configurable).
- `undefined` on the server (no `document`).

When it installs, it also starts declarative `<form toolname>` tools (found on install and with a `MutationObserver` on `document.documentElement`, including `toolautosubmit` and the confirmation pause) and logs `[web-agents] document.modelContext polyfilled: this browser has no native WebMCP` once.

## Notes

- Safe to call more than once: later calls return the installed instance.
- It steps aside when the browser has the real API. In a WebMCP-enabled Chrome you get Chrome's behaviour, including its event order and its cancelling of calls whose tool changes.
- Installed by hand, it must come before tools register: outside `createWebAgents` and the provider, `registerWebTool` without `document.modelContext` warns once and registers nothing. Tools that `createWebAgents` or the provider manage wait for the polyfill instead.
- Imported statically, it is in your main bundle; `loadWebMCPPolyfill` keeps it in a chunk that only browsers without WebMCP download.
- The declarative-form observer is never disconnected.
- `@webmcp-agents/polyfill` (deprecated) re-exports it, so `import { installWebMCPPolyfill } from "@webmcp-agents/polyfill"` keeps working.

## See also

- [Browsers without WebMCP](/docs/more/polyfill)
- [`loadWebMCPPolyfill`](/docs/reference/core/load-webmcp-polyfill), what the provider calls
- [`PolyfillModelContext`](/docs/reference/polyfill/polyfill-model-context)
- [`@webmcp-agents/core/polyfill/auto`](/docs/reference/polyfill/auto)
- [`isWebMCPAvailable`](/docs/reference/core/is-webmcp-available)
- [`WebAgentsProvider`](/docs/reference/react/web-agents-provider)