Class McpServerToolAttribute
- Namespace
- ModelContextProtocol.Server
- Assembly
- ModelContextProtocol.dll
Used to indicate that a method should be considered an McpServerTool.
[AttributeUsage(AttributeTargets.Method)]
public sealed class McpServerToolAttribute : Attribute- Inheritance
-
McpServerToolAttribute
- Inherited Members
Remarks
This attribute is applied to methods that should be exposed as tools in the Model Context Protocol. When a class containing methods marked with this attribute is registered with McpServerBuilderExtensions, these methods become available as tools that can be called by MCP clients.
When methods are provided directly to McpServerTool.Create, the attribute is not required.
By default, parameters are sourced from the Arguments dictionary, which is a collection of key/value pairs, and are represented in the JSON schema for the function, as exposed in the returned McpServerTool's ProtocolTool's InputSchema. Those parameters are deserialized from the JsonElement values in that collection. There are a few exceptions to this:
- CancellationToken parameters are automatically bound to a CancellationToken provided by the IMcpServer and that respects any CancelledNotifications sent by the client for this operation's RequestId. The parameter is not included in the generated JSON schema.
- IServiceProvider parameters are bound from the RequestContext<TParams> for this request, and are not included in the JSON schema.
- IMcpServer parameters are not included in the JSON schema and are bound directly to the IMcpServer instance associated with this request's RequestContext<TParams>. Such parameters may be used to understand what server is being used to process the request, and to interact with the client issuing the request to that server.
- IProgress<T> parameters accepting ProgressNotificationValue values are not included in the JSON schema and are bound to an IProgress<T> instance manufactured to forward progress notifications from the tool to the client. If the client included a ProgressToken in their request, progress reports issued to this instance will propagate to the client as ProgressNotification notifications with that token. If the client did not include a ProgressToken, the instance will ignore any progress reports issued to it.
- When the McpServerTool is constructed, it may be passed an IServiceProvider via Services. Any parameter that can be satisfied by that IServiceProvider according to IServiceProviderIsService will not be included in the generated JSON schema and will be resolved from the IServiceProvider provided to when the tool is invoked rather than from the argument collection.
- Any parameter attributed with FromKeyedServicesAttribute will similarly be resolved from the IServiceProvider provided when the tool is invoked rather than from the argument collection, and will not be included in the generated JSON schema.
All other parameters are deserialized from the JsonElements in the Arguments dictionary, using the JsonSerializerOptions supplied in SerializerOptions, or if none was provided, using DefaultOptions.
In general, the data supplied via the Arguments's dictionary is passed along from the caller and should thus be considered unvalidated and untrusted. To provide validated and trusted data to the invocation of the tool, consider having the tool be an instance method, referring to data stored in the instance, or using an instance or parameters resolved from the IServiceProvider to provide data to the method.
Return values from a method are used to create the CallToolResponse that is sent back to the client:
| null | Returns an empty Content list. |
| Microsoft.Extensions.AI.AIContent | Converted to a single Content object using ModelContextProtocol.AIContentExtensions.ToContent(Microsoft.Extensions.AI.AIContent). |
| string | Converted to a single Content object with Text set to the string value and Type set to "text". |
| Content | Returned as a single-item Content list. |
| IEnumerable<T> of string | Each string is converted to a Content object with Text set to the string value and Type set to "text". |
| IEnumerable<T> of Microsoft.Extensions.AI.AIContent | Each Microsoft.Extensions.AI.AIContent is converted to a Content object using ModelContextProtocol.AIContentExtensions.ToContent(Microsoft.Extensions.AI.AIContent). |
| IEnumerable<T> of Content | Returned as the Content list. |
| CallToolResponse | Returned directly without modification. |
| Other types | Serialized to JSON and returned as a single Content object with Type set to "text". |
Constructors
McpServerToolAttribute()
Initializes a new instance of the McpServerToolAttribute class.
public McpServerToolAttribute()Properties
Destructive
Gets or sets whether the tool may perform destructive updates to its environment.
public bool Destructive { get; set; }Property Value
Remarks
If true, the tool may perform destructive updates to its environment. If false, the tool performs only additive updates. This property is most relevant when the tool modifies its environment (ReadOnly = false).
The default is true.
Idempotent
Gets or sets whether calling the tool repeatedly with the same arguments will have no additional effect on its environment.
public bool Idempotent { get; set; }Property Value
Remarks
This property is most relevant when the tool modifies its environment (ReadOnly = false).
The default is false.
Name
Gets the name of the tool.
public string? Name { get; set; }Property Value
Remarks
If null, the method name will be used.
OpenWorld
Gets or sets whether this tool may interact with an "open world" of external entities.
public bool OpenWorld { get; set; }Property Value
Remarks
If true, the tool may interact with an unpredictable or dynamic set of entities (like web search). If false, the tool's domain of interaction is closed and well-defined (like memory access).
The default is true.
ReadOnly
Gets or sets whether this tool does not modify its environment.
public bool ReadOnly { get; set; }Property Value
Remarks
If true, the tool only performs read operations without changing state. If false, the tool may make modifications to its environment.
Read-only tools do not have side effects beyond computational resource usage. They don't create, update, or delete data in any system.
The default is false.
Title
Gets or sets a human-readable title for the tool that can be displayed to users.
public string? Title { get; set; }Property Value
Remarks
The title provides a more descriptive, user-friendly name for the tool than the tool's programmatic name. It is intended for display purposes and to help users understand the tool's purpose at a glance.
Unlike the tool name (which follows programmatic naming conventions), the title can include spaces, special characters, and be phrased in a more natural language style.