Add draft-mode tests and update XML docs

Adds round-trip tests for the new draft protocol revision and updates the XML
documentation on ExperimentalProtocolVersion (client + server) to describe the
full SEP-2575 + SEP-2567 behavior (sessionless, handshake-less, server/discover,
MRTR-only server-to-client interactions, fallback to legacy initialize on
unsupported-version responses).

Tests added:
- DiscoverProtocolTests / SubscriptionsListenProtocolTests / DraftErrorDataTests:
  JSON-serialization round-trip coverage for the new protocol types and error
  data payloads.
- DraftConnectionTests: end-to-end client/server connection flow for draft
  client vs. draft server, draft client vs. legacy server (fallback), legacy
  client vs. draft server, and explicit server/discover invocation.
- DraftHttpHandlerTests (AspNetCore): HTTP-level checks that draft requests
  don't emit Mcp-Session-Id, unsupported protocol versions return -32004 with
  the structured supportedVersions payload, draft requests carrying an
  Mcp-Session-Id route through the legacy lookup, and draft GET/DELETE are
  rejected.

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

Author: halter73

tests/ModelContextProtocol.AspNetCore.Tests/DraftHttpHandlerTests.cs

@@ -0,0 +1,139 @@
+using Microsoft.AspNetCore.Builder;
+using Microsoft.Extensions.DependencyInjection;
+using ModelContextProtocol.AspNetCore.Tests.Utils;
+using ModelContextProtocol.Protocol;
+using System.Net;
+using System.Text;
+using System.Text.Json;
+
+namespace ModelContextProtocol.AspNetCore.Tests;
+
+/// <summary>
+/// HTTP-level tests for the draft protocol revision (SEP-2575 + SEP-2567): verify that the server
+/// suppresses the <c>Mcp-Session-Id</c> header for draft requests and returns structured
+/// <see cref="McpErrorCode.UnsupportedProtocolVersion"/> errors instead of plain 400s.
+/// </summary>
+public class DraftHttpHandlerTests(ITestOutputHelper outputHelper) : KestrelInMemoryTest(outputHelper), IAsyncDisposable
+{
+    private const string DraftVersion = "2026-06-XX";
+
+    private WebApplication? _app;
+
+    private async Task StartAsync(bool experimentalServer)
+    {
+#pragma warning disable MCPEXP001 // ExperimentalProtocolVersion is experimental
+        Builder.Services.AddMcpServer(options =>
+        {
+            options.ServerInfo = new Implementation { Name = nameof(DraftHttpHandlerTests), Version = "1" };
+            if (experimentalServer)
+            {
+                options.ExperimentalProtocolVersion = DraftVersion;
+            }
+        }).WithHttpTransport();
+#pragma warning restore MCPEXP001
+
+        _app = Builder.Build();
+        _app.MapMcp();
+        await _app.StartAsync(TestContext.Current.CancellationToken);
+
+        HttpClient.DefaultRequestHeaders.Accept.Add(new("application/json"));
+        HttpClient.DefaultRequestHeaders.Accept.Add(new("text/event-stream"));
+    }
+
+    public async ValueTask DisposeAsync()
+    {
+        if (_app is not null)
+        {
+            await _app.DisposeAsync();
+        }
+        base.Dispose();
+    }
+
+    [Fact]
+    public async Task DraftRequest_DoesNotEmitMcpSessionIdHeader()
+    {
+        await StartAsync(experimentalServer: true);
+
+        HttpClient.DefaultRequestHeaders.Add("MCP-Protocol-Version", DraftVersion);
+
+        // server/discover should succeed without creating a session.
+        var content = new StringContent(
+            """{"jsonrpc":"2.0","id":1,"method":"server/discover","params":{}}""",
+            Encoding.UTF8, "application/json");
+        using var response = await HttpClient.PostAsync("", content, TestContext.Current.CancellationToken);
+
+        Assert.Equal(HttpStatusCode.OK, response.StatusCode);
+        Assert.False(response.Headers.Contains("Mcp-Session-Id"), "Draft responses must not include Mcp-Session-Id");
+    }
+
+    [Fact]
+    public async Task RequestWithUnsupportedProtocolVersion_Returns_UnsupportedProtocolVersionError()
+    {
+        await StartAsync(experimentalServer: false);
+
+        HttpClient.DefaultRequestHeaders.Add("MCP-Protocol-Version", "2099-12-31");
+
+        var content = new StringContent(
+            """{"jsonrpc":"2.0","id":1,"method":"server/discover","params":{}}""",
+            Encoding.UTF8, "application/json");
+        using var response = await HttpClient.PostAsync("", content, TestContext.Current.CancellationToken);
+
+        Assert.Equal(HttpStatusCode.BadRequest, response.StatusCode);
+
+        var body = await response.Content.ReadAsStringAsync(TestContext.Current.CancellationToken);
+        var rpcMessage = JsonSerializer.Deserialize<JsonRpcMessage>(body, McpJsonUtilities.DefaultOptions);
+        var rpcError = Assert.IsType<JsonRpcError>(rpcMessage);
+        Assert.Equal((int)McpErrorCode.UnsupportedProtocolVersion, rpcError.Error.Code);
+
+        // Validate the structured data payload (SEP-2575 §"Unsupported Protocol Versions").
+        var dataElement = (JsonElement)rpcError.Error.Data!;
+        var errorData = dataElement.Deserialize<UnsupportedProtocolVersionErrorData>(McpJsonUtilities.DefaultOptions);
+        Assert.NotNull(errorData);
+        Assert.Equal("2099-12-31", errorData.Requested);
+        Assert.NotEmpty(errorData.Supported);
+    }
+
+    [Fact]
+    public async Task DraftRequest_WithMcpSessionIdHeader_RoutesThroughLegacyPath()
+    {
+        // For back-compat with clients that opted into the experimental version on top of the legacy
+        // stateful session model (MRTR-as-extension-on-initialize), draft-version requests that DO
+        // include an Mcp-Session-Id are still accepted via the legacy session lookup path.
+        await StartAsync(experimentalServer: true);
+
+        HttpClient.DefaultRequestHeaders.Add("MCP-Protocol-Version", DraftVersion);
+        HttpClient.DefaultRequestHeaders.Add("Mcp-Session-Id", "non-existent-session-id");
+
+        var content = new StringContent(
+            """{"jsonrpc":"2.0","id":1,"method":"server/discover","params":{}}""",
+            Encoding.UTF8, "application/json");
+        using var response = await HttpClient.PostAsync("", content, TestContext.Current.CancellationToken);
+
+        // Legacy path returns 404 for unknown sessions.
+        Assert.Equal(HttpStatusCode.NotFound, response.StatusCode);
+    }
+
+    [Fact]
+    public async Task DraftGet_WithoutSessionId_IsRejected()
+    {
+        await StartAsync(experimentalServer: true);
+
+        HttpClient.DefaultRequestHeaders.Add("MCP-Protocol-Version", DraftVersion);
+
+        using var response = await HttpClient.GetAsync("", TestContext.Current.CancellationToken);
+
+        Assert.Equal(HttpStatusCode.BadRequest, response.StatusCode);
+    }
+
+    [Fact]
+    public async Task DraftDelete_WithoutSessionId_IsRejected()
+    {
+        await StartAsync(experimentalServer: true);
+
+        HttpClient.DefaultRequestHeaders.Add("MCP-Protocol-Version", DraftVersion);
+
+        using var response = await HttpClient.DeleteAsync("", TestContext.Current.CancellationToken);
+
+        Assert.Equal(HttpStatusCode.BadRequest, response.StatusCode);
+    }
+}

tests/ModelContextProtocol.Tests/Client/DraftConnectionTests.cs

@@ -0,0 +1,116 @@
+using Microsoft.Extensions.DependencyInjection;
+using ModelContextProtocol.Client;
+using ModelContextProtocol.Protocol;
+using ModelContextProtocol.Server;
+using System.Text.Json;
+
+namespace ModelContextProtocol.Tests.Client;
+
+/// <summary>
+/// Tests for the draft protocol revision (SEP-2575 + SEP-2567) connection flow on
+/// <see cref="McpClient"/> — the client should call <c>server/discover</c> instead of
+/// <c>initialize</c> when <see cref="McpClientOptions.ExperimentalProtocolVersion"/> is set and
+/// the server supports the requested version, and it should fall back to the legacy
+/// <c>initialize</c> handshake otherwise.
+/// </summary>
+#pragma warning disable MCPEXP002 // ExperimentalProtocolVersion
+public class DraftConnectionTests : ClientServerTestBase
+{
+    private const string DraftVersion = "2026-06-XX";
+    private const string LatestStableVersion = "2025-11-25";
+
+    private bool _serverHasExperimental;
+
+    public DraftConnectionTests(ITestOutputHelper testOutputHelper)
+        : base(testOutputHelper, startServer: false)
+    {
+    }
+
+    protected override void ConfigureServices(ServiceCollection services, IMcpServerBuilder mcpServerBuilder)
+    {
+        services.Configure<McpServerOptions>(options =>
+        {
+            options.ServerInfo = new Implementation { Name = nameof(DraftConnectionTests), Version = "1.0" };
+            if (_serverHasExperimental)
+            {
+                options.ExperimentalProtocolVersion = DraftVersion;
+            }
+        });
+    }
+
+    [Fact]
+    public async Task DraftClient_ConnectingToDraftServer_NegotiatesExperimentalVersion()
+    {
+        _serverHasExperimental = true;
+        StartServer();
+
+        var options = new McpClientOptions { ExperimentalProtocolVersion = DraftVersion };
+        await using var client = await CreateMcpClientForServer(options);
+
+        Assert.Equal(DraftVersion, client.NegotiatedProtocolVersion);
+        Assert.NotNull(client.ServerCapabilities);
+        Assert.Equal(nameof(DraftConnectionTests), client.ServerInfo.Name);
+    }
+
+    [Fact]
+    public async Task DraftClient_ConnectingToLegacyServer_FallsBackToLegacyInitialize()
+    {
+        _serverHasExperimental = false;
+        StartServer();
+
+        var options = new McpClientOptions { ExperimentalProtocolVersion = DraftVersion };
+        await using var client = await CreateMcpClientForServer(options);
+
+        Assert.NotEqual(DraftVersion, client.NegotiatedProtocolVersion);
+        Assert.Equal(LatestStableVersion, client.NegotiatedProtocolVersion);
+    }
+
+    [Fact]
+    public async Task LegacyClient_ConnectingToDraftServer_NegotiatesLegacyVersion()
+    {
+        _serverHasExperimental = true;
+        StartServer();
+
+        await using var client = await CreateMcpClientForServer();
+
+        Assert.NotEqual(DraftVersion, client.NegotiatedProtocolVersion);
+    }
+
+    [Fact]
+    public async Task LegacyClient_CanCallServerDiscover_EvenWithoutDraftConfigured()
+    {
+        // server/discover is registered unconditionally, so a legacy client can probe it
+        // (e.g., to learn capabilities without doing a second initialize).
+        _serverHasExperimental = false;
+        StartServer();
+
+        await using var client = await CreateMcpClientForServer();
+
+        var response = await client.SendRequestAsync(
+            new JsonRpcRequest { Method = RequestMethods.ServerDiscover },
+            TestContext.Current.CancellationToken);
+
+        var discoverResult = JsonSerializer.Deserialize<DiscoverResult>(response.Result, McpJsonUtilities.DefaultOptions);
+        Assert.NotNull(discoverResult);
+        Assert.NotEmpty(discoverResult.SupportedVersions);
+        Assert.Contains(LatestStableVersion, discoverResult.SupportedVersions);
+        Assert.Equal(nameof(DraftConnectionTests), discoverResult.ServerInfo.Name);
+    }
+
+    [Fact]
+    public async Task DraftServer_DiscoverIncludesExperimentalVersion()
+    {
+        _serverHasExperimental = true;
+        StartServer();
+
+        await using var client = await CreateMcpClientForServer();
+
+        var response = await client.SendRequestAsync(
+            new JsonRpcRequest { Method = RequestMethods.ServerDiscover },
+            TestContext.Current.CancellationToken);
+
+        var discoverResult = JsonSerializer.Deserialize<DiscoverResult>(response.Result, McpJsonUtilities.DefaultOptions);
+        Assert.NotNull(discoverResult);
+        Assert.Contains(DraftVersion, discoverResult.SupportedVersions);
+    }
+}

tests/ModelContextProtocol.Tests/Protocol/DiscoverProtocolTests.cs

@@ -0,0 +1,80 @@
+using ModelContextProtocol.Protocol;
+using System.Text.Json;
+using System.Text.Json.Nodes;
+
+namespace ModelContextProtocol.Tests.Protocol;
+
+/// <summary>
+/// Serialization tests for the request/result types introduced by the draft protocol revision (SEP-2575).
+/// </summary>
+public static class DiscoverProtocolTests
+{
+    [Fact]
+    public static void DiscoverRequestParams_SerializationRoundTrip_WithMeta()
+    {
+        var original = new DiscoverRequestParams
+        {
+            Meta = new JsonObject
+            {
+                [NotificationMethods.ProtocolVersionMetaKey] = "2026-06-XX",
+                [NotificationMethods.ClientInfoMetaKey] = new JsonObject
+                {
+                    ["name"] = "test-client",
+                    ["version"] = "1.0",
+                },
+                [NotificationMethods.ClientCapabilitiesMetaKey] = new JsonObject(),
+            },
+        };
+
+        var json = JsonSerializer.Serialize(original, McpJsonUtilities.DefaultOptions);
+        var deserialized = JsonSerializer.Deserialize<DiscoverRequestParams>(json, McpJsonUtilities.DefaultOptions);
+
+        Assert.NotNull(deserialized);
+        Assert.NotNull(deserialized.Meta);
+        Assert.Equal("2026-06-XX", (string)deserialized.Meta[NotificationMethods.ProtocolVersionMetaKey]!);
+    }
+
+    [Fact]
+    public static void DiscoverResult_SerializationRoundTrip_PreservesAllProperties()
+    {
+        var original = new DiscoverResult
+        {
+            SupportedVersions = new List<string> { "2025-11-25", "2026-06-XX" },
+            Capabilities = new ServerCapabilities
+            {
+                Tools = new ToolsCapability { ListChanged = true },
+            },
+            ServerInfo = new Implementation { Name = "test-server", Version = "2.0" },
+            Instructions = "Use this server for testing.",
+        };
+
+        var json = JsonSerializer.Serialize(original, McpJsonUtilities.DefaultOptions);
+        var deserialized = JsonSerializer.Deserialize<DiscoverResult>(json, McpJsonUtilities.DefaultOptions);
+
+        Assert.NotNull(deserialized);
+        Assert.Equal(["2025-11-25", "2026-06-XX"], deserialized.SupportedVersions);
+        Assert.NotNull(deserialized.Capabilities.Tools);
+        Assert.True(deserialized.Capabilities.Tools.ListChanged);
+        Assert.Equal("test-server", deserialized.ServerInfo.Name);
+        Assert.Equal("Use this server for testing.", deserialized.Instructions);
+    }
+
+    [Fact]
+    public static void DiscoverResult_SerializationRoundTrip_WithMinimalProperties()
+    {
+        var original = new DiscoverResult
+        {
+            SupportedVersions = new List<string> { "2026-06-XX" },
+            Capabilities = new ServerCapabilities(),
+            ServerInfo = new Implementation { Name = "minimal-server", Version = "1.0" },
+        };
+
+        var json = JsonSerializer.Serialize(original, McpJsonUtilities.DefaultOptions);
+        var deserialized = JsonSerializer.Deserialize<DiscoverResult>(json, McpJsonUtilities.DefaultOptions);
+
+        Assert.NotNull(deserialized);
+        Assert.Single(deserialized.SupportedVersions);
+        Assert.Equal("2026-06-XX", deserialized.SupportedVersions[0]);
+        Assert.Null(deserialized.Instructions);
+    }
+}