WebMCP Documentation

Full Example

Production-ready React example with useWebMCP() hooks

React users should use @mcp-b/react-webmcp instead of @mcp-b/global directly—it handles lifecycle automatically and provides Zod validation. This guide covers SSR-specific challenges when using WebMCP with Next.js App Router.

The fundamental challenge

WebMCP relies on browser APIs (navigator.modelContext, postMessage, DOM access) that do not exist on the server. Next.js App Router defaults to Server Components, which means:

Tools cannot be registered in Server Components
The @mcp-b/global polyfill must run on the client
Any component using useWebMCP or useWebMCPPrompt must be a Client Component

Polyfill placement

The @mcp-b/global polyfill must be imported in a Client Component before any tools are registered. Import it at the highest layout that contains your tools—but not necessarily at the root.

Don’t make your root layout a Client Component unless you need to. This disables SSR for your entire application. Instead, import the polyfill in the feature layout(s) where tools are used.

'use client';

import '@mcp-b/global';  // Import FIRST, before other components
import { DashboardTools } from '@/components/dashboard-tools';

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

If you have tools in multiple unrelated sections, import the polyfill in each feature layout:

src/app/layout.tsx              # Server Component - keeps SSR benefits
src/app/(dashboard)/layout.tsx  # 'use client' + @mcp-b/global
src/app/(settings)/layout.tsx   # 'use client' + @mcp-b/global

The polyfill is small and idempotent—importing it multiple times is fine.

If the polyfill isn’t working, you’ll see:

navigator.modelContext is undefined
Tools don’t appear in the MCP inspector
No errors, but tools simply don’t register

Client components are required

Every WebMCP hook needs 'use client':

// Server Component (default in App Router)
import { useWebMCP } from '@mcp-b/react-webmcp';

export function MyTools() {
  useWebMCP({ ... });  
  // Will fail - hooks can't run on server
  return null;
}

// Client Component
'use client';  

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

export function MyTools() {
  useWebMCP({ ... });  
  // Works - runs in browser
  return null;
}

Hooks that require Client Components:

useWebMCP() - tool registration
useWebMCPPrompt() - prompt registration
useWebMCPResource() - resource registration
useWebMCPContext() - context registration
useMcpClient() - MCP client access

Embedded agent setup

The embedded agent uses browser APIs and must be loaded client-side only using dynamic import:

'use client';

import dynamic from 'next/dynamic';

const EmbeddedAgent = dynamic(
  () => import('@mcp-b/embedded-agent/web-component').then(mod => mod.EmbeddedAgent),
  { ssr: false }  // Critical - prevents server-side rendering
);

export function MyEmbeddedAgent() {
  return (
    <EmbeddedAgent
      appId="your-app-id"
      devMode={{
        anthropicApiKey: process.env.NEXT_PUBLIC_ANTHROPIC_API_KEY || '',
      }}
    />
  );
}

ssr: false is required because the embedded agent accesses window, document, and other browser APIs. Server-side rendering will crash with “window is not defined”.

Avoiding duplicate components

Next.js App Router supports nested layouts. If you add the embedded agent to multiple layouts, it will render multiple times:

src/app/(calendar)/layout.tsx → Has <EmbeddedAgent />
src/app/(calendar)/week/layout.tsx → Also has <EmbeddedAgent />

Result: TWO embedded agents on the page!

Place the agent in ONE feature layout that wraps all pages needing AI access:

'use client';

import '@mcp-b/global';
import { CalendarProvider } from '@/contexts/calendar';
import { CalendarTools } from '@/components/calendar-tools';
import { MyEmbeddedAgent } from '@/components/embedded-agent';

export default function CalendarLayout({ children }) {
  return (
    <CalendarProvider>
      <CalendarTools />
      <MyEmbeddedAgent />
      {children}
    </CalendarProvider>
  );
}

This keeps your root layout as a Server Component while giving tools access to the context they need.

Tool registration with context

WebMCP tools frequently need access to application state. This creates a dependency chain:

Context Provider → Tools Component → Tools can access state

'use client';

import '@mcp-b/global';
import { FeatureProvider } from '@/contexts/feature';
import { FeatureTools } from '@/components/feature-tools';

export default function FeatureLayout({ children }) {
  return (
    <FeatureProvider>        {/* 1. Provider wraps everything */}
      <FeatureTools />       {/* 2. Tools inside provider */}
      {children}
    </FeatureProvider>
  );
}

'use client';

import { useWebMCP } from '@mcp-b/react-webmcp';
import { useFeature } from '@/contexts/feature';
import { z } from 'zod';

export function FeatureTools() {
  const { data, setData } = useFeature();

  useWebMCP({
    name: 'get_data',
    description: 'Get current feature data',
    handler: async () => data,
  });

  useWebMCP({
    name: 'update_data',
    description: 'Update feature data',
    inputSchema: { value: z.string() },
    handler: async (input) => {
      setData(input.value);
      return { success: true };
    },
  });

  return null;  // Tools component renders nothing
}

Tools placed outside the provider can’t access context:

// Tools can't access context here
export default function Layout({ children }) {
  return (
    <>
      <FeatureTools />      {/* Outside provider - useFeature() fails */}
      <FeatureProvider>
        {children}
      </FeatureProvider>
    </>
  );
}

Tools can navigate using Next.js router:

'use client';

import { useRouter, usePathname } from 'next/navigation';
import { useWebMCP } from '@mcp-b/react-webmcp';
import { z } from 'zod';

export function NavigationTools() {
  const router = useRouter();
  const pathname = usePathname();

  useWebMCP({
    name: 'navigate_to_page',
    description: 'Navigate to a specific page',
    inputSchema: {
      path: z.enum(['/dashboard', '/settings', '/profile']),
    },
    handler: async ({ path }) => {
      if (pathname !== path) {
        router.push(path);
      }
      return { navigatedTo: path };
    },
  });

  return null;
}

In Next.js App Router, the root layout persists across navigations. Tools registered in root layout stay registered, while tools in page components unmount/remount on navigation.

Common errors

'navigator.modelContext is undefined'

Cause: Polyfill not loaded or running on serverSolution:

Ensure import '@mcp-b/global' is in a Client Component
Import it at the very top, before other imports
Make sure the component has 'use client' directive

'window is not defined'

Cause: Browser-only code running during SSRSolution:

// Use dynamic import with ssr: false
const Component = dynamic(() => import('./Component'), { ssr: false });

// Or check for browser environment
if (typeof window !== 'undefined') {
  // Browser-only code
}

'Cannot read properties of undefined (reading registerTool)'

Cause: Polyfill hasn’t initialized yetSolution:

// Ensure polyfill is imported before any tool registration
import '@mcp-b/global';  // FIRST
import { useWebMCP } from '@mcp-b/react-webmcp';  // AFTER

Tools not appearing

Possible Causes:

Component using useWebMCP isn’t mounted
Component is a Server Component (missing 'use client')
Tool registration is conditional and condition is false
Polyfill loaded after tools tried to register

Debug:

const { state } = useWebMCP({
  name: 'my_tool',
  // ...
});

console.log('Tool registered, state:', state);

Duplicate tools or agents

Cause: Component mounted multiple times (e.g., in nested layouts)Solution: Only render WebMCP components in ONE layout. Use React DevTools to check component tree for duplicates.

Deployment checklist

Before deploying your WebMCP + Next.js app:

Root layout is a Server Component (no 'use client') to preserve SSR
Feature layout(s) have 'use client' and import @mcp-b/global
All components using WebMCP hooks have 'use client'
Embedded agent uses dynamic() with { ssr: false }
Embedded agent is rendered in only ONE layout
Tools that need context are inside their Provider
Environment variables use NEXT_PUBLIC_ prefix for client access

Recommended architecture

src/
├── app/
│   ├── layout.tsx          # Server Component - keeps SSR benefits
│   └── (feature)/
│       ├── layout.tsx      # 'use client' + @mcp-b/global + provider + tools + agent
│       └── page.tsx        # Can be Server Component for data fetching
├── components/
│   ├── embedded-agent.tsx  # Dynamic import, ssr: false
│   └── feature-tools.tsx   # 'use client', useWebMCP hooks
└── contexts/
    └── feature.tsx         # 'use client', React context

This structure ensures:

Root layout stays a Server Component (SSR preserved)
Polyfill loads in feature layouts where tools are used
Tools have access to context (feature layout)
Agent renders once (feature layout only)
Pages can still use Server Components for data fetching

Development

Use Chrome DevTools MCP for AI-driven development - your AI can write, discover, and test tools in real-time.

Start Here

React & Next.js Integration

Full Example

The fundamental challenge

Polyfill placement

Client components are required

Embedded agent setup

Avoiding duplicate components

Tool registration with context

Navigation tools

Common errors

Deployment checklist

Recommended architecture

Development

Full Example

​The fundamental challenge

​Polyfill placement

​Client components are required

​Embedded agent setup

​Avoiding duplicate components

​Tool registration with context

​Navigation tools

​Common errors

​Deployment checklist

​Recommended architecture

​Development

The fundamental challenge

Polyfill placement

Client components are required

Embedded agent setup

Avoiding duplicate components

Tool registration with context

Navigation tools

Common errors

Deployment checklist

Recommended architecture

Development