WebMCP Documentation - AI-Powered Web Tools

A

AI Agent

A software program powered by large language models (LLMs) that can understand natural language, make decisions, and execute actions. In WebMCP, AI agents discover and call tools exposed by websites. Examples: Claude, ChatGPT, GitHub Copilot

Annotations

Metadata hints attached to tools that inform AI agents about tool behavior:

readOnlyHint: Tool only reads data (doesn’t modify state)
idempotentHint: Tool can be safely called multiple times with same result
destructiveHint: Tool performs irreversible actions (e.g., deletions)

B

Background Script

A service worker in a Chrome extension that runs in the background, independent of web pages. In WebMCP, it often acts as an MCP hub aggregating tools from multiple tabs. Location: Specified in manifest.json under background.service_worker

Base Tools (Bucket A)

Tools registered via provideContext() that define an application’s core functionality. These tools are replaced entirely each time provideContext() is called. Alternative: Dynamic Tools (Bucket B)

Bridge

See MCP Bridge

C

Client

An MCP client that connects to MCP servers to discover and call tools. Created using @modelcontextprotocol/sdk/client. Example:

import { Client } from '@modelcontextprotocol/sdk/client/index.js';

const client = new Client({
  name: 'my-client',
  version: '1.0.0'
});

Content Script

JavaScript code injected by a browser extension that runs in the context of a web page. Content scripts can access both the page’s DOM and limited extension APIs. Use in WebMCP: Acts as a bridge between page MCP servers and the extension background. Security mechanism that restricts web pages from making requests to different origins. WebMCP transports use origin validation to control which domains can connect.

D

Dynamic Tools (Bucket B)

Tools registered via registerTool() that persist independently of base tools. Each returns an unregister() function for cleanup. Best for: Component-scoped tools, lifecycle-managed tools, React/Vue components

E

Execute Function

The async function that implements a tool’s logic. Called when an AI agent invokes the tool. Signature:

async execute(args: TInput): Promise<ToolResponse>

Extension Transport

MCP transport implementation for communication between browser extension components (background, content scripts, popup, sidebar). Package: @mcp-b/transports Classes: ExtensionClientTransport, ExtensionServerTransport

H

Handler

Another term for the execute function in a tool definition. In React hooks (useWebMCP), referred to as handler.

I

Input Schema

JSON Schema or Zod schema defining the parameters a tool accepts. Used for validation and AI tool understanding. JSON Schema format:

{
  type: "object",
  properties: {
    name: { type: "string" }
  },
  required: ["name"]
}

Zod format:

{
  name: z.string()
}

M

MCP (Model Context Protocol)

An open standard protocol developed by Anthropic for connecting AI systems with data sources and tools. MCP standardizes how AI agents discover and interact with external capabilities. WebMCP is inspired by MCP but adapted specifically for web browsers as a W3C standard. Specification: https://modelcontextprotocol.io Documentation: https://modelcontextprotocol.io/docs GitHub: https://github.com/modelcontextprotocol

MCP-B

The reference implementation and tooling ecosystem for the WebMCP standard, originally created as the first browser port of MCP concepts. MCP-B packages serve two key purposes:

Polyfill the W3C WebMCP API (navigator.modelContext) for current browsers
Translation layer between WebMCP’s web-native API and the MCP protocol

This dual architecture allows:

Tools declared in WebMCP format to work with MCP clients
Tools declared in MCP format to work with WebMCP browsers
Version independence as both standards evolve
Web-specific security features (same-origin policy, CSP)

The name “MCP-B” refers to both the package ecosystem (@mcp-b/*) and the browser extension.

MCP-B Extension

Browser extension for building, testing, and using WebMCP servers. Key features:

Collects WebMCP servers from all open tabs
Userscript injection for custom tool development
Specialized agents (browsing, userscript, chat)

Download: Chrome Web Store

MCP Bridge

The internal component in @mcp-b/global that serves as both a polyfill and translation layer:

Implements the WebMCP navigator.modelContext API
Translates between WebMCP and MCP protocols
Allows tools declared in either format to work with both standards

Location: Created automatically when importing @mcp-b/global

MCP Hub

A centralized MCP server (typically in an extension background) that aggregates tools from multiple sources (tabs, native servers) and exposes them through a unified interface.

MCP Server

A server that exposes tools, resources, and prompts via the Model Context Protocol. Created using @modelcontextprotocol/sdk/server/mcp.js. Example:

import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';

const server = new McpServer({
  name: 'my-server',
  version: '1.0.0'
});

Manifest V3

The third version of Chrome’s extension platform. Required for modern Chrome extensions and WebMCP extension tools. Key changes: Service workers instead of background pages, improved security, declarative permissions.

N

Native Host

A local program that browser extensions can communicate with using native messaging. In WebMCP, the native host bridges extension tools to local MCP servers via HTTP/SSE. Package: @mcp-b/native-server

navigator.modelContext

The W3C Web Model Context API exposed on the browser’s navigator object. Provides registerTool() and provideContext() methods for tool registration. Status: Polyfilled by @mcp-b/global, proposed W3C standard

P

Polyfill

JavaScript code that implements modern browser features in older browsers. @mcp-b/global is a polyfill for the W3C Web Model Context API.

Port

In Chrome extensions, a long-lived connection between different extension components. Used by Extension Transport for persistent MCP communication. Creation:

const port = chrome.runtime.connect({ name: 'mcp' });

provideContext()

Method on navigator.modelContext for registering base tools. Replaces all base tools (Bucket A) each time it’s called. Usage: Top-level application tools only Syntax:

navigator.modelContext.provideContext({
  tools: [/* tool array */]
});

R

registerTool()

Recommended method on navigator.modelContext for registering individual tools. Returns an object with unregister() function. Usage: Most use cases, component-scoped tools Syntax:

const registration = navigator.modelContext.registerTool({
  name: "my_tool",
  description: "Tool description",
  inputSchema: {},
  async execute(args) {
    return { content: [{ type: "text", text: "Result" }] };
  }
});

// Later
registration.unregister();

Resource

In MCP, a resource is static or dynamic content (files, data, API responses) that servers can expose. WebMCP primarily focuses on tools, but resources are part of the broader MCP spec.

S

SDK (Software Development Kit)

The official MCP SDK provided by @modelcontextprotocol/sdk containing client and server implementations. Installation: npm install @modelcontextprotocol/sdk

Server

See MCP Server

Session

User authentication state maintained by the website. WebMCP tools automatically run with the user’s existing session (cookies, tokens, etc.). Benefit: No credential sharing needed between AI and website

T

Tab Transport

MCP transport implementation for communication within a browser tab using window.postMessage. Package: @mcp-b/transports Classes: TabClientTransport, TabServerTransport Use case: Website exposing tools to extension content scripts

Tool

A function or capability exposed via MCP that AI agents can discover and call. Defined by name, description, input schema, and execute function. Anatomy:

{
  name: "tool_name",              // Unique identifier
  description: "What it does",    // Human-readable description
  inputSchema: {},                // JSON Schema or Zod
  async execute(args) {           // Implementation
    return { content: [...] };
  },
  annotations: {}                 // Optional metadata
}

Tool Descriptor

An object defining a tool’s interface and behavior. Includes name, description, inputSchema, and execute function.

Tool Response

The object returned by a tool’s execute function, conforming to MCP response format:

{
  content: [
    {
      type: "text",      // or "image", "resource"
      text: "Result..."  // response content
    }
  ],
  isError: false        // optional error flag
}

Transport

An implementation of the MCP transport layer that handles message passing between clients and servers. Types in WebMCP:

TabClientTransport / TabServerTransport - In-page communication
ExtensionClientTransport / ExtensionServerTransport - Extension communication
InMemoryTransport - Testing

U

unregister()

Function returned by registerTool() to remove a dynamic tool from the registry. Example:

const reg = navigator.modelContext.registerTool({...});

// Later, clean up
reg.unregister();

Userscript

Custom JavaScript code that modifies web page behavior or appearance. The MCP-B Extension includes agents to help create MCP-powered userscripts.

W

W3C (World Wide Web Consortium)

International standards organization for the web. The Web Model Context API is a proposed W3C standard.

Web Model Context API

See WebMCP

WebMCP (Web Model Context Protocol)

A W3C web standard (currently being incubated by the Web Machine Learning Community Group) that defines how websites expose structured tools to AI agents through the browser’s navigator.modelContext API. Design Philosophy: Human-in-the-loop workflows where agents augment (not replace) user interaction. The human web interface remains primary. Not Designed For:

❌ Headless browsing or fully autonomous agents
❌ Backend service integration (use MCP for that)
❌ Replacing human-facing interfaces
❌ Workflows without user oversight

Architectural Approach: WebMCP is implemented as an SDK/abstraction layer (not just a transport), allowing browsers to maintain backwards compatibility as protocols evolve and enforce web-specific security models. While inspired by Anthropic’s Model Context Protocol, WebMCP is evolving as an independent web-native standard with its own specification path and design decisions. Relationship to MCP: WebMCP shares similar concepts (tools, resources, structured communication) but is diverging as a web-specific standard. Both protocols are complementary and can work together. W3C Specification: https://github.com/webmachinelearning/webmcp Technical Proposal: https://github.com/webmachinelearning/webmcp/blob/main/docs/proposal.md Community Group: https://www.w3.org/community/webmachinelearning/

Z

Zod

TypeScript-first schema validation library used with @mcp-b/react-webmcp for type-safe input validation. Example:

import { z } from 'zod';

const schema = {
  email: z.string().email(),
  age: z.number().min(0).max(120)
};

Acronyms

Acronym	Full Form	Description
AI	Artificial Intelligence	Computer systems that perform tasks requiring human intelligence
API	Application Programming Interface	Set of rules for software interaction
CORS	Cross-Origin Resource Sharing	Security feature controlling cross-domain requests
DOM	Document Object Model	Programming interface for web documents
IIFE	Immediately Invoked Function Expression	JavaScript function that runs immediately
JSON	JavaScript Object Notation	Lightweight data interchange format
LLM	Large Language Model	AI model trained on text data
MCP	Model Context Protocol	Protocol for AI-tool integration
NPM	Node Package Manager	Package manager for JavaScript
SDK	Software Development Kit	Tools for software development
SSE	Server-Sent Events	Standard for server push technology
UI	User Interface	Visual elements users interact with
W3C	World Wide Web Consortium	Web standards organization

Common Patterns

Tool Naming Conventions

Follow the domain_verb_noun or verb_noun pattern:

Good	Bad	Why
`posts_create`	`createPost`	Consistent, domain-prefixed
`graph_navigate_node`	`navigate`	Specific, clear purpose
`db_query_users`	`query`	Scoped to functionality
`search_products`	`search1`	Descriptive, not numbered

Response Patterns

Always return properly formatted responses:

// Success
{
  content: [{ type: "text", text: JSON.stringify(data) }]
}

// Error
{
  content: [{ type: "text", text: "Error message" }],
  isError: true
}

Core Concepts

Architecture and component overview

Quick Start

Get started with WebMCP

API Reference

Detailed package documentation

Examples

Real-world implementations

Understanding WebMCP

Core Features

Advanced Topics

Best Practices

Reference

​A

​AI Agent

​Annotations

​B

​Background Script

​Base Tools (Bucket A)

​Bridge

​C

​Client

​Content Script

​CORS (Cross-Origin Resource Sharing)

​D

​Dynamic Tools (Bucket B)

​E

​Execute Function

​Extension Transport

​H

​Handler

​I

​Input Schema

​M

​MCP (Model Context Protocol)

​MCP-B

​MCP-B Extension

​MCP Bridge

​MCP Hub

​MCP Server

​Manifest V3

​N

​Native Host

​navigator.modelContext

​P

​Polyfill

​Port

​provideContext()

​R

​registerTool()

​Resource

​S

​SDK (Software Development Kit)

​Server

​Session

​T

​Tab Transport

​Tool

​Tool Descriptor

​Tool Response

​Transport

​U

​unregister()

​Userscript

​W

​W3C (World Wide Web Consortium)

​Web Model Context API

​WebMCP (Web Model Context Protocol)

​Z

​Zod

​Acronyms

​Common Patterns

​Tool Naming Conventions

​Response Patterns

​Related Pages