MCP stdio: negotiate initialize protocol version, default to 2025-11-25, return description in serverInfo, and add initialize wire-shape tests (#3622)

## Why make this change?

DAB MCP stdio always returned `2025-06-18` in `initialize`, even when
clients requested newer protocol versions, causing modern MCP clients
(e.g., Claude Code 2.x) to disconnect.
This update aligns initialize negotiation behavior with MCP version
selection expectations, updates the default supported version to
`2025-11-25`, aligns initialize metadata shape for newer protocol
versions, and adds focused wiring tests to lock down the initialize
response wire format end-to-end.

## What is this change?

- **Protocol default**
- Bumped MCP default protocol from `2025-06-18` to `2025-11-25` in
`McpProtocolDefaults`.

- **Initialize version negotiation**
- `initialize` now reads `params.protocolVersion` from the client
request.
- Server responds with the greatest supported version `<=` client
requested (never higher than the client).

- **Initialize metadata field shape by negotiated protocol**
- For negotiated protocol versions `>= 2025-11-25`, runtime MCP
description is returned as `serverInfo.description`.
- For older negotiated protocol versions, description remains top-level
`instructions` for backward compatibility.

- **Negotiation utility + parsing behavior**
  - Added centralized negotiation helper in `McpProtocolDefaults`.
- Compares date-formatted versions (`yyyy-MM-dd`) with ordinal string
fallback for non-date values.
- Added protocol-threshold helper for choosing `serverInfo.description`
vs `instructions`.

- **Focused test coverage**
  - Added helper unit tests for:
    - new default protocol value,
    - client newer than server (server version returned),
    - client older than server (client version returned),
    - missing client version,
    - non-date fallback comparison path,
    - protocol threshold behavior for `serverInfo.description`.
- Added focused initialize wiring tests for `HandleInitialize` that
validate:
    - JSON-RPC envelope shape (`jsonrpc`, `id`),
    - negotiated `result.protocolVersion`,
    - capabilities shape,
- field placement across protocol/description scenarios
(`serverInfo.description` vs `instructions` vs neither).

```csharp
string negotiatedProtocolVersion =
    McpProtocolDefaults.ResolveInitializeResponseProtocolVersion(
        _protocolVersion,
        clientRequestedProtocolVersion);
```

## How was this tested?

- [ ] Integration Tests
- [x] Unit Tests

## Sample Request(s)

- Example CLI usage:
  - `dab start --mcp-stdio`

- Example initialize request:
```json
{"jsonrpc":"2.0","method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"claude-code","version":"2.1.98"}},"id":1}
```

- Example initialize response behavior for negotiated `2025-11-25`:
```json
{"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2025-11-25","capabilities":{"tools":{"listChanged":true},"logging":{}},"serverInfo":{"name":"SQL MCP Server","version":"<dab-version>","description":"<mcp-runtime-description>"}}}
```

- Example initialize response behavior for negotiated older versions:
```json
{"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2025-06-18","capabilities":{"tools":{"listChanged":true},"logging":{}},"serverInfo":{"name":"SQL MCP Server","version":"<dab-version>"},"instructions":"<mcp-runtime-description>"}}
```

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: Aniruddh25 <3513779+Aniruddh25@users.noreply.github.com>
Co-authored-by: Aniruddh Munde <anmunde@microsoft.com>
Co-authored-by: aaronburtle <93220300+aaronburtle@users.noreply.github.com>

Author: 3 people

src/Azure.DataApiBuilder.Mcp/Core/McpProtocolDefaults.cs

@@ -1,3 +1,4 @@
+using System.Globalization;
 using Azure.DataApiBuilder.Product;
 using Microsoft.Extensions.Configuration;
 
@@ -19,13 +20,18 @@ public static class McpProtocolDefaults
         /// <summary>
         /// Default MCP protocol version advertised when no configuration override is provided.
         /// </summary>
-        public const string DEFAULT_PROTOCOL_VERSION = "2025-06-18";
+        public const string DEFAULT_PROTOCOL_VERSION = "2025-11-25";
 
         /// <summary>
         /// Configuration key used to override the MCP protocol version.
         /// </summary>
         public const string PROTOCOL_VERSION_CONFIG_KEY = "MCP:ProtocolVersion";
 
+        /// <summary>
+        /// Protocol version where MCP initialize server description is expected under serverInfo.description.
+        /// </summary>
+        public const string SERVER_INFO_DESCRIPTION_PROTOCOL_VERSION = "2025-11-25";
+
         /// <summary>
         /// Helper to resolve the effective protocol version from configuration.
         /// Falls back to <see cref="DEFAULT_PROTOCOL_VERSION"/> when the key is not set.
@@ -34,6 +40,44 @@ public static string ResolveProtocolVersion(IConfiguration? configuration)
         {
             return configuration?.GetValue<string>(PROTOCOL_VERSION_CONFIG_KEY) ?? DEFAULT_PROTOCOL_VERSION;
         }
+
+        /// <summary>
+        /// Resolves the protocol version to send in initialize response as the
+        /// greatest version that does not exceed the client requested version.
+        /// </summary>
+        /// <param name="supportedProtocolVersion">The server's effective supported protocol version.</param>
+        /// <param name="clientRequestedProtocolVersion">The protocol version requested by the client.</param>
+        /// <returns>The protocol version to return to the client.</returns>
+        public static string ResolveInitializeResponseProtocolVersion(string supportedProtocolVersion, string? clientRequestedProtocolVersion)
+        {
+            if (string.IsNullOrWhiteSpace(clientRequestedProtocolVersion))
+            {
+                return supportedProtocolVersion;
+            }
+
+            return CompareProtocolVersions(supportedProtocolVersion, clientRequestedProtocolVersion) <= 0
+                ? supportedProtocolVersion
+                : clientRequestedProtocolVersion;
+        }
+
+        /// <summary>
+        /// Indicates whether initialize response metadata should use serverInfo.description instead of top-level instructions.
+        /// </summary>
+        public static bool ShouldUseServerInfoDescription(string protocolVersion)
+        {
+            return CompareProtocolVersions(protocolVersion, SERVER_INFO_DESCRIPTION_PROTOCOL_VERSION) >= 0;
+        }
+
+        private static int CompareProtocolVersions(string leftVersion, string rightVersion)
+        {
+            const string PROTOCOL_VERSION_DATE_FORMAT = "yyyy-MM-dd";
+            if (DateOnly.TryParseExact(leftVersion, PROTOCOL_VERSION_DATE_FORMAT, CultureInfo.InvariantCulture, DateTimeStyles.None, out DateOnly leftDate) &&
+                DateOnly.TryParseExact(rightVersion, PROTOCOL_VERSION_DATE_FORMAT, CultureInfo.InvariantCulture, DateTimeStyles.None, out DateOnly rightDate))
+            {
+                return leftDate.CompareTo(rightDate);
+            }
+
+            return string.Compare(leftVersion, rightVersion, StringComparison.Ordinal);
+        }
     }
 }
-

src/Azure.DataApiBuilder.Mcp/Core/McpStdioServer.cs

@@ -122,7 +122,7 @@ public async Task RunAsync(CancellationToken cancellationToken)
                         switch (method)
                         {
                             case "initialize":
-                                HandleInitialize(id);
+                                HandleInitialize(id, root);
                                 break;
 
                             case "notifications/initialized":
@@ -167,22 +167,27 @@ public async Task RunAsync(CancellationToken cancellationToken)
         /// <param name="id">
         /// The request identifier extracted from the incoming JSON-RPC request. Used to correlate the response with the request.
         /// </param>
+        /// <param name="root">The incoming initialize request payload.</param>
         /// <remarks>
-        /// This method constructs and writes the MCP "initialize" response to STDOUT. It uses the protocol version defined by <c>PROTOCOL_VERSION</c>
-        /// and includes supported capabilities and server information. No notifications are sent here; the server waits for the client to send
-        /// "notifications/initialized" before sending any notifications.
+        /// This method constructs and writes the MCP "initialize" response to STDOUT. It negotiates the response protocol version from the
+        /// server-supported version and client-requested version, and includes supported capabilities and server information. No notifications
+        /// are sent here; the server waits for the client to send "notifications/initialized" before sending any notifications.
         /// </remarks>
-        private void HandleInitialize(JsonElement? id)
+        private void HandleInitialize(JsonElement? id, JsonElement root)
         {
+            string? clientRequestedProtocolVersion = GetClientProtocolVersion(root);
+            string negotiatedProtocolVersion =
+                McpProtocolDefaults.ResolveInitializeResponseProtocolVersion(_protocolVersion, clientRequestedProtocolVersion);
+
             // Get the description from runtime config if available
-            string? instructions = null;
+            string? description = null;
             RuntimeConfigProvider? runtimeConfigProvider = _serviceProvider.GetService<RuntimeConfigProvider>();
             if (runtimeConfigProvider != null)
             {
                 try
                 {
                     RuntimeConfig runtimeConfig = runtimeConfigProvider.GetConfig();
-                    instructions = runtimeConfig.Runtime?.Mcp?.Description;
+                    description = runtimeConfig.Runtime?.Mcp?.Description;
                 }
                 catch (Exception)
                 {
@@ -191,13 +196,33 @@ private void HandleInitialize(JsonElement? id)
                 }
             }
 
-            // Create the initialize response - only include instructions if non-empty
+            bool shouldUseServerInfoDescription = McpProtocolDefaults.ShouldUseServerInfoDescription(negotiatedProtocolVersion);
+
+            // Create the initialize response - only include description/instructions if non-empty
             object result;
-            if (!string.IsNullOrWhiteSpace(instructions))
+            if (!string.IsNullOrWhiteSpace(description) && shouldUseServerInfoDescription)
             {
                 result = new
                 {
-                    protocolVersion = _protocolVersion,
+                    protocolVersion = negotiatedProtocolVersion,
+                    capabilities = new
+                    {
+                        tools = new { listChanged = true },
+                        logging = new { }
+                    },
+                    serverInfo = new
+                    {
+                        name = McpProtocolDefaults.MCP_SERVER_NAME,
+                        version = McpProtocolDefaults.MCP_SERVER_VERSION,
+                        description = description
+                    }
+                };
+            }
+            else if (!string.IsNullOrWhiteSpace(description))
+            {
+                result = new
+                {
+                    protocolVersion = negotiatedProtocolVersion,
                     capabilities = new
                     {
                         tools = new { listChanged = true },
@@ -208,14 +233,14 @@ private void HandleInitialize(JsonElement? id)
                         name = McpProtocolDefaults.MCP_SERVER_NAME,
                         version = McpProtocolDefaults.MCP_SERVER_VERSION
                     },
-                    instructions = instructions
+                    instructions = description
                 };
             }
             else
             {
                 result = new
                 {
-                    protocolVersion = _protocolVersion,
+                    protocolVersion = negotiatedProtocolVersion,
                     capabilities = new
                     {
                         tools = new { listChanged = true },
@@ -232,6 +257,22 @@ private void HandleInitialize(JsonElement? id)
             WriteResult(id, result);
         }
 
+        private static string? GetClientProtocolVersion(JsonElement root)
+        {
+            if (!root.TryGetProperty("params", out JsonElement paramsElement) || paramsElement.ValueKind != JsonValueKind.Object)
+            {
+                return null;
+            }
+
+            if (!paramsElement.TryGetProperty("protocolVersion", out JsonElement protocolVersionElement) ||
+                protocolVersionElement.ValueKind != JsonValueKind.String)
+            {
+                return null;
+            }
+
+            return protocolVersionElement.GetString();
+        }
+
         /// <summary>
         /// Handles the "tools/list" JSON-RPC method by sending the list of available tools to the client.
         /// </summary>

src/Service.Tests/UnitTests/McpProtocolDefaultsTests.cs

@@ -0,0 +1,54 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+using Azure.DataApiBuilder.Mcp.Core;
+using Microsoft.Extensions.Configuration;
+using Microsoft.VisualStudio.TestTools.UnitTesting;
+
+namespace Azure.DataApiBuilder.Service.Tests.UnitTests
+{
+    [TestClass]
+    public class McpProtocolDefaultsTests
+    {
+        [TestMethod]
+        public void ResolveProtocolVersion_WithoutOverride_UsesLatestDefault()
+        {
+            IConfiguration config = new ConfigurationBuilder().Build();
+
+            string resolved = McpProtocolDefaults.ResolveProtocolVersion(config);
+
+            Assert.AreEqual("2025-11-25", resolved);
+        }
+
+        [DataTestMethod]
+        [DataRow("2025-11-25", "2026-01-01", "2025-11-25")]
+        [DataRow("2025-11-25", "2025-06-18", "2025-06-18")]
+        [DataRow("2025-11-25", "2025-11-25", "2025-11-25")]
+        [DataRow("2025-11-25", null, "2025-11-25")]
+        [DataRow("a-version", "z-version", "a-version")]
+        public void ResolveInitializeResponseProtocolVersion_ReturnsExpectedNegotiatedVersion(
+            string supportedProtocolVersion,
+            string clientRequestedProtocolVersion,
+            string expectedVersion)
+        {
+            string resolved = McpProtocolDefaults.ResolveInitializeResponseProtocolVersion(
+                supportedProtocolVersion,
+                clientRequestedProtocolVersion);
+
+            Assert.AreEqual(expectedVersion, resolved);
+        }
+
+        [TestMethod]
+        public void ShouldUseServerInfoDescription_AtOrAboveThreshold_ReturnsTrue()
+        {
+            Assert.IsTrue(McpProtocolDefaults.ShouldUseServerInfoDescription("2025-11-25"));
+            Assert.IsTrue(McpProtocolDefaults.ShouldUseServerInfoDescription("2025-12-01"));
+        }
+
+        [TestMethod]
+        public void ShouldUseServerInfoDescription_BelowThreshold_ReturnsFalse()
+        {
+            Assert.IsFalse(McpProtocolDefaults.ShouldUseServerInfoDescription("2025-06-18"));
+        }
+    }
+}