Reuse MCPEXP002 for RunSessionHandler (remove MCPEXP003)

Co-authored-by: jeffhandley <1031940+jeffhandley@users.noreply.github.com>

Author: Copilot

docs/list-of-diagnostics.md

@@ -23,9 +23,8 @@ If you use experimental APIs, you will get one of the diagnostics shown below. T
 
 | Diagnostic ID | Description |
 | :------------ | :---------- |
-| `MCPEXP001` | MCP experimental APIs including Tasks and Extensions. Tasks provide a mechanism for asynchronous long-running operations that can be polled for status and results (see [MCP Tasks specification](https://modelcontextprotocol.io/specification/draft/basic/utilities/tasks)). Extensions provide a framework for extending the Model Context Protocol while maintaining interoperability (see [SEP-2133](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2133)). |
-| `MCPEXP002` | Subclassing `McpClient` and `McpServer` is experimental and subject to change (see [#1363](https://github.com/modelcontextprotocol/csharp-sdk/pull/1363)). |
-| `MCPEXP003` | `RunSessionHandler` is experimental and may be removed or change signatures in a future release. Consider using `ConfigureSessionOptions` instead, which provides access to the `HttpContext` of the initializing request with fewer known issues. |
+| `MCPEXP001` | Experimental APIs for features in the MCP specification itself, including Tasks and Extensions. Tasks provide a mechanism for asynchronous long-running operations that can be polled for status and results (see [MCP Tasks specification](https://modelcontextprotocol.io/specification/draft/basic/utilities/tasks)). Extensions provide a framework for extending the Model Context Protocol while maintaining interoperability (see [SEP-2133](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2133)). |
+| `MCPEXP002` | Experimental SDK APIs unrelated to the MCP specification itself, including subclassing `McpClient`/`McpServer` (see [#1363](https://github.com/modelcontextprotocol/csharp-sdk/pull/1363)) and `RunSessionHandler`, which may be removed or change signatures in a future release (consider using `ConfigureSessionOptions` instead). |
 
 ## Obsolete APIs
 

samples/EverythingServer/Program.cs

@@ -51,7 +51,7 @@
     .WithHttpTransport(options =>
     {
         // Add a RunSessionHandler to remove all subscriptions for the session when it ends
-#pragma warning disable MCPEXP003 // RunSessionHandler is experimental
+#pragma warning disable MCPEXP002 // RunSessionHandler is experimental
         options.RunSessionHandler = async (httpContext, mcpServer, token) =>
         {
             if (mcpServer.SessionId == null)
@@ -77,7 +77,7 @@
                 subscriptions.TryRemove(mcpServer.SessionId, out _);
             }
         };
-#pragma warning restore MCPEXP003
+#pragma warning restore MCPEXP002
     })
     .WithTools<AddTool>()
     .WithTools<AnnotatedMessageTool>()

src/Common/Experimentals.cs

@@ -6,10 +6,24 @@ namespace ModelContextProtocol;
 /// Defines diagnostic IDs, messages, and URLs for APIs annotated with <see cref="ExperimentalAttribute"/>.
 /// </summary>
 /// <remarks>
+/// Experimental diagnostic IDs are grouped by category:
+/// <list type="bullet">
+/// <item><description>
+/// <c>MCPEXP001</c> covers APIs related to experimental features in the MCP specification itself,
+/// such as Tasks and Extensions. These APIs may change as the specification evolves.
+/// </description></item>
+/// <item><description>
+/// <c>MCPEXP002</c> covers experimental SDK APIs that are unrelated to the MCP specification,
+/// such as subclassing internal types or SDK-specific extensibility hooks. These APIs may
+/// change or be removed based on SDK design feedback.
+/// </description></item>
+/// </list>
+/// <para>
 /// When an experimental API is associated with an experimental specification, the message
 /// should refer to the specification version that introduces the feature and the SEP
 /// when available. If there is a SEP associated with the experimental API, the Url should
 /// point to the SEP issue.
+/// </para>
 /// <para>
 /// Experimental diagnostic IDs are in the format MCPEXP###.
 /// </para>
@@ -58,8 +72,14 @@ internal static class Experimentals
     public const string Extensions_Url = "https://github.com/modelcontextprotocol/csharp-sdk/blob/main/docs/list-of-diagnostics.md#mcpexp001";
 
     /// <summary>
-    /// Diagnostic ID for experimental subclassing of McpClient and McpServer.
+    /// Diagnostic ID for experimental SDK APIs unrelated to the MCP specification,
+    /// such as subclassing <c>McpClient</c>/<c>McpServer</c> and <c>RunSessionHandler</c>.
     /// </summary>
+    /// <remarks>
+    /// This diagnostic ID covers experimental SDK-level extensibility APIs. All constants
+    /// in this group share the same diagnostic ID so users need only one suppression point
+    /// for SDK design preview features.
+    /// </remarks>
     public const string Subclassing_DiagnosticId = "MCPEXP002";
 
     /// <summary>
@@ -70,12 +90,16 @@ internal static class Experimentals
     /// <summary>
     /// URL for experimental subclassing of McpClient and McpServer.
     /// </summary>
-    public const string Subclassing_Url = "https://github.com/modelcontextprotocol/csharp-sdk/pull/1363";
+    public const string Subclassing_Url = "https://github.com/modelcontextprotocol/csharp-sdk/blob/main/docs/list-of-diagnostics.md#mcpexp002";
 
     /// <summary>
     /// Diagnostic ID for the experimental <c>RunSessionHandler</c> API.
     /// </summary>
-    public const string RunSessionHandler_DiagnosticId = "MCPEXP003";
+    /// <remarks>
+    /// This uses the same diagnostic ID as <see cref="Subclassing_DiagnosticId"/> because
+    /// both are experimental SDK APIs unrelated to the MCP specification.
+    /// </remarks>
+    public const string RunSessionHandler_DiagnosticId = "MCPEXP002";
 
     /// <summary>
     /// Message for the experimental <c>RunSessionHandler</c> API.
@@ -85,5 +109,5 @@ internal static class Experimentals
     /// <summary>
     /// URL for the experimental <c>RunSessionHandler</c> API.
     /// </summary>
-    public const string RunSessionHandler_Url = "https://github.com/modelcontextprotocol/csharp-sdk/blob/main/docs/list-of-diagnostics.md#mcpexp003";
+    public const string RunSessionHandler_Url = "https://github.com/modelcontextprotocol/csharp-sdk/blob/main/docs/list-of-diagnostics.md#mcpexp002";
 }

src/ModelContextProtocol.AspNetCore/SseHandler.cs

@@ -56,9 +56,9 @@ public async Task HandleSseRequestAsync(HttpContext context)
                 await using var mcpServer = McpServer.Create(transport, mcpServerOptions, loggerFactory, context.RequestServices);
                 context.Features.Set(mcpServer);
 
-#pragma warning disable MCPEXP003 // RunSessionHandler is experimental
+#pragma warning disable MCPEXP002 // RunSessionHandler is experimental
                 var runSessionAsync = httpMcpServerOptions.Value.RunSessionHandler ?? StreamableHttpHandler.RunSessionAsync;
-#pragma warning restore MCPEXP003
+#pragma warning restore MCPEXP002
                 await runSessionAsync(context, mcpServer, cancellationToken);
             }
             finally

src/ModelContextProtocol.AspNetCore/StreamableHttpHandler.cs

@@ -390,9 +390,9 @@ private async ValueTask<StreamableHttpSession> CreateSessionAsync(
         var userIdClaim = GetUserIdClaim(context.User);
         var session = new StreamableHttpSession(sessionId, transport, server, userIdClaim, sessionManager);
 
-#pragma warning disable MCPEXP003 // RunSessionHandler is experimental
+#pragma warning disable MCPEXP002 // RunSessionHandler is experimental
         var runSessionAsync = HttpServerTransportOptions.RunSessionHandler ?? RunSessionAsync;
-#pragma warning restore MCPEXP003
+#pragma warning restore MCPEXP002
         session.ServerRunTask = runSessionAsync(context, server, session.SessionClosed);
 
         return session;

tests/ModelContextProtocol.AspNetCore.Tests/MapMcpStreamableHttpTests.cs

@@ -213,14 +213,14 @@ public async Task CanResumeSessionWithMapMcpAndRunSessionHandler()
         }).WithHttpTransport(opts =>
         {
             ConfigureStateless(opts);
-#pragma warning disable MCPEXP003 // RunSessionHandler is experimental
+#pragma warning disable MCPEXP002 // RunSessionHandler is experimental
             opts.RunSessionHandler = async (context, server, cancellationToken) =>
             {
                 Interlocked.Increment(ref runSessionCount);
                 serverTcs.TrySetResult(server);
                 await server.RunAsync(cancellationToken);
             };
-#pragma warning restore MCPEXP003
+#pragma warning restore MCPEXP002
         }).WithTools<EchoHttpContextUserTools>();
 
         await using var app = Builder.Build();
@@ -483,13 +483,13 @@ public async Task DisposeAsync_DoesNotHang_WhenOwnsSessionIsFalse_WithUnsolicite
         Builder.Services.AddMcpServer().WithHttpTransport(opts =>
         {
             ConfigureStateless(opts);
-#pragma warning disable MCPEXP003 // RunSessionHandler is experimental
+#pragma warning disable MCPEXP002 // RunSessionHandler is experimental
             opts.RunSessionHandler = async (context, server, cancellationToken) =>
             {
                 serverTcs.TrySetResult(server);
                 await server.RunAsync(cancellationToken);
             };
-#pragma warning restore MCPEXP003
+#pragma warning restore MCPEXP002
         }).WithTools<ClaimsPrincipalTools>();
 
         await using var app = Builder.Build();

tests/ModelContextProtocol.AspNetCore.Tests/ResumabilityIntegrationTestsBase.cs

@@ -253,13 +253,13 @@ public virtual async Task Client_CanResumeUnsolicitedMessageStream_AfterDisconne
 
         await using var app = await CreateServerAsync(configureTransport: options =>
         {
-#pragma warning disable MCPEXP003 // RunSessionHandler is experimental
+#pragma warning disable MCPEXP002 // RunSessionHandler is experimental
             options.RunSessionHandler = (httpContext, mcpServer, cancellationToken) =>
             {
                 serverTcs.TrySetResult(mcpServer);
                 return mcpServer.RunAsync(cancellationToken);
             };
-#pragma warning restore MCPEXP003
+#pragma warning restore MCPEXP002
         });
 
         await using var client = await ConnectClientAsync();

tests/ModelContextProtocol.AspNetCore.Tests/SseIntegrationTests.cs

@@ -83,7 +83,7 @@ public async Task ConnectAndReceiveNotification_InMemoryServer()
         Builder.Services.AddMcpServer()
             .WithHttpTransport(httpTransportOptions =>
             {
-#pragma warning disable MCPEXP003 // RunSessionHandler is experimental
+#pragma warning disable MCPEXP002 // RunSessionHandler is experimental
                 httpTransportOptions.RunSessionHandler = (httpContext, mcpServer, cancellationToken) =>
                 {
                     // We could also use ServerCapabilities.NotificationHandlers, but it's good to have some test coverage of RunSessionHandler.
@@ -94,7 +94,7 @@ public async Task ConnectAndReceiveNotification_InMemoryServer()
                     });
                     return mcpServer.RunAsync(cancellationToken);
                 };
-#pragma warning restore MCPEXP003
+#pragma warning restore MCPEXP002
             });
 
         await using var app = Builder.Build();

tests/ModelContextProtocol.AspNetCore.Tests/StatelessServerTests.cs

@@ -158,15 +158,15 @@ public async Task UnsolicitedNotification_Fails_WithInvalidOperationException()
         Builder.Services.AddMcpServer()
             .WithHttpTransport(options =>
             {
-#pragma warning disable MCPEXP003 // RunSessionHandler is experimental
+#pragma warning disable MCPEXP002 // RunSessionHandler is experimental
                 options.RunSessionHandler = async (context, server, cancellationToken) =>
                 {
                     unsolicitedNotificationException = await Assert.ThrowsAsync<InvalidOperationException>(
                         () => server.SendNotificationAsync(NotificationMethods.PromptListChangedNotification, TestContext.Current.CancellationToken));
 
                     await server.RunAsync(cancellationToken);
                 };
-#pragma warning restore MCPEXP003
+#pragma warning restore MCPEXP002
             });
 
         await StartAsync();

tests/ModelContextProtocol.AspNetCore.Tests/StreamableHttpServerConformanceTests.cs

@@ -325,13 +325,13 @@ public async Task GetRequest_Receives_UnsolicitedNotifications()
         Builder.Services.AddMcpServer()
             .WithHttpTransport(options =>
             {
-#pragma warning disable MCPEXP003 // RunSessionHandler is experimental
+#pragma warning disable MCPEXP002 // RunSessionHandler is experimental
                 options.RunSessionHandler = (httpContext, mcpServer, cancellationToken) =>
                 {
                     server = mcpServer;
                     return mcpServer.RunAsync(cancellationToken);
                 };
-#pragma warning restore MCPEXP003
+#pragma warning restore MCPEXP002
             });
 
         await StartAsync();
@@ -367,13 +367,13 @@ public async Task SendNotificationAsync_DoesNotThrow_WhenNoGetRequestHasBeenMade
         Builder.Services.AddMcpServer()
             .WithHttpTransport(options =>
             {
-#pragma warning disable MCPEXP003 // RunSessionHandler is experimental
+#pragma warning disable MCPEXP002 // RunSessionHandler is experimental
                 options.RunSessionHandler = (httpContext, mcpServer, cancellationToken) =>
                 {
                     server = mcpServer;
                     return mcpServer.RunAsync(cancellationToken);
                 };
-#pragma warning restore MCPEXP003
+#pragma warning restore MCPEXP002
             });
 
         await StartAsync();
@@ -506,13 +506,13 @@ public async Task AsyncLocalSetInRunSessionHandlerCallback_Flows_ToAllToolCalls_
             .WithHttpTransport(options =>
             {
                 options.PerSessionExecutionContext = true;
-#pragma warning disable MCPEXP003 // RunSessionHandler is experimental
+#pragma warning disable MCPEXP002 // RunSessionHandler is experimental
                 options.RunSessionHandler = async (httpContext, mcpServer, cancellationToken) =>
                 {
                     asyncLocal.Value = $"RunSessionHandler ({totalSessionCount++})";
                     await mcpServer.RunAsync(cancellationToken);
                 };
-#pragma warning restore MCPEXP003
+#pragma warning restore MCPEXP002
             });
 
         Builder.Services.AddSingleton(McpServerTool.Create([McpServerTool(Name = "async-local-session")] () => asyncLocal.Value));