@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?

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

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

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

Documentation

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