Skip to main content
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.
FeatureBenefit
React-First DesignHooks follow React patterns with automatic cleanup and StrictMode support
Type-Safe with ZodFull TypeScript support with Zod schema validation for inputs/outputs
Two-Way IntegrationBoth expose tools TO AI agents AND consume tools FROM MCP servers
Execution State TrackingBuilt-in loading, success, and error states for UI feedback
Works with Any AICompatible 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

HookDescription
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 / ComponentDescription
McpClientProviderProvider 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.

​
Resources

​
License

MIT - see LICENSE for details