mcp-stateless
Companion module for the ankurm.com post MCP 2026-07-28 for Java Developers: Migrating an MCP Server to the Stateless Spec.
One order-lookup MCP server that runs as a 2025-era stateful server (legacy profile) or as a 2026-07-28 stateless server
(modern profile). The tools are the same @McpTool beans in both. The tests start real instances, put a plain
round-robin proxy in front of them and write what happened to output/.
Versions (verified on Maven Central, 2026-11-22)
| Component |
Version |
Note |
| Spring Boot |
4.2.0 |
GA 2026-11-19 |
Spring AI spring-ai-starter-mcp-server-webmvc |
2.1.0 |
GA 2026-11-19. protocol: MODERN first exists in 2.1.0-RC2; it is absent from 2.0.x and 2.1.0-RC1 |
MCP Java SDK io.modelcontextprotocol.sdk:mcp |
2.2.0 |
brought in by Spring AI. The io.modelcontextprotocol.modern package first appears in 2.2.0-M1; 2.1.0 has none |
| JDK |
25 LTS |
Temurin 25.0.5 |
Run
Profiles
| Profile |
Property |
Wire behaviour |
legacy |
spring.ai.mcp.server.protocol=STREAMABLE |
initialize, Mcp-Session-Id, session held in server memory |
modern |
spring.ai.mcp.server.protocol=MODERN |
server/discover, _meta on every request, Mcp-Method / Mcp-Name headers, no session |
Tools
| Tool |
Profiles |
Purpose |
order_status |
both |
read-only lookup; reports which instance answered |
cancel_order |
modern |
asks for confirmation by returning input_required (multi-round-trip request) |
Captured output (output/)
| File |
Shows |
01-legacy-handshake.txt |
initialize, session id, a call without a session, an unknown session |
02-legacy-behind-lb.txt |
two 2025 instances behind round-robin: 3 of 6 calls fail; affinity; instance stopped |
03-modern-wire.txt |
server/discover, tools/list, tools/call with no session |
04-modern-errors.txt |
header and body mismatches, wrong version, a 2025 initialize, a stray session header |
05-modern-behind-lb.txt |
two 2026-07-28 instances behind round-robin, one stopped mid-run |
06-modern-mrtr.txt |
input_required, requestState, a retry on another instance with and without a shared secret |
07-both-versions.txt |
one URL, two generations, routed on MCP-Protocol-Version |
08-sdk-modern-client.txt |
the 2.2.0 modern SDK client through round-robin |
09-sdk-version-mismatch.txt |
what each SDK client says against the other generation's server |
10-sdk-clients-through-router.txt |
both SDK clients through the version router |
Layout