| name | webmcp-setup |
| description | Bootstraps webmcp-react into an existing React or Next.js app. Installs dependencies, adds WebMCPProvider, creates a first tool, and configures the MCP client bridge. Use when the user wants to set up WebMCP, add MCP tools to their app, integrate webmcp-react, or make their React app accessible to AI agents. |
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:
"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:
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:
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 }) => ({
content: [{ type: "text", text: `Hello, ${name}!` }],
}),
});
return null;
}
Render it inside the provider:
<WebMCPProvider name="my-app" version="1.0">
<GreetTool />
{}
</WebMCPProvider>
Step 4: Connect to AI clients
Desktop MCP clients (Cursor, Claude Code) cannot access document.modelContext directly. A Chrome extension + local MCP server bridges the gap.
4a. Install the Chrome extension
Install the "WebMCP Bridge" extension from the Chrome Web Store, or build from source:
git clone https://github.com/MCPCat/webmcp-react.git
cd webmcp-react/extension && pnpm install && pnpm build
Then load unpacked from extension/dist/ at chrome://extensions/.
4b. Configure the MCP client
Cursor -- add to .cursor/mcp.json:
{
"mcpServers": {
"webmcp-server": {
"command": "npx",
"args": ["webmcp-server"]
}
}
}
Claude Code:
claude mcp add --transport stdio webmcp-server -- npx webmcp-server
4c. Activate the extension
- Open your app in Chrome
- Click the WebMCP Bridge extension icon
- Choose "Always on" for persistent activation, or "Until reload" for one-shot testing
- Green dot = connected to MCP client and tools are available
Step 5: Verify
- Run the app in the browser
- Open the extension popup -- registered tools should appear
- From Cursor or Claude Code, the tools should be discoverable and callable
Troubleshooting
| Symptom | Fix |
|---|
| Tools not appearing in AI client | Check extension is activated (green/yellow dot). Verify MCP server is running. |
| Yellow dot (no MCP connection) | Ensure webmcp-server is configured in your MCP client. Check port 12315 is free. |
useMcpTool warning about missing provider | Ensure the component is rendered inside <WebMCPProvider>. |
| Next.js hydration errors | Add "use client" to any file using useMcpTool or WebMCPProvider. |
