@mcp-b/react-webmcp

React hooks for Model Context Protocol (MCP) - Let AI agents like Claude, ChatGPT, Cursor, and Copilot control your React components

React hooks for Model Context Protocol (MCP) - Let AI agents like Claude, ChatGPT, Cursor, and Copilot control your React components

Version

Current release: v3.0.0 — aligned with the WebMCP v3 document-first API. Provider hooks register tools against document.modelContext (the canonical v3 surface) while retaining a navigator.modelContext fallback for older preview runtimes.

When to use this package

• You want the full MCP-B feature set from React (tools, prompts, resources, sampling, elicitation).
• You want Zod v3 object-map support and Standard Schema v1 (e.g., Zod v4 ~standard) in hook configuration.
• You need client/provider hooks (McpClientProvider, useMcpClient) in addition to browser-exposed tools.

@mcp-b/react-webmcp provides React hooks that expose your components as AI-callable tools via the Model Context Protocol. Build AI-powered React applications where Claude, ChatGPT, Gemini, Cursor, and Copilot can interact with your app’s functionality.

• You only need strict-core registerTool behavior. Use usewebmcp.
• You are not using a BrowserMcpServer-based runtime. Install @mcp-b/global first.

Feature	Benefit
React-First Design	Hooks follow React patterns with automatic cleanup and StrictMode support
Type-Safe with Zod	Full TypeScript support with Zod schema validation for inputs/outputs
Two-Way Integration	Both expose tools TO AI agents AND consume tools FROM MCP servers
Execution State Tracking	Built-in loading, success, and error states for UI feedback
Works with Any AI	Compatible with Claude, ChatGPT, Gemini, Cursor, Copilot, and any MCP client

This package sits above the full runtime stack. It expects document.modelContext to come from a browser-native implementation or from the MCP-B runtime that wraps the strict core with BrowserMcpServer.

React peer dependency: ^17.0.0 || ^18.0.0 || ^19.0.0. Zod peer dependency (optional): ^3.25 || ^4.0.

pnpm add @mcp-b/react-webmcp zod

If you only want strict core WebMCP hooks (without MCP-B extension APIs like prompts/resources/sampling/elicitation), use usewebmcp instead.

For client functionality, you’ll also need:

pnpm add @mcp-b/transports @modelcontextprotocol/sdk

Prerequisites: Provider hooks require the document.modelContext API. Install @mcp-b/global or use a browser that implements the Web Model Context API.

Provider hooks register tools with document.modelContext.registerTool(tool, { signal }) and abort the controller on unmount. The hooks retain a navigator.modelContext fallback for older preview runtimes, but document.modelContext is the canonical v3 surface. On Chrome Beta 147 native (which ignores the second arg) cleanup cannot remove the tool. Install @mcp-b/global for spec-aligned behavior.

Quick Start - Provider (Registering Tools)

import { useWebMCP } from '@mcp-b/react-webmcp';
import { z } from 'zod';

function PostsPage() {
  const likeTool = useWebMCP({
    name: 'posts_like',
    description: 'Like a post by ID. Increments the like count.',
    inputSchema: {
      postId: z.string().uuid().describe('The post ID to like'),
    },
    annotations: {
      title: 'Like Post',
      readOnlyHint: false,
      idempotentHint: true,
    },
    handler: async (input) => {
      await api.posts.like(input.postId);
      return { success: true, postId: input.postId };
    },
    formatOutput: (result) => `Post ${result.postId} liked successfully!`,
  });

  return (
    <div>
      {likeTool.state.isExecuting && <Spinner />}
      {likeTool.state.error && <ErrorAlert error={likeTool.state.error} />}
    </div>
  );
}

Quick Start - Client (Consuming Tools)

import { McpClientProvider, useMcpClient } from '@mcp-b/react-webmcp';
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { TabClientTransport } from '@mcp-b/transports';

const client = new Client({ name: 'MyApp', version: '1.0.0' });
const transport = new TabClientTransport('mcp', { clientInstanceId: 'my-app' });

function App() {
  return (
    <McpClientProvider client={client} transport={transport}>
      <ToolConsumer />
    </McpClientProvider>
  );
}

function ToolConsumer() {
  const { client, tools, isConnected } = useMcpClient();

  const handleCallTool = async () => {
    const result = await client.callTool({ name: 'posts_like', arguments: { postId: '123' } });
    console.log('Result:', result.content[0].text);
  };

  return (
    <div>
      <p>Connected: {isConnected ? 'Yes' : 'No'}</p>
      <p>Available Tools: {tools.length}</p>
      <button onClick={handleCallTool} disabled={!isConnected}>
        Call Tool
      </button>
    </div>
  );
}

API Overview

Provider Hooks

Hook	Description
useWebMCP(config, deps?)	Register a tool with full control over behavior and state
useWebMCPContext(name, description, getValue)	Simplified hook for read-only context exposure

Client Hooks

Hook / Component	Description
McpClientProvider	Provider component managing an MCP client connection
useMcpClient()	Access client, tools, connection status, and capabilities

Zod Version Compatibility

This package supports Zod 3.25.76+ (3.x only).

Documentation

For full API reference, output schemas, memoization patterns, migration guide, best practices, and complete examples, see the React WebMCP Guide.

Related Packages

• @mcp-b/global - W3C Web Model Context API polyfill (required for provider hooks)
• @mcp-b/transports - Browser-specific MCP transports
• @mcp-b/chrome-devtools-mcp - Connect desktop AI agents to browser tools
• usewebmcp - React hooks for strict core WebMCP API only

Resources

• WebMCP Documentation
• Model Context Protocol Spec

License

MIT - see LICENSE for details