Files

3.2 KiB

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

scripts/run-all.sh                       # all tests, regenerates output/
scripts/run.sh modern 8082 M1            # one 2026-07-28 server
scripts/run.sh legacy 8081 L1            # one 2025-era server
scripts/curl-modern.sh 8082 A-101        # a single stateless request

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

src/main/java/com/ankurm/mcpstateless/   StatelessApp, OrderTools, CancelOrderTool
src/main/resources/                      application.yml, application-legacy.yml, application-modern.yml
src/test/java/com/ankurm/mcpstateless/   one test class per transcript group
src/test/java/.../support/               Wire (raw HTTP), Transcript, Instance, Proxy (the stand-in balancer)