Skip to main content
React hooks for Model Context Protocol (MCP) - Let AI agents like Claude, ChatGPT, Cursor, and Copilot control your React components
npm version npm downloads License: MIT TypeScript React Full Documentation | Quick Start | AI Framework Integration @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.

​
Why Use @mcp-b/react-webmcp?

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

​
Installation

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