webmcp-react

React hooks for exposing typed tools on document.modelContext, aligned with the current WebMCP specification.

• Zod-first. Define inputs with Zod and get full type inference in handlers
• JSON Schema support. Pass raw JSON Schema when you do not use Zod
• Built-in polyfill. Installs a lightweight polyfill when native WebMCP is unavailable
• SSR-safe. Works with Next.js, Remix, and other server-rendering frameworks
• StrictMode-safe. Prevents duplicate registrations and orphaned tools
• Spec-aligned. Tracks the WebMCP specification and native Chrome behavior release by release

Requirements

• React 18 or later
• Zod 3.25 or later, or Zod 4, as a peer dependency. Tools can also be defined with JSON Schema.

Install

npm install webmcp-react zod

Quick start

Wrap your app in <WebMCPProvider> and register tools with useMcpTool:

import { WebMCPProvider, useMcpTool } from "webmcp-react";
import { z } from "zod";

function SearchTool() {
  useMcpTool({
    name: "search",
    description: "Search the catalog",
    input: z.object({ query: z.string() }),
    handler: async ({ query }) => ({
      content: [{ type: "text", text: `Results for: ${query}` }],
    }),
  });
  return null;
}

export default function App() {
  return (
    <WebMCPProvider name="my-app" version="1.0">
      <SearchTool />
    </WebMCPProvider>
  );
}

The tool is now registered on document.modelContext and any WebMCP-compatible agent can call it.

Agent skills

This repository ships agent skills that install webmcp-react and scaffold tools for you. Install them with the skills CLI:

npx skills add agentcathq/webmcp-react

The skills work with Cursor, Claude Code, GitHub Copilot, Cline, and 18+ other agents.

Playground

Try it live: WebMCP Wordle Demo

The playground is a fully playable Wordle clone built on webmcp-react hooks. Tools register and unregister as the game moves through its phases (idle, playing, won, lost). You can make guesses with the keyboard or through an AI agent. A DevPanel shows the current tool state, and an easy-mode toggle enables a hint tool.

To play with an AI agent:

• Codex. Open the demo in Codex and ask it to play. Codex discovers and calls the page's WebMCP tools directly.
• Claude, Cursor, and other MCP clients. Install the WebMCP Bridge extension, open the demo in Chrome, and activate the extension for the page.

How it works

WebMCP is a proposed web standard from the W3C Web Machine Learning Community Group. It adds document.modelContext to the browser, an API that lets any page expose typed, callable tools to AI agents. Chrome ships the API in Early Preview.

This library provides the React bindings for that API. <WebMCPProvider> installs a polyfill when native support is absent, and each useMcpTool call registers a tool that agents can discover and execute.

Connect to AI clients