use-mcp

The useMcp React hook abstracts MCP server communication complexity through a state machine-driven connection lifecycle that automatically manages connection establishment, reconnection with configurable backoff delays, and graceful disconnection. It exposes connection state (connecting, connected, disconnecting, disconnected, error) and error details through hook return values, enabling React components to reactively render UI based on connection status without manual socket or transport layer management.

The library provides an onMcpAuthorization function that orchestrates OAuth 2.0 authentication by opening a popup window to the MCP server's authorization endpoint, capturing the callback through a configurable callback URL route, and exchanging the authorization code for credentials. It includes fallback mechanisms for browsers that block popups and integrates with multiple routing frameworks (React Router, Next.js Pages, custom setups) through a flexible callback handler pattern.

The useMcp hook exposes a callTool(name, args) method that executes MCP tools with type safety enforced through the MCP protocol's schema definitions. The library validates arguments against the tool's declared schema before transmission and provides structured error responses if validation fails or execution errors occur. This enables IDE autocomplete and compile-time type checking for tool arguments when used with TypeScript.

The useMcp hook automatically detects and selects between HTTP long-polling and Server-Sent Events (SSE) transports based on MCP server capabilities and network conditions. The library abstracts transport selection logic so developers specify only the server URL, and the underlying transport layer is chosen transparently. This enables seamless fallback from SSE to HTTP if the server doesn't support streaming, without requiring explicit configuration.

The useMcp hook accepts an autoReconnect configuration parameter (boolean or number) that enables automatic reconnection attempts when the MCP connection drops unexpectedly. When enabled with a numeric value, it implements exponential backoff with configurable delay intervals, preventing connection storms and allowing the server time to recover. The hook tracks reconnection attempts and exposes connection state changes through the hook return value.

The useMcp hook implements a state machine with four explicit connection states (connecting, connected, disconnecting, disconnected) plus an error state that captures detailed error information. The hook exposes both the current state and error details through its return value, enabling components to render different UI based on connection status and error type. The state machine enforces valid transitions and prevents invalid operations (e.g., calling tools while disconnected).

The use-mcp library is distributed as an NPM package with two entry points: the root export (.) provides general utilities like onMcpAuthorization for OAuth handling, while the React export (./react) provides the useMcp hook and React-specific components. This dual-export structure allows developers to use OAuth utilities in non-React contexts (e.g., Node.js backends) while keeping React dependencies optional for utility-only consumers. The build system uses tsup to compile TypeScript to both CommonJS and ES modules.

The onMcpAuthorization function provides a routing adapter pattern that integrates OAuth callbacks with React Router, Next.js Pages, and custom routing setups through a flexible handler interface. Developers define a callback route in their routing framework and pass the authorization code to onMcpAuthorization, which exchanges it for credentials and returns the authenticated connection. This pattern decouples the OAuth flow from specific routing frameworks, allowing the same logic to work across different application architectures.

The useMcp hook accepts a debug configuration parameter that enables detailed logging of MCP protocol messages, connection state transitions, and error events. When enabled, the hook populates a log array with timestamped entries that capture the full lifecycle of MCP communication, enabling developers to diagnose connection issues and protocol violations. The logging system is designed to be low-overhead when disabled and provides structured log entries for programmatic analysis.