Class McpClient

Namespace

ModelContextProtocol.Client

Assembly

ModelContextProtocol.Core.dll

Represents an instance of a Model Context Protocol (MCP) client session that connects to and communicates with an MCP server.

public abstract class McpClient : McpSession, IAsyncDisposable

Inheritance

object

McpSession

McpClient

Implements

IAsyncDisposable

Inherited Members

McpSession.SessionId

McpSession.NegotiatedProtocolVersion

McpSession.SendRequestAsync(JsonRpcRequest, CancellationToken)

McpSession.SendMessageAsync(JsonRpcMessage, CancellationToken)

McpSession.RegisterNotificationHandler(string, Func<JsonRpcNotification, CancellationToken, ValueTask>)

McpSession.DisposeAsync()

McpSession.SendRequestAsync<TParameters, TResult>(string, TParameters, JsonSerializerOptions, RequestId, CancellationToken)

McpSession.SendNotificationAsync(string, CancellationToken)

McpSession.SendNotificationAsync<TParameters>(string, TParameters, JsonSerializerOptions, CancellationToken)

McpSession.NotifyProgressAsync(ProgressToken, ProgressNotificationValue, CancellationToken)

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Properties

ServerCapabilities

Gets the capabilities supported by the connected server.

public abstract ServerCapabilities ServerCapabilities { get; }

Property Value

ServerCapabilities

Exceptions

InvalidOperationException

The client is not connected.

ServerInfo

Gets the implementation information of the connected server.

public abstract Implementation ServerInfo { get; }

Property Value

Implementation

Remarks

This property provides identification details about the connected server, including its name and version. It is populated during the initialization handshake and is available after a successful connection.

This information can be useful for logging, debugging, compatibility checks, and displaying server information to users.

Exceptions

InvalidOperationException

The client is not connected.

ServerInstructions

Gets any instructions describing how to use the connected server and its features.

public abstract string? ServerInstructions { get; }

Property Value

string

Remarks

This property contains instructions provided by the server during initialization that explain how to effectively use its capabilities. These instructions can include details about available tools, expected input formats, limitations, or any other helpful information.

This can be used by clients to improve an LLM's understanding of available tools, prompts, and resources. It can be thought of like a "hint" to the model and may be added to a system prompt.

Methods

CallToolAsync(string, IReadOnlyDictionary<string, object?>?, IProgress<ProgressNotificationValue>?, JsonSerializerOptions?, CancellationToken)

Invokes a tool on the server.

public ValueTask<CallToolResult> CallToolAsync(string toolName, IReadOnlyDictionary<string, object?>? arguments = null, IProgress<ProgressNotificationValue>? progress = null, JsonSerializerOptions? serializerOptions = null, CancellationToken cancellationToken = default)

Parameters

toolName string

The name of the tool to call on the server..

arguments IReadOnlyDictionary<string, object>

An optional dictionary of arguments to pass to the tool.

progress IProgress<ProgressNotificationValue>

Optional progress reporter for server notifications.

serializerOptions JsonSerializerOptions

JSON serializer options.

cancellationToken CancellationToken

A cancellation token.

Returns

ValueTask<CallToolResult>

The CallToolResult from the tool execution.

CompleteAsync(Reference, string, string, CancellationToken)

Requests completion suggestions for a prompt argument or resource reference.

public ValueTask<CompleteResult> CompleteAsync(Reference reference, string argumentName, string argumentValue, CancellationToken cancellationToken = default)

Parameters

reference Reference

The reference object specifying the type and optional URI or name.

argumentName string

The name of the argument for which completions are requested.

argumentValue string

The current value of the argument, used to filter relevant completions.

cancellationToken CancellationToken

The CancellationToken to monitor for cancellation requests. The default is None.

Returns

ValueTask<CompleteResult>

A CompleteResult containing completion suggestions.

CreateAsync(IClientTransport, McpClientOptions?, ILoggerFactory?, CancellationToken)

Creates an McpClient, connecting it to the specified server.

public static Task<McpClient> CreateAsync(IClientTransport clientTransport, McpClientOptions? clientOptions = null, ILoggerFactory? loggerFactory = null, CancellationToken cancellationToken = default)

Parameters

clientTransport IClientTransport

The transport instance used to communicate with the server.

clientOptions McpClientOptions

A client configuration object which specifies client capabilities and protocol version. If null, details based on the current process will be employed.

loggerFactory ILoggerFactory

A logger factory for creating loggers for clients.

cancellationToken CancellationToken

The CancellationToken to monitor for cancellation requests. The default is None.

Returns

Task<McpClient>

An McpClient that's connected to the specified server.

Exceptions

ArgumentNullException

clientTransport is null.

ArgumentNullException

clientOptions is null.

CreateSamplingHandler(IChatClient)

Creates a sampling handler for use with SamplingHandler that will satisfy sampling requests using the specified Microsoft.Extensions.AI.IChatClient.

public static Func<CreateMessageRequestParams?, IProgress<ProgressNotificationValue>, CancellationToken, ValueTask<CreateMessageResult>> CreateSamplingHandler(IChatClient chatClient)

Parameters

chatClient IChatClient

The Microsoft.Extensions.AI.IChatClient with which to satisfy sampling requests.

Returns

Func<CreateMessageRequestParams, IProgress<ProgressNotificationValue>, CancellationToken, ValueTask<CreateMessageResult>>

The created handler delegate that can be assigned to SamplingHandler.

Exceptions

ArgumentNullException

chatClient is null.

EnumeratePromptsAsync(CancellationToken)

Creates an enumerable for asynchronously enumerating all available prompts from the server.

public IAsyncEnumerable<McpClientPrompt> EnumeratePromptsAsync(CancellationToken cancellationToken = default)

Parameters

cancellationToken CancellationToken

The CancellationToken to monitor for cancellation requests. The default is None.

Returns

IAsyncEnumerable<McpClientPrompt>

An asynchronous sequence of all available prompts as McpClientPrompt instances.

EnumerateResourceTemplatesAsync(CancellationToken)

Creates an enumerable for asynchronously enumerating all available resource templates from the server.

public IAsyncEnumerable<McpClientResourceTemplate> EnumerateResourceTemplatesAsync(CancellationToken cancellationToken = default)

Parameters

cancellationToken CancellationToken

The CancellationToken to monitor for cancellation requests. The default is None.

Returns

IAsyncEnumerable<McpClientResourceTemplate>

An asynchronous sequence of all available resource templates as ResourceTemplate instances.

EnumerateResourcesAsync(CancellationToken)

Creates an enumerable for asynchronously enumerating all available resources from the server.

public IAsyncEnumerable<McpClientResource> EnumerateResourcesAsync(CancellationToken cancellationToken = default)

Parameters

cancellationToken CancellationToken

The CancellationToken to monitor for cancellation requests. The default is None.

Returns

IAsyncEnumerable<McpClientResource>

An asynchronous sequence of all available resources as Resource instances.

EnumerateToolsAsync(JsonSerializerOptions?, CancellationToken)

Creates an enumerable for asynchronously enumerating all available tools from the server.

public IAsyncEnumerable<McpClientTool> EnumerateToolsAsync(JsonSerializerOptions? serializerOptions = null, CancellationToken cancellationToken = default)

Parameters

serializerOptions JsonSerializerOptions

The serializer options governing tool parameter serialization. If null, the default options will be used.

cancellationToken CancellationToken

The CancellationToken to monitor for cancellation requests. The default is None.

Returns

IAsyncEnumerable<McpClientTool>

An asynchronous sequence of all available tools as McpClientTool instances.

GetPromptAsync(string, IReadOnlyDictionary<string, object?>?, JsonSerializerOptions?, CancellationToken)

Retrieves a specific prompt from the MCP server.

public ValueTask<GetPromptResult> GetPromptAsync(string name, IReadOnlyDictionary<string, object?>? arguments = null, JsonSerializerOptions? serializerOptions = null, CancellationToken cancellationToken = default)

Parameters

name string

The name of the prompt to retrieve.

arguments IReadOnlyDictionary<string, object>

Optional arguments for the prompt. Keys are parameter names, and values are the argument values.

serializerOptions JsonSerializerOptions

The serialization options governing argument serialization.

cancellationToken CancellationToken

The CancellationToken to monitor for cancellation requests. The default is None.

Returns

ValueTask<GetPromptResult>

A task containing the prompt's result with content and messages.

ListPromptsAsync(CancellationToken)

Retrieves a list of available prompts from the server.

public ValueTask<IList<McpClientPrompt>> ListPromptsAsync(CancellationToken cancellationToken = default)

Parameters

cancellationToken CancellationToken

The CancellationToken to monitor for cancellation requests. The default is None.

Returns

ValueTask<IList<McpClientPrompt>>

A list of all available prompts as McpClientPrompt instances.

ListResourceTemplatesAsync(CancellationToken)

Retrieves a list of available resource templates from the server.

public ValueTask<IList<McpClientResourceTemplate>> ListResourceTemplatesAsync(CancellationToken cancellationToken = default)

Parameters

cancellationToken CancellationToken

The CancellationToken to monitor for cancellation requests. The default is None.

Returns

ValueTask<IList<McpClientResourceTemplate>>

A list of all available resource templates as ResourceTemplate instances.

ListResourcesAsync(CancellationToken)

Retrieves a list of available resources from the server.

public ValueTask<IList<McpClientResource>> ListResourcesAsync(CancellationToken cancellationToken = default)

Parameters

cancellationToken CancellationToken

The CancellationToken to monitor for cancellation requests. The default is None.

Returns

ValueTask<IList<McpClientResource>>

A list of all available resources as Resource instances.

ListToolsAsync(JsonSerializerOptions?, CancellationToken)

Retrieves a list of available tools from the server.

public ValueTask<IList<McpClientTool>> ListToolsAsync(JsonSerializerOptions? serializerOptions = null, CancellationToken cancellationToken = default)

Parameters

serializerOptions JsonSerializerOptions

The serializer options governing tool parameter serialization. If null, the default options will be used.

cancellationToken CancellationToken

The CancellationToken to monitor for cancellation requests. The default is None.

Returns

ValueTask<IList<McpClientTool>>

A list of all available tools as McpClientTool instances.

PingAsync(CancellationToken)

Sends a ping request to verify server connectivity.

public Task PingAsync(CancellationToken cancellationToken = default)

Parameters

cancellationToken CancellationToken

The CancellationToken to monitor for cancellation requests. The default is None.

Returns

Task

A task that completes when the ping is successful.

Exceptions

McpException

Thrown when the server cannot be reached or returns an error response.

ReadResourceAsync(string, IReadOnlyDictionary<string, object?>, CancellationToken)

Reads a resource from the server.

public ValueTask<ReadResourceResult> ReadResourceAsync(string uriTemplate, IReadOnlyDictionary<string, object?> arguments, CancellationToken cancellationToken = default)

Parameters

uriTemplate string

The uri template of the resource.

arguments IReadOnlyDictionary<string, object>

Arguments to use to format uriTemplate.

cancellationToken CancellationToken

The CancellationToken to monitor for cancellation requests. The default is None.

Returns

ValueTask<ReadResourceResult>

ReadResourceAsync(string, CancellationToken)

Reads a resource from the server.

public ValueTask<ReadResourceResult> ReadResourceAsync(string uri, CancellationToken cancellationToken = default)

Parameters

uri string

The uri of the resource.

cancellationToken CancellationToken

The CancellationToken to monitor for cancellation requests. The default is None.

Returns

ValueTask<ReadResourceResult>

ReadResourceAsync(Uri, CancellationToken)

Reads a resource from the server.

public ValueTask<ReadResourceResult> ReadResourceAsync(Uri uri, CancellationToken cancellationToken = default)

Parameters

uri Uri

The uri of the resource.

cancellationToken CancellationToken

The CancellationToken to monitor for cancellation requests. The default is None.

Returns

ValueTask<ReadResourceResult>

SetLoggingLevel(LogLevel, CancellationToken)

Sets the logging level for the server to control which log messages are sent to the client.

public Task SetLoggingLevel(LogLevel level, CancellationToken cancellationToken = default)

Parameters

level LogLevel

The minimum severity level of log messages to receive from the server.

cancellationToken CancellationToken

The CancellationToken to monitor for cancellation requests. The default is None.

Returns

Task

A task representing the asynchronous operation.

SetLoggingLevel(LoggingLevel, CancellationToken)

Sets the logging level for the server to control which log messages are sent to the client.

public Task SetLoggingLevel(LoggingLevel level, CancellationToken cancellationToken = default)

Parameters

level LoggingLevel

The minimum severity level of log messages to receive from the server.

cancellationToken CancellationToken

The CancellationToken to monitor for cancellation requests. The default is None.

Returns

Task

A task representing the asynchronous operation.

SubscribeToResourceAsync(string, CancellationToken)

Subscribes to a resource on the server to receive notifications when it changes.

public Task SubscribeToResourceAsync(string uri, CancellationToken cancellationToken = default)

Parameters

uri string

The URI of the resource to which to subscribe.

cancellationToken CancellationToken

The CancellationToken to monitor for cancellation requests. The default is None.

Returns

Task

A task that represents the asynchronous operation.

SubscribeToResourceAsync(Uri, CancellationToken)

Subscribes to a resource on the server to receive notifications when it changes.

public Task SubscribeToResourceAsync(Uri uri, CancellationToken cancellationToken = default)

Parameters

uri Uri

The URI of the resource to which to subscribe.

cancellationToken CancellationToken

The CancellationToken to monitor for cancellation requests. The default is None.

Returns

Task

A task that represents the asynchronous operation.

UnsubscribeFromResourceAsync(string, CancellationToken)

Unsubscribes from a resource on the server to stop receiving notifications about its changes.

public Task UnsubscribeFromResourceAsync(string uri, CancellationToken cancellationToken = default)

Parameters

uri string

The URI of the resource to unsubscribe from.

cancellationToken CancellationToken

The CancellationToken to monitor for cancellation requests. The default is None.

Returns

Task

A task that represents the asynchronous operation.

UnsubscribeFromResourceAsync(Uri, CancellationToken)

Unsubscribes from a resource on the server to stop receiving notifications about its changes.

public Task UnsubscribeFromResourceAsync(Uri uri, CancellationToken cancellationToken = default)

Parameters

uri Uri

The URI of the resource to unsubscribe from.

cancellationToken CancellationToken

The CancellationToken to monitor for cancellation requests. The default is None.

Returns

Task

A task that represents the asynchronous operation.