Class McpServerToolAttribute
- Namespace
- ModelContextProtocol.Server
- Assembly
- ModelContextProtocol.Core.dll
Indicates 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 McpServer and that respects any CancelledNotificationParamss 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.
- McpServer parameters are not included in the JSON schema and are bound directly to the McpServer 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 CallToolResult that is sent back to the client:
| null | Returns an empty Content list. |
| Microsoft.Extensions.AI.AIContent | Converted to a single ContentBlock object using ToContentBlock(AIContent). |
| string | Converted to a single TextContentBlock object with its text set to the string value. |
| ContentBlock | Returned as a single-item ContentBlock list. |
| IEnumerable<T> of string | Each string is converted to a ContentBlock object with its text set to the string value. |
| IEnumerable<T> of Microsoft.Extensions.AI.AIContent | Each Microsoft.Extensions.AI.AIContent is converted to a ContentBlock object using ToContentBlock(AIContent). |
| IEnumerable<T> of ContentBlock | Returned as the ContentBlock list. |
| CallToolResult | Returned directly without modification. |
| Other types | Serialized to JSON and returned as a single ContentBlock object with Type set to "text". |
Constructors
McpServerToolAttribute()
Initializes a new instance of the McpServerToolAttribute class.
public McpServerToolAttribute()Properties
Destructive
Gets or sets a value that indicates whether the tool might perform destructive updates to its environment.
public bool Destructive { get; set; }Property Value
- bool
true if the tool might perform destructive updates to its environment. false if the tool performs only additive updates. The default is true.
Remarks
This property is most relevant when the tool modifies its environment (ReadOnly = false).
IconSource
Gets or sets the source URI for the tool's icon.
public string? IconSource { get; set; }Property Value
Remarks
This value can be an HTTP/HTTPS URL pointing to an image file or a data URI with base64-encoded image data. When specified, a single icon will be added to the tool.
For more advanced icon configuration (multiple icons, MIME type specification, size characteristics), use Icons when creating the tool programmatically.
Idempotent
Gets or sets a value that indicates whether calling the tool repeatedly with the same arguments has no additional effect on its environment.
public bool Idempotent { get; set; }Property Value
- bool
true if calling the tool repeatedly with the same arguments has no additional effect on the environment; false if it does. The default is false.
Remarks
This property is most relevant when the tool modifies its environment (ReadOnly = false).
Name
Gets the name of the tool.
public string? Name { get; set; }Property Value
Remarks
If null, the method name is used.
OpenWorld
Gets or sets a value that indicates whether this tool can interact with an "open world" of external entities.
public bool OpenWorld { get; set; }Property Value
- bool
true if the tool can interact with an unpredictable or dynamic set of entities (like web search). false if the tool's domain of interaction is closed and well-defined (like memory access). The default is true.
ReadOnly
Gets or sets a value that indicates whether this tool does not modify its environment.
public bool ReadOnly { get; set; }Property Value
- bool
true if the tool only performs read operations without changing state. false if the tool might make modifications to its environment. The default is false.
Remarks
Read-only tools do not have side effects beyond computational resource usage. They don't create, update, or delete data in any system.
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.
UseStructuredContent
Gets or sets a value that indicates whether the tool should report an output schema for structured content.
public bool UseStructuredContent { get; set; }Property Value
Remarks
When enabled, the tool will attempt to populate the OutputSchema and provide structured content in the StructuredContent property.