Table of Contents

Class McpServerBuilderExtensions

Namespace
Microsoft.Extensions.DependencyInjection
Assembly
ModelContextProtocol.dll

Provides methods for configuring MCP servers via dependency injection.

public static class McpServerBuilderExtensions
Inheritance
McpServerBuilderExtensions
Inherited Members

Methods

WithCallToolHandler(IMcpServerBuilder, Func<RequestContext<CallToolRequestParams>, CancellationToken, ValueTask<CallToolResponse>>)

Configures a handler for calling tools available from the Model Context Protocol server.

public static IMcpServerBuilder WithCallToolHandler(this IMcpServerBuilder builder, Func<RequestContext<CallToolRequestParams>, CancellationToken, ValueTask<CallToolResponse>> handler)

Parameters

builder IMcpServerBuilder

The builder instance.

handler Func<RequestContext<CallToolRequestParams>, CancellationToken, ValueTask<CallToolResponse>>

The handler function that processes tool calls.

Returns

IMcpServerBuilder

The builder provided in builder.

Remarks

The call tool handler is responsible for executing custom tools and returning their results to clients. This method is typically paired with WithListToolsHandler(IMcpServerBuilder, Func<RequestContext<ListToolsRequestParams>, CancellationToken, ValueTask<ListToolsResult>>) to provide a complete tools implementation, where WithListToolsHandler(IMcpServerBuilder, Func<RequestContext<ListToolsRequestParams>, CancellationToken, ValueTask<ListToolsResult>>) advertises available tools and this handler executes them.

Exceptions

ArgumentNullException

builder is null.

WithCompleteHandler(IMcpServerBuilder, Func<RequestContext<CompleteRequestParams>, CancellationToken, ValueTask<CompleteResult>>)

Configures a handler for auto-completion suggestions for prompt arguments or resource references available from the Model Context Protocol server.

public static IMcpServerBuilder WithCompleteHandler(this IMcpServerBuilder builder, Func<RequestContext<CompleteRequestParams>, CancellationToken, ValueTask<CompleteResult>> handler)

Parameters

builder IMcpServerBuilder

The builder instance.

handler Func<RequestContext<CompleteRequestParams>, CancellationToken, ValueTask<CompleteResult>>

The handler function that processes completion requests.

Returns

IMcpServerBuilder

The builder provided in builder.

Remarks

The completion handler is invoked when clients request suggestions for argument values. This enables auto-complete functionality for both prompt arguments and resource references.

Exceptions

ArgumentNullException

builder is null.

WithGetPromptHandler(IMcpServerBuilder, Func<RequestContext<GetPromptRequestParams>, CancellationToken, ValueTask<GetPromptResult>>)

Configures a handler for getting a prompt available from the Model Context Protocol server.

public static IMcpServerBuilder WithGetPromptHandler(this IMcpServerBuilder builder, Func<RequestContext<GetPromptRequestParams>, CancellationToken, ValueTask<GetPromptResult>> handler)

Parameters

builder IMcpServerBuilder

The builder instance.

handler Func<RequestContext<GetPromptRequestParams>, CancellationToken, ValueTask<GetPromptResult>>

The handler function that processes prompt requests.

Returns

IMcpServerBuilder

The builder provided in builder.

Exceptions

ArgumentNullException

builder is null.

WithListPromptsHandler(IMcpServerBuilder, Func<RequestContext<ListPromptsRequestParams>, CancellationToken, ValueTask<ListPromptsResult>>)

Configures a handler for listing prompts available from the Model Context Protocol server.

public static IMcpServerBuilder WithListPromptsHandler(this IMcpServerBuilder builder, Func<RequestContext<ListPromptsRequestParams>, CancellationToken, ValueTask<ListPromptsResult>> handler)

Parameters

builder IMcpServerBuilder

The builder instance.

handler Func<RequestContext<ListPromptsRequestParams>, CancellationToken, ValueTask<ListPromptsResult>>

The handler that processes list prompts requests.

Returns

IMcpServerBuilder

The builder provided in builder.

Remarks

This handler is called when a client requests a list of available prompts. It should return all prompts that can be invoked through the server, including their names, descriptions, and parameter specifications. The handler can optionally support pagination via the cursor mechanism for large or dynamically-generated prompt collections.

When prompts are also defined using McpServerPrompt collection, both sets of prompts will be combined in the response to clients. This allows for a mix of programmatically defined prompts and dynamically generated prompts.

This method is typically paired with WithGetPromptHandler(IMcpServerBuilder, Func<RequestContext<GetPromptRequestParams>, CancellationToken, ValueTask<GetPromptResult>>) to provide a complete prompts implementation, where WithListPromptsHandler(IMcpServerBuilder, Func<RequestContext<ListPromptsRequestParams>, CancellationToken, ValueTask<ListPromptsResult>>) advertises available prompts and WithGetPromptHandler(IMcpServerBuilder, Func<RequestContext<GetPromptRequestParams>, CancellationToken, ValueTask<GetPromptResult>>) produces them when invoked by clients.

Exceptions

ArgumentNullException

builder is null.

WithListResourceTemplatesHandler(IMcpServerBuilder, Func<RequestContext<ListResourceTemplatesRequestParams>, CancellationToken, ValueTask<ListResourceTemplatesResult>>)

Configures a handler for listing resource templates available from the Model Context Protocol server.

public static IMcpServerBuilder WithListResourceTemplatesHandler(this IMcpServerBuilder builder, Func<RequestContext<ListResourceTemplatesRequestParams>, CancellationToken, ValueTask<ListResourceTemplatesResult>> handler)

Parameters

builder IMcpServerBuilder

The builder instance.

handler Func<RequestContext<ListResourceTemplatesRequestParams>, CancellationToken, ValueTask<ListResourceTemplatesResult>>

The handler function that processes resource template list requests.

Returns

IMcpServerBuilder

The builder provided in builder.

Remarks

This handler is responsible for providing clients with information about available resource templates that can be used to construct resource URIs.

Resource templates describe the structure of resource URIs that the server can handle. They include URI templates (according to RFC 6570) that clients can use to construct valid resource URIs.

This handler is typically paired with WithReadResourceHandler(IMcpServerBuilder, Func<RequestContext<ReadResourceRequestParams>, CancellationToken, ValueTask<ReadResourceResult>>) to provide a complete resource system where templates define the URI patterns and the read handler provides the actual content.

Exceptions

ArgumentNullException

builder is null.

WithListResourcesHandler(IMcpServerBuilder, Func<RequestContext<ListResourcesRequestParams>, CancellationToken, ValueTask<ListResourcesResult>>)

Configures a handler for listing resources available from the Model Context Protocol server.

public static IMcpServerBuilder WithListResourcesHandler(this IMcpServerBuilder builder, Func<RequestContext<ListResourcesRequestParams>, CancellationToken, ValueTask<ListResourcesResult>> handler)

Parameters

builder IMcpServerBuilder

The builder instance.

handler Func<RequestContext<ListResourcesRequestParams>, CancellationToken, ValueTask<ListResourcesResult>>

The handler function that processes resource list requests.

Returns

IMcpServerBuilder

The builder provided in builder.

Remarks

This handler is typically paired with WithReadResourceHandler(IMcpServerBuilder, Func<RequestContext<ReadResourceRequestParams>, CancellationToken, ValueTask<ReadResourceResult>>) to provide a complete resources implementation, where this handler advertises available resources and the read handler provides their content when requested.

Exceptions

ArgumentNullException

builder is null.

WithListToolsHandler(IMcpServerBuilder, Func<RequestContext<ListToolsRequestParams>, CancellationToken, ValueTask<ListToolsResult>>)

Configures a handler for listing tools available from the Model Context Protocol server.

public static IMcpServerBuilder WithListToolsHandler(this IMcpServerBuilder builder, Func<RequestContext<ListToolsRequestParams>, CancellationToken, ValueTask<ListToolsResult>> handler)

Parameters

builder IMcpServerBuilder

The builder instance.

handler Func<RequestContext<ListToolsRequestParams>, CancellationToken, ValueTask<ListToolsResult>>

The handler that processes list tools requests.

Returns

IMcpServerBuilder

The builder provided in builder.

Remarks

This handler is called when a client requests a list of available tools. It should return all tools that can be invoked through the server, including their names, descriptions, and parameter specifications. The handler can optionally support pagination via the cursor mechanism for large or dynamically-generated tool collections.

When tools are also defined using McpServerTool collection, both sets of tools will be combined in the response to clients. This allows for a mix of programmatically defined tools and dynamically generated tools.

This method is typically paired with WithCallToolHandler(IMcpServerBuilder, Func<RequestContext<CallToolRequestParams>, CancellationToken, ValueTask<CallToolResponse>>) to provide a complete tools implementation, where WithListToolsHandler(IMcpServerBuilder, Func<RequestContext<ListToolsRequestParams>, CancellationToken, ValueTask<ListToolsResult>>) advertises available tools and WithCallToolHandler(IMcpServerBuilder, Func<RequestContext<CallToolRequestParams>, CancellationToken, ValueTask<CallToolResponse>>) executes them when invoked by clients.

Exceptions

ArgumentNullException

builder is null.

WithPrompts(IMcpServerBuilder, IEnumerable<Type>, JsonSerializerOptions?)

Adds McpServerPrompt instances to the service collection backing builder.

public static IMcpServerBuilder WithPrompts(this IMcpServerBuilder builder, IEnumerable<Type> promptTypes, JsonSerializerOptions? serializerOptions = null)

Parameters

builder IMcpServerBuilder

The builder instance.

promptTypes IEnumerable<Type>

Types with marked methods to add as prompts to the server.

serializerOptions JsonSerializerOptions

The serializer options governing prompt parameter marshalling.

Returns

IMcpServerBuilder

The builder provided in builder.

Remarks

This method discovers all instance and static methods (public and non-public) on the specified promptTypes types, where the methods are attributed as McpServerPromptAttribute, and adds an McpServerPrompt instance for each. For instance methods, an instance will be constructed for each invocation of the prompt.

Exceptions

ArgumentNullException

builder is null.

ArgumentNullException

promptTypes is null.

WithPromptsFromAssembly(IMcpServerBuilder, Assembly?, JsonSerializerOptions?)

Adds types marked with the McpServerPromptTypeAttribute attribute from the given assembly as prompts to the server.

public static IMcpServerBuilder WithPromptsFromAssembly(this IMcpServerBuilder builder, Assembly? promptAssembly = null, JsonSerializerOptions? serializerOptions = null)

Parameters

builder IMcpServerBuilder

The builder instance.

promptAssembly Assembly

The assembly to load the types from. If null, the calling assembly will be used.

serializerOptions JsonSerializerOptions

The serializer options governing prompt parameter marshalling.

Returns

IMcpServerBuilder

The builder provided in builder.

Remarks

This method scans the specified assembly (or the calling assembly if none is provided) for classes marked with the McpServerPromptTypeAttribute. It then discovers all methods within those classes that are marked with the McpServerPromptAttribute and registers them as McpServerPrompts in the builder's IServiceCollection.

The method automatically handles both static and instance methods. For instance methods, a new instance of the containing class will be constructed for each invocation of the prompt.

Prompts registered through this method can be discovered by clients using the list_prompts request and invoked using the call_prompt request.

Note that this method performs reflection at runtime and may not work in Native AOT scenarios. For Native AOT compatibility, consider using the generic WithPrompts<TPromptType>(IMcpServerBuilder, JsonSerializerOptions?) method instead.

Exceptions

ArgumentNullException

builder is null.

WithPrompts<TPromptType>(IMcpServerBuilder, JsonSerializerOptions?)

Adds McpServerPrompt instances to the service collection backing builder.

public static IMcpServerBuilder WithPrompts<TPromptType>(this IMcpServerBuilder builder, JsonSerializerOptions? serializerOptions = null)

Parameters

builder IMcpServerBuilder

The builder instance.

serializerOptions JsonSerializerOptions

The serializer options governing prompt parameter marshalling.

Returns

IMcpServerBuilder

The builder provided in builder.

Type Parameters

TPromptType

The prompt type.

Remarks

This method discovers all instance and static methods (public and non-public) on the specified TPromptType type, where the methods are attributed as McpServerPromptAttribute, and adds an McpServerPrompt instance for each. For instance methods, an instance will be constructed for each invocation of the prompt.

Exceptions

ArgumentNullException

builder is null.

WithReadResourceHandler(IMcpServerBuilder, Func<RequestContext<ReadResourceRequestParams>, CancellationToken, ValueTask<ReadResourceResult>>)

Configures a handler for reading a resource available from the Model Context Protocol server.

public static IMcpServerBuilder WithReadResourceHandler(this IMcpServerBuilder builder, Func<RequestContext<ReadResourceRequestParams>, CancellationToken, ValueTask<ReadResourceResult>> handler)

Parameters

builder IMcpServerBuilder

The builder instance.

handler Func<RequestContext<ReadResourceRequestParams>, CancellationToken, ValueTask<ReadResourceResult>>

The handler function that processes resource read requests.

Returns

IMcpServerBuilder

The builder provided in builder.

Remarks

This handler is typically paired with WithListResourcesHandler(IMcpServerBuilder, Func<RequestContext<ListResourcesRequestParams>, CancellationToken, ValueTask<ListResourcesResult>>) to provide a complete resources implementation, where the list handler advertises available resources and the read handler provides their content when requested.

Exceptions

ArgumentNullException

builder is null.

WithSetLoggingLevelHandler(IMcpServerBuilder, Func<RequestContext<SetLevelRequestParams>, CancellationToken, ValueTask<EmptyResult>>)

Configures a handler for processing logging level change requests from clients.

public static IMcpServerBuilder WithSetLoggingLevelHandler(this IMcpServerBuilder builder, Func<RequestContext<SetLevelRequestParams>, CancellationToken, ValueTask<EmptyResult>> handler)

Parameters

builder IMcpServerBuilder

The server builder instance.

handler Func<RequestContext<SetLevelRequestParams>, CancellationToken, ValueTask<EmptyResult>>

The handler that processes requests to change the logging level.

Returns

IMcpServerBuilder

The builder provided in builder.

Remarks

When a client sends a logging/setLevel request, this handler will be invoked to process the requested level change. The server typically adjusts its internal logging level threshold and may begin sending log messages at or above the specified level to the client.

Regardless of whether a handler is provided, an IMcpServer should itself handle such notifications by updating its LoggingLevel property to return the most recently set level.

Exceptions

ArgumentNullException

builder is null.

WithStdioServerTransport(IMcpServerBuilder)

Adds a server transport that uses standard input (stdin) and standard output (stdout) for communication.

public static IMcpServerBuilder WithStdioServerTransport(this IMcpServerBuilder builder)

Parameters

builder IMcpServerBuilder

The builder instance.

Returns

IMcpServerBuilder

The builder provided in builder.

Remarks

This method configures the server to communicate using the standard input and output streams, which is commonly used when the Model Context Protocol server is launched locally by a client process.

When using this transport, the server runs as a single-session service that exits when the stdin stream is closed. This makes it suitable for scenarios where the server should terminate when the parent process disconnects.

Exceptions

ArgumentNullException

builder is null.

ArgumentNullException

builder is null.

WithStreamServerTransport(IMcpServerBuilder, Stream, Stream)

Adds a server transport that uses the specified input and output streams for communication.

public static IMcpServerBuilder WithStreamServerTransport(this IMcpServerBuilder builder, Stream inputStream, Stream outputStream)

Parameters

builder IMcpServerBuilder

The builder instance.

inputStream Stream

The input Stream to use as standard input.

outputStream Stream

The output Stream to use as standard output.

Returns

IMcpServerBuilder

The builder provided in builder.

Exceptions

ArgumentNullException

builder is null.

ArgumentNullException

inputStream is null.

ArgumentNullException

outputStream is null.

WithSubscribeToResourcesHandler(IMcpServerBuilder, Func<RequestContext<SubscribeRequestParams>, CancellationToken, ValueTask<EmptyResult>>)

Configures a handler for resource subscription requests.

public static IMcpServerBuilder WithSubscribeToResourcesHandler(this IMcpServerBuilder builder, Func<RequestContext<SubscribeRequestParams>, CancellationToken, ValueTask<EmptyResult>> handler)

Parameters

builder IMcpServerBuilder

The builder instance.

handler Func<RequestContext<SubscribeRequestParams>, CancellationToken, ValueTask<EmptyResult>>

The handler function that processes resource subscription requests.

Returns

IMcpServerBuilder

The builder provided in builder.

Remarks

The subscribe handler is responsible for registering client interest in specific resources. When a resource changes, the server can notify all subscribed clients about the change.

This handler is typically paired with WithUnsubscribeFromResourcesHandler(IMcpServerBuilder, Func<RequestContext<UnsubscribeRequestParams>, CancellationToken, ValueTask<EmptyResult>>) to provide a complete subscription management system. Resource subscriptions allow clients to maintain up-to-date information without needing to poll resources constantly.

After registering a subscription, it's the server's responsibility to track which client is subscribed to which resources and to send appropriate notifications through the connection when resources change.

Exceptions

ArgumentNullException

builder is null.

WithTools(IMcpServerBuilder, IEnumerable<Type>, JsonSerializerOptions?)

Adds McpServerTool instances to the service collection backing builder.

public static IMcpServerBuilder WithTools(this IMcpServerBuilder builder, IEnumerable<Type> toolTypes, JsonSerializerOptions? serializerOptions = null)

Parameters

builder IMcpServerBuilder

The builder instance.

toolTypes IEnumerable<Type>

Types with marked methods to add as tools to the server.

serializerOptions JsonSerializerOptions

The serializer options governing tool parameter marshalling.

Returns

IMcpServerBuilder

The builder provided in builder.

Remarks

This method discovers all instance and static methods (public and non-public) on the specified toolTypes types, where the methods are attributed as McpServerToolAttribute, and adds an McpServerTool instance for each. For instance methods, an instance will be constructed for each invocation of the tool.

Exceptions

ArgumentNullException

builder is null.

ArgumentNullException

toolTypes is null.

WithToolsFromAssembly(IMcpServerBuilder, Assembly?, JsonSerializerOptions?)

Adds types marked with the McpServerToolTypeAttribute attribute from the given assembly as tools to the server.

public static IMcpServerBuilder WithToolsFromAssembly(this IMcpServerBuilder builder, Assembly? toolAssembly = null, JsonSerializerOptions? serializerOptions = null)

Parameters

builder IMcpServerBuilder

The builder instance.

toolAssembly Assembly

The assembly to load the types from. If null, the calling assembly will be used.

serializerOptions JsonSerializerOptions

The serializer options governing tool parameter marshalling.

Returns

IMcpServerBuilder

The builder provided in builder.

Remarks

This method scans the specified assembly (or the calling assembly if none is provided) for classes marked with the McpServerToolTypeAttribute. It then discovers all methods within those classes that are marked with the McpServerToolAttribute and registers them as McpServerTools in the builder's IServiceCollection.

The method automatically handles both static and instance methods. For instance methods, a new instance of the containing class will be constructed for each invocation of the tool.

Tools registered through this method can be discovered by clients using the list_tools request and invoked using the call_tool request.

Note that this method performs reflection at runtime and may not work in Native AOT scenarios. For Native AOT compatibility, consider using the generic WithTools<TToolType>(IMcpServerBuilder, JsonSerializerOptions?) method instead.

Exceptions

ArgumentNullException

builder is null.

WithTools<TToolType>(IMcpServerBuilder, JsonSerializerOptions?)

Adds McpServerTool instances to the service collection backing builder.

public static IMcpServerBuilder WithTools<TToolType>(this IMcpServerBuilder builder, JsonSerializerOptions? serializerOptions = null)

Parameters

builder IMcpServerBuilder

The builder instance.

serializerOptions JsonSerializerOptions

The serializer options governing tool parameter marshalling.

Returns

IMcpServerBuilder

The builder provided in builder.

Type Parameters

TToolType

The tool type.

Remarks

This method discovers all instance and static methods (public and non-public) on the specified TToolType type, where the methods are attributed as McpServerToolAttribute, and adds an McpServerTool instance for each. For instance methods, an instance will be constructed for each invocation of the tool.

Exceptions

ArgumentNullException

builder is null.

WithUnsubscribeFromResourcesHandler(IMcpServerBuilder, Func<RequestContext<UnsubscribeRequestParams>, CancellationToken, ValueTask<EmptyResult>>)

Configures a handler for resource unsubscription requests.

public static IMcpServerBuilder WithUnsubscribeFromResourcesHandler(this IMcpServerBuilder builder, Func<RequestContext<UnsubscribeRequestParams>, CancellationToken, ValueTask<EmptyResult>> handler)

Parameters

builder IMcpServerBuilder

The builder instance.

handler Func<RequestContext<UnsubscribeRequestParams>, CancellationToken, ValueTask<EmptyResult>>

The handler function that processes resource unsubscription requests.

Returns

IMcpServerBuilder

The builder provided in builder.

Remarks

The unsubscribe handler is responsible for removing client interest in specific resources. When a client no longer needs to receive notifications about resource changes, it can send an unsubscribe request.

This handler is typically paired with WithSubscribeToResourcesHandler(IMcpServerBuilder, Func<RequestContext<SubscribeRequestParams>, CancellationToken, ValueTask<EmptyResult>>) to provide a complete subscription management system. The unsubscribe operation is idempotent, meaning it can be called multiple times for the same resource without causing errors, even if there is no active subscription.

After removing a subscription, the server should stop sending notifications to the client about changes to the specified resource.

Exceptions

ArgumentNullException

builder is null.

Edit this page