WebMCP Documentation

Expose existing application functionality to AI agents while keeping your app’s own UI and state model intact. For framework-specific lifecycle patterns (React hooks, Vue composables, Svelte actions), see Integrate with your framework.

Install the runtime

If you have a build step, install @mcp-b/global from npm:

npm install @mcp-b/global

main.ts

import '@mcp-b/global';

If you do not have a build step, add a single script tag. Place it before any code that registers tools:

<script src="https://unpkg.com/@mcp-b/global@latest/dist/index.iife.js"></script>

Both approaches auto-initialize document.modelContext on load.

If you only need the strict core API (no MCP bridge, no transports), use @mcp-b/webmcp-polyfill instead. See Choose a Runtime for guidance.

Register tools that wrap existing functions

Identify functions in your app that an AI agent would find useful (search, add to cart, submit a form, fetch data). Wrap each one as a tool descriptor and register it.

Register tools with `registerTool`

Call registerTool for each tool you want to expose. You can register them all at startup or add them incrementally (for example, after user login or after a feature flag check).

tools.ts

import '@mcp-b/global';

await document.modelContext.registerTool({
  name: 'search-products',
  description: 'Search products by keyword, category, or price range',
  inputSchema: {
    type: 'object',
    properties: {
      query: { type: 'string', description: 'Search terms' },
      category: { type: 'string', description: 'Product category' },
      maxPrice: { type: 'number', description: 'Maximum price filter' },
    },
    required: ['query'],
  },
  async execute(args) {
    const results = await fetch(
      `/api/products?q=${args.query}&cat=${args.category ?? ''}&max=${args.maxPrice ?? ''}`
    );
    return { content: [{ type: 'text', text: await results.text() }] };
  },
});

await document.modelContext.registerTool({
  name: 'add-to-cart',
  description: 'Add a product to the shopping cart',
  inputSchema: {
    type: 'object',
    properties: {
      productId: { type: 'string' },
      quantity: { type: 'integer' },
    },
    required: ['productId'],
  },
  async execute(args) {
    await fetch('/api/cart', {
      method: 'POST',
      body: JSON.stringify({ productId: args.productId, quantity: args.quantity ?? 1 }),
    });
    return { content: [{ type: 'text', text: 'Added to cart' }] };
  },
});

Register tools conditionally

admin-tools.ts

import '@mcp-b/global';

if (currentUser.isAdmin) {
  await document.modelContext.registerTool({
    name: 'delete-user',
    description: 'Delete a user account (admin only)',
    inputSchema: {
      type: 'object',
      properties: { userId: { type: 'string' } },
      required: ['userId'],
    },
    async execute(args) {
      await fetch(`/api/users/${args.userId}`, { method: 'DELETE' });
      return { content: [{ type: 'text', text: 'User deleted' }] };
    },
  });
}

registerTool returns a rejected promise if a tool with the same name already exists. To update a tool, abort the previous registration signal, then await the new registration.

Update tools when app state changes

If your available tools depend on state (logged in vs. guest, current page, feature flags), update the registry when that state changes.

auth.ts

import type { ToolDescriptor } from '@mcp-b/webmcp-types';

const registeredToolControllers = new Map<string, AbortController>();

function registerRoleTool(tool: ToolDescriptor): Promise<void> {
  registeredToolControllers.get(tool.name)?.abort();

  const controller = new AbortController();
  registeredToolControllers.set(tool.name, controller);
  return document.modelContext.registerTool(tool, { signal: controller.signal });
}

async function onLogin(user: User) {
  // Register tools appropriate for the user's role
  for (const tool of getToolsForRole(user.role)) {
    await registerRoleTool(tool);
  }
}

function onLogout() {
  // Abort each registration signal
  for (const controller of registeredToolControllers.values()) {
    controller.abort();
  }
  registeredToolControllers.clear();
}

Use registerTool and an AbortController to add or remove individual tools:

registration-lifetime.ts

const controller = new AbortController();
await document.modelContext.registerTool(adminTool, { signal: controller.signal });

// later:
controller.abort();

Interact with the DOM

Tools can read from and write to the DOM. This is useful for form-filling, page navigation, or surfacing visible content.

form-tools.ts

const nameInput = document.querySelector<HTMLInputElement>('#name');
const emailInput = document.querySelector<HTMLInputElement>('#email');
const messageInput = document.querySelector<HTMLInputElement>('#message');
const contactForm = document.querySelector<HTMLFormElement>('#contact-form');

if (!nameInput || !emailInput || !messageInput || !contactForm) {
  throw new Error('Contact form is incomplete');
}

await document.modelContext.registerTool({
  name: 'fill-contact-form',
  description: 'Fill the contact form with provided details',
  inputSchema: {
    type: 'object',
    properties: {
      name: { type: 'string' },
      email: { type: 'string' },
      message: { type: 'string' },
    },
    required: ['name', 'email', 'message'],
  },
  async execute(args) {
    nameInput.value = args.name;
    emailInput.value = args.email;
    messageInput.value = args.message;
    return { content: [{ type: 'text', text: 'Form filled' }] };
  },
});

await document.modelContext.registerTool({
  name: 'submit-form',
  description: 'Submit the contact form',
  inputSchema: { type: 'object', properties: {} },
  async execute() {
    contactForm.requestSubmit();
    return { content: [{ type: 'text', text: 'Form submitted' }] };
  },
});

Return errors from tools

If a tool execution fails, return an error response instead of throwing. This gives the AI agent a structured signal to retry or adjust its approach.

tool-errors.ts

async execute(args) {
  try {
    const result = await riskyOperation(args);
    return { content: [{ type: 'text', text: JSON.stringify(result) }] };
  } catch (error) {
    const message = error instanceof Error ? error.message : String(error);
    return {
      content: [{ type: 'text', text: `Operation failed: ${message}` }],
      isError: true,
    };
  }
}

Add annotations for AI planning

Tool annotations give the AI agent hints about side effects. They do not change execution behavior, but help the agent decide when and how to call the tool.

Read-only tool annotations

await document.modelContext.registerTool({
  name: 'get-cart',
  title: 'Get shopping cart',
  description: 'Get the current shopping cart contents',
  inputSchema: { type: 'object', properties: {} },
  annotations: {
    readOnlyHint: true,
    untrustedContentHint: true,
  },
  async execute() {
    return { content: [{ type: 'text', text: JSON.stringify(getCart()) }] };
  },
});

The WebMCP draft standardizes readOnlyHint and untrustedContentHint. title is a top-level tool field. MCP-B runtimes also accept the MCP-specific destructiveHint, idempotentHint, and openWorldHint annotations for MCP clients. Annotations are planning hints, not authorization checks.

Verify tools are registered

Use standard discovery, then feature-detect Chrome’s optional execution extension:

import type { ChromeModelContext } from '@mcp-b/webmcp-types';

const modelContext = document.modelContext as ChromeModelContext;
const tools = await modelContext.getTools();
const searchTool = tools.find((tool) => tool.name === 'search-products');
if (!searchTool) throw new Error('search-products is not available');

const executeTool = modelContext.executeTool;
if (!executeTool) throw new Error('This runtime does not expose Chrome executeTool');

const resultJson = await executeTool.call(
  modelContext,
  searchTool,
  JSON.stringify({ query: 'laptop' })
);
const result = resultJson === null ? null : JSON.parse(resultJson);

Next steps

Use Schemas and Structured Output to add type-safe input validation and structured responses.
Choose a Runtime if you are unsure whether @mcp-b/global is the right package.
Framework integration guide for framework-specific patterns.
Debug and Troubleshoot if tools are not appearing to AI agents.

How-To Guides

Adoption

Frameworks

Connectivity

Add Tools to an Existing App

Install the runtime

Register tools that wrap existing functions

Register tools with `registerTool`

Register tools conditionally

Update tools when app state changes

Interact with the DOM

Return errors from tools

Add annotations for AI planning

Verify tools are registered

Next steps

​Install the runtime

​Register tools that wrap existing functions

​Register tools with registerTool

​Register tools conditionally

​Update tools when app state changes

​Interact with the DOM

​Return errors from tools

​Add annotations for AI planning

​Verify tools are registered

​Next steps

Install the runtime

Register tools that wrap existing functions

Register tools with `registerTool`

Register tools conditionally

Update tools when app state changes

Interact with the DOM

Return errors from tools

Add annotations for AI planning

Verify tools are registered

Next steps