Add fallback negotiation, MinProtocolVersion, server-side _meta protocolVersion validation, and raw stream conformance tests

Phase 2-5 of the draft (2026-07-28) rollout:

- McpClientImpl.ConnectAsync: tighten the draft probe fallback to match the spec's stdio rules. Apply a 5-second probe timeout (bounded by InitializationTimeout), broaden the catch to treat any McpProtocolException OR probe-timeout as a legacy-server signal, and special-case the two modern-server JSON-RPC errors (-32004 retries with supported[]; -32003 surfaces). Honor MinProtocolVersion before falling back to legacy initialize.

- McpClientOptions: add MinProtocolVersion public string? with XML docs. Setting this to McpSessionHandler.DraftProtocolVersion disables the automatic legacy fallback.

- McpServerImpl.CreateDraftStateSyncFilter: reject any per-request _meta/io.modelcontextprotocol/protocolVersion that is not in SupportedProtocolVersions with UnsupportedProtocolVersionException (-32004). The HTTP handler already validated the MCP-Protocol-Version header; this closes the corresponding gap for stdio/Stream and for HTTP bodies where the header is absent.

- HttpTaskIntegrationTests: Tasks pin per-session state into the in-memory store, so the tests require stateful HTTP. With Stateless=true the default after Phase 1, the tests would deadlock on the second request because the task ID wasn't visible to the new stateless server invocation. Opt back into stateful mode with WithHttpTransport(options => options.Stateless = false).

- New tests/ModelContextProtocol.Tests/Server/RawStreamConformanceTests.cs: drive McpServer directly via paired Pipe streams without going through McpClient. Hand-writes JSON-RPC messages and asserts on the exact bytes the server emits. Covers server/discover -> supportedVersions[], draft tools/call without initialize, -32004 with data.supported on unsupported version, legacy initialize on the same dual-era server, and a mixed Discover->Initialize->ToolsCall sequence.

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

Author: halter73

src/ModelContextProtocol.Core/Client/McpClientImpl.cs

@@ -686,27 +686,55 @@ public async Task ConnectAsync(CancellationToken cancellationToken = default)
                     DiscoverResult? discoverResult = null;
                     bool fallbackToLegacy = false;
                     IList<string>? serverSupportedVersions = null;
+
+                    // Apply a probe timeout so dual-era clients don't block forever waiting for a
+                    // legacy server that silently drops unknown methods (per stdio.mdx fallback rules).
+                    // The probe timeout is bounded by InitializationTimeout, but we cap it at 5s so we
+                    // can quickly fall back when a server isn't going to respond.
+                    var probeTimeout = TimeSpan.FromSeconds(5);
+                    using var probeCts = CancellationTokenSource.CreateLinkedTokenSource(initializationCts.Token);
+                    if (_options.InitializationTimeout > probeTimeout)
+                    {
+                        probeCts.CancelAfter(probeTimeout);
+                    }
+
                     try
                     {
                         discoverResult = await SendRequestAsync(
                             RequestMethods.ServerDiscover,
                             new DiscoverRequestParams(),
                             McpJsonUtilities.JsonContext.Default.DiscoverRequestParams,
                             McpJsonUtilities.JsonContext.Default.DiscoverResult,
-                            cancellationToken: initializationCts.Token).ConfigureAwait(false);
+                            cancellationToken: probeCts.Token).ConfigureAwait(false);
                     }
-                    catch (McpProtocolException ex) when (ex.ErrorCode == McpErrorCode.MethodNotFound)
+                    catch (UnsupportedProtocolVersionException ex)
                     {
-                        // Server doesn't implement server/discover (likely a legacy server). Fall back
-                        // to the legacy initialize handshake per SEP-2575 §"Supporting Multiple Versions".
+                        // Spec-recognized modern-server signal: -32004 with data.supported[]. The server is
+                        // modern but doesn't speak our preferred version. Retry with a mutually supported
+                        // version from data.supported[] instead of falling back to legacy initialize.
                         fallbackToLegacy = true;
+                        serverSupportedVersions = (IList<string>)ex.Supported;
                     }
-                    catch (UnsupportedProtocolVersionException ex)
+                    catch (MissingRequiredClientCapabilityException)
+                    {
+                        // Spec-recognized modern-server signal: -32003. The server is modern but rejected
+                        // our capability set. Surface as-is (no fallback): the user must add capabilities.
+                        throw;
+                    }
+                    catch (McpProtocolException)
                     {
-                        // Server rejected the experimental protocol version at the transport layer.
-                        // Per SEP-2575, fall back to a mutually-supported version reported in ex.Supported.
+                        // Any other JSON-RPC error from the probe indicates a legacy server (e.g.,
+                        // -32601 MethodNotFound, -32602 InvalidParams from a server confused by _meta,
+                        // -32700 ParseError from a server that can't handle our payload shape).
+                        // Per the spec's stdio fallback rules, treat all non-modern errors as a
+                        // legacy-server signal and fall back to the initialize handshake.
+                        fallbackToLegacy = true;
+                    }
+                    catch (OperationCanceledException) when (probeCts.IsCancellationRequested && !initializationCts.IsCancellationRequested)
+                    {
+                        // Probe timeout elapsed without a response. Per stdio.mdx fallback rules, no
+                        // response within a reasonable timeout means the server is legacy. Fall back.
                         fallbackToLegacy = true;
-                        serverSupportedVersions = (IList<string>)ex.Supported;
                     }
 
                     if (discoverResult is not null && !discoverResult.SupportedVersions.Contains(draftVersion))
@@ -730,6 +758,18 @@ public async Task ConnectAsync(CancellationToken cancellationToken = default)
                             .FirstOrDefault()
                             ?? McpSessionHandler.LatestProtocolVersion;
 
+                        // Honor MinProtocolVersion: refuse to fall back below the configured minimum.
+                        // String.Compare is the spec's prescribed ordering for ISO-8601 date-based versions.
+                        if (_options.MinProtocolVersion is { } minVersion &&
+                            StringComparer.Ordinal.Compare(fallbackVersion, minVersion) < 0)
+                        {
+                            throw new McpException(
+                                $"Server does not support the configured minimum protocol version '{minVersion}'. " +
+                                (serverSupportedVersions is null
+                                    ? "The server appears to be a legacy server that requires the deprecated initialize handshake."
+                                    : $"Server-supported versions: {string.Join(", ", serverSupportedVersions)}."));
+                        }
+
                         await PerformLegacyInitializeAsync(fallbackVersion, initializationCts.Token).ConfigureAwait(false);
                     }
                     else

src/ModelContextProtocol.Core/Client/McpClientOptions.cs

@@ -48,6 +48,37 @@ public sealed class McpClientOptions
     /// </remarks>
     public string? ProtocolVersion { get; set; }
 
+    /// <summary>
+    /// Gets or sets the minimum protocol version the client will accept during version negotiation.
+    /// </summary>
+    /// <remarks>
+    /// <para>
+    /// When negotiating with a server that advertises multiple supported versions, or when falling back
+    /// to a legacy server, the client will refuse any version older than this minimum and surface an
+    /// <see cref="McpException"/> instead.
+    /// </para>
+    /// <para>
+    /// This is useful when the client requires features (such as the draft revision's removal of the
+    /// <c>initialize</c> handshake or <c>Mcp-Session-Id</c>) that are not available in older protocol
+    /// revisions. Setting this to <see cref="McpSessionHandler.DraftProtocolVersion"/> disables the
+    /// automatic legacy-server fallback that otherwise switches to the <c>initialize</c> handshake.
+    /// </para>
+    /// <para>
+    /// If <see langword="null"/> (the default), the client falls back to any version the server
+    /// advertises, including legacy versions such as 2025-11-25.
+    /// </para>
+    /// <example>
+    /// <code>
+    /// var clientOptions = new McpClientOptions
+    /// {
+    ///     ProtocolVersion = McpSessionHandler.DraftProtocolVersion,
+    ///     MinProtocolVersion = McpSessionHandler.DraftProtocolVersion,
+    /// };
+    /// </code>
+    /// </example>
+    /// </remarks>
+    public string? MinProtocolVersion { get; set; }
+
     /// <summary>
     /// Gets or sets a timeout for the client-server initialization handshake sequence.
     /// </summary>

src/ModelContextProtocol.Core/Server/McpServerImpl.cs

@@ -172,7 +172,8 @@ private static JsonRpcMessageFilter ComposeFilters(JsonRpcMessageFilter outer, J
     /// <summary>
     /// Builds an incoming message filter that, for every JSON-RPC request, synchronizes server-side state
     /// (<see cref="_negotiatedProtocolVersion"/>, <see cref="_clientCapabilities"/>, <see cref="_clientInfo"/>)
-    /// from the per-request <c>_meta</c> values projected onto <see cref="JsonRpcMessageContext"/>.
+    /// from the per-request <c>_meta</c> values projected onto <see cref="JsonRpcMessageContext"/> and
+    /// validates the per-request protocol version.
     /// </summary>
     /// <remarks>
     /// Under the draft protocol revision (SEP-2575) there is no <c>initialize</c> handshake, so these values
@@ -187,11 +188,23 @@ private JsonRpcMessageFilter CreateDraftStateSyncFilter()
             {
                 bool endpointNameNeedsRefresh = false;
 
-                if (context.ProtocolVersion is { } protocolVersion &&
-                    !string.Equals(_negotiatedProtocolVersion, protocolVersion, StringComparison.Ordinal))
+                if (context.ProtocolVersion is { } protocolVersion)
                 {
-                    _negotiatedProtocolVersion = protocolVersion;
-                    _sessionHandler.NegotiatedProtocolVersion = protocolVersion;
+                    // Per SEP-2575, the server MUST reject any request whose per-request
+                    // _meta/io.modelcontextprotocol/protocolVersion is not one of its supported versions
+                    // with an UnsupportedProtocolVersionError (-32004) carrying the supported list.
+                    if (!McpSessionHandler.SupportedProtocolVersions.Contains(protocolVersion))
+                    {
+                        throw new UnsupportedProtocolVersionException(
+                            requested: protocolVersion,
+                            supported: McpSessionHandler.SupportedProtocolVersions);
+                    }
+
+                    if (!string.Equals(_negotiatedProtocolVersion, protocolVersion, StringComparison.Ordinal))
+                    {
+                        _negotiatedProtocolVersion = protocolVersion;
+                        _sessionHandler.NegotiatedProtocolVersion = protocolVersion;
+                    }
                 }
 
                 if (context.ClientCapabilities is { } clientCapabilities)

tests/ModelContextProtocol.AspNetCore.Tests/HttpTaskIntegrationTests.cs

@@ -48,7 +48,7 @@ public async Task CallToolAsTask_ReturnsTask_WhenServerSupportsTasksAsync()
         {
             options.TaskStore = taskStore;
         })
-        .WithHttpTransport()
+        .WithHttpTransport(options => options.Stateless = false)
         .WithTools<LongRunningTools>();
 
         await using var app = Builder.Build();
@@ -81,7 +81,7 @@ public async Task GetTaskAsync_ReturnsTaskStatus_WhenTaskExistsAsync()
         {
             options.TaskStore = taskStore;
         })
-        .WithHttpTransport()
+        .WithHttpTransport(options => options.Stateless = false)
         .WithTools<LongRunningTools>();
 
         await using var app = Builder.Build();
@@ -121,7 +121,7 @@ public async Task ListTasksAsync_ReturnsTasks_WhenTasksExistAsync()
         {
             options.TaskStore = taskStore;
         })
-        .WithHttpTransport()
+        .WithHttpTransport(options => options.Stateless = false)
         .WithTools<LongRunningTools>();
 
         await using var app = Builder.Build();
@@ -160,7 +160,7 @@ public async Task CancelTaskAsync_CancelsTask_WhenTaskIsRunningAsync()
         {
             options.TaskStore = taskStore;
         })
-        .WithHttpTransport()
+        .WithHttpTransport(options => options.Stateless = false)
         .WithTools<LongRunningTools>();
 
         await using var app = Builder.Build();
@@ -199,7 +199,7 @@ public async Task GetTaskResultAsync_ReturnsResult_WhenTaskCompletesAsync()
         {
             options.TaskStore = taskStore;
         })
-        .WithHttpTransport()
+        .WithHttpTransport(options => options.Stateless = false)
         .WithTools<LongRunningTools>();
 
         await using var app = Builder.Build();
@@ -240,7 +240,7 @@ public async Task TasksIsolated_BetweenSessions_WhenMultipleClientsConnectAsync(
         {
             options.TaskStore = taskStore;
         })
-        .WithHttpTransport()
+        .WithHttpTransport(options => options.Stateless = false)
         .WithTools<LongRunningTools>();
 
         await using var app = Builder.Build();
@@ -279,7 +279,7 @@ public async Task ServerCapabilities_IncludesTasks_WhenTaskStoreConfiguredAsync(
         {
             options.TaskStore = taskStore;
         })
-        .WithHttpTransport()
+        .WithHttpTransport(options => options.Stateless = false)
         .WithTools<LongRunningTools>();
 
         await using var app = Builder.Build();
@@ -302,7 +302,7 @@ public async Task ListTools_ShowsTaskSupport_WhenToolIsAsyncAsync()
         {
             options.TaskStore = taskStore;
         })
-        .WithHttpTransport()
+        .WithHttpTransport(options => options.Stateless = false)
         .WithTools<LongRunningTools>();
 
         await using var app = Builder.Build();
@@ -340,3 +340,4 @@ public static string SyncTool([Description("Input message")] string message)
         }
     }
 }
+