Surface HeaderMismatch errors instead of falling back to legacy

McpClientImpl.ConnectAsync's draft probe path catches McpProtocolException to
fall back to a legacy `initialize` exchange. The handler had passthrough
cases for the two modern draft error codes whose semantics are not ""I'm a
legacy server"" (UnsupportedProtocolVersion -32004 and
MissingRequiredClientCapability -32003) but was missing the third:
HeaderMismatch -32001 from SEP-2243. That code means the body's
`_meta.io.modelcontextprotocol/protocolVersion` does not match the
`MCP-Protocol-Version` HTTP header — which is a client-side bug that should
surface to the caller, not a signal to retry with `initialize`.

Add the third passthrough so all three modern draft codes propagate, with an
in-memory transport regression test that exercises the path against a server
which only returns `-32001`.

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

Author: halter73

src/ModelContextProtocol.Core/Client/McpClientImpl.cs

@@ -340,16 +340,25 @@ public async Task ConnectAsync(CancellationToken cancellationToken = default)
                         // our capability set. Surface as-is (no fallback): the user must add capabilities.
                         throw;
                     }
+                    catch (McpProtocolException ex) when (ex.ErrorCode == McpErrorCode.HeaderMismatch)
+                    {
+                        // Spec-recognized modern-server signal: -32001. The server is modern but rejected
+                        // our request envelope (e.g., the MCP-Protocol-Version HTTP header didn't match
+                        // the body _meta.io.modelcontextprotocol/protocolVersion). Surface as-is (no
+                        // fallback): falling back to legacy initialize wouldn't fix a malformed envelope.
+                        throw;
+                    }
                     catch (McpProtocolException)
                     {
                         // Per spec PR #2844, the fallback MUST NOT be keyed to a single error code —
                         // any non-modern JSON-RPC error from the probe indicates a legacy server.
                         // Common causes include MethodNotFound from a server that has no
                         // server/discover handler, InvalidParams from a server confused by the
                         // SEP-2575 _meta envelope, ParseError from a server that can't handle our
-                        // payload shape, or any other transport-defined error. The two modern-server
+                        // payload shape, or any other transport-defined error. The three modern-server
                         // signals (-32004 UnsupportedProtocolVersion, -32003
-                        // MissingRequiredClientCapability) are caught above and never reach here.
+                        // MissingRequiredClientCapability, -32001 HeaderMismatch) are caught above and
+                        // never reach here.
                         fallbackToLegacy = true;
                     }
                     catch (OperationCanceledException) when (probeCts.IsCancellationRequested && !initializationCts.IsCancellationRequested)

tests/ModelContextProtocol.Tests/Client/DraftProtocolFallbackTests.cs

@@ -96,6 +96,30 @@ public async Task LegacyClient_WithExplicitPin_StillRequires_ExactVersionMatch()
         Assert.Contains("mismatch", exception.Message, StringComparison.OrdinalIgnoreCase);
     }
 
+    [Fact]
+    public async Task DraftClient_OnHeaderMismatch_Surfaces_NoFallback()
+    {
+        // The peer is modern (returns the spec-defined -32001 HeaderMismatch on the probe).
+        // Falling back to legacy initialize would just produce another malformed envelope.
+        // Verify the connect-time logic surfaces the error to the caller instead of falling back.
+        var ct = TestContext.Current.CancellationToken;
+        await using var transport = new LegacyServerTestTransport(
+            serverNegotiatedVersion: "2025-11-25",
+            probeErrorCode: (int)McpErrorCode.HeaderMismatch);
+
+        var exception = await Assert.ThrowsAnyAsync<McpException>(async () =>
+        {
+            await using var client = await McpClient.CreateAsync(transport, new McpClientOptions
+            {
+                ProtocolVersion = McpSession.DraftProtocolVersion,
+            }, loggerFactory: LoggerFactory, cancellationToken: ct);
+        });
+
+        Assert.True(transport.ServerDiscoverProbed);
+        Assert.False(transport.LegacyInitializeReceived);
+        Assert.Equal(McpErrorCode.HeaderMismatch, ((McpProtocolException)exception).ErrorCode);
+    }
+
     /// <summary>
     /// Minimal in-memory transport that simulates a legacy server: rejects
     /// <c>server/discover</c> (with a configurable JSON-RPC error code) and