Interface McpServerConfig

Serializable configuration for one server managed by McpClientProvider. Pass this to addServer / updateServer.

interface McpServerConfig {
    authProvider?: OAuthClientProvider;
    autoProxyFallback?: boolean | { enabled?: boolean; proxyAddress?: string };
    autoReconnect?:
        | number
        | boolean
        | {
            enabled?: boolean;
            healthCheckInterval?: number
            | false;
            healthCheckTimeout?: number;
            initialDelay?: number;
        };
    autoRetry?: number
    | boolean;
    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?: {} & { views?: boolean };
    };
    connectionMode?: "auto"
    | "direct"
    | "proxy";
    displayName?: string;
    enabled?: boolean;
    fetch?: {
        (input: URL | RequestInfo, init?: RequestInit): Promise<Response>;
        (input: string | URL | Request, init?: RequestInit): Promise<Response>;
    };
    headers?: Record<string, string>;
    logLevel?:
        | "silent"
        | "error"
        | "warn"
        | "info"
        | "http"
        | "verbose"
        | "debug"
        | "silly";
    oauth?: { clientId?: string; clientMetadataUrl?: string; scope?: string };
    oauthProxyUrl?: string;
    onElicitationRequest?: (request: PendingElicitationRequest) => void;
    onNotificationReceived?: (notification: McpNotification) => void;
    onPopupWindow?: (
        url: string,
        features: string,
        window: Window | null,
    ) => void;
    onSamplingRequest?: (request: PendingSamplingRequest) => void;
    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;
}

Hierarchy

Omit<UseMcpOptions, "onSampling" | "onElicitation" | "onNotification">
- McpServerConfig

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?:
    | number
    | boolean
    | {
        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

number
boolean
{
    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?: number | boolean

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?: {} & { 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?: {} & { 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`displayName

displayName?: string

Optional user-facing alias. server.name always comes from MCP server metadata.

`Optional`enabled

enabled?: boolean

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

`Optional`fetch

fetch?: {
(input: URL | RequestInfo, init?: RequestInit): Promise<Response>;
(input: string | URL | Request, init?: RequestInit): Promise<Response>;
}

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.

Type Declaration

- (input: URL | RequestInfo, init?: RequestInit): Promise<Response>
- MDN Reference
  Parameters
  - input: URL | RequestInfo
  - Optionalinit: RequestInit
  Returns Promise<Response>
- (input: string | URL | Request, init?: RequestInit): Promise<Response>
- MDN Reference
  Parameters
  - input: string | URL | Request
  - Optionalinit: RequestInit
  Returns Promise<Response>

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`onElicitationRequest

onElicitationRequest?: (request: PendingElicitationRequest) => void

Optional callback invoked when the provider queues elicitation.

`Optional`onNotificationReceived

onNotificationReceived?: (notification: McpNotification) => void

Optional callback invoked when the provider receives a notification.

`Optional`onPopupWindow

onPopupWindow?: (url: string, features: string, window: 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: 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: Window | null
  Returns void

`Optional`onSamplingRequest

onSamplingRequest?: (request: PendingSamplingRequest) => void

Optional callback invoked when the provider queues sampling.

`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.

Interface McpServerConfig

Hierarchy

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?: {} & { views?: boolean }

Example

OptionalconnectionMode

OptionaldisplayName

Optionalenabled

Optionalfetch

Type Declaration

Parameters

Returns Promise<Response>

Parameters

Returns Promise<Response>

Example

Optionalheaders

OptionallogLevel

Default Value

Optionaloauth

Type Declaration

OptionalclientId?: string

OptionalclientMetadataUrl?: string

Optionalscope?: string

Example

OptionaloauthProxyUrl

OptionalonElicitationRequest

OptionalonNotificationReceived

OptionalonPopupWindow

Type Declaration

Parameters

Returns void

OptionalonSamplingRequest

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?: {} & { views?: boolean }

`Optional`connectionMode

`Optional`displayName

`Optional`enabled

`Optional`fetch

`Optional`headers

`Optional`logLevel

`Optional`oauth

`Optional`clientId?: string

`Optional`clientMetadataUrl?: string

`Optional`scope?: string

`Optional`oauthProxyUrl

`Optional`onElicitationRequest

`Optional`onNotificationReceived

`Optional`onPopupWindow

`Optional`onSamplingRequest

`Optional`popupFeatures

`Optional`preventAutoAuth

`Optional`protocolNegotiation

`Optional`proxyConfig

`Optional`reconnectionOptions

`Optional`serverId

`Optional`storageKeyPrefix

`Optional`timeout

`Optional`url

`Optional`useRedirectFlow

`Optional`wrapTransport