@mcp-b

Polyfill and MCP bridge for the Web Model Context API (navigator.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:

navigator.modelContext
├── .registerTool(tool)       Register a tool for AI agents
├── .unregisterTool(name)     Remove a tool
├── .provideContext(options)   Set tools (replaces existing)
└── .clearContext()            Remove all tools

MCP-b polyfills that API for all browsers today, and bridges it to the full Model Context Protocol — turning that tool source into a complete MCP server with prompts, resources, sampling, and 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 with --enable-experimental-web-platform-features, navigator.modelContext is already there. Just use it:

Add @mcp-b/webmcp-types (pnpm add -D @mcp-b/webmcp-types) for full input/output schema inference:

navigator.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 }
  outputSchema: {                         // ← optional — infers return type
    type: 'object',
    properties: { id: { type: 'number' }, title: { type: 'string' } },
    required: ['id', 'title'],
  } as const,
  execute: async (args) => ({ id: Date.now(), title: args.title }),
});

2. Polyfill it

Want it to work in any browser without the Chrome flag? Add the polyfill — same API, same code:

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

initializeWebMCPPolyfill(); // no-op if native support exists

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

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, sampling, transports, interop with Claude Desktop / Cursor / any MCP client? Use @mcp-b/global:

import '@mcp-b/global'; // pnpm add @mcp-b/global

// Same registerTool API — now backed by a full MCP server
navigator.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/dist/index.iife.js"></script>
<script>
  navigator.modelContext.registerTool({ /* ... */ });
</script>

Or with React: pnpm add @mcp-b/react-webmcp

import { useWebMCP } from '@mcp-b/react-webmcp';

function TodoApp({ todos, addTodo }) {
  useWebMCP({
    name: 'add_todo',
    description: 'Add a new todo item',
    schema: { title: z.string().describe('Todo title') },
    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                                           │
│  navigator.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 from docs.mcp-b.ai/extension. Discovers tools on any page.

Chrome Native — 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?

I want to…	Package
Add tools to my site (simplest)	@mcp-b/global
Just the polyfill, no MCP bridge	@mcp-b/webmcp-polyfill
Register tools from React	@mcp-b/react-webmcp
Forward tools to local AI agents	@mcp-b/webmcp-local-relay
Build a Chrome extension with tools	@mcp-b/extension-tools
Control Chrome from an AI agent	@mcp-b/chrome-devtools-mcp
Just the TypeScript types	@mcp-b/webmcp-types

---

Installation

# Full runtime: polyfill + MCP bridge (most users start here)
pnpm add @mcp-b/global

# Strict WebMCP core polyfill only (no MCP extensions)
pnpm add @mcp-b/webmcp-polyfill

# TypeScript definitions (dev dependency)
pnpm add -D @mcp-b/webmcp-types

# React hooks for full runtime
pnpm add @mcp-b/react-webmcp zod

# React hooks for strict WebMCP core only
pnpm add usewebmcp zod

# Transport layer (custom integrations)
pnpm add @mcp-b/transports

# Chrome Extension API tools
pnpm add @mcp-b/extension-tools

# DOM extraction for AI
pnpm add @mcp-b/smart-dom-reader

All Packages

Core

Package	Version	Description
@mcp-b/webmcp-polyfill		navigator.modelContext polyfill — strict spec-aligned surface
@mcp-b/webmcp-types		TypeScript definitions for the WebMCP core API
@mcp-b/global		Full runtime — polyfill + MCP bridge (prompts, resources, sampling)
@mcp-b/webmcp-ts-sdk		Browser-adapted MCP TypeScript SDK with dynamic tool registration

Transports & Composition

Package	Version	Description
@mcp-b/transports		postMessage, iframe, and Chrome extension transports
@mcp-b/mcp-iframe		<mcp-iframe> web component — surfaces iframe tools to the parent page
@mcp-b/webmcp-local-relay		Localhost relay — forwards website tools to Claude Desktop, Cursor, etc.

React

Package	Version	Description
@mcp-b/react-webmcp		React hooks for full runtime (register tools + consume MCP servers)
usewebmcp		React hooks for strict WebMCP core only

Browser Tooling

Package	Version	Description
@mcp-b/extension-tools		Pre-built MCP tools for Chrome Extension APIs (tabs, bookmarks, history, …)
@mcp-b/smart-dom-reader		Token-efficient DOM extraction for AI agents
@mcp-b/chrome-devtools-mcp		MCP server for Chrome DevTools with WebMCP integration

Deprecated packages

Package	Status	Migration
@mcp-b/mcp-react-hooks	Deprecated	Use @mcp-b/react-webmcp instead
@mcp-b/mcp-react-hook-form	Removed	Use custom useWebMCP wrappers

Architecture

┌──────────────────────────────────────────────────────────┐
│  Your web app                                            │
│  navigator.modelContext.registerTool({ ... })             │
├────────────── @mcp-b/global ─────────────────────────────┤
│  MCP bridge: prompts, resources, sampling, elicitation   │
├────────────── @mcp-b/webmcp-ts-sdk ──────────────────────┤
│  BrowserMcpServer — wraps native/polyfill context        │
├────────────── @mcp-b/webmcp-polyfill ────────────────────┤
│  Strict WebMCP core (registerTool, provideContext, …)    │
├──────────────────────────────────────────────────────────┤
│  Native browser API (when available)                     │
└──────────────────────────────────────────────────────────┘
         ▲                              ▲
         │ postMessage / extension      │ WebSocket
         ▼                              ▼
   AI agent in browser            Local AI agent
   (extension, tab)          (Claude Desktop, Cursor)

Dependency Graph

webmcp-types          (canonical type definitions)
├── webmcp-polyfill   (canonical runtime polyfill)
├── webmcp-ts-sdk     (TypeScript SDK adapter)
├── transports        (browser transports)
│   ├── mcp-iframe    (iframe custom element)
│   └── global        (full MCP-B runtime)
│       └── react-webmcp (React hooks for MCP-B)
└── usewebmcp         (React hooks for strict core)

Standalone packages: extension-tools, smart-dom-reader, chrome-devtools-mcp, webmcp-local-relay.

Development

git clone https://github.com/WebMCP-org/npm-packages.git
cd npm-packages
pnpm install
pnpm build

Command	What it does
pnpm build	Build all packages
pnpm typecheck	Type-check all packages
pnpm check	Lint + format (Biome)
pnpm test:unit	Unit tests
pnpm test:e2e	E2E tests (Playwright)
pnpm test	All tests
pnpm --filter <pkg> build	Build a single package
pnpm --filter <pkg> test	Test a single package
pnpm changeset	Create a changeset for versioning

Prerequisites: Node.js >= 22.12 (see .nvmrc), pnpm >= 10

Documentation

Document	Purpose
CONTRIBUTING.md	How to contribute: setup, PR process, commit format
CLAUDE.md	Quick reference for AI agents working in this repo
Package Philosophy	Package boundaries and layering model
Testing Philosophy	Test layers, mocking policy, coverage expectations
E2E Testing	Playwright setup, test apps, debugging
@mcp-b/global guide	Advanced usage for the full runtime
@mcp-b/react-webmcp guide	Advanced React patterns
WebMCP Alignment Matrix	Spec vs native vs polyfill parity tracking
AI Contribution Manifesto	Safety rules and code quality bar
Relevant Links	Curated external best practices for contributors

Contributing

Contributions welcome — see CONTRIBUTING.md for guidelines.

License

MIT

Links

• MCP-b Documentation
• MCP-b Browser Extension
• W3C WebMCP Spec
• W3C Web Machine Learning Community Group
• Model Context Protocol Specification
• Chromium WebMCP Implementation
• npm: @mcp-b
• GitHub Repository
• Issue Tracker