webmcp-setup

Set Up webmcp-react

Overview

webmcp-react exposes React app functionality as typed tools on document.modelContext (the W3C WebMCP API). AI agents discover and call these tools. This skill bootstraps the full setup.

Step 1: Install dependencies

npm install webmcp-react zod

zod is a peer dependency used for typed tool input schemas.

Step 2: Add WebMCPProvider

All useMcpTool calls must be descendants of <WebMCPProvider>. It installs a polyfill when native browser support is absent.

React / Vite

Wrap the app root:

import { WebMCPProvider } from "webmcp-react";

function App() {
  return (
    <WebMCPProvider name="my-app" version="1.0">
      {/* existing app content */}
    </WebMCPProvider>
  );
}

Next.js (App Router)

Create a client component wrapper since webmcp-react uses browser APIs:

// app/providers.tsx
"use client";

import { WebMCPProvider } from "webmcp-react";

export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <WebMCPProvider name="my-app" version="1.0">
      {children}
    </WebMCPProvider>
  );
}

Then wrap children in the root layout:

// app/layout.tsx
import { Providers } from "./providers";

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <Providers>{children}</Providers>
      </body>
    </html>
  );
}

The library ships with a "use client" banner in its build output, so no transpilePackages config is needed when installing from npm.

Step 3: Create a first tool

Create a simple tool component to verify the wiring works:

// components/mcp-tools.tsx  (add "use client" at top if Next.js)
import { useMcpTool } from "webmcp-react";
import { z } from "zod";

export function GreetTool() {
  useMcpTool({
    name: "greet",
    description: "Greet someone by name",
    input: z.object({
      name: z.string().describe("The name to greet"),
    }),
    handler: async ({ name }, { signal }) => {
      // signal aborts if the agent cancels — forward it to cancellable work
      const res = await fetch(`/api/greet?name=${encodeURIComponent(name)}`, { signal });
      return { content: [{ type: "text", text: await res.text() }] };
    },
  });
  return null;
}