Type Alias UseMcpOptions

Configures the useMcp hook and its browser connection lifecycle.

type UseMcpOptions = {
    authProvider?: OAuthClientProvider;
    autoProxyFallback?: boolean | { enabled?: boolean; proxyAddress?: string };
    autoReconnect?:
        | boolean
        | number
        | {
            enabled?: boolean;
            healthCheckInterval?: number
            | false;
            healthCheckTimeout?: number;
            initialDelay?: number;
        };
    autoRetry?: boolean
    | number;
    callbackUrl?: string;
    clientInfo?: {
        description?: string;
        icons?: { mimeType?: string; sizes?: string[]; src: string }[];
        name: string;
        title?: string;
        version: string;
        websiteUrl?: string;
    };
    clientOptions?: Omit<ClientOptions, "capabilities"> & {
        capabilities?: NonNullable<ClientOptions["capabilities"]> & {
            views?: boolean;
        };
    };
    connectionMode?: "auto"
    | "direct"
    | "proxy";
    enabled?: boolean;
    fetch?: typeof __type;
    headers?: Record<string, string>;
    logLevel?:
        | "silent"
        | "error"
        | "warn"
        | "info"
        | "http"
        | "verbose"
        | "debug"
        | "silly";
    oauth?: { clientId?: string; clientMetadataUrl?: string; scope?: string };
    oauthProxyUrl?: string;
    onElicitation?: (
        params: ElicitRequestFormParams | ElicitRequestURLParams,
    ) => Promise<ElicitResult>;
    onNotification?: (notification: Notification) => void;
    onPopupWindow?: (
        url: string,
        features: string,
        window: globalThis.Window | null,
    ) => void;
    onSampling?: (
        params: SamplingCreateMessageParams,
    ) => Promise<SamplingCreateMessageResult>;
    popupFeatures?: string;
    preventAutoAuth?: boolean;
    protocolNegotiation?: VersionNegotiationMode;
    proxyConfig?: ProxyConfig;
    reconnectionOptions?: ReconnectionOptions;
    serverId?: string;
    storageKeyPrefix?: string;
    timeout?: number;
    url?: string;
    useRedirectFlow?: boolean;
    wrapTransport?: (transport: Transport, serverId: string) => Transport;
}

Properties

`Optional`authProvider

authProvider?: OAuthClientProvider

Optional external OAuth client provider.

When provided, useMcp will use this provider directly instead of creating BrowserOAuthClientProvider internally. This is useful for headless/testing runtimes where popup/redirect flows are not available.

`Optional`autoProxyFallback

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

Enable automatic proxy fallback when direct connection fails When enabled, if a direct connection fails with FastMCP or CORS errors, automatically retries using the proxy configuration

Can be:

true: Enable with proxyConfig.proxyAddress
false: Disable automatic fallback (default)
{ enabled: boolean, proxyAddress?: string }: Custom configuration

Type Declaration

boolean
{ enabled?: boolean; proxyAddress?: string }
- Optionalenabled?: boolean
  
  Whether fallback is enabled.
- OptionalproxyAddress?: string
  
  Proxy endpoint used after a qualifying direct failure.

Default Value

false

Example

// Use default proxy
useMcp({ url: '...', autoProxyFallback: true })

// Use custom proxy
useMcp({
  url: '...',
  autoProxyFallback: {
    enabled: true,
    proxyAddress: 'https://my-proxy.com/api/proxy'
  }
})

`Optional`autoReconnect

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

Auto reconnect if an established connection is lost.

Can be:

boolean: Enable/disable with default 3000ms delay and 10s health check
number: Reconnect delay in ms (enables health checks with defaults)
object: Full configuration for reconnection and health checks

Type Declaration

boolean
number
{
    enabled?: boolean;
    healthCheckInterval?: number | false;
    healthCheckTimeout?: number;
    initialDelay?: number;
}
- Optionalenabled?: boolean
  
  Whether to enable automatic reconnection (default: true)
- OptionalhealthCheckInterval?: number | false
  
  Interval in ms for health check polling via HEAD requests. Set to false to disable health checks entirely.
  
  Default Value
  10000
- OptionalhealthCheckTimeout?: number
  
  Time in ms without a successful health check before triggering reconnect.
  
  Default Value
  30000
- OptionalinitialDelay?: number
  
  Delay in ms before reconnection attempt (default: 3000)

Default Value

true with a 3000 ms initial delay

`Optional`autoRetry

autoRetry?: boolean | number

Auto retry connection if initial connection fails, with delay in ms (default: false)

`Optional`callbackUrl

callbackUrl?: string

Custom callback URL for OAuth redirect (defaults to /oauth/callback on the current origin)

`Optional`clientInfo

clientInfo?: {
    description?: string;
    icons?: { mimeType?: string; sizes?: string[]; src: string }[];
    name: string;
    title?: string;
    version: string;
    websiteUrl?: string;
}

Client information advertised while establishing the MCP connection.

Type Declaration

Optionaldescription?: string

Optional human-readable client description.
Optionalicons?: { mimeType?: string; sizes?: string[]; src: string }[]

Icons representing the client.
name: string

Stable programmatic client name.
Optionaltitle?: string

Optional human-readable client title.
version: string

Client version.
OptionalwebsiteUrl?: string

Public website describing the client.

`Optional`clientOptions

clientOptions?: Omit<ClientOptions, "capabilities"> & {
    capabilities?: NonNullable<ClientOptions["capabilities"]> & {
        views?: boolean;
    };
}

Additional client options passed to the underlying MCP SDK Client. Use capabilities.views: true as shorthand for the MCP Apps UI extension, or set capabilities.extensions directly.

Type Declaration

Optionalcapabilities?: NonNullable<ClientOptions["capabilities"]> & { views?: boolean }

MCP capabilities advertised by the underlying SDK client.

Example

useMcp({
  url: '...',
  clientOptions: {
    capabilities: {
      views: true,
    },
  },
})

`Optional`connectionMode

connectionMode?: "auto" | "direct" | "proxy"

Connection policy for proxy routing.

auto: start direct and use autoProxyFallback after a qualifying failure
direct: never use proxyConfig and never fall back
proxy: use proxyConfig immediately and never fall back

When omitted, proxyConfig retains its legacy immediate-proxy behavior, except when autoProxyFallback explicitly requests a direct-first attempt.

`Optional`enabled

enabled?: boolean

Enable/disable the connection (similar to TanStack Query). When false, no connection will be attempted (default: true)

`Optional`fetch

fetch?: typeof __type

Optional custom fetch function to use for all MCP HTTP requests.

When provided, this replaces the default global fetch for transport-level requests. Useful for adding custom auth retry logic, logging, or proxying.

Example

useMcp({
  url: 'http://localhost:3000/mcp',
  fetch: myCustomFetch,
})

`Optional`headers

headers?: Record<string, string>

Headers that can be used to bypass auth

`Optional`logLevel

Log level for console output. Set to 'silent' to suppress ALL console logging (the mcp.log state array is still populated).

Default Value

"silent"

`Optional`oauth

oauth?: { clientId?: string; clientMetadataUrl?: string; scope?: string }

OAuth client registration settings.

Use this when the upstream auth server does not support Dynamic Client Registration — for example, MCP servers running in proxy mode against Slack, WorkOS, or similar providers. Prefer clientMetadataUrl when the authorization server advertises CIMD support; the SDK falls back to DCR when appropriate.

Type Declaration

OptionalclientId?: string

Pre-registered OAuth client_id.
OptionalclientMetadataUrl?: string

Public HTTPS OAuth Client ID Metadata Document URL (CIMD). The document must contain a matching client_id and redirect_uris.
Optionalscope?: string

OAuth scope string included in the authorize request.

Example

useMcp({
  url: 'https://mcp.example.com',
  oauth: {
    clientId: 'my-preregistered-client-id',
    clientMetadataUrl: 'https://app.example.com/oauth/client-metadata.json',
    scope: 'openid profile email',
  },
})

`Optional`oauthProxyUrl

oauthProxyUrl?: string

OAuth proxy base URL (e.g. https://inspector.example.com/inspector/api/oauth) used to route OAuth requests (.well-known discovery, DCR, token exchange) through a transparent server-side proxy — bypassing browser CORS against third-party identity providers — WITHOUT proxying MCP traffic itself.

The proxy is transparent: it forwards requests and responses unmodified, so the SDK's authorization-server issuer validation (RFC 8414 §3.3) still passes. When omitted, the OAuth proxy URL is derived from proxyConfig.proxyAddress (replacing a trailing /proxy with /oauth), preserving the existing behavior for fully-proxied connections.

`Optional`onElicitation

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

Optional callback function to handle elicitation requests from servers. When provided, the client will declare elicitation capability and handle elicitation/create requests by calling this callback.

Elicitation allows servers to request additional information from users:

Form mode: Collect structured data with JSON schema validation
URL mode: Direct users to external URLs for sensitive interactions

`Optional`onNotification

onNotification?: (notification: Notification) => void

Callback function that is invoked when a notification is received from the MCP server

`Optional`onPopupWindow

onPopupWindow?: (
    url: string,
    features: string,
    window: globalThis.Window | null,
) => void

Callback function that is invoked just before the authentication popup window is opened. Only used when useRedirectFlow is false (popup mode).

Type Declaration

- (url: string, features: string, window: globalThis.Window | null): void
- Parameters
  - url: string
    The URL that will be opened in the popup.
  - features: string
    The features string for the popup window.
  - window: globalThis.Window | null
  Returns void

`Optional`onSampling

onSampling?: (
params: SamplingCreateMessageParams,
) => Promise<SamplingCreateMessageResult>

Optional callback function to handle sampling requests from servers. When provided, the client will declare sampling capability and handle sampling/createMessage requests by calling this callback.

Deprecated

Sampling is deprecated by the 2026 protocol. Retained for v1 push requests and v2 multi-round-trip compatibility.

`Optional`popupFeatures

popupFeatures?: string

Popup window features string (dimensions and behavior) for OAuth

`Optional`preventAutoAuth

preventAutoAuth?: boolean

Prevent automatic authentication popup/redirect on initial connection (default: true) When true, the connection will enter 'pending_auth' state and wait for user to call authenticate() Set to true to show a modal/button before triggering OAuth instead of auto-redirecting

`Optional`protocolNegotiation

protocolNegotiation?: VersionNegotiationMode

Protocol version negotiation mode passed to the underlying SDK Client.

"auto" (default): probe with server/discover to detect modern (2026-07-28) servers, falling back to the 2025 handshake against legacy servers.
"legacy": classic 2025 initialize handshake, no probe.
{ pin: "2026-07-28" }: modern era only, no fallback.

`Optional`proxyConfig

proxyConfig?: ProxyConfig

Proxy configuration for routing through a proxy server

`Optional`reconnectionOptions

reconnectionOptions?: ReconnectionOptions

SDK-level reconnection options for the streamable HTTP transport

`Optional`serverId

serverId?: string

Stable identifier supplied to wrapTransport; defaults to url.

`Optional`storageKeyPrefix

storageKeyPrefix?: string

Storage key prefix for OAuth data in localStorage (defaults to "mcp:auth")

`Optional`timeout

timeout?: number

Connection timeout in milliseconds for establishing initial connection (default: 30000 / 30 seconds)

`Optional`url

url?: string

The /sse URL of your remote MCP server

`Optional`useRedirectFlow

useRedirectFlow?: boolean

Use full-page redirect for OAuth instead of popup window (default: false) Redirect flow avoids popup blockers and provides better UX on mobile. Set to true to use redirect flow instead of popup.

`Optional`wrapTransport

wrapTransport?: (transport: Transport, serverId: string) => Transport

Optional callback to wrap the transport before passing it to the Client. Useful for logging, monitoring, or other transport-level interceptors.

Type Alias UseMcpOptions

Index

Properties

Properties

OptionalauthProvider

OptionalautoProxyFallback

Type Declaration

Optionalenabled?: boolean

OptionalproxyAddress?: string

Default Value

Example

OptionalautoReconnect

Type Declaration

Optionalenabled?: boolean

OptionalhealthCheckInterval?: number | false

Default Value

OptionalhealthCheckTimeout?: number

Default Value

OptionalinitialDelay?: number

Default Value

OptionalautoRetry

OptionalcallbackUrl

OptionalclientInfo

Type Declaration

Optionaldescription?: string

Optionalicons?: { mimeType?: string; sizes?: string[]; src: string }[]

name: string

Optionaltitle?: string

version: string

OptionalwebsiteUrl?: string

OptionalclientOptions

Type Declaration

Optionalcapabilities?: NonNullable<ClientOptions["capabilities"]> & { views?: boolean }

Example

OptionalconnectionMode

Optionalenabled

Optionalfetch

Example

Optionalheaders

OptionallogLevel

Default Value

Optionaloauth

Type Declaration

OptionalclientId?: string

OptionalclientMetadataUrl?: string

Optionalscope?: string

Example

OptionaloauthProxyUrl

OptionalonElicitation

OptionalonNotification

OptionalonPopupWindow

Type Declaration

Parameters

Returns void

OptionalonSampling

Deprecated

OptionalpopupFeatures

OptionalpreventAutoAuth

OptionalprotocolNegotiation

OptionalproxyConfig

OptionalreconnectionOptions

OptionalserverId

OptionalstorageKeyPrefix

Optionaltimeout

Optionalurl

OptionaluseRedirectFlow

OptionalwrapTransport

Settings

On This Page

`Optional`authProvider

`Optional`autoProxyFallback

`Optional`enabled?: boolean

`Optional`proxyAddress?: string

`Optional`autoReconnect

`Optional`enabled?: boolean

`Optional`healthCheckInterval?: number | false

`Optional`healthCheckTimeout?: number

`Optional`initialDelay?: number

`Optional`autoRetry

`Optional`callbackUrl

`Optional`clientInfo

`Optional`description?: string

`Optional`icons?: { mimeType?: string; sizes?: string[]; src: string }[]

`Optional`title?: string

`Optional`websiteUrl?: string

`Optional`clientOptions

`Optional`capabilities?: NonNullable<ClientOptions["capabilities"]> & { views?: boolean }

`Optional`connectionMode

`Optional`enabled

`Optional`fetch

`Optional`headers

`Optional`logLevel

`Optional`oauth

`Optional`clientId?: string

`Optional`clientMetadataUrl?: string

`Optional`scope?: string

`Optional`oauthProxyUrl

`Optional`onElicitation

`Optional`onNotification

`Optional`onPopupWindow

`Optional`onSampling

`Optional`popupFeatures

`Optional`preventAutoAuth

`Optional`protocolNegotiation

`Optional`proxyConfig

`Optional`reconnectionOptions

`Optional`serverId

`Optional`storageKeyPrefix

`Optional`timeout

`Optional`url

`Optional`useRedirectFlow

`Optional`wrapTransport