@mcp-fe/react-tools

React hooks and components for seamless integration with MCP (Model Context Protocol) tools.

Simplify dynamic MCP tool integration in React applications with automatic lifecycle management, reference counting, and full access to React features.

🔗 Requires: @mcp-fe/mcp-worker - The browser-based MCP server that powers these React hooks.

✨ Key Features

• 🔄 Automatic Lifecycle - Register on mount, unregister on unmount
• 📊 Reference Counting - Share tools across multiple components safely
• ⚡ Re-render Safe - Smart refs prevent duplicate registrations
• 🎯 Full React Access - Handlers have complete access to state, props, and context
• 🔌 Optional Context - Works standalone or with Provider
• 📘 TypeScript First - Complete type safety out of the box

⚠️ Prerequisites

This library requires @mcp-fe/mcp-worker to function. The worker library runs an MCP server in your browser that enables AI agents to interact with your application.

You must install and initialize the worker library first:

npm install @mcp-fe/mcp-worker @mcp-fe/react-tools

pnpm add @mcp-fe/mcp-worker @mcp-fe/react-tools

yarn add @mcp-fe/mcp-worker @mcp-fe/react-tools

💡 New to MCP Worker? Check out the @mcp-fe/mcp-worker documentation to set up the browser-based MCP server first.

🚀 Quick Example

Step 1: Wrap your app with MCPToolsProvider:

import { MCPToolsProvider } from '@mcp-fe/react-tools';

function App() {
  return (
    <MCPToolsProvider 
      backendWsUrl="ws://localhost:3001"
      authToken="your-auth-token" 
      onInitialized={() => console.log('MCP ready!')}
    >
      <MyApp />
    </MCPToolsProvider>
  );
}

Step 2: Register tools with React hooks in your components:

import { useMCPTool } from '@mcp-fe/react-tools';

function MyComponent() {
  const user = useUser();
  
  useMCPTool({
    name: 'get_user_profile',
    description: 'Get current user profile',
    inputSchema: {
      type: 'object',
      properties: {}
    },
    handler: async () => ({
      content: [{
        type: 'text',
        text: JSON.stringify({ 
          userId: user.id,
          name: user.name,
          email: user.email
        })
      }]
    })
  });
  
  return <div>Profile tool is active!</div>;
}

💡 Alternative: You can also initialize the worker client manually outside React. See the Getting Started Guide for details.

📖 Need more details? See the Complete Setup Guide for step-by-step instructions.

📚 Documentation

📖 View Complete Documentation →

Comprehensive documentation is available in the docs/ directory:

• Getting Started - Installation, quick start, and basic usage
• API Reference - Complete API documentation for all hooks and utilities
• Guides - Advanced patterns and best practices
• Examples - Real-world implementation examples
• Architecture - Internal design and data flow
• Troubleshooting - Common issues and solutions

🎯 Core Hooks

useMCPTool

The main hook for registering MCP tools with full lifecycle management.

useMCPGetter

Simplified hook for getter tools (no input parameters).

useMCPAction

Hook for action tools that accept inputs and perform operations.

→ See full API documentation

🏗️ Project Links

• 📦 npm Package
• 🐙 GitHub Repository
• 🌐 Homepage
• 📝 Changelog

📄 License

Apache-2.0 - See LICENSE for details.

Ready to get started? Check out the Getting Started Guide!