!GitHub License

A lightweight React hook for connecting to Model Context Protocol (MCP) servers. Simplifies authentication and tool calling for AI systems implementing the MCP standard.

Try it out: Chat Demo | MCP Inspector | Cloudflare Workers AI Playground

Installation

``bash
npm install use-mcp


or

`bash
pnpm dev
`

This starts:
- Inspector: http://localhost:5001 - MCP server debugging tool
- Chat UI: http://localhost:5002 - Example chat interface
- Hono MCP Server: http://localhost:5101 - Example MCP server
- CF Agents MCP Server: http://localhost:5102 - Cloudflare Workers AI MCP server

$3

Integration tests are located in the test/ directory and run headlessly by default:

`bash
cd test && pnpm test # Run tests headlessly (default)
cd test && pnpm test:headed # Run tests with visible browser
cd test && pnpm test:watch # Run tests in watch mode
cd test && pnpm test:ui # Run tests with interactive UI
`

Features

- 🔄 Automatic connection management with reconnection and retries
- 🔐 OAuth authentication flow handling with popup and fallback support
- 📦 Simple React hook interface for MCP integration
- 🧰 Full support for MCP tools, resources, and prompts
- 📄 Access server resources and read their contents
- 💬 Use server-provided prompt templates
- 🧰 TypeScript types for editor assistance and type checking
- 📝 Comprehensive logging for debugging
- 🌐 Works with both HTTP and SSE (Server-Sent Events) transports

Quick Start

`tsx
import { useMcp } from 'use-mcp/react'

function MyAIComponent() {
const {
state, // Connection state: 'discovering' | 'pending_auth' | 'authenticating' | 'connecting' | 'loading' | 'ready' | 'failed'
tools, // Available tools from MCP server
resources, // Available resources from MCP server
prompts, // Available prompts from MCP server
error, // Error message if connection failed
callTool, // Function to call tools on the MCP server
readResource, // Function to read resource contents
getPrompt, // Function to get prompt messages
retry, // Retry connection manually
authenticate, // Manually trigger authentication
clearStorage, // Clear stored tokens and credentials
} = useMcp({
url: 'https://your-mcp-server.com',
clientName: 'My App',
autoReconnect: true,
})

// Handle different states
if (state === 'failed') {
return (


`tsx
// App.tsx with React Router
import { BrowserRouter as Router, Routes, Route } from 'react-router-dom'
import { useEffect } from 'react'
import { onMcpAuthorization } from 'use-mcp'

function OAuthCallback() {
useEffect(() => {
onMcpAuthorization()
}, [])

return (


function App() {
return (


} />
} />


)
}
`

$3

`tsx
// pages/oauth/callback.tsx
import { useEffect } from 'react'
import { onMcpAuthorization } from 'use-mcp'

export default function OAuthCallbackPage() {
useEffect(() => {
onMcpAuthorization()
}, [])

return (


`ts
function useMcp(options: UseMcpOptions): UseMcpResult
`

#### Options

| Option | Type | Description |
|--------|------|-------------|
| url | string | Required. URL of your MCP server |
| clientName | string | Name of your client for OAuth registration |
| clientUri | string | URI of your client for OAuth registration |
| callbackUrl | string | Custom callback URL for OAuth redirect (defaults to /oauth/callback on the current origin) |
| storageKeyPrefix | string | Storage key prefix for OAuth data in localStorage (defaults to "mcp:auth") |
| clientConfig | object | Custom configuration for the MCP client identity |
| debug | boolean | Whether to enable verbose debug logging |
| autoRetry | boolean \| number | Auto retry connection if initial connection fails, with delay in ms |
| autoReconnect | boolean \| number | Auto reconnect if an established connection is lost, with delay in ms (default: 3000) |
| transportType | 'auto' \| 'http' \| 'sse' | Transport type preference: 'auto' (HTTP with SSE fallback), 'http' (HTTP only), 'sse' (SSE only) (default: 'auto') |
| preventAutoAuth | boolean | Prevent automatic authentication popup on initial connection (default: false) |
| onPopupWindow | (url: string, features: string, window: Window \| null) => void | Callback invoked just after the authentication popup window is opened |

#### Return Value

| Property | Type | Description |
|----------|------|-------------|
| state | string | Current connection state: 'discovering', 'pending_auth', 'authenticating', 'connecting', 'loading', 'ready', 'failed' |
| tools | Tool[] | Available tools from the MCP server |
| resources | Resource[] | Available resources from the MCP server |
| resourceTemplates | ResourceTemplate[] | Available resource templates from the MCP server |
| prompts | Prompt[] | Available prompts from the MCP server |
| error | string \| undefined | Error message if connection failed |
| authUrl | string \| undefined | Manual authentication URL if popup is blocked |
| log | { level: 'debug' \| 'info' \| 'warn' \| 'error'; message: string; timestamp: number }[] | Array of log messages |
| callTool | (name: string, args?: Record) => Promise | Function to call a tool on the MCP server |
| listResources | () => Promise | Refresh the list of available resources |
| readResource | (uri: string) => Promise<{ contents: Array<...> }> | Read the contents of a specific resource |
| listPrompts | () => Promise | Refresh the list of available prompts |
| getPrompt | (name: string, args?: Record) => Promise<{ messages: Array<...> }> | Get a specific prompt with optional arguments |
| retry | () => void | Manually attempt to reconnect |
| disconnect | () => void | Disconnect from the MCP server |
| authenticate | () => void | Manually trigger authentication |
| clearStorage | () => void` | Clear all stored authentication data |

License

MIT