Add SEP-2575 + SEP-2567 draft protocol support

Implements the protocol-level changes for the draft revision (SEP-2575 stateless MCP and SEP-2567 sessionless MCP):

- New _meta keys for per-request protocolVersion / clientInfo / clientCapabilities / logLevel
- New RPCs: server/discover and subscriptions/listen, plus the acknowledgement notification
- New JSON-RPC error codes -32004 (UnsupportedProtocolVersion) and -32003 (MissingRequiredClientCapability) with typed exception classes
- Client skips initialize under draft mode, calls server/discover instead, and falls back to legacy initialize when the server doesn't support the experimental version
- Server keeps the legacy initialize handler for back-compat, and a new built-in incoming message filter projects per-request _meta values onto the per-session client info/capabilities/version state under draft
- HTTP server suppresses Mcp-Session-Id and routes draft requests through the stateless path regardless of HttpServerTransportOptions.Stateless
- HTTP server returns -32004 with a structured supportedVersions data payload when a client requests an unsupported protocol version
- HTTP client transport carries the protocol version header on every request (sourced from per-request _meta when present), and surfaces -32004/-32003 from HTTP error responses as typed McpProtocolException for the connection logic to react

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: halter73

src/ModelContextProtocol.AspNetCore/StreamableHttpHandler.cs

@@ -8,8 +8,10 @@
 using ModelContextProtocol.Protocol;
 using ModelContextProtocol.Server;
 using System.Collections.Concurrent;
+using System.Diagnostics.CodeAnalysis;
 using System.Security.Claims;
 using System.Security.Cryptography;
+using System.Text.Json;
 using System.Text.Json.Serialization.Metadata;
 
 namespace ModelContextProtocol.AspNetCore;
@@ -51,9 +53,9 @@ internal sealed class StreamableHttpHandler(
 
     public async Task HandlePostRequestAsync(HttpContext context)
     {
-        if (!ValidateProtocolVersionHeader(context, out var errorMessage))
+        if (!ValidateProtocolVersionHeader(context, out var protocolVersionError))
         {
-            await WriteJsonRpcErrorAsync(context, errorMessage!, StatusCodes.Status400BadRequest);
+            await WriteJsonRpcErrorDetailAsync(context, protocolVersionError, StatusCodes.Status400BadRequest);
             return;
         }
 
@@ -99,9 +101,24 @@ await WriteJsonRpcErrorAsync(context,
 
     public async Task HandleGetRequestAsync(HttpContext context)
     {
-        if (!ValidateProtocolVersionHeader(context, out var errorMessage))
+        if (!ValidateProtocolVersionHeader(context, out var protocolVersionError))
         {
-            await WriteJsonRpcErrorAsync(context, errorMessage!, StatusCodes.Status400BadRequest);
+            await WriteJsonRpcErrorDetailAsync(context, protocolVersionError, StatusCodes.Status400BadRequest);
+            return;
+        }
+
+        var sessionId = context.Request.Headers[McpSessionIdHeaderName].ToString();
+
+        // Under the draft protocol revision (SEP-2575), the standalone HTTP GET endpoint for unsolicited
+        // server-to-client messages is removed. Clients should use subscriptions/listen (POST) instead.
+        // We only reject GET when the request looks like a draft-mode probe (experimental version with
+        // no Mcp-Session-Id); legacy stateful sessions that opted into MRTR via the experimental version
+        // are still allowed to use GET for back-compat.
+        if (IsDraftProtocolRequest(context) && string.IsNullOrEmpty(sessionId))
+        {
+            await WriteJsonRpcErrorAsync(context,
+                "Bad Request: The GET endpoint is not supported by the draft protocol revision. Use subscriptions/listen via POST instead.",
+                StatusCodes.Status400BadRequest);
             return;
         }
 
@@ -113,7 +130,6 @@ await WriteJsonRpcErrorAsync(context,
             return;
         }
 
-        var sessionId = context.Request.Headers[McpSessionIdHeaderName].ToString();
         var session = await GetSessionAsync(context, sessionId);
         if (session is null)
         {
@@ -202,13 +218,25 @@ private static async Task HandleResumePostResponseStreamAsync(HttpContext contex
 
     public async Task HandleDeleteRequestAsync(HttpContext context)
     {
-        if (!ValidateProtocolVersionHeader(context, out var errorMessage))
+        if (!ValidateProtocolVersionHeader(context, out var protocolVersionError))
         {
-            await WriteJsonRpcErrorAsync(context, errorMessage!, StatusCodes.Status400BadRequest);
+            await WriteJsonRpcErrorDetailAsync(context, protocolVersionError, StatusCodes.Status400BadRequest);
             return;
         }
 
         var sessionId = context.Request.Headers[McpSessionIdHeaderName].ToString();
+
+        // Under the draft revision there are no sessions to terminate. Reject DELETE requests that
+        // declare the draft version without an Mcp-Session-Id. Legacy stateful sessions opted into
+        // the experimental version may still call DELETE for back-compat.
+        if (IsDraftProtocolRequest(context) && string.IsNullOrEmpty(sessionId))
+        {
+            await WriteJsonRpcErrorAsync(context,
+                "Bad Request: The DELETE endpoint is not supported by the draft protocol revision (no Mcp-Session-Id sessions exist).",
+                StatusCodes.Status400BadRequest);
+            return;
+        }
+
         if (sessionManager.TryRemove(sessionId, out var session))
         {
             await session.DisposeAsync();
@@ -293,6 +321,22 @@ await WriteJsonRpcErrorAsync(context,
     private async ValueTask<StreamableHttpSession?> GetOrCreateSessionAsync(HttpContext context, JsonRpcMessage message)
     {
         var sessionId = context.Request.Headers[McpSessionIdHeaderName].ToString();
+        bool isDraftRequest = IsDraftProtocolRequest(context);
+
+        // Under the draft protocol revision (SEP-2575 + SEP-2567), sessions are removed entirely.
+        // A request that declares the experimental draft version via MCP-Protocol-Version and that
+        // does NOT include an Mcp-Session-Id is treated as sessionless regardless of the
+        // HttpServerTransportOptions.Stateless setting (which governs only legacy clients).
+        //
+        // For back-compat with clients that previously used the experimental version on top of the
+        // legacy stateful session model (e.g., MRTR-as-extension-on-initialize), we still route
+        // experimental-version requests that DO include an Mcp-Session-Id through the legacy session
+        // lookup path. SEP-2567 will eventually phase that out, but we preserve it now to avoid
+        // breaking existing consumers without forcing them to change their setup code.
+        if (isDraftRequest && string.IsNullOrEmpty(sessionId))
+        {
+            return await StartNewSessionAsync(context, forceStateless: true);
+        }
 
         if (string.IsNullOrEmpty(sessionId))
         {
@@ -322,12 +366,33 @@ await WriteJsonRpcErrorAsync(context,
         }
     }
 
-    private async ValueTask<StreamableHttpSession> StartNewSessionAsync(HttpContext context)
+    /// <summary>
+    /// Returns <see langword="true"/> when the request declares the experimental draft protocol revision via
+    /// the <c>MCP-Protocol-Version</c> header. Draft requests are always sessionless and do not perform
+    /// the legacy <c>initialize</c> handshake (SEP-2575 + SEP-2567).
+    /// </summary>
+    private bool IsDraftProtocolRequest(HttpContext context)
+    {
+#pragma warning disable MCPEXP001 // ExperimentalProtocolVersion is for evaluation purposes only
+        var experimental = mcpServerOptionsSnapshot.Value.ExperimentalProtocolVersion;
+#pragma warning restore MCPEXP001
+        if (experimental is null)
+        {
+            return false;
+        }
+
+        var protocolVersionHeader = context.Request.Headers[McpProtocolVersionHeaderName].ToString();
+        return string.Equals(protocolVersionHeader, experimental, StringComparison.Ordinal);
+    }
+
+    private async ValueTask<StreamableHttpSession> StartNewSessionAsync(HttpContext context, bool forceStateless = false)
     {
         string sessionId;
         StreamableHttpServerTransport transport;
 
-        if (!HttpServerTransportOptions.Stateless)
+        bool isStateless = HttpServerTransportOptions.Stateless || forceStateless;
+
+        if (!isStateless)
         {
             sessionId = MakeNewSessionId();
             transport = new(loggerFactory)
@@ -344,7 +409,7 @@ private async ValueTask<StreamableHttpSession> StartNewSessionAsync(HttpContext
         }
         else
         {
-            // In stateless mode, each request is independent. Don't set any session ID on the transport.
+            // In stateless mode (legacy or draft), each request is independent. Don't set any session ID on the transport.
             // If in the future we support resuming stateless requests, we should populate
             // the event stream store and retry interval here as well.
             sessionId = "";
@@ -354,22 +419,25 @@ private async ValueTask<StreamableHttpSession> StartNewSessionAsync(HttpContext
             };
         }
 
-        return await CreateSessionAsync(context, transport, sessionId);
+        return await CreateSessionAsync(context, transport, sessionId, forceStateless: forceStateless);
     }
 
     private async ValueTask<StreamableHttpSession> CreateSessionAsync(
         HttpContext context,
         StreamableHttpServerTransport transport,
         string sessionId,
-        Action<McpServerOptions>? configureOptions = null)
+        Action<McpServerOptions>? configureOptions = null,
+        bool forceStateless = false)
     {
         var mcpServerServices = applicationServices;
         var mcpServerOptions = mcpServerOptionsSnapshot.Value;
-        if (HttpServerTransportOptions.Stateless || HttpServerTransportOptions.ConfigureSessionOptions is not null || configureOptions is not null)
+        bool effectivelyStateless = HttpServerTransportOptions.Stateless || forceStateless;
+
+        if (effectivelyStateless || HttpServerTransportOptions.ConfigureSessionOptions is not null || configureOptions is not null)
         {
             mcpServerOptions = mcpServerOptionsFactory.Create(Options.DefaultName);
 
-            if (HttpServerTransportOptions.Stateless)
+            if (effectivelyStateless)
             {
                 // The session does not outlive the request in stateless mode.
                 mcpServerServices = context.RequestServices;
@@ -531,23 +599,51 @@ internal static Task RunSessionAsync(HttpContext httpContext, McpServer session,
 
     /// <summary>
     /// Validates the MCP-Protocol-Version header if present. A missing header is allowed for backwards compatibility,
-    /// but an invalid or unsupported value must be rejected with 400 Bad Request per the MCP spec.
+    /// but an invalid or unsupported value must be rejected with 400 Bad Request per the MCP spec. Per SEP-2575, the
+    /// rejection uses the <see cref="McpErrorCode.UnsupportedProtocolVersion"/> error code with a data payload
+    /// listing the server's supported versions so the client can select a fallback.
     /// </summary>
-    private bool ValidateProtocolVersionHeader(HttpContext context, out string? errorMessage)
+    private bool ValidateProtocolVersionHeader(HttpContext context, [NotNullWhen(false)] out JsonRpcErrorDetail? errorDetail)
     {
         var protocolVersionHeader = context.Request.Headers[McpProtocolVersionHeaderName].ToString();
+#pragma warning disable MCPEXP001 // ExperimentalProtocolVersion is for evaluation purposes only
+        var experimental = mcpServerOptionsSnapshot.Value.ExperimentalProtocolVersion;
+#pragma warning restore MCPEXP001
         if (!string.IsNullOrEmpty(protocolVersionHeader) &&
             !s_supportedProtocolVersions.Contains(protocolVersionHeader) &&
-            !(mcpServerOptionsSnapshot.Value.ExperimentalProtocolVersion is { } experimentalVersion && protocolVersionHeader == experimentalVersion))
+            !(experimental is not null && protocolVersionHeader == experimental))
         {
-            errorMessage = $"Bad Request: The MCP-Protocol-Version header value '{protocolVersionHeader}' is not supported.";
+            var supported = new List<string>(s_supportedProtocolVersions);
+            if (experimental is not null)
+            {
+                supported.Add(experimental);
+            }
+
+            errorDetail = new JsonRpcErrorDetail
+            {
+                Code = (int)McpErrorCode.UnsupportedProtocolVersion,
+                Message = $"Bad Request: The MCP-Protocol-Version header value '{protocolVersionHeader}' is not supported.",
+                Data = JsonSerializer.SerializeToNode(
+                    new UnsupportedProtocolVersionErrorData
+                    {
+                        Supported = supported,
+                        Requested = protocolVersionHeader,
+                    },
+                    GetRequiredJsonTypeInfo<UnsupportedProtocolVersionErrorData>()),
+            };
             return false;
         }
 
-        errorMessage = null;
+        errorDetail = null;
         return true;
     }
 
+    private static Task WriteJsonRpcErrorDetailAsync(HttpContext context, JsonRpcErrorDetail detail, int statusCode)
+    {
+        var jsonRpcError = new JsonRpcError { Error = detail };
+        return Results.Json(jsonRpcError, s_errorTypeInfo, statusCode: statusCode).ExecuteAsync(context);
+    }
+
     private static bool MatchesApplicationJsonMediaType(MediaTypeHeaderValue acceptHeaderValue)
         => acceptHeaderValue.MatchesMediaType("application/json");