WebMCP Documentation

Register WebMCP tools in any frontend framework by following its native lifecycle patterns. For cross-cutting patterns like conditional registration, error handling, and annotations, see Add Tools to an Existing App.

Install the runtime

@mcp-b/global (recommended)
@mcp-b/webmcp-polyfill (strict core)

The full runtime: polyfill, MCP server, transports, prompts, resources, and direct access to the official MCP server.

npm install @mcp-b/global

pnpm add @mcp-b/global

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

@mcp-b/global checks for window and document before auto-initializing, so the import is SSR-safe. Tool registration still belongs in client-side lifecycle code.

Installs the strict registerTool and getTools surface on document.modelContext, plus a feature-detectable Chrome-compatible executeTool extension. No MCP extensions or transports.

npm install @mcp-b/webmcp-polyfill

import { initializeWebMCPPolyfill } from '@mcp-b/webmcp-polyfill';

initializeWebMCPPolyfill();

The initializer checks for a browser environment internally and is SSR-safe. No client guards needed.For details on when to use the polyfill vs the full runtime, see Choose a Runtime.

React users also need a hook package. Install @mcp-b/react-webmcp (recommended) or usewebmcp alongside your chosen runtime. See Register a tool below.

Initialize at your entry point

Import @mcp-b/global once before any component mounts. The import is a side effect that installs document.modelContext. Strict-core projects call initializeWebMCPPolyfill() once, as shown above.

import '@mcp-b/global';
import { createRoot } from 'react-dom/client';
import { App } from './App';

createRoot(document.getElementById('root')!).render(<App />);

import '@mcp-b/global';
import { createApp } from 'vue';
import App from './App.vue';

createApp(App).mount('#app');

import '@mcp-b/global';
import { mount } from 'svelte';
import App from './App.svelte';

const app = mount(App, { target: document.getElementById('app')! });
export default app;

import '@mcp-b/global';
import { bootstrapApplication } from '@angular/platform-browser';
import { AppComponent } from './app/app.component';

bootstrapApplication(AppComponent);

Next.js App Router defaults to Server Components. Import @mcp-b/global in a Client Component layout, not the root layout.

'use client';

import '@mcp-b/global';

export default function DashboardLayout({ children }) {
  return <>{children}</>;
}

The polyfill is idempotent. If tools live in multiple sections, import it in each feature layout.

Keep the root layout as a Server Component. Marking it as a Client Component expands the client boundary and prevents Server Component-only features below it.

Import inside a <script> tag. Astro processes these through its bundler and runs them on the client.

<script>
  import '@mcp-b/global';
</script>

Alternatively, load the IIFE in your layout’s <head>:

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

import '@mcp-b/global';

Or without a build step:

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

Register a tool

Each framework has its own lifecycle hooks for mount and unmount. Register tools on mount, unregister on unmount.

Two hook packages are available:

Package	Use when
@mcp-b/react-webmcp	You want tools, prompts, resources, and MCP client-provider hooks
usewebmcp	You want strict-core `document.modelContext` tools only

Both handle registration on mount and cleanup on unmount automatically.

import { useWebMCP } from '@mcp-b/react-webmcp';

export function LikeTool() {
  const likeTool = useWebMCP({
    name: 'posts_like',
    description: 'Like a post by ID. Increments the like count.',
    inputSchema: {
      type: 'object',
      properties: {
        postId: { type: 'string', description: 'The post ID to like' },
      },
      required: ['postId'],
    } as const,
    annotations: {
      readOnlyHint: false,
    },
    execute: async (input) => {
      await api.posts.like(input.postId);
      return { success: true, postId: input.postId };
    },
  });

  return (
    <div>
      {likeTool.state.isExecuting && <p>Liking...</p>}
      {likeTool.state.error && <p>Error: {likeTool.state.error.message}</p>}
    </div>
  );
}

Call registerTool() in onMounted and abort the registration signal in onUnmounted. The execute function can read and write Vue reactive state through .value access.

<script setup lang="ts">
import { ref, onMounted, onUnmounted } from 'vue';

const count = ref(0);
let controller: AbortController | undefined;

onMounted(async () => {
  controller = new AbortController();
  await document.modelContext.registerTool(
    {
      name: 'increment',
      description: 'Increment the counter by a given amount',
      inputSchema: {
        type: 'object',
        properties: {
          amount: { type: 'number', description: 'Amount to add' },
        },
      },
      async execute({ amount = 1 }) {
        count.value += amount as number;
        return {
          content: [{ type: 'text', text: `Count: ${count.value}` }],
        };
      },
    },
    { signal: controller.signal }
  );
});

onUnmounted(() => {
  controller?.abort();
});
</script>

<template>
  <p>Count: {{ count }}</p>
</template>

Use onMount to register and onDestroy to unregister. Svelte 5 runes work in the execute handler.

<script lang="ts">
  import { onMount, onDestroy } from 'svelte';

  let count = $state(0);
  let controller: AbortController | undefined;

  onMount(() => {
    controller = new AbortController();
    void document.modelContext.registerTool(
      {
        name: 'increment',
        description: 'Increment the counter by a given amount',
        inputSchema: {
          type: 'object',
          properties: {
            amount: { type: 'number', description: 'Amount to add' },
          },
        },
        async execute({ amount = 1 }) {
          count += amount as number;
          return {
            content: [{ type: 'text', text: `Count: ${count}` }],
          };
        },
      },
      { signal: controller.signal }
    ).catch(console.error);
  });

  onDestroy(() => {
    controller?.abort();
  });
</script>

<p>Count: {count}</p>

Use ngOnInit to register and ngOnDestroy to abort the registration signal.

import { Component, OnInit, OnDestroy } from '@angular/core';
import '@mcp-b/global';

@Component({
  selector: 'app-counter',
  template: `<p>Count: {{ count }}</p>`,
})
export class CounterComponent implements OnInit, OnDestroy {
  count = 0;
  private toolController?: AbortController;

  ngOnInit() {
    if (!('modelContext' in document)) return;

    this.toolController = new AbortController();
    void document.modelContext.registerTool(
      {
        name: 'increment',
        description: 'Increment the counter by a given amount',
        inputSchema: {
          type: 'object',
          properties: {
            amount: { type: 'number', description: 'Amount to add' },
          },
        },
        execute: async ({ amount = 1 }) => {
          this.count += amount as number;
          return {
            content: [{ type: 'text', text: `Count: ${this.count}` }],
          };
        },
      },
      { signal: this.toolController.signal }
    ).catch(console.error);
  }

  ngOnDestroy() {
    this.toolController?.abort();
  }
}

Mark tool components with 'use client' and use the same React hooks.

'use client';

import { useWebMCP } from '@mcp-b/react-webmcp';

export function DashboardTools() {
  useWebMCP({
    name: 'get_metrics',
    description: 'Get dashboard metrics for a date range',
    inputSchema: {
      type: 'object',
      properties: {
        startDate: { type: 'string', description: 'ISO date string' },
        endDate: { type: 'string', description: 'ISO date string' },
      },
      required: ['startDate', 'endDate'],
    } as const,
    execute: async ({ startDate, endDate }) => {
      const res = await fetch(`/api/metrics?start=${startDate}&end=${endDate}`);
      return await res.json();
    },
  });

  return null;
}

<script>
  import '@mcp-b/global';

  const controller = new AbortController();
  await document.modelContext.registerTool(
    {
      name: 'get_page_title',
      description: 'Get the current page title',
      inputSchema: { type: 'object', properties: {} },
      async execute() {
        return {
          content: [{ type: 'text', text: document.title }],
        };
      },
    },
    { signal: controller.signal }
  );
</script>

If you use View Transitions, abort the registration before navigation:

document.addEventListener('astro:before-preparation', () => {
  controller.abort();
});

Call registerTool() directly after importing the runtime.

import '@mcp-b/global';

const controller = new AbortController();

await document.modelContext.registerTool(
  {
    name: 'get-page-title',
    description: 'Get the current page title',
    inputSchema: { type: 'object', properties: {} },
    async execute() {
      return {
        content: [{ type: 'text', text: document.title }],
      };
    },
  },
  { signal: controller.signal }
);

Abort the registration when the tool is no longer needed:

controller.abort();

Handle SSR

Both @mcp-b/global and initializeWebMCPPolyfill() are SSR-safe: they no-op when browser globals are unavailable. Components that call document.modelContext or read page state still need to do so in client-side lifecycle code.

Next.js
Nuxt / Vue SSR
SvelteKit
Angular Universal
Astro

Mark components with 'use client'. For components that access window or document directly, use dynamic imports:

BrowserOnly.tsx

'use client';

import dynamic from 'next/dynamic';
const BrowserOnly = dynamic(() => import('./BrowserOnly'), { ssr: false });

In Nuxt, guard with import.meta.client:

<script setup lang="ts">
import { onMounted, onUnmounted } from 'vue';

let controller: AbortController | undefined;

onMounted(() => {
  if (!import.meta.client) return;

  void import('@mcp-b/global')
    .then(async () => {
      controller = new AbortController();
      await document.modelContext.registerTool(
        {
          name: 'my_tool',
          description: 'A tool that only runs on the client',
          inputSchema: { type: 'object', properties: {} },
          async execute() {
            return { content: [{ type: 'text', text: 'Done' }] };
          },
        },
        { signal: controller.signal }
      );
    })
    .catch(console.error);
});

onUnmounted(() => {
  controller?.abort();
});
</script>

Guard with browser from $app/environment:

<script lang="ts">
  import { browser } from '$app/environment';
  import { onMount, onDestroy } from 'svelte';
  import '@mcp-b/global';

  let controller: AbortController | undefined;

  onMount(() => {
    if (!browser) return;

    controller = new AbortController();
    void document.modelContext.registerTool(
      {
        name: 'my_tool',
        description: 'A tool that only runs on the client',
        inputSchema: { type: 'object', properties: {} },
        async execute() {
          return { content: [{ type: 'text', text: 'Done' }] };
        },
      },
      { signal: controller.signal }
    ).catch(console.error);
  });

  onDestroy(() => {
    controller?.abort();
  });
</script>

To persist tools across route navigations in SvelteKit, register them in +layout.svelte instead of +page.svelte.

Guard with isPlatformBrowser:

import { Component, OnInit, OnDestroy, PLATFORM_ID, Inject } from '@angular/core';
import { isPlatformBrowser } from '@angular/common';
import '@mcp-b/global';

@Component({ selector: 'app-my', template: '' })
export class MyComponent implements OnInit, OnDestroy {
  private isBrowser: boolean;
  private controller?: AbortController;

  constructor(@Inject(PLATFORM_ID) platformId: object) {
    this.isBrowser = isPlatformBrowser(platformId);
  }

  ngOnInit() {
    if (!this.isBrowser || !('modelContext' in document)) return;

    this.controller = new AbortController();
    void document.modelContext.registerTool(
      {
        name: 'my_tool',
        description: 'A tool that only runs on the client',
        inputSchema: { type: 'object', properties: {} },
        execute: async () => ({
          content: [{ type: 'text', text: 'Done' }],
        }),
      },
      { signal: this.controller.signal }
    ).catch(console.error);
  }

  ngOnDestroy() {
    this.controller?.abort();
  }
}

Astro renders pages as static HTML by default. Code inside <script> tags runs on the client only, so no guard is needed for standard Astro pages. For framework islands, use client:load or client:only:

---
import DashboardTools from '../components/DashboardTools';
---

<DashboardTools client:load />

Verify registration

Open the browser console and run:

await document.modelContext.getTools();

This resolves to the registered tool descriptors, including their names, descriptions, and serialized input schemas. For a richer inspection experience, see Debug and Troubleshoot.

How-To Guides

Adoption

Frameworks

Connectivity

Integrate with your framework

Install the runtime

Initialize at your entry point

Register a tool

Handle SSR

Verify registration

​Install the runtime

​Initialize at your entry point

​Register a tool

​Handle SSR

​Verify registration

Install the runtime

Initialize at your entry point

Register a tool

Handle SSR

Verify registration