---

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, inputJson)     Execute a discovered tool

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, document.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:

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 }
  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

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

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
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/dist/index.iife.js"></script>
<script>
  document.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                                           │
│  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 — 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	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	npm	document.modelContext polyfill, with a deprecated navigator alias
@mcp-b/webmcp-types	npm	TypeScript definitions for the WebMCP core API
@mcp-b/global	npm	Full runtime — polyfill + MCP bridge (prompts, resources, sampling)
@mcp-b/webmcp-ts-sdk	npm	Browser-adapted MCP TypeScript SDK with dynamic tool registration

Transports & Composition

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

React

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

Browser Tooling

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

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                                            │
│  document.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, getTools, executeTool)│
├──────────────────────────────────────────────────────────┤
│  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, 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
AGENTS.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