Decouple Handlers and Collections (e.g. ToolsHandler and ToolsCollection) from Capabilities by promoting them to the options types.

Also, group all handlers in container classes, for server, I decided to move McpServerHandlers down to Mcp.Core and move the NotificationHandlers there too.

Author: jozkee

samples/ChatWithTools/Program.cs

@@ -41,7 +41,10 @@
     }),
     clientOptions: new()
     {
-        Capabilities = new() { Sampling = new() { SamplingHandler = samplingClient.CreateSamplingHandler() } },
+        Handlers = new()
+        {
+            SamplingHandler = samplingClient.CreateSamplingHandler()
+        }
     },
     loggerFactory: loggerFactory);
 

samples/InMemoryTransport/Program.cs

@@ -10,13 +10,7 @@
     new StreamServerTransport(clientToServerPipe.Reader.AsStream(), serverToClientPipe.Writer.AsStream()),
     new McpServerOptions()
     {
-        Capabilities = new()
-        {
-            Tools = new()
-            {
-                ToolCollection = [McpServerTool.Create((string arg) => $"Echo: {arg}", new() { Name = "Echo" })]
-            }
-        }
+        ToolCollection = [McpServerTool.Create((string arg) => $"Echo: {arg}", new() { Name = "Echo" })]
     });
 _ = server.RunAsync();
 

src/ModelContextProtocol.Core/Client/McpClient.cs

@@ -39,57 +39,48 @@ public McpClient(IClientTransport clientTransport, McpClientOptions? options, IL
 
         EndpointName = clientTransport.Name;
 
-        if (options.Capabilities is { } capabilities)
+        if (options.Handlers?.NotificationHandlers is { } notificationHandlers)
         {
-            if (capabilities.NotificationHandlers is { } notificationHandlers)
-            {
-                NotificationHandlers.RegisterRange(notificationHandlers);
-            }
-
-            if (capabilities.Sampling is { } samplingCapability)
-            {
-                if (samplingCapability.SamplingHandler is not { } samplingHandler)
-                {
-                    throw new InvalidOperationException("Sampling capability was set but it did not provide a handler.");
-                }
-
-                RequestHandlers.Set(
-                    RequestMethods.SamplingCreateMessage,
-                    (request, _, cancellationToken) => samplingHandler(
-                        request,
-                        request?.ProgressToken is { } token ? new TokenProgress(this, token) : NullProgress.Instance,
-                        cancellationToken),
-                    McpJsonUtilities.JsonContext.Default.CreateMessageRequestParams,
-                    McpJsonUtilities.JsonContext.Default.CreateMessageResult);
-            }
-
-            if (capabilities.Roots is { } rootsCapability)
-            {
-                if (rootsCapability.RootsHandler is not { } rootsHandler)
-                {
-                    throw new InvalidOperationException("Roots capability was set but it did not provide a handler.");
-                }
+            NotificationHandlers.RegisterRange(notificationHandlers);
+        }
 
-                RequestHandlers.Set(
-                    RequestMethods.RootsList,
-                    (request, _, cancellationToken) => rootsHandler(request, cancellationToken),
-                    McpJsonUtilities.JsonContext.Default.ListRootsRequestParams,
-                    McpJsonUtilities.JsonContext.Default.ListRootsResult);
-            }
+        if (options.Handlers?.SamplingHandler is { } samplingHandler)
+        {
+            RequestHandlers.Set(
+                RequestMethods.SamplingCreateMessage,
+                (request, _, cancellationToken) => samplingHandler(
+                    request,
+                    request?.ProgressToken is { } token ? new TokenProgress(this, token) : NullProgress.Instance,
+                    cancellationToken),
+                McpJsonUtilities.JsonContext.Default.CreateMessageRequestParams,
+                McpJsonUtilities.JsonContext.Default.CreateMessageResult);
+            
+            _options.Capabilities ??= new();
+            _options.Capabilities.Sampling ??= new();
+        }
 
-            if (capabilities.Elicitation is { } elicitationCapability)
-            {
-                if (elicitationCapability.ElicitationHandler is not { } elicitationHandler)
-                {
-                    throw new InvalidOperationException("Elicitation capability was set but it did not provide a handler.");
-                }
+        if (options.Handlers?.RootsHandler is { } rootsHandler)
+        {
+            RequestHandlers.Set(
+                RequestMethods.RootsList,
+                (request, _, cancellationToken) => rootsHandler(request, cancellationToken),
+                McpJsonUtilities.JsonContext.Default.ListRootsRequestParams,
+                McpJsonUtilities.JsonContext.Default.ListRootsResult);
+
+            _options.Capabilities ??= new();
+            _options.Capabilities.Roots ??= new();
+        }
 
-                RequestHandlers.Set(
-                    RequestMethods.ElicitationCreate,
-                    (request, _, cancellationToken) => elicitationHandler(request, cancellationToken),
-                    McpJsonUtilities.JsonContext.Default.ElicitRequestParams,
-                    McpJsonUtilities.JsonContext.Default.ElicitResult);
-            }
+        if (options.Handlers?.ElicitationHandler is { } elicitationHandler)
+        {
+            RequestHandlers.Set(
+                RequestMethods.ElicitationCreate,
+                (request, _, cancellationToken) => elicitationHandler(request, cancellationToken),
+                McpJsonUtilities.JsonContext.Default.ElicitRequestParams,
+                McpJsonUtilities.JsonContext.Default.ElicitResult);
+
+            _options.Capabilities ??= new();
+            _options.Capabilities.Elicitation ??= new();
         }
     }
 

src/ModelContextProtocol.Core/Client/McpClientExtensions.cs

@@ -965,11 +965,11 @@ internal static CreateMessageResult ToCreateMessageResult(this ChatResponse chat
     }
 
     /// <summary>
-    /// Creates a sampling handler for use with <see cref="SamplingCapability.SamplingHandler"/> that will
+    /// Creates a sampling handler for use with <see cref="McpClientHandlers.SamplingHandler"/> that will
     /// satisfy sampling requests using the specified <see cref="IChatClient"/>.
     /// </summary>
     /// <param name="chatClient">The <see cref="IChatClient"/> with which to satisfy sampling requests.</param>
-    /// <returns>The created handler delegate that can be assigned to <see cref="SamplingCapability.SamplingHandler"/>.</returns>
+    /// <returns>The created handler delegate that can be assigned to <see cref="McpClientHandlers.SamplingHandler"/>.</returns>
     /// <remarks>
     /// <para>
     /// This method creates a function that converts MCP message requests into chat client calls, enabling

src/ModelContextProtocol.Core/Client/McpClientHandlers.cs

@@ -0,0 +1,89 @@
+using Microsoft.Extensions.AI;
+using ModelContextProtocol.Protocol;
+
+namespace ModelContextProtocol.Client;
+
+/// <summary>
+/// Provides a container for handlers used in the creation of an MCP client.
+/// </summary>
+/// <remarks>
+/// <para>
+/// This class provides a centralized collection of delegates that implement various capabilities of the Model Context Protocol.
+/// </para>
+/// <para>
+/// Each handler in this class corresponds to a specific client endpoint in the Model Context Protocol and
+/// is responsible for processing a particular type of message. The handlers are used to customize
+/// the behavior of the MCP server by providing implementations for the various protocol operations.
+/// </para>
+/// <para>
+/// When a server sends a message to the client, the appropriate handler is invoked to process it
+/// according to the protocol specification. Which handler is selected
+/// is done based on an ordinal, case-sensitive string comparison.
+/// </para>
+/// </remarks>
+public class McpClientHandlers
+{
+
+    /// <summary>Gets or sets notification handlers to register with the client.</summary>
+    /// <remarks>
+    /// <para>
+    /// When constructed, the client will enumerate these handlers once, which may contain multiple handlers per notification method key.
+    /// The client will not re-enumerate the sequence after initialization.
+    /// </para>
+    /// <para>
+    /// Notification handlers allow the client to respond to server-sent notifications for specific methods.
+    /// Each key in the collection is a notification method name, and each value is a callback that will be invoked
+    /// when a notification with that method is received.
+    /// </para>
+    /// <para>
+    /// Handlers provided via <see cref="NotificationHandlers"/> will be registered with the client for the lifetime of the client.
+    /// For transient handlers, <see cref="IMcpEndpoint.RegisterNotificationHandler"/> may be used to register a handler that can
+    /// then be unregistered by disposing of the <see cref="IAsyncDisposable"/> returned from the method.
+    /// </para>
+    /// </remarks>
+    public IEnumerable<KeyValuePair<string, Func<JsonRpcNotification, CancellationToken, ValueTask>>>? NotificationHandlers { get; set; }
+
+    /// <summary>
+    /// Gets or sets the handler for <see cref="RequestMethods.RootsList"/> requests.
+    /// </summary>
+    /// <remarks>
+    /// This handler is invoked when a client sends a <see cref="RequestMethods.RootsList"/> request to retrieve available roots.
+    /// The handler receives request parameters and should return a <see cref="ListRootsResult"/> containing the collection of available roots.
+    /// </remarks>
+    public Func<ListRootsRequestParams?, CancellationToken, ValueTask<ListRootsResult>>? RootsHandler { get; set; }
+
+    /// <summary>
+    /// Gets or sets the handler for processing <see cref="RequestMethods.ElicitationCreate"/> requests.
+    /// </summary>
+    /// <remarks>
+    /// <para>
+    /// This handler function is called when an MCP server requests the client to provide additional
+    /// information during interactions. The client must set this property for the elicitation capability to work.
+    /// </para>
+    /// <para>
+    /// The handler receives message parameters and a cancellation token.
+    /// It should return a <see cref="ElicitResult"/> containing the response to the elicitation request.
+    /// </para>
+    /// </remarks>
+    public Func<ElicitRequestParams?, CancellationToken, ValueTask<ElicitResult>>? ElicitationHandler { get; set; }
+
+    /// <summary>
+    /// Gets or sets the handler for processing <see cref="RequestMethods.SamplingCreateMessage"/> requests.
+    /// </summary>
+    /// <remarks>
+    /// <para>
+    /// This handler function is called when an MCP server requests the client to generate content
+    /// using an AI model. The client must set this property for the sampling capability to work.
+    /// </para>
+    /// <para>
+    /// The handler receives message parameters, a progress reporter for updates, and a 
+    /// cancellation token. It should return a <see cref="CreateMessageResult"/> containing the 
+    /// generated content.
+    /// </para>
+    /// <para>
+    /// You can create a handler using the <see cref="McpClientExtensions.CreateSamplingHandler"/> extension
+    /// method with any implementation of <see cref="IChatClient"/>.
+    /// </para>
+    /// </remarks>
+    public Func<CreateMessageRequestParams?, IProgress<ProgressNotificationValue>, CancellationToken, ValueTask<CreateMessageResult>>? SamplingHandler { get; set; }
+}

src/ModelContextProtocol.Core/Client/McpClientOptions.cs

@@ -63,4 +63,9 @@ public sealed class McpClientOptions
     /// <para>The default value is 60 seconds.</para>
     /// </remarks>
     public TimeSpan InitializationTimeout { get; set; } = TimeSpan.FromSeconds(60);
+
+    /// <summary>
+    /// Gets or sets the container of handlers used by the client for processing protocol messages.
+    /// </summary>
+    public McpClientHandlers? Handlers { get; set; }
 }

src/ModelContextProtocol.Core/Protocol/ClientCapabilities.cs

@@ -45,7 +45,7 @@ public sealed class ClientCapabilities
     /// </para>
     /// <para>
     /// The server can use <see cref="McpServerExtensions.RequestRootsAsync"/> to request the list of
-    /// available roots from the client, which will trigger the client's <see cref="RootsCapability.RootsHandler"/>.
+    /// available roots from the client, which will trigger the client's <see cref="ModelContextProtocol.Client.McpClientHandlers.RootsHandler"/>.
     /// </para>
     /// </remarks>
     [JsonPropertyName("roots")]
@@ -64,24 +64,4 @@ public sealed class ClientCapabilities
     /// </summary>
     [JsonPropertyName("elicitation")]
     public ElicitationCapability? Elicitation { get; set; }
-
-    /// <summary>Gets or sets notification handlers to register with the client.</summary>
-    /// <remarks>
-    /// <para>
-    /// When constructed, the client will enumerate these handlers once, which may contain multiple handlers per notification method key.
-    /// The client will not re-enumerate the sequence after initialization.
-    /// </para>
-    /// <para>
-    /// Notification handlers allow the client to respond to server-sent notifications for specific methods.
-    /// Each key in the collection is a notification method name, and each value is a callback that will be invoked
-    /// when a notification with that method is received.
-    /// </para>
-    /// <para>
-    /// Handlers provided via <see cref="NotificationHandlers"/> will be registered with the client for the lifetime of the client.
-    /// For transient handlers, <see cref="IMcpEndpoint.RegisterNotificationHandler"/> may be used to register a handler that can
-    /// then be unregistered by disposing of the <see cref="IAsyncDisposable"/> returned from the method.
-    /// </para>
-    /// </remarks>
-    [JsonIgnore]
-    public IEnumerable<KeyValuePair<string, Func<JsonRpcNotification, CancellationToken, ValueTask>>>? NotificationHandlers { get; set; }
 }

src/ModelContextProtocol.Core/Protocol/CompletionsCapability.cs

@@ -1,6 +1,3 @@
-using ModelContextProtocol.Server;
-using System.Text.Json.Serialization;
-
 namespace ModelContextProtocol.Protocol;
 
 /// <summary>
@@ -23,15 +20,4 @@ namespace ModelContextProtocol.Protocol;
 public sealed class CompletionsCapability
 {
     // Currently empty in the spec, but may be extended in the future.
-
-    /// <summary>
-    /// Gets or sets the handler for completion requests.
-    /// </summary>
-    /// <remarks>
-    /// This handler provides auto-completion suggestions for prompt arguments or resource references in the Model Context Protocol.
-    /// The handler receives a reference type (e.g., "ref/prompt" or "ref/resource") and the current argument value,
-    /// and should return appropriate completion suggestions.
-    /// </remarks>
-    [JsonIgnore]
-    public McpRequestHandler<CompleteRequestParams, CompleteResult>? CompleteHandler { get; set; }
 }

src/ModelContextProtocol.Core/Protocol/ElicitationCapability.cs

@@ -1,5 +1,3 @@
-using System.Text.Json.Serialization;
-
 namespace ModelContextProtocol.Protocol;
 
 /// <summary>
@@ -11,26 +9,10 @@ namespace ModelContextProtocol.Protocol;
 /// </para>
 /// <para>
 /// When this capability is enabled, an MCP server can request the client to provide additional information
-/// during interactions. The client must set a <see cref="ElicitationHandler"/> to process these requests.
+/// during interactions. The client must set a <see cref="ModelContextProtocol.Client.McpClientHandlers.ElicitationHandler"/> to process these requests.
 /// </para>
 /// </remarks>
 public sealed class ElicitationCapability
 {
     // Currently empty in the spec, but may be extended in the future.
-
-    /// <summary>
-    /// Gets or sets the handler for processing <see cref="RequestMethods.ElicitationCreate"/> requests.
-    /// </summary>
-    /// <remarks>
-    /// <para>
-    /// This handler function is called when an MCP server requests the client to provide additional
-    /// information during interactions. The client must set this property for the elicitation capability to work.
-    /// </para>
-    /// <para>
-    /// The handler receives message parameters and a cancellation token.
-    /// It should return a <see cref="ElicitResult"/> containing the response to the elicitation request.
-    /// </para>
-    /// </remarks>
-    [JsonIgnore]
-    public Func<ElicitRequestParams?, CancellationToken, ValueTask<ElicitResult>>? ElicitationHandler { get; set; }
 }

src/ModelContextProtocol.Core/Protocol/LoggingCapability.cs

@@ -1,6 +1,3 @@
-using ModelContextProtocol.Server;
-using System.Text.Json.Serialization;
-
 namespace ModelContextProtocol.Protocol;
 
 /// <summary>
@@ -13,10 +10,4 @@ namespace ModelContextProtocol.Protocol;
 public sealed class LoggingCapability
 {
     // Currently empty in the spec, but may be extended in the future
-
-    /// <summary>
-    /// Gets or sets the handler for set logging level requests from clients.
-    /// </summary>
-    [JsonIgnore]
-    public McpRequestHandler<SetLevelRequestParams, EmptyResult>? SetLoggingLevelHandler { get; set; }
 }