TanStack Start

Integrate WebMCP with TanStack Start using client-only patterns for SSR safety.

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

The challenge

Unlike Next.js which has explicit 'use client' directives, TanStack Start components run during both SSR and client-side hydration by default. This means:

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

Client-only tool registration

Wrap your WebMCP tools in a client-only component using dynamic imports:

import { createFileRoute } from '@tanstack/react-router';
import { lazy, Suspense } from 'react';

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

export const Route = createFileRoute('/')({
  component: Home,
});

function Home() {
  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.

Alternative: Environment check

If you prefer keeping tools in the same file, guard with an environment check:

import { createFileRoute } from '@tanstack/react-router';
import { useEffect, useState } from 'react';

export const Route = createFileRoute('/')({
  component: Home,
});

function Home() {
  const [isClient, setIsClient] = useState(false);

  useEffect(() => {
    setIsClient(true);
  }, []);

  return (
    <div>
      <h1>Home</h1>
      {isClient && <HomeTools />}
    </div>
  );
}

// Separate component that only mounts on client
function HomeTools() {
  // Dynamic import ensures this only loads on client
  const [ready, setReady] = useState(false);

  useEffect(() => {
    import('@mcp-b/global').then(() => {
      setReady(true);
    });
  }, []);

  if (!ready) return null;

  return <ToolsInner />;
}

function ToolsInner() {
  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;
}

The lazy import pattern (first example) is cleaner and recommended. The environment check pattern is useful when you can’t easily split into separate files.

Tools that persist across navigation

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

import { createRootRoute, Outlet } from '@tanstack/react-router';
import { lazy, Suspense } from 'react';

const GlobalTools = lazy(() => import('../components/global-tools'));

export const Route = createRootRoute({
  component: Root,
});

function Root() {
  return (
    <>
      <Suspense fallback={null}>
        <GlobalTools />
      </Suspense>
      <Outlet />
    </>
  );
}

Common errors

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

Cause: @mcp-b/global is being imported during SSR

Solution: Use lazy imports or dynamic import() to ensure the polyfill only loads on the client.

Tools not appearing after navigation

Cause: Tools are registered in page components that unmount on navigation

Solution: Move persistent tools to __root.tsx using the client-only pattern above.

Hydration mismatch errors

Cause: Server HTML doesn’t match client HTML because tools render differently

Solution: Ensure tool components return null and use Suspense with 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 TanStack Start as well.