@mcp-b
Polyfill and MCP bridge for the Web Model Context API (document.modelContext)
The Web Standard
The Web Model Context API is a W3C Community Group draft spec. It makes every browser tab a tool source — web pages register tools that AI agents can discover and call:
document.modelContext
├── .registerTool(tool, { signal }) Register a tool for AI agents
├── .getTools() Discover registered tools
└── .executeTool(tool, inputObject) Execute a discovered tool
MCP-b polyfills that API in browsers without native support (Chrome and Firefox 126+, Safari 18+), and bridges it to the full Model Context Protocol — turning that tool source into a complete MCP server with prompts, resources, and browser transports.
Built by MCP-b. Not an official W3C or MCP project.
Getting Started
1. Use the web standard directly
If you're running Chrome 155 or later with --enable-experimental-web-platform-features, document.modelContext is already there. Just use it:
Use upstream webmcp-types for core browser
contracts and input schema inference. MCP-B adapter extensions and schema helpers live in
@mcp-b/webmcp-ts-sdk.
if (!document.modelContext) throw new Error('WebMCP is unavailable');
await document.modelContext.registerTool({
name: 'add_todo',
description: 'Add a new todo item',
inputSchema: {
type: 'object',
properties: { title: { type: 'string' }, done: { type: 'boolean' } },
required: ['title'],
} as const, // ← args inferred: { title: string; done?: boolean }
execute: async (args) => ({ id: Date.now(), title: args.title }),
});
2. Polyfill it
Want it to work without the Chrome flag, including in Firefox and Safari? Add the polyfill — same API, same code:
import { installWebMCP } from '@mcp-b/webmcp-polyfill'; // pnpm add @mcp-b/webmcp-polyfill
installWebMCP(); // keeps native support when present
if (!document.modelContext) throw new Error('WebMCP is unavailable');
await document.modelContext.registerTool({
name: 'get_page_title',
description: 'Returns the current page title',
inputSchema: { type: 'object', properties: {} },
execute: async () => ({
content: [{ type: 'text', text: document.title }],
}),
});
Or with React: pnpm add usewebmcp
'use client';
import { useWebMCP } from 'usewebmcp';
function PageTitle() {
useWebMCP({
name: 'get_page_title',
description: 'Returns the current page title',
execute: async () => ({ title: document.title }),
});
// ...
}
3. Full MCP server
Need the full Model Context Protocol — prompts, resources, transports, and interop with Claude Desktop, Cursor, or another MCP client? Use @mcp-b/global:
import '@mcp-b/global'; // pnpm add @mcp-b/global
if (!document.modelContext) throw new Error('WebMCP is unavailable');
// Same registerTool API — now backed by a full MCP server
await document.modelContext.registerTool({
name: 'add_todo',
description: 'Add a new todo item',
inputSchema: {
type: 'object',
properties: {
title: { type: 'string', description: 'Todo title' },
},
required: ['title'],
},
execute: async (args) => {
const todo = { id: Date.now(), ...args };
return { content: [{ type: 'text', text: JSON.stringify(todo) }] };
},
});
Or as a script tag (zero build step):
<script src="https://unpkg.com/@mcp-b/global@6/dist/index.iife.js"></script>
<script type="module">
if (!document.modelContext) throw new Error('WebMCP is unavailable');
await document.modelContext.registerTool({
/* ... */
});
</script>
Or with React: pnpm add @mcp-b/global @mcp-b/react-webmcp
'use client';
import '@mcp-b/global';
import { useWebMCP } from '@mcp-b/react-webmcp';
function TodoApp({ todos, addTodo }) {
useWebMCP({
name: 'add_todo',
description: 'Add a new todo item',
inputSchema: {
type: 'object',
properties: {
title: { type: 'string', description: 'Todo title' },
},
required: ['title'],
} as const,
execute: async ({ title }) => {
addTodo(title);
return { success: true };
},
});
return (
<ul>
{todos.map((t) => (
<li key={t.id}>{t.title}</li>
))}
</ul>
);
}
Call Those Tools
Three ways for AI agents to discover and call your tools:
┌─────────────────────────────────────────────────────────┐
│ Your website │
│ document.modelContext.registerTool({ ... }) │
└────────┬────────────────────┬───────────────────┬───────┘
│ │ │
┌────▼─────┐ ┌────────▼────────┐ ┌─────▼──────┐
│ MCP-B │ │ Chrome Native │ │ Local │
│Extension │ │ (experimental) │ │ Relay │
└────┬─────┘ └────────┬────────┘ └─────┬──────┘
│ │ │
▼ ▼ ▼
AI agent in Browser's Claude Desktop
browser built-in agent Cursor, VS Code
MCP-B Extension — Install it from the Chrome Web Store. It discovers tools exposed by pages and connects them to extension-side agent experiences.
Chrome Native (Chrome 155 or later) — Enable at chrome://flags → Experimental Web Platform features, or:
google-chrome --enable-experimental-web-platform-features
See Chromium flags reference for macOS / Windows / Linux commands.
Local Relay — Add to your MCP client config (Claude Desktop, Cursor, etc.):
{
"mcpServers": {
"webmcp-local-relay": {
"command": "npx",
"args": ["-y", "@mcp-b/webmcp-local-relay@latest"]
}
}
}
Any website running @mcp-b/global becomes callable from your desktop AI agent. See the relay README for details.
Which Package?
Chrome DevTools integration now lives entirely upstream; its WebMCP changes have all landed there.
Installation
# Full runtime: polyfill + MCP bridge (most users start here)
pnpm add @mcp-b/global
# WebMCP polyfill with temporary declarative tools (no MCP bridge)
pnpm add @mcp-b/webmcp-polyfill
# Official WebMCP TypeScript definitions (dev dependency)
pnpm add -D [email protected]
# MCP-B adapter and schema helpers
pnpm add @mcp-b/webmcp-ts-sdk
# React hooks for full runtime
pnpm add @mcp-b/react-webmcp
# React hooks for the WebMCP core (JSON Schema only)
pnpm add usewebmcp
# Transport layer (custom integrations)
pnpm add @mcp-b/transports
# Chromium extension template and content-script client
pnpm add @mcp-b/global @mcp-b/webmcp-extension
# DOM extraction for AI
pnpm add @mcp-b/smart-dom-reader
All Packages
Core
Transports & Composition
React
Browser Tooling
Architecture
┌──────────────────────────────────────────────────────────┐
│ Your web app │
│ document.modelContext.registerTool({ ... }) │
├────────────── @mcp-b/global ─────────────────────────────┤
│ MCP bridge: prompts, resources, browser transports │
├────────────── @mcp-b/webmcp-ts-sdk ──────────────────────┤
│ BrowserMcpServer — wraps native/polyfill context │
├────────────── @mcp-b/webmcp-polyfill ────────────────────┤
│ WebMCP core + temporary declarative tools │
├──────────────────────────────────────────────────────────┤
│ Native browser API (when available) │
└──────────────────────────────────────────────────────────┘
▲ ▲
│ postMessage / extension │ WebSocket
▼ ▼
AI agent in browser Local AI agent
(extension, tab) (Claude Desktop, Cursor)
Dependency Graph
webmcp-types (upstream browser contracts)
├── @mcp-b/webmcp-types (compatibility alias)
├── usewebmcp (React hooks for strict core)
└── webmcp-polyfill (vendored upstream runtime)
└── webmcp-ts-sdk (MCP-B adapter, extensions, and schema helpers)
├── global (full runtime; also uses transports)
├── mcp-iframe (iframe element; also uses transports)
├── react-webmcp (also uses usewebmcp; pair with global at app level)
└── webmcp-local-relay (bundles SDK helpers into its browser scripts)
transports (browser transports shared by integrations)
└── webmcp-extension (MV3 template and isolated content-script client)
Standalone package: smart-dom-reader.
Development
git clone https://github.com/WebMCP-org/npm-packages.git
cd npm-packages
pnpm install
pnpm build
Prerequisites: Node.js >= 22.18 (see .nvmrc), pnpm >= 10
Documentation
Contributing
Contributions welcome — see CONTRIBUTING.md for guidelines.