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';

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() }] };
  },
});

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) {
  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 throws if a tool with the same name already exists. To update a tool, abort the previous registration signal, then register the new version.

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) {
  registeredToolControllers.get(tool.name)?.abort();

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

function onLogin(user: User) {
  // Register tools appropriate for the user's role
  for (const tool of getToolsForRole(user.role)) {
    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:

const controller = new AbortController();
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

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) {
    document.querySelector('#name').value = args.name;
    document.querySelector('#email').value = args.email;
    document.querySelector('#message').value = args.message;
    return { content: [{ type: 'text', text: 'Form filled' }] };
  },
});

document.modelContext.registerTool({
  name: 'submit-form',
  description: 'Submit the contact form',
  inputSchema: { type: 'object', properties: {} },
  async execute() {
    document.querySelector('#contact-form').submit();
    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.

async execute(args) {
  try {
    const result = await riskyOperation(args);
    return { content: [{ type: 'text', text: JSON.stringify(result) }] };
  } catch (error) {
    return {
      content: [{ type: 'text', text: `Operation failed: ${error.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.

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

Available annotation fields: title, readOnlyHint, destructiveHint, idempotentHint, openWorldHint. See the @mcp-b/webmcp-types reference for the full ToolAnnotations interface.

Verify tools are registered

Use navigator.modelContextTesting to list registered tools and execute them programmatically. This API is available when the testing shim is installed (the default for both @mcp-b/global and @mcp-b/webmcp-polyfill).

const tools = navigator.modelContextTesting?.listTools();
console.log(
  'Registered tools:',
  tools?.map((t) => t.name)
);

const result = await navigator.modelContextTesting?.executeTool(
  'search-products',
  '{"query": "laptop"}'
);
console.log('Result:', result);

If you installed @mcp-b/global, use the standard in-page consumer methods directly:

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

const resultJson = await document.modelContext.executeTool(
  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