Add mcp-stateless module: migrate an MCP server from the 2025 stateful protocol to 2026-07-28 on Spring AI 2.1.0

Co-Authored-By: Claude Sonnet 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017ic4b4tJPXfq5UyiLSFr49
This commit is contained in:
Ankur
2026-11-22 02:18:48 +05:30
co-authored by Claude Sonnet 5.5
parent 3aa20a1dce
commit 26e0a3875a
34 changed files with 1922 additions and 0 deletions
@@ -0,0 +1,44 @@
# 2025-era server (protocol STREAMABLE): the session lives in the server's memory
# Error bodies are shown without the Java stack trace the SDK serialises into them.
## 1. tools/call with no session yet
> POST /mcp
> {"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"order_status","arguments":{"orderId":"A-101"}}}
< 400
< Content-Type: application/json
< {"jsonRpcError":{"code":-32601,"message":"Session ID missing"}}
## 2. initialize
> POST /mcp
> {"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"wire-test","version":"1"}}}
< 200
< Mcp-Session-Id: <session-id>
< Content-Type: application/json
< {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2025-11-25","capabilities":{"completions":{},"logging":{},"prompts":{"listChanged":true},"resources":{"subscribe":false,"listChanged":true},"tools":{"listChanged":true}},"serverInfo":{"name":"orders","version":"1.0.0"},"instructions":"Order lookup server used to compare the 2025 and 2026-07-28 MCP protocol generations."}}
## 3. notifications/initialized
> POST /mcp
> MCP-Protocol-Version: 2025-11-25
> Mcp-Session-Id: <session-id>
> {"jsonrpc":"2.0","method":"notifications/initialized"}
< 202
## 4. tools/call with the session
> POST /mcp
> MCP-Protocol-Version: 2025-11-25
> Mcp-Session-Id: <session-id>
> {"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"order_status","arguments":{"orderId":"A-101"}}}
< 200
< Content-Type: text/event-stream
< id:<session-id>
< event:message
< data: {"jsonrpc":"2.0","id":2,"result":{"content":[{"type":"text","text":"order A-101 is SHIPPED (answered by instance L1)"}],"isError":false}}
## 5. tools/call with a session id this server never issued
> POST /mcp
> MCP-Protocol-Version: 2025-11-25
> Mcp-Session-Id: <session-id>
> {"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"order_status","arguments":{"orderId":"A-101"}}}
< 404
< Content-Type: application/json
< {"jsonRpcError":{"code":-32603,"message":"Session not found: <session-id>"}}
@@ -0,0 +1,55 @@
# Two 2025-era instances behind a balancer: round-robin, then session affinity, then an instance dies
# PART A: plain round-robin. Request n goes to L1 when n is even and to L2 when n is odd.
## A1. initialize
> POST balancer/mcp
> {"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"wire-test","version":"1"}}}
< 200
< Mcp-Session-Id: <session-id>
< Content-Type: application/json
< X-Served-By: L1
< {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2025-11-25","capabilities":{"completions":{},"logging":{},"prompts":{"listChanged":true},"resources":{"subscribe":false,"listChanged":true},"tools":{"listChanged":true}},"serverInfo":{"name":"orders","version":"1.0.0"},"instructions":"Order lookup server used to compare the 2025 and 2026-07-28 MCP protocol generations."}}
## A2. notifications/initialized
> POST balancer/mcp
> MCP-Protocol-Version: 2025-11-25
> Mcp-Session-Id: <session-id>
> {"jsonrpc":"2.0","method":"notifications/initialized"}
< 404
< Content-Type: application/json
< X-Served-By: L2
< {"jsonRpcError":{"code":-32603,"message":"Session not found: <session-id>"}}
# Six tools/call with the same session id, through the same balancer:
call 1 -> L1: 200 OK
call 2 -> L2: 404 Session not found: <session-id>
call 3 -> L1: 200 OK
call 4 -> L2: 404 Session not found: <session-id>
call 5 -> L1: 200 OK
call 6 -> L2: 404 Session not found: <session-id>
succeeded: 3 of 6
# PART B: the balancer learns Mcp-Session-Id from the initialize response and pins the session.
initialize served by L1, then 6 calls pinned to the same instance
succeeded: 6 of 6
# PART C: the pinned instance L1 is stopped, as in a rolling deploy.
## C1. the same session after L1 is gone
> POST balancer/mcp
> MCP-Protocol-Version: 2025-11-25
> Mcp-Session-Id: <session-id>
> {"jsonrpc":"2.0","id":30,"method":"tools/call","params":{"name":"order_status","arguments":{"orderId":"A-101"}}}
< 404
< Content-Type: application/json
< X-Served-By: L2
< {"jsonRpcError":{"code":-32603,"message":"Session not found: <session-id>"}}
## C2. the client has to start over with initialize
> POST balancer/mcp
> {"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"wire-test","version":"1"}}}
< 200
< Mcp-Session-Id: <session-id>
< Content-Type: application/json
< X-Served-By: L2
< {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2025-11-25","capabilities":{"completions":{},"logging":{},"prompts":{"listChanged":true},"resources":{"subscribe":false,"listChanged":true},"tools":{"listChanged":true}},"serverInfo":{"name":"orders","version":"1.0.0"},"instructions":"Order lookup server used to compare the 2025 and 2026-07-28 MCP protocol generations."}}
+29
View File
@@ -0,0 +1,29 @@
# 2026-07-28 server (protocol MODERN): no handshake, no session, three self-contained POSTs
## 1. server/discover replaces initialize
> POST /mcp
> MCP-Protocol-Version: 2026-07-28
> Mcp-Method: server/discover
> {"jsonrpc":"2.0","id":1,"method":"server/discover","params":{"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientInfo":{"name":"wire-test","version":"1"},"io.modelcontextprotocol/clientCapabilities":{"elicitation":{"form":{}}}}}}
< 200
< Content-Type: application/json
< {"jsonrpc":"2.0","id":1,"result":{"supportedVersions":["2026-07-28"],"capabilities":{"completions":{},"prompts":{"listChanged":true},"resources":{"subscribe":false,"listChanged":true},"tools":{"listChanged":true}},"instructions":"Order lookup server used to compare the 2025 and 2026-07-28 MCP protocol generations.","ttlMs":300000,"cacheScope":"public","resultType":"complete","_meta":{"io.modelcontextprotocol/serverInfo":{"name":"orders","version":"1.0.0"}}}}
## 2. tools/list
> POST /mcp
> MCP-Protocol-Version: 2026-07-28
> Mcp-Method: tools/list
> {"jsonrpc":"2.0","id":2,"method":"tools/list","params":{"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientInfo":{"name":"wire-test","version":"1"},"io.modelcontextprotocol/clientCapabilities":{"elicitation":{"form":{}}}}}}
< 200
< Content-Type: application/json
< {"jsonrpc":"2.0","id":2,"result":{"tools":[{"name":"cancel_order","title":"cancel_order","description":"Cancels an order after the user confirms","inputSchema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"orderId":{"type":"string","description":"Order id such as A-101"}},"required":["orderId"]},"annotations":{"title":"","readOnlyHint":false,"destructiveHint":true,"idempotentHint":true,"openWorldHint":false}},{"name":"order_status","title":"order_status","description":"Looks up the status of an order by its id","inputSchema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"orderId":{"type":"string","description":"Order id such as A-101"}},"required":["orderId"]},"annotations":{"title":"","readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false}}],"ttlMs":300000,"cacheScope":"public","resultType":"complete","_meta":{"io.modelcontextprotocol/serverInfo":{"name":"orders","version":"1.0.0"}}}}
## 3. tools/call carries the tool name in a header as well as in the body
> POST /mcp
> MCP-Protocol-Version: 2026-07-28
> Mcp-Method: tools/call
> Mcp-Name: order_status
> {"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"order_status","arguments":{"orderId":"A-101"},"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientInfo":{"name":"wire-test","version":"1"},"io.modelcontextprotocol/clientCapabilities":{"elicitation":{"form":{}}}}}}
< 200
< Content-Type: application/json
< {"jsonrpc":"2.0","id":3,"result":{"content":[{"type":"text","text":"order A-101 is SHIPPED (answered by instance M1)"}],"isError":false,"resultType":"complete","_meta":{"io.modelcontextprotocol/serverInfo":{"name":"orders","version":"1.0.0"}}}}
+80
View File
@@ -0,0 +1,80 @@
# 2026-07-28 server: how a malformed request fails
## 1. tools/call without Mcp-Name
> POST /mcp
> MCP-Protocol-Version: 2026-07-28
> Mcp-Method: tools/call
> {"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"order_status","arguments":{"orderId":"A-101"},"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientInfo":{"name":"wire-test","version":"1"},"io.modelcontextprotocol/clientCapabilities":{"elicitation":{"form":{}}}}}}
< 400
< Content-Type: application/json
< {"jsonrpc":"2.0","id":3,"error":{"code":-32020,"message":"Missing required header: Mcp-Name"}}
## 2. Mcp-Method says tools/list, the body says tools/call
> POST /mcp
> MCP-Protocol-Version: 2026-07-28
> Mcp-Method: tools/list
> Mcp-Name: order_status
> {"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"order_status","arguments":{"orderId":"A-101"},"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientInfo":{"name":"wire-test","version":"1"},"io.modelcontextprotocol/clientCapabilities":{"elicitation":{"form":{}}}}}}
< 400
< Content-Type: application/json
< {"jsonrpc":"2.0","id":3,"error":{"code":-32020,"message":"Mcp-Method header does not match request method"}}
## 3. the version header is present but params._meta is missing
> POST /mcp
> MCP-Protocol-Version: 2026-07-28
> Mcp-Method: tools/list
> {"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}
< 400
< Content-Type: application/json
< {"jsonrpc":"2.0","id":2,"error":{"code":-32602,"message":"params._meta is required"}}
## 4. a protocol version the server does not support
> POST /mcp
> MCP-Protocol-Version: 2027-01-01
> Mcp-Method: tools/list
> {"jsonrpc":"2.0","id":2,"method":"tools/list","params":{"_meta":{"io.modelcontextprotocol/protocolVersion":"2027-01-01"}}}
< 400
< Content-Type: application/json
< {"jsonrpc":"2.0","id":2,"error":{"code":-32022,"message":"Unsupported protocol version","data":{"supported":["2026-07-28"],"requested":"2027-01-01"}}}
## 5. a 2025-era client's first request, initialize
> POST /mcp
> {"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"wire-test","version":"1"}}}
< 400
< Content-Type: application/json
< {"jsonrpc":"2.0","id":1,"error":{"code":-32020,"message":"Missing required header: Mcp-Method"}}
## 6. a stray Mcp-Session-Id on a modern request
> POST /mcp
> MCP-Protocol-Version: 2026-07-28
> Mcp-Method: tools/call
> Mcp-Name: order_status
> Mcp-Session-Id: left-over-from-a-2025-client
> {"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"order_status","arguments":{"orderId":"A-101"},"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientInfo":{"name":"wire-test","version":"1"},"io.modelcontextprotocol/clientCapabilities":{"elicitation":{"form":{}}}}}}
< 200
< Content-Type: application/json
< {"jsonrpc":"2.0","id":3,"result":{"content":[{"type":"text","text":"order A-101 is SHIPPED (answered by instance M1)"}],"isError":false,"resultType":"complete","_meta":{"io.modelcontextprotocol/serverInfo":{"name":"orders","version":"1.0.0"}}}}
## 7. GET /mcp
< 405
< Allow: POST
## 8. unknown tool
> POST /mcp
> MCP-Protocol-Version: 2026-07-28
> Mcp-Method: tools/call
> Mcp-Name: nope
> {"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"nope","arguments":{},"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientInfo":{"name":"wire-test","version":"1"},"io.modelcontextprotocol/clientCapabilities":{"elicitation":{"form":{}}}}}}
< 400
< Content-Type: application/json
< {"jsonrpc":"2.0","id":3,"error":{"code":-32602,"message":"Unknown tool: nope"}}
## 9. a missing argument
> POST /mcp
> MCP-Protocol-Version: 2026-07-28
> Mcp-Method: tools/call
> Mcp-Name: order_status
> {"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"order_status","arguments":{},"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientInfo":{"name":"wire-test","version":"1"},"io.modelcontextprotocol/clientCapabilities":{"elicitation":{"form":{}}}}}}
< 200
< Content-Type: application/json
< {"jsonrpc":"2.0","id":3,"result":{"content":[{"type":"text","text":"Invalid arguments: Validation failed: JSON schema validation errors: [: required property 'orderId' not found]"}],"isError":true,"resultType":"complete","_meta":{"io.modelcontextprotocol/serverInfo":{"name":"orders","version":"1.0.0"}}}}
@@ -0,0 +1,16 @@
# Two 2026-07-28 instances behind plain round-robin: no affinity, no handshake, no state to lose
# PART A: six tools/call, no initialize, no session id, one URL.
call 1 -> M1: 200 order A-102 is DELIVERED (answered by instance M1)
call 2 -> M2: 200 order A-102 is DELIVERED (answered by instance M2)
call 3 -> M1: 200 order A-102 is DELIVERED (answered by instance M1)
call 4 -> M2: 200 order A-102 is DELIVERED (answered by instance M2)
call 5 -> M1: 200 order A-102 is DELIVERED (answered by instance M1)
call 6 -> M2: 200 order A-102 is DELIVERED (answered by instance M2)
succeeded: 6 of 6
# PART B: M1 is stopped, as in a rolling deploy. The client changes nothing.
call 1 -> M2: 200 order A-102 is DELIVERED (answered by instance M2)
call 2 -> M2: 200 order A-102 is DELIVERED (answered by instance M2)
call 3 -> M2: 200 order A-102 is DELIVERED (answered by instance M2)
call 4 -> M2: 200 order A-102 is DELIVERED (answered by instance M2)
succeeded: 4 of 4
+77
View File
@@ -0,0 +1,77 @@
# Multi-round-trip request: cancel_order asks for confirmation by returning input_required
# PART A: no spring.ai.mcp.server.modern.request-state-secret, so each instance seals with its own random key.
## A1. first call, no answer yet
> POST /mcp (M1)
> MCP-Protocol-Version: 2026-07-28
> Mcp-Method: tools/call
> Mcp-Name: cancel_order
> {"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"cancel_order","arguments":{"orderId":"A-101"},"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientInfo":{"name":"wire-test","version":"1"},"io.modelcontextprotocol/clientCapabilities":{"elicitation":{"form":{}}}}}}
< 200
< Content-Type: application/json
< {"jsonrpc":"2.0","id":1,"result":{"inputRequests":{"confirm":{"params":{"mode":"form","message":"Cancel order A-101?","requestedSchema":{"type":"object","properties":{"ok":{"type":"boolean"}}}},"method":"elicitation/create"}},"requestState":"<requestState>","resultType":"input_required","_meta":{"io.modelcontextprotocol/serverInfo":{"name":"orders","version":"1.0.0"}}}}
# The part of requestState before the dot is base64url JSON, readable by anyone who holds it:
{"v":1,"s":"orderId=A-101","exp":<epoch-millis>,"m":"tools/call","n":"cancel_order"}
## A2. retry, answer yes, back on the SAME instance
> POST /mcp (M1)
> MCP-Protocol-Version: 2026-07-28
> Mcp-Method: tools/call
> Mcp-Name: cancel_order
> {"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"cancel_order","arguments":{"orderId":"A-101"},"inputResponses":{"confirm":{"action":"accept","content":{"ok":true}}},"requestState":"<requestState>","_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientInfo":{"name":"wire-test","version":"1"},"io.modelcontextprotocol/clientCapabilities":{"elicitation":{"form":{}}}}}}
< 200
< Content-Type: application/json
< {"jsonrpc":"2.0","id":2,"result":{"content":[{"type":"text","text":"order A-101 cancelled (answered by instance M1)"}],"resultType":"complete","_meta":{"io.modelcontextprotocol/serverInfo":{"name":"orders","version":"1.0.0"}}}}
## A3. the same retry, but the balancer sends it to the OTHER instance
> POST /mcp (M2)
> MCP-Protocol-Version: 2026-07-28
> Mcp-Method: tools/call
> Mcp-Name: cancel_order
> {"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"cancel_order","arguments":{"orderId":"A-101"},"inputResponses":{"confirm":{"action":"accept","content":{"ok":true}}},"requestState":"<requestState>","_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientInfo":{"name":"wire-test","version":"1"},"io.modelcontextprotocol/clientCapabilities":{"elicitation":{"form":{}}}}}}
< 400
< Content-Type: application/json
< {"jsonrpc":"2.0","id":2,"error":{"code":-32602,"message":"Invalid or expired requestState"}}
## A4. the right instance, but the state was altered in transit
> POST /mcp (M1)
> MCP-Protocol-Version: 2026-07-28
> Mcp-Method: tools/call
> Mcp-Name: cancel_order
> {"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"cancel_order","arguments":{"orderId":"A-101"},"inputResponses":{"confirm":{"action":"accept","content":{"ok":true}}},"requestState":"<requestState>","_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientInfo":{"name":"wire-test","version":"1"},"io.modelcontextprotocol/clientCapabilities":{"elicitation":{"form":{}}}}}}
< 400
< Content-Type: application/json
< {"jsonrpc":"2.0","id":2,"error":{"code":-32602,"message":"Invalid or expired requestState"}}
# PART B: the same secret on every instance (32 bytes or more).
## B1. first call on M1
> POST /mcp (M1)
> MCP-Protocol-Version: 2026-07-28
> Mcp-Method: tools/call
> Mcp-Name: cancel_order
> {"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"cancel_order","arguments":{"orderId":"A-101"},"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientInfo":{"name":"wire-test","version":"1"},"io.modelcontextprotocol/clientCapabilities":{"elicitation":{"form":{}}}}}}
< 200
< Content-Type: application/json
< {"jsonrpc":"2.0","id":1,"result":{"inputRequests":{"confirm":{"params":{"mode":"form","message":"Cancel order A-101?","requestedSchema":{"type":"object","properties":{"ok":{"type":"boolean"}}}},"method":"elicitation/create"}},"requestState":"<requestState>","resultType":"input_required","_meta":{"io.modelcontextprotocol/serverInfo":{"name":"orders","version":"1.0.0"}}}}
## B2. retry, answer yes, on M2
> POST /mcp (M2)
> MCP-Protocol-Version: 2026-07-28
> Mcp-Method: tools/call
> Mcp-Name: cancel_order
> {"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"cancel_order","arguments":{"orderId":"A-101"},"inputResponses":{"confirm":{"action":"accept","content":{"ok":true}}},"requestState":"<requestState>","_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientInfo":{"name":"wire-test","version":"1"},"io.modelcontextprotocol/clientCapabilities":{"elicitation":{"form":{}}}}}}
< 200
< Content-Type: application/json
< {"jsonrpc":"2.0","id":2,"result":{"content":[{"type":"text","text":"order A-101 cancelled (answered by instance M2)"}],"resultType":"complete","_meta":{"io.modelcontextprotocol/serverInfo":{"name":"orders","version":"1.0.0"}}}}
## B3. the user declines, retry on M1
> POST /mcp (M1)
> MCP-Protocol-Version: 2026-07-28
> Mcp-Method: tools/call
> Mcp-Name: cancel_order
> {"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"cancel_order","arguments":{"orderId":"A-101"},"inputResponses":{"confirm":{"action":"decline"}},"requestState":"<requestState>","_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientInfo":{"name":"wire-test","version":"1"},"io.modelcontextprotocol/clientCapabilities":{"elicitation":{"form":{}}}}}}
< 200
< Content-Type: application/json
< {"jsonrpc":"2.0","id":2,"result":{"content":[{"type":"text","text":"order A-101 kept (answered by instance M1)"}],"resultType":"complete","_meta":{"io.modelcontextprotocol/serverInfo":{"name":"orders","version":"1.0.0"}}}}
+31
View File
@@ -0,0 +1,31 @@
# One URL, two server generations, split on the MCP-Protocol-Version header
# Rule: MCP-Protocol-Version >= 2026-07-28 goes to the modern pool (M1, M2). Everything else goes to the legacy pool (L1).
# A 2025-era client: initialize, initialized, tools/call.
## 1. initialize carries no MCP-Protocol-Version header
> POST router/mcp
> {"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"wire-test","version":"1"}}}
< 200
< Mcp-Session-Id: <session-id>
< Content-Type: application/json
< X-Served-By: L1
< {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2025-11-25","capabilities":{"completions":{},"logging":{},"prompts":{"listChanged":true},"resources":{"subscribe":false,"listChanged":true},"tools":{"listChanged":true}},"serverInfo":{"name":"orders","version":"1.0.0"},"instructions":"Order lookup server used to compare the 2025 and 2026-07-28 MCP protocol generations."}}
## 2. tools/call with the session and MCP-Protocol-Version: 2025-11-25
> POST router/mcp
> MCP-Protocol-Version: 2025-11-25
> Mcp-Session-Id: <session-id>
> {"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"order_status","arguments":{"orderId":"A-101"}}}
< 200
< Content-Type: text/event-stream
< X-Served-By: L1
< id:<session-id>
< event:message
< data: {"jsonrpc":"2.0","id":2,"result":{"content":[{"type":"text","text":"order A-101 is SHIPPED (answered by instance L1)"}],"isError":false}}
# A 2026-07-28 client through the same URL: four tools/call, nothing else.
modern call 1 -> M1: 200 order A-101 is SHIPPED (answered by instance M1)
modern call 2 -> M2: 200 order A-101 is SHIPPED (answered by instance M2)
modern call 3 -> M1: 200 order A-101 is SHIPPED (answered by instance M1)
modern call 4 -> M2: 200 order A-101 is SHIPPED (answered by instance M2)
@@ -0,0 +1,23 @@
# The 2.2.0 modern SDK client against two 2026-07-28 instances behind round-robin
discover: supportedVersions=[2026-07-28] ttlMs=300000 cacheScope=PUBLIC
tools: [cancel_order, order_status]
order_status #1: order A-100 is PACKED (answered by instance M1)
order_status #2: order A-100 is PACKED (answered by instance M2)
order_status #3: order A-100 is PACKED (answered by instance M1)
order_status #4: order A-100 is PACKED (answered by instance M2)
cancel_order (the client answered the confirmation itself): order A-102 cancelled (answered by instance M2)
What the balancer saw, in order:
POST server/discover
POST tools/list
POST tools/call
POST tools/call
POST tools/call
POST tools/call
POST tools/call
POST tools/call
total requests: 8
# Same client and balancer, but the instances have no shared request-state-secret:
cancel_order: io.modelcontextprotocol.modern.McpException
Invalid or expired requestState
@@ -0,0 +1,6 @@
# What each SDK client says when it meets a server of the other generation
2025-era client -> modern server: java.lang.RuntimeException
RuntimeException: Client failed to initialize by explicit API call
McpTransportException: Bad Request. Status code:400, response body: {"jsonrpc":"2.0","id":"<id>","error":{"code":-32020,"message":"Missing required header: Mcp-Method"}}
modern client -> 2025-era server: io.modelcontextprotocol.modern.client.transport.McpHttpStatusException
HTTP 400 from http://localhost:<port>/mcp: {"jsonRpcError":{"code":-32601,"message":"Session ID missing"}... (stack trace omitted)
@@ -0,0 +1,10 @@
# A 2025-era SDK client and a 2026-07-28 SDK client, one router URL, split on MCP-Protocol-Version
2025-era client: order A-101 is SHIPPED (answered by instance L1)
2026-07-28 client: order A-101 is SHIPPED (answered by instance M2)
What the router saw (HTTP method and Mcp-Method header; '-' means the header is absent):
1 x DELETE -
1 x GET -
3 x POST -
1 x POST tools/call
1 x POST tools/list