Table of Contents

Class McpClientTool

Namespace
ModelContextProtocol.Client
Assembly
ModelContextProtocol.Core.dll

Provides an Microsoft.Extensions.AI.AIFunction that calls a tool via an IMcpClient.

public sealed class McpClientTool : AIFunction
Inheritance
AITool
AIFunction
McpClientTool
Inherited Members
AIFunction.UnderlyingMethod
AITool.ToString()

Remarks

The McpClientTool class encapsulates an IMcpClient along with a description of a tool available via that client, allowing it to be invoked as an Microsoft.Extensions.AI.AIFunction. This enables integration with AI models that support function calling capabilities.

Tools retrieved from an MCP server can be customized for model presentation using methods like WithName(string) and WithDescription(string) without changing the underlying tool functionality.

Typically, you would get instances of this class by calling the ListToolsAsync(IMcpClient, JsonSerializerOptions?, CancellationToken) or EnumerateToolsAsync(IMcpClient, JsonSerializerOptions?, CancellationToken) extension methods on an IMcpClient instance.

Properties

AdditionalProperties

Gets any additional properties associated with the tool.

public override IReadOnlyDictionary<string, object?> AdditionalProperties { get; }

Property Value

IReadOnlyDictionary<string, object>

Description

Gets a description of the tool, suitable for use in describing the purpose to a model.

public override string Description { get; }

Property Value

string

JsonSchema

Gets a JSON Schema describing the function and its input parameters.

public override JsonElement JsonSchema { get; }

Property Value

JsonElement

Remarks

When specified, declares a self-contained JSON schema document that describes the function and its input parameters. A simple example of a JSON schema for a function that adds two numbers together is shown below: 

{
  "title" : "addNumbers",
  "description": "A simple function that adds two numbers together.",
  "type": "object",
  "properties": {
    "a" : { "type": "number" },
    "b" : { "type": "number", "default": 1 }
  }, 
  "required" : ["a"]
}

The metadata present in the schema document plays an important role in guiding AI function invocation.

When no schema is specified, consuming chat clients should assume the "{}" or "true" schema, indicating that any JSON input is admissible.

JsonSerializerOptions

Gets a Microsoft.Extensions.AI.AIFunction.JsonSerializerOptions that can be used to marshal function parameters.

public override JsonSerializerOptions JsonSerializerOptions { get; }

Property Value

JsonSerializerOptions

Name

Gets the name of the tool.

public override string Name { get; }

Property Value

string

ProtocolTool

Gets the protocol Tool type for this instance.

public Tool ProtocolTool { get; }

Property Value

Tool

Remarks

This property provides direct access to the underlying protocol representation of the tool, which can be useful for advanced scenarios or when implementing custom MCP client extensions. It contains the original metadata about the tool as provided by the server, including its name, description, and schema information before any customizations applied through methods like WithName(string) or WithDescription(string).

Methods

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

Invokes the tool on the server.

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

Parameters

arguments IReadOnlyDictionary<string, object>

An optional dictionary of arguments to pass to the tool. Each key represents a parameter name, and its associated value represents the argument value.

progress IProgress<ProgressNotificationValue>

An optional IProgress<T> to have progress notifications reported to it. Setting this to a non-null value will result in a progress token being included in the call, and any resulting progress notifications during the operation routed to this instance.

serializerOptions JsonSerializerOptions

The JSON serialization options governing argument serialization. If null, the default serialization options will be used.

cancellationToken CancellationToken

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

Returns

ValueTask<CallToolResponse>

A task containing the CallToolResponse from the tool execution. The response includes the tool's output content, which may be structured data, text, or an error message.

Examples

var result = await tool.CallAsync(
    new Dictionary<string, object?>
    {
        ["message"] = "Hello MCP!"
    });

Remarks

The base InvokeAsync(AIFunctionArguments, CancellationToken) method is overridden to invoke this CallAsync(IReadOnlyDictionary<string, object?>?, IProgress<ProgressNotificationValue>?, JsonSerializerOptions?, CancellationToken) method. The only difference in behavior is InvokeAsync(AIFunctionArguments, CancellationToken) will serialize the resulting CallToolResponse"/> such that the object returned is a JsonElement containing the serialized CallToolResponse. This CallToolResponse method is intended to be called directly by user code, whereas the base InvokeAsync(AIFunctionArguments, CancellationToken) is intended to be used polymorphically via the base class, typically as part of an Microsoft.Extensions.AI.IChatClient operation.

Exceptions

McpException

The server could not find the requested tool, or the server encountered an error while processing the request.

InvokeCoreAsync(AIFunctionArguments, CancellationToken)

Invokes the Microsoft.Extensions.AI.AIFunction and returns its result.

protected override ValueTask<object?> InvokeCoreAsync(AIFunctionArguments arguments, CancellationToken cancellationToken)

Parameters

arguments AIFunctionArguments

The arguments to pass to the function's invocation.

cancellationToken CancellationToken

The CancellationToken to monitor for cancellation requests.

Returns

ValueTask<object>

The result of the function's execution.

WithDescription(string)

Creates a new instance of the tool but modified to return the specified description from its Description property.

public McpClientTool WithDescription(string description)

Parameters

description string

The description to give the tool.

Returns

McpClientTool

A new instance of McpClientTool with the provided description.

Remarks

Changing the description can help the model better understand the tool's purpose or provide more context about how the tool should be used. This is particularly useful when:

  • The original description is too technical or lacks clarity for the model
  • You want to add example usage scenarios to improve the model's understanding
  • You need to tailor the tool's description for specific model requirements

When invoking InvokeAsync(AIFunctionArguments, CancellationToken), the MCP server will still be called with the original tool description, so no mapping is required on the server side. This new description only affects the value returned from this instance's Microsoft.Extensions.AI.AITool.Description.

WithName(string)

Creates a new instance of the tool but modified to return the specified name from its Name property.

public McpClientTool WithName(string name)

Parameters

name string

The model-facing name to give the tool.

Returns

McpClientTool

A new instance of McpClientTool with the provided name.

Remarks

This is useful for optimizing the tool name for specific models or for prefixing the tool name with a namespace to avoid conflicts.

Changing the name can help with:

  • Making the tool name more intuitive for the model
  • Preventing name collisions when using tools from multiple sources
  • Creating specialized versions of a general tool for specific contexts

When invoking InvokeAsync(AIFunctionArguments, CancellationToken), the MCP server will still be called with the original tool name, so no mapping is required on the server side. This new name only affects the value returned from this instance's Microsoft.Extensions.AI.AITool.Name.

WithProgress(IProgress<ProgressNotificationValue>)

Creates a new instance of the tool but modified to report progress via the specified IProgress<T>.

public McpClientTool WithProgress(IProgress<ProgressNotificationValue> progress)

Parameters

progress IProgress<ProgressNotificationValue>

The IProgress<T> to which progress notifications should be reported.

Returns

McpClientTool

A new instance of McpClientTool, configured with the provided progress instance.

Remarks

Adding an IProgress<T> to the tool does not impact how it is reported to any AI model. Rather, when the tool is invoked, the request to the MCP server will include a unique progress token, and any progress notifications issued by the server with that progress token while the operation is in flight will be reported to the progress instance.

Only one IProgress<T> can be specified at a time. Calling WithProgress(IProgress<ProgressNotificationValue>) again will overwrite any previously specified progress instance.

Edit this page