Using the @mcp-b/global Polyfill for Cross-Browser WebMCP Today
You do not have to wait for Chrome Stable. The @mcp-b/global polyfill implements the full navigator.modelContext surface today, in every evergreen browser.
The WebMCP native API is only in Chrome 146 Canary as of April 2026. That's fine for dogfooding but not for production. The @mcp-b/global polyfill fills the gap — it implements the same navigator.modelContext surface on top of a postMessage + extension-bridge architecture, which means Chrome Stable, Edge, Firefox, and Safari can all serve as WebMCP targets today.
Why a polyfill for a browser API?
Browser APIs usually ship as spec → Chromium implementation → Firefox/Safari implementation, and adoption lags 12–24 months. WebMCP is important enough to the AI ecosystem that the community didn't wait. The polyfill team built @mcp-b/global to mirror the spec surface so code you write today runs unchanged when native support arrives.
Install
npm install @mcp-b/global
# or
pnpm add @mcp-b/global
# or via CDN
<script src="https://cdn.jsdelivr.net/npm/@mcp-b/global/dist/global.min.js"></script>In a bundled app, import once at the top of your entry file:
import "@mcp-b/global"; // attaches navigator.modelContext if absentThat's it — the polyfill is now a no-op on browsers that already have native support and an active implementation on browsers that don't.
Feature-detect the right way
Even with the polyfill installed, always gate registration on the presence check. That lets you strip the polyfill later without breaking code:
if ("modelContext" in navigator) {
navigator.modelContext.registerTool({ /* ... */ });
}How the polyfill actually works
On native browsers, nothing. On non-native browsers, it does two things:
- Adds
navigator.modelContextas a shim that stores tool definitions and fires the standard events. - Exposes those definitions to any cooperating browser extension or companion agent via
postMessageand a well-known channel ID.
The practical consequence: non-native browsers only benefit from WebMCP if the user has an agent extension installed that speaks the polyfill's bridge protocol. Chrome native needs no extension.
Testing your polyfilled setup
You can drive the polyfill from the JavaScript console:
// Confirm registration surfaces
console.log(Object.keys(navigator.modelContext));
// Invoke a tool manually
navigator.modelContext.__invokeForTesting("searchProducts", { query: "shoes" })
.then(result => console.log(result));The __invokeForTesting hook only exists on the polyfill — it will throw on native. Wrap it in if ("__invokeForTesting" in navigator.modelContext) if you reuse the helper in tests.
Production deployment checklist
- Load the polyfill synchronously in <head> if you have WebMCP bindings in above-the-fold UI.
- Subset the bundle: the polyfill is ~8KB gzipped, but tree-shaking works only if you import from the submodule path.
- Pin to a minor version in production (
^1.4.0) so breaking changes don't ship unattended. - Log polyfill usage via
navigator.modelContext.__isPolyfill— useful for analytics segmentation.
Gotchas I've hit in production
- Content Security Policy. The polyfill needs
'unsafe-inline'on some CDN setups or a nonce. Audit your CSP before shipping. - SSR frameworks (Next.js, Nuxt). Guard all registerTool calls in a
typeof navigator !== "undefined"check; the polyfill runs only in the browser. - Shadow DOM. Tools registered from inside a shadow root are discovered, but
provideContext()data from shadow components is not bubbled by default — pass context through the root. - Double polyfill. If a browser extension already installed a shim, the library detects and yields. Don't fight it.
When to drop the polyfill
Once Chrome Stable, Edge Stable, and Firefox Nightly all ship native support, you can remove the polyfill for ~60% of your traffic without breaking anything — all your code still runs through feature detection. Safari will likely be last; keep the polyfill loaded conditionally (if (isSafari)) for another release cycle. Treat the polyfill as a migration aid, not permanent infrastructure — it belongs on your 14-point readiness checklist under "optional but recommended," not as a hard dependency.
For how the API works under the hood, see the navigator.modelContext reference. For the broader implementation plan, read the full guide.
Frequently Asked Questions
Is the polyfill maintained by Google?
No. @mcp-b/global is a community project. Google maintains the Chrome native implementation, but the polyfill is independent and open source.
Does the polyfill work on mobile browsers?
The JS shim loads, but discovery requires a cooperating agent. Most mobile browsers today lack an agent layer, so the polyfill is practically useful mainly on desktop browsers with an agent extension installed.
Can I ship the polyfill to users on Chrome Canary?
Yes — it detects native support and becomes a no-op. You never have to branch your code by browser.
What is the bundle size?
Approximately 8KB gzipped as of v1.4. Tree-shake by importing from the submodule path if you only need tool registration, not the full event bridge.
Will my code need changes when Chrome Stable launches?
Almost certainly none. The polyfill mirrors the spec surface; Chrome Stable will expose the same methods and fire the same events. Your feature-detection guard handles the switch automatically.
Is your site ready for AI agents?
Run a free WebMCP readiness audit in 15 seconds — no signup.
Run Free Audit →