API Reference

useMcp(options)

The main hook for connecting to an MCP server.

Options (UseMcpOptions)

Property Type Default Description
url string Required The URL of the MCP server (e.g., http://localhost:8080/sse).
transportType 'auto' \| 'http' \| 'sse' 'auto' The transport mechanism to use. auto tries HTTP then falls back to SSE.
clientName string 'MCP React Client' Name sent to the server for identification/logging.
clientUri string window.location.origin URI sent to the server for OAuth identification.
callbackUrl string /oauth/callback Absolute URL for OAuth redirect. Must handle onMcpAuthorization.
storageKeyPrefix string 'mcp:auth' Prefix for localStorage keys used for auth tokens.
autoReconnect boolean \| number 3000 Time in ms to wait before reconnecting on disconnect. false to disable.
autoRetry boolean \| number false Time in ms to wait before retrying initial connection failure.
debug boolean false Enables verbose logging to console and log state.
preventAutoAuth boolean false If true, prevents automatic popup windows for authentication.

Returns (UseMcpResult)

State

  • state: 'discovering' | 'pending_auth' | 'authenticating' | 'connecting' | 'loading' | 'ready' | 'failed'
  • error: string | undefined - Error message if state is failed.
  • log: Array<{ level: string, message: string, timestamp: number }> - Debug logs.

Data

  • tools: Tool[] - List of available tools.
  • resources: Resource[] - List of available static resources.
  • resourceTemplates: ResourceTemplate[] - List of resource URI templates.
  • prompts: Prompt[] - List of available prompts.

Actions

  • callTool(name, args): Executes a tool. Returns Promise<any>.
  • readResource(uri): Reads resource content. Returns Promise<{ contents: ... }>.
  • getPrompt(name, args): Hydrates a prompt. Returns Promise<{ messages: ... }>.
  • listResources(): Forces a refresh of the resources list.
  • listPrompts(): Forces a refresh of the prompts list.
  • retry(): Manually triggers a connection retry.
  • disconnect(): Closes the connection.
  • authenticate(): Manually opens the OAuth popup window.
  • clearStorage(): Clears authentication tokens from local storage.

onMcpAuthorization()

A helper function that must be called on your OAuth callback page. It parses URL parameters (code, state, error), completes the handshake with the auth provider, and communicates with the main window via postMessage.