WebMCP Documentation

WebMCP relies on browser APIs (navigator.modelContext) that don’t exist on the server. Remix renders components on both server and client during SSR, so you must ensure WebMCP code only runs in the browser.

The challenge

Remix components run during both SSR and client-side hydration by default. This means:

@mcp-b/global polyfill cannot be imported at module level in routes
useWebMCP hooks will fail during SSR if not guarded
You need explicit client-only patterns

Client-only tool registration

Use ClientOnly from remix-utils (recommended) or lazy imports to ensure tools only register on the client:

Using ClientOnly (recommended)

pnpm add remix-utils

import { ClientOnly } from 'remix-utils/client-only';

export default function Index() {
  return (
    <div>
      <h1>Home</h1>
      <ClientOnly fallback={null}>
        {() => <HomeTools />}
      </ClientOnly>
    </div>
  );
}

// Separate component ensures imports happen client-side
function HomeTools() {
  // These imports only execute on the client
  require('@mcp-b/global');
  const { useWebMCP } = require('@mcp-b/react-webmcp');
  const { z } = require('zod');

  useWebMCP({
    name: 'greet',
    description: 'Greet a user',
    inputSchema: { name: z.string() },
    handler: async ({ name }) => `Hello, ${name}!`,
  });

  return null;
}

Using lazy imports

import { lazy, Suspense } from 'react';

// Lazy load the tools component - only runs on client
const HomeTools = lazy(() => import('~/components/home-tools'));

export default function Index() {
  return (
    <div>
      <h1>Home</h1>
      <Suspense fallback={null}>
        <HomeTools />
      </Suspense>
    </div>
  );
}

import '@mcp-b/global'; // Safe - only imported when this module loads on client
import { useWebMCP } from '@mcp-b/react-webmcp';
import { z } from 'zod';

export default function HomeTools() {
  useWebMCP({
    name: 'greet',
    description: 'Greet a user',
    inputSchema: { name: z.string() },
    handler: async ({ name }) => `Hello, ${name}!`,
  });

  return null; // Tools component renders nothing
}

Don’t import @mcp-b/global in route files directly. Route files are bundled for SSR and will fail when the polyfill tries to access navigator. Always import it in lazily-loaded client components or inside ClientOnly.

For tools that should remain registered across route changes, place them in root.tsx using the same client-only pattern:

import { ClientOnly } from 'remix-utils/client-only';
import {
  Links,
  Meta,
  Outlet,
  Scripts,
  ScrollRestoration,
} from '@remix-run/react';

export default function App() {
  return (
    <html lang="en">
      <head>
        <Meta />
        <Links />
      </head>
      <body>
        <ClientOnly fallback={null}>
          {() => <GlobalTools />}
        </ClientOnly>
        <Outlet />
        <ScrollRestoration />
        <Scripts />
      </body>
    </html>
  );
}

function GlobalTools() {
  require('@mcp-b/global');
  const { useWebMCP } = require('@mcp-b/react-webmcp');

  useWebMCP({
    name: 'navigate',
    description: 'Navigate to a page',
    inputSchema: { path: require('zod').z.string() },
    handler: async ({ path }) => {
      window.location.href = path;
      return { navigatedTo: path };
    },
  });

  return null;
}

Common errors

'navigator is not defined' or 'navigator.modelContext is undefined'

Cause: @mcp-b/global is being imported during SSRSolution: Use ClientOnly from remix-utils or lazy imports to ensure the polyfill only loads on the client.

Tools not appearing after navigation

Hydration mismatch errors

Cause: Server HTML doesn’t match client HTML because tools render differentlySolution: Ensure tool components return null and use ClientOnly fallback={null} for consistent server/client output.

Next steps

For complex patterns (nested layouts, context providers, embedded agents), see the Next.js guide which covers React SSR patterns in depth—the concepts apply to Remix as well.

Start Here

Remix

The challenge

Client-only tool registration

Using ClientOnly (recommended)

Using lazy imports

Tools that persist across navigation

Common errors

Next steps

​The challenge

​Client-only tool registration

​Using ClientOnly (recommended)

​Using lazy imports

​Tools that persist across navigation

​Common errors

​Next steps

The challenge

Client-only tool registration

Using ClientOnly (recommended)

Using lazy imports

Tools that persist across navigation

Common errors

Next steps