Cherry pick MCP stdio: negotiate initialize protocol version, default to 2025-11-25, return description in serverInfo, and add initialize wire-shape tests #3622#3627
Open
aaronburtle wants to merge 1 commit into
Conversation
…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> (cherry picked from commit 7f4a34d)
aaronburtle
requested review from
Alekhya-Polavarapu,
Aniruddh25,
JerryNixon,
RubenCerna2079,
anushakolan,
rusamant,
sourabh1007,
souvikghosh04,
stuartpa and
vadeveka
as code owners
Contributor
There was a problem hiding this comment.
Pull request overview
This PR cherry-picks the MCP stdio “initialize” protocol negotiation improvements needed for 2.0 compatibility with newer MCP clients by negotiating the initialize protocol version, updating the default protocol version, and adjusting where runtime description is emitted based on negotiated protocol.
Changes:
- Bump the default MCP protocol version to
2025-11-25and add centralized helpers for initialize protocol negotiation and description field placement. - Update MCP stdio
initializehandling to negotiate the response protocol version from client request + server support and emit description asserverInfo.descriptionfor newer protocols (orinstructionsfor legacy). - Add focused unit tests validating protocol negotiation helpers and end-to-end initialize wire shape behavior.
Reviewed changes
Copilot reviewed 4 out of 4 changed files in this pull request and generated no comments.
| File | Description |
|---|---|
| src/Azure.DataApiBuilder.Mcp/Core/McpProtocolDefaults.cs | Updates default protocol version and adds helpers for version negotiation + description placement threshold. |
| src/Azure.DataApiBuilder.Mcp/Core/McpStdioServer.cs | Negotiates initialize protocol version using client request and moves description to serverInfo.description for newer protocols. |
| src/Service.Tests/UnitTests/McpProtocolDefaultsTests.cs | Adds unit tests for default protocol, negotiation behavior, and description-threshold helper. |
| src/Service.Tests/UnitTests/McpStdioServerInitializeTests.cs | Adds initialize “wire-shape” tests validating negotiated protocolVersion and description field placement. |
Aniruddh25
approved these changes
May 21, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why make this change?
Closes #3626
What is this change?
Cherry picks this PR: #3622
How was this tested?
Built locally and passes normal test suite.