React client

import {
  LocalStorageProvider,
  McpClientProvider,
  MemoryStorageProvider,
  useMcp,
  useMcpClient,
  useMcpServer,
} from "mcp-use/react";
import type {
  McpClientContextType,
  McpClientProviderProps,
  McpServer,
  McpServerOptions,
  StorageProvider,
  UseMcpOptions,
  UseMcpResult,
} from "mcp-use/react";

​

McpClientProvider

​

children

ReactNode

required

React children rendered inside the provider.

​

mcpServers

Record<string, McpServerOptions>

default:"undefined"

Initial server map. Servers in this map connect when the provider mounts.

​

defaultCallbackUrl

string

default:"\"/oauth/callback\" on the current origin"

Default OAuth callback URL for servers that do not set callbackUrl.

​

defaultProxyConfig

{ proxyAddress?: string; headers?: Record<string, string> }

default:"undefined"

Default proxy configuration for all servers. Per-server proxyConfig overrides these values.

​

defaultAutoProxyFallback

boolean | { enabled?: boolean; proxyAddress?: string }

default:"true"

Whether direct connection failures caused by FastMCP or CORS should retry through a proxy.

​

clientInfo

ClientInfo & { capabilities?: Record<string, unknown> }

default:"mcp-use client info"

Client metadata and default advertised MCP capabilities for every managed server.

​

storageProvider

StorageProvider

default:"undefined"

Storage adapter used to load, save, and remove server configurations.

​

enableRpcLogging

boolean

default:"false"

When true, logs MCP protocol messages in the browser for debugging.

​

onServerAdded

(id: string, server: McpServer) => void

default:"undefined"

Called after a server is added.

​

onServerRemoved

(id: string) => void

default:"undefined"

Called after a server is removed.

​

onServerStateChange

(id: string, state: McpServer["state"]) => void

default:"undefined"

Called when a managed server changes connection state.

​

onSamplingRequest

(request, serverId, serverName, approve, reject) => void

default:"undefined"

Called when any managed server requests sampling.

​

onElicitationRequest

(request, serverId, serverName, approve, reject) => void

default:"undefined"

Called when any managed server requests elicitation.

function McpClientProvider(props: McpClientProviderProps): JSX.Element

​

useMcpClient

​

servers

McpServer[]

All managed servers with connection state, methods, notifications, and pending request queues.

​

addServer

(id: string, options: McpServerOptions) => void

Adds a server. Calls with an existing id are ignored.

​

removeServer

(id: string, opts?: { clearCredentials?: boolean }) => void

Removes a server. Set clearCredentials: true to also clear persisted OAuth credentials.

​

updateServerMetadata

(id: string, metadata: { name: string }) => Promise<void>

Updates display metadata without reconnecting.

​

updateServer

(id: string, options: Partial<McpServerOptions>) => Promise<void>

Updates connection-affecting options and reconnects the server.

​

getServer

(id: string) => McpServer | undefined

Returns a managed server by id.

​

storageLoaded

boolean

Whether configured storage has finished loading.

function useMcpClient(): McpClientContextType

​

useMcpServer

​

id

string

required

Server id passed to addServer() or the mcpServers map.

​

returns

McpServer | undefined

The matching server, or undefined when no server with that id is registered.

function useMcpServer(id: string): McpServer | undefined

​

useMcp

​

options

UseMcpOptions

required

Connection, authentication, callback, reconnection, and transport options.

​

returns

UseMcpResult

Connection state, discovered tools/resources/prompts, protocol methods, auth metadata, logs, and the underlying browser client.

function useMcp(options: UseMcpOptions): UseMcpResult

​

McpServerOptions

​

url

string

HTTP MCP endpoint URL.

​

name

string

Display name shown before server metadata loads.

​

enabled

boolean

When false, the provider does not connect to the server. Defaults to true.

​

headers

Record<string, string>

Headers sent with HTTP transport requests.

​

transportType

"auto" | "http" | "sse"

Transport preference. Use "auto" for streamable HTTP with fallback.

​

timeout

number

Initial connection timeout in milliseconds. Defaults to 30000.

​

proxyConfig

{ proxyAddress?: string; headers?: Record<string, string> }

Proxy settings for this server.

​

autoProxyFallback

boolean | { enabled?: boolean; proxyAddress?: string }

Per-server automatic proxy fallback setting.

​

preventAutoAuth

boolean

When true, the server enters pending_auth until authenticate() is called.

​

useRedirectFlow

boolean

When true, OAuth uses full-page redirect instead of a popup.

​

callbackUrl

string

OAuth callback URL for this server.

​

authProvider

OAuthClientProvider

External OAuth provider for headless or custom runtimes.

​

oauth

{ clientId?: string; clientSecret?: string; scope?: string }

Pre-registered OAuth client credentials for servers without Dynamic Client Registration.

​

clientInfo

ClientInfo

Client metadata sent during MCP initialization and OAuth registration.

​

autoRetry

boolean | number

Retry initial connection failures. A number sets the retry delay in milliseconds.

​

autoReconnect

boolean | number | { enabled?: boolean; initialDelay?: number; healthCheckInterval?: number | false; healthCheckTimeout?: number }

Application-level reconnection and health check behavior.

​

reconnectionOptions

ReconnectionOptions

SDK transport-level retry settings.

​

wrapTransport

(transport: any, serverId: string) => any

Transport wrapper for logging, monitoring, or custom behavior.

​

onSamplingRequest

(request: PendingSamplingRequest) => void

Per-server app callback for sampling requests.

​

onElicitationRequest

(request: PendingElicitationRequest) => void

Per-server app callback for elicitation requests.

​

onNotificationReceived

(notification: McpNotification) => void

Per-server app callback for notifications.

​

McpServer

​

id

string

Provider server id.

​

url

string

Server URL.

​

name

string

Display name supplied by the app.

​

state

"discovering" | "pending_auth" | "authenticating" | "ready" | "failed"

Current connection state.

​

tools

Tool[]

Discovered server tools.

​

resources

Resource[]

Discovered server resources.

​

resourceTemplates

ResourceTemplate[]

Discovered server resource templates.

​

prompts

Prompt[]

Discovered server prompts.

​

serverInfo

{ name: string; title?: string; version?: string; websiteUrl?: string; icons?: Array<{ src: string; mimeType?: string }>; icon?: string }

Server metadata from initialization.

​

error

string | undefined

Failure message when state is "failed".

​

callTool

(name: string, args?: Record<string, unknown>, options?: RequestOptions) => Promise<any>

Calls a server tool.

​

readResource

(uri: string) => Promise<ReadResourceResult>

Reads a resource by URI.

​

listResources

() => Promise<void>

Refreshes the resource list.

​

listPrompts

() => Promise<void>

Refreshes the prompt list.

​

getPrompt

(name: string, args?: Record<string, string>) => Promise<GetPromptResult>

Gets a prompt by name.

​

complete

(params: CompleteRequestParams) => Promise<CompleteResult>

Requests prompt or resource template completions.

​

refreshTools

() => Promise<void>

Refreshes the tool list.

​

refreshResources

() => Promise<void>

Refreshes the resource list.

​

refreshResourceTemplates

() => Promise<void>

Refreshes the resource template list.

​

refreshPrompts

() => Promise<void>

Refreshes the prompt list.

​

refreshAll

() => Promise<void>

Refreshes tools, resources, resource templates, and prompts.

​

retry

() => void

Attempts to reconnect after failure.

​

disconnect

() => void

Disconnects from the server.

​

authenticate

() => void

Starts OAuth authentication.

​

clearStorage

() => void

Clears OAuth storage for this server URL.

​

notifications

McpNotification[]

Stored notifications from this server.

​

unreadNotificationCount

number

Unread notification count.

​

markNotificationRead

(id: string) => void

Marks one notification as read.

​

markAllNotificationsRead

() => void

Marks all notifications as read.

​

clearNotifications

() => void

Clears stored notifications.

​

pendingSamplingRequests

PendingSamplingRequest[]

Pending sampling requests from this server.

​

approveSampling

(requestId: string, result: CreateMessageResult) => void

Approves a sampling request.

​

rejectSampling

(requestId: string, error?: string) => void

Rejects a sampling request.

​

pendingElicitationRequests

PendingElicitationRequest[]

Pending elicitation requests from this server.

​

approveElicitation

(requestId: string, result: ElicitResult) => void

Approves an elicitation request.

​

rejectElicitation

(requestId: string, error?: string) => void

Rejects an elicitation request.

​

client

BrowserMCPClient | null

Underlying browser client.

​

UseMcpOptions

​

url

string

HTTP MCP endpoint URL.

​

enabled

boolean

When false, no connection is attempted. Defaults to true.

​

proxyConfig

{ proxyAddress?: string; headers?: Record<string, string> }

Proxy settings for this connection.

​

autoProxyFallback

boolean | { enabled?: boolean; proxyAddress?: string }

Retries direct FastMCP or CORS failures through a proxy. Defaults to true for standalone useMcp().

​

callbackUrl

string

OAuth callback URL. Defaults to /oauth/callback on the current origin.

​

storageKeyPrefix

string

OAuth localStorage key prefix. Defaults to "mcp:auth".

​

headers

Record<string, string>

HTTP request headers.

​

logLevel

"silent" | "error" | "warn" | "info" | "http" | "verbose" | "debug" | "silly"

Console log level.

​

autoRetry

boolean | number

Retry initial connection failures. A number sets the retry delay in milliseconds.

​

autoReconnect

boolean | number | { enabled?: boolean; initialDelay?: number; healthCheckInterval?: number | false; healthCheckTimeout?: number }

Application-level reconnection and health check behavior. Defaults to 3000.

​

reconnectionOptions

ReconnectionOptions

SDK transport-level retry settings.

​

popupFeatures

string

Popup feature string for OAuth popup mode.

​

transportType

"auto" | "http" | "sse"

Transport preference. "sse" is deprecated but supported.

​

preventAutoAuth

boolean

When true, wait for authenticate() before opening OAuth.

​

useRedirectFlow

boolean

Use full-page OAuth redirect instead of a popup.

​

onPopupWindow

(url: string, features: string, window: Window | null) => void

Called just before the OAuth popup opens.

​

clientOptions

{ capabilities?: Record<string, unknown> }

Options passed to the underlying MCP SDK client.

​

timeout

number

Initial connection timeout in milliseconds. Defaults to 30000.

​

sseReadTimeout

number

SSE read timeout in milliseconds. Defaults to 300000.

​

wrapTransport

(transport: any, serverId: string) => any

Transport wrapper.

​

onNotification

(notification: Notification) => void

Called when the server sends a notification.

​

onSampling

(params: CreateMessageRequest['params']) => Promise<CreateMessageResult>

Handles sampling/createMessage requests.

​

onElicitation

(params: ElicitRequestFormParams | ElicitRequestURLParams) => Promise<ElicitResult>

Handles elicitation/create requests.

​

clientInfo

ClientInfo

Client metadata sent during MCP initialization and OAuth registration.

​

fetch

typeof globalThis.fetch

Custom fetch function for MCP HTTP requests.

​

authProvider

OAuthClientProvider

External OAuth provider.

​

oauth

{ clientId?: string; clientSecret?: string; scope?: string }

Pre-registered OAuth client settings.

​

StorageProvider

​

getServers

() => Promise<Record<string, McpServerOptions>> | Record<string, McpServerOptions>

Returns all stored server configurations.

​

setServers

(servers: Record<string, McpServerOptions>) => Promise<void> | void

Replaces all stored server configurations.

​

setServer

(id: string, config: McpServerOptions) => Promise<void> | void

Adds or updates one server configuration.

​

removeServer

(id: string) => Promise<void> | void

Removes one server configuration.

​

clear

() => Promise<void> | void

Clears all server configurations.

​

getServerMetadata

(id: string) => Promise<CachedServerMetadata | undefined> | CachedServerMetadata | undefined

Optionally returns cached server metadata.

​

setServerMetadata

(id: string, metadata: CachedServerMetadata) => Promise<void> | void

Optionally stores cached server metadata.

​

removeServerMetadata

(id: string) => Promise<void> | void

Optionally removes cached server metadata.

​

LocalStorageProvider

​

storageKey

string

default:"\"mcp-client-servers\""

localStorage key used for server configurations. Metadata uses ${storageKey}-metadata.

class LocalStorageProvider implements StorageProvider {
  constructor(storageKey?: string)
}

​

MemoryStorageProvider

class MemoryStorageProvider implements StorageProvider {
  constructor()
}

​

Related

• React Integration: guide to using the provider and hooks in a React app.
• Authentication: OAuth and bearer token setup.
• Completions: prompt and resource template completion examples.