Class McpClientOptions

Namespace

ModelContextProtocol.Client

Assembly

ModelContextProtocol.Core.dll

Provides configuration options for creating McpClient instances.

public sealed class McpClientOptions

Inheritance

object

McpClientOptions

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Remarks

These options are typically passed to CreateAsync(IClientTransport, McpClientOptions?, ILoggerFactory?, CancellationToken) when creating a client. They define client capabilities, protocol version, and other client-specific settings.

Properties

Capabilities

Gets or sets the client capabilities to advertise to the server.

public ClientCapabilities? Capabilities { get; set; }

Property Value

ClientCapabilities

ClientInfo

Gets or sets information about this client implementation, including its name and version.

public Implementation? ClientInfo { get; set; }

Property Value

Implementation

Remarks

This information is sent to the server during initialization to identify the client. It's often displayed in server logs and can be used for debugging and compatibility checks.

When not specified, information sourced from the current process is used.

DiscoverProbeTimeout

Gets or sets the timeout applied to the server/discover probe that the client issues before falling back to the legacy initialize handshake.

public TimeSpan DiscoverProbeTimeout { get; set; }

Property Value

TimeSpan

The probe timeout. The default value is 5 seconds. Use InfiniteTimeSpan to disable the separate probe timeout and rely solely on InitializationTimeout.

Remarks

This timeout only has an effect when the client prefers the 2026-07-28 protocol revision, that is, when ProtocolVersion is null (the default) or 2026-07-28. In that mode the client first probes the server with a server/discover request. A legacy server that predates the 2026-07-28 revision may silently drop the unknown method, so the probe is bounded by this timeout; when it elapses the client concludes the server is legacy and falls back to the initialize handshake on the same connection. When the caller pins a legacy ProtocolVersion, no probe is issued and this value has no effect.

The default is intentionally short so that dual-era clients fall back quickly against legacy servers. Increase it for high-latency environments (for example, cold-start serverless peers or satellite links) where a short probe could trigger the legacy fallback before a server on the new revision server has had a chance to respond. The probe is always also bounded by InitializationTimeout, which governs the overall connect budget: if this value is greater than or equal to InitializationTimeout, the probe is effectively bounded by InitializationTimeout alone.

Exceptions

ArgumentOutOfRangeException

The value is not positive and is not InfiniteTimeSpan.

Handlers

Gets or sets the container of handlers used by the client for processing protocol messages.

public McpClientHandlers Handlers { get; set; }

Property Value

McpClientHandlers

InitializationTimeout

Gets or sets a timeout for the client-server initialization handshake sequence.

public TimeSpan InitializationTimeout { get; set; }

Property Value

TimeSpan

The timeout for the client-server initialization handshake sequence. The default value is 60 seconds.

Remarks

This timeout determines how long the client will wait for the server to respond during the initialization protocol handshake. If the server doesn't respond within this timeframe, an exception is thrown.

Setting an appropriate timeout prevents the client from hanging indefinitely when connecting to unresponsive servers.

InitializeMeta

Gets or sets the metadata to include in the _meta field of the Initialize request.

public JsonObject? InitializeMeta { get; set; }

Property Value

JsonObject

Remarks

When set, this value is sent as Meta on the InitializeRequestParams during the initialization handshake. This allows passing implementation-specific data to the server alongside the standard initialize parameters, such as authentication context a server validates before completing the handshake.

When null, no _meta field is sent.

MaxConsecutiveStuckPolls

Gets or sets the maximum number of consecutive task polls during which a task may report InputRequired without publishing any new input requests, before the client treats the task as stuck, issues a best-effort tasks/cancel, and throws an McpException.

public int MaxConsecutiveStuckPolls { get; set; }

Property Value

int

The maximum number of consecutive stuck polls allowed. The default value is 60.

Remarks

This guard prevents an unbounded poll loop when the server keeps a task in InputRequired but never publishes new input requests after the client has already responded to every previously surfaced request. It only affects the long-poll path used by CallToolAsync(CallToolRequestParams, CancellationToken); it does not affect direct GetTaskAsync(string, CancellationToken) calls.

Callers should size this value with the configured server-side poll interval in mind: the effective wall-clock timeout is roughly MaxConsecutiveStuckPolls * pollIntervalMs. Setting this to a very small value can cause false positives for servers that are slow to surface follow-up input requests; setting it too large can mask misbehaving servers.

Exceptions

ArgumentOutOfRangeException

The value is less than 1.

ProtocolVersion

Gets or sets the protocol version to request from the server, using a date-based versioning scheme.

public string? ProtocolVersion { get; set; }

Property Value

string

Remarks

When null (the default), the client prefers the latest revision (2026-07-28), which removed the initialize handshake and Streamable HTTP sessions. It probes with server/discover and automatically falls back to the legacy initialize handshake, downgrading to any version the server advertises, when the server does not support that revision.

When non-null, this value is both the requested version and the minimum the client will accept: the client requests exactly this version and refuses to downgrade below it, throwing an McpException instead of falling back. Setting it to 2026-07-28 therefore disables the automatic legacy-server fallback, and setting it to a version that still supports Streamable HTTP sessions, such as 2025-11-25, forces the initialize handshake and fails if the server negotiates a different version. To try more than one version, leave this unset for automatic fallback or retry the connection with a different value.