Mark RunSessionHandler experimental (MCPEXP002) (#1383)

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: halter73 <54385+halter73@users.noreply.github.com>
Co-authored-by: jeffhandley <1031940+jeffhandley@users.noreply.github.com>

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> or referencing <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,5 +90,24 @@ 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>
+    /// <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.
+    /// </summary>
+    public const string RunSessionHandler_Message = "RunSessionHandler is experimental and may be removed or changed in a future release. Consider using ConfigureSessionOptions instead.";
+
+    /// <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#mcpexp002";
 }

src/ModelContextProtocol.AspNetCore/HttpServerTransportOptions.cs

@@ -24,7 +24,20 @@ public class HttpServerTransportOptions
     /// </summary>
     /// <remarks>
     /// This callback is useful for running logic before a session starts and after it completes.
+    /// <para>
+    /// The <see cref="HttpContext"/> parameter comes from the request that initiated the session (e.g., the
+    /// initialize request) and may not be usable after <see cref="McpServer.RunAsync"/> starts, since that
+    /// request will have already completed.
+    /// </para>
+    /// <para>
+    /// Consider using <see cref="ConfigureSessionOptions"/> instead, which provides access to the
+    /// <see cref="HttpContext"/> of the initializing request with fewer known issues.
+    /// </para>
+    /// <para>
+    /// This API is experimental and may be removed or change signatures in a future release.
+    /// </para>
     /// </remarks>
+    [System.Diagnostics.CodeAnalysis.Experimental(Experimentals.RunSessionHandler_DiagnosticId, UrlFormat = Experimentals.RunSessionHandler_Url)]
     public Func<HttpContext, McpServer, CancellationToken, Task>? RunSessionHandler { get; set; }
 
     /// <summary>

src/ModelContextProtocol.AspNetCore/ModelContextProtocol.AspNetCore.csproj

@@ -20,6 +20,10 @@
     <None Include="README.md" pack="true" PackagePath="\" />
   </ItemGroup>
 
+  <ItemGroup>
+    <Compile Include="..\Common\Experimentals.cs" Link="Experimentals.cs" />
+  </ItemGroup>
+
   <ItemGroup>
     <ProjectReference Include="..\ModelContextProtocol\ModelContextProtocol.csproj" />
   </ItemGroup>

src/ModelContextProtocol.AspNetCore/SseHandler.cs

@@ -56,7 +56,9 @@ internal sealed class SseHandler(
                 await using var mcpServer = McpServer.Create(transport, mcpServerOptions, loggerFactory, context.RequestServices);
                 context.Features.Set(mcpServer);
 
+#pragma warning disable MCPEXP002 // RunSessionHandler is experimental
                 var runSessionAsync = httpMcpServerOptions.Value.RunSessionHandler ?? StreamableHttpHandler.RunSessionAsync;
+#pragma warning restore MCPEXP002
                 await runSessionAsync(context, mcpServer, cancellationToken);
             }
             finally

src/ModelContextProtocol.AspNetCore/StreamableHttpHandler.cs

@@ -390,7 +390,9 @@ internal sealed class StreamableHttpHandler(
         var userIdClaim = GetUserIdClaim(context.User);
         var session = new StreamableHttpSession(sessionId, transport, server, userIdClaim, sessionManager);
 
+#pragma warning disable MCPEXP002 // RunSessionHandler is experimental
         var runSessionAsync = HttpServerTransportOptions.RunSessionHandler ?? RunSessionAsync;
+#pragma warning restore MCPEXP002
         session.ServerRunTask = runSessionAsync(context, server, session.SessionClosed);
 
         return session;