McpClient Class

API reference for the McpClient class in ModelContextProtocol.Client namespace

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

Namespace

ModelContextProtocol.Client

Inheritance

McpClient → McpSession → IAsyncDisposable

Overview

The McpClient class provides the primary interface for connecting to MCP servers and invoking their capabilities. It handles:

• Server connection and initialization handshake
• Tool execution
• Prompt retrieval
• Resource access and subscription
• Session lifecycle management

Creating a Client

CreateAsync

Creates an McpClient, connecting it to the specified server.

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

clientTransport · IClientTransport · required

The transport instance used to communicate with the server.

clientOptions · McpClientOptions

A client configuration object that specifies client capabilities and protocol version. If null, details based on the current process are used.

loggerFactory · ILoggerFactory

A logger factory for creating loggers for clients.

cancellationToken · CancellationToken

The cancellation token to monitor for cancellation requests.

Returns: An McpClient that’s connected to the specified server.

Exceptions:

• ArgumentNullException: clientTransport is null.
• HttpRequestException: An error occurred while connecting to the server over HTTP.
• McpException: The server returned an error response during initialization.

Stdio Transport Example

using ModelContextProtocol.Client;

// Create stdio transport
var transport = new StdioClientTransport(new StdioClientTransportOptions
{
    Command = "node",
    Arguments = ["server.js"]
});

// Connect to server
await using var client = await McpClient.CreateAsync(transport);

ResumeSessionAsync

Recreates an McpClient using an existing transport session without sending a new initialize request.

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

clientTransport · IClientTransport · required

The transport instance already configured to connect to the target server.

resumeOptions · ResumeClientSessionOptions · required

The metadata captured from the original session that should be applied when resuming.

Properties

ServerCapabilities

Gets the capabilities supported by the connected server.

public abstract ServerCapabilities ServerCapabilities { get; }

Exceptions: InvalidOperationException - The client is not connected.

ServerInfo

Gets the implementation information of the connected server.

public abstract Implementation ServerInfo { get; }

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

ServerInstructions

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

public abstract string? ServerInstructions { get; }

These instructions are provided by the server during initialization and can be used to improve an LLM’s understanding of how to use the server effectively.

Completion

Gets a Task that completes when the client session has completed.

public abstract Task<ClientCompletionDetails> Completion { get; }

The task always completes successfully. The result provides details about why the session completed.

Tool Methods

ListToolsAsync

Retrieves a list of available tools from the server.

public async ValueTask<IList<McpClientTool>> ListToolsAsync(
    RequestOptions? options = null,
    CancellationToken cancellationToken = default)

options · RequestOptions

Optional request options including metadata, serialization settings, and progress tracking.

Returns: A list of all available tools as McpClientTool instances.

Example

var tools = await client.ListToolsAsync();
foreach (var tool in tools)
{
    Console.WriteLine($"Tool: {tool.Name} - {tool.Description}");
}

CallToolAsync

Invokes a tool on the server.

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

toolName · string · required

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>

An optional progress reporter for server notifications.

Returns: The CallToolResult from the tool execution.

Example

var result = await client.CallToolAsync(
    "get_weather",
    new Dictionary<string, object?>
    {
        ["location"] = "San Francisco",
        ["units"] = "celsius"
    });

foreach (var content in result.Content)
{
    if (content is TextContentBlock text)
    {
        Console.WriteLine(text.Text);
    }
}

Prompt Methods

ListPromptsAsync

Retrieves a list of available prompts from the server.

public async ValueTask<IList<McpClientPrompt>> ListPromptsAsync(
    RequestOptions? options = null,
    CancellationToken cancellationToken = default)

Returns: A list of all available prompts as McpClientPrompt instances.

GetPromptAsync

Retrieves a specific prompt from the MCP server.

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

name · string · required

The name of the prompt to retrieve.

arguments · IReadOnlyDictionary<string, object?>

Optional arguments for the prompt. The dictionary keys are parameter names, and the values are the argument values.

Returns: A task containing the prompt’s result with content and messages.

Example

var promptResult = await client.GetPromptAsync(
    "code_review",
    new Dictionary<string, object?>
    {
        ["language"] = "csharp",
        ["code"] = sourceCode
    });

Resource Methods

ListResourcesAsync

Retrieves a list of available resources from the server.

public async ValueTask<IList<McpClientResource>> ListResourcesAsync(
    RequestOptions? options = null,
    CancellationToken cancellationToken = default)

Returns: A list of all available resources as McpClientResource instances.

ListResourceTemplatesAsync

Retrieves a list of available resource templates from the server.

public async ValueTask<IList<McpClientResourceTemplate>> ListResourceTemplatesAsync(
    RequestOptions? options = null,
    CancellationToken cancellationToken = default)

Returns: A list of all available resource templates.

ReadResourceAsync

Reads a resource from the server.

public ValueTask<ReadResourceResult> ReadResourceAsync(
    string uri,
    RequestOptions? options = null,
    CancellationToken cancellationToken = default)

uri · string · required

The URI of the resource.

Returns: The result containing resource contents.

Example

var result = await client.ReadResourceAsync("file:///path/to/document.txt");
foreach (var content in result.Contents)
{
    if (content is TextResourceContents textContent)
    {
        Console.WriteLine(textContent.Text);
    }
}

SubscribeToResourceAsync

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

public async Task<IAsyncDisposable> SubscribeToResourceAsync(
    string uri,
    Func<ResourceUpdatedNotificationParams, CancellationToken, ValueTask> handler,
    RequestOptions? options = null,
    CancellationToken cancellationToken = default)

uri · string · required

The URI of the resource to which to subscribe.

handler · Func<ResourceUpdatedNotificationParams, CancellationToken, ValueTask> · required

The handler to invoke when the resource is updated.

Returns: An IAsyncDisposable that, when disposed, unsubscribes from the resource and removes the notification handler.

Example

await using var subscription = await client.SubscribeToResourceAsync(
    "file:///config.json",
    async (notification, ct) =>
    {
        Console.WriteLine($"Resource updated: {notification.Uri}");
    });

// Subscription is automatically disposed when leaving scope

UnsubscribeFromResourceAsync

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

public Task UnsubscribeFromResourceAsync(
    string uri,
    RequestOptions? options = null,
    CancellationToken cancellationToken = default)

Other Methods

PingAsync

Sends a ping request to verify server connectivity.

public ValueTask<PingResult> PingAsync(
    RequestOptions? options = null,
    CancellationToken cancellationToken = default)

Returns: A task containing the ping result.

CompleteAsync

Requests completion suggestions for a prompt argument or resource reference.

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

reference · Reference · required

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

argumentName · string · required

The name of the argument for which completions are requested.

argumentValue · string · required

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

Returns: A CompleteResult containing completion suggestions.

See Also

• McpSession - Base class providing core communication functionality
• Transports - Transport classes for connecting to servers
• Protocol Types - MCP protocol types and messages