Skip to main content

MCP 2026-07-28 for Java Developers: Migrating an MCP Server to the Stateless Spec

The MCP 2026-07-28 spec removes the initialize handshake and the session id. This post migrates a Spring AI 2.1.0 MCP server to it with one property, shows 3 of 6 calls failing behind a round-robin balancer on the old protocol and 6 of 6 succeeding on the new one, and covers input_required, requestState secrets and serving both generations during the move.

You run one copy of your MCP server and everything works. You add a second copy behind a load balancer and tool calls start failing at random, with an error about a session your client definitely created. That is not a bug in your code. It is a property of the protocol you were built on, and the 2026-07-28 revision of the Model Context Protocol removes it. This post migrates a small Java MCP server to the new revision. It starts from what a session was and why it hurt, shows the new request shape on the wire, flips a Spring AI server over with one property, and then covers the parts that bite: asking the user a question in the middle of a tool call, a signed value that must be shared between instances, and how to keep old clients working while you migrate. Every transcript below is copied from a file in the companion repository, and the tests that write those files assert the same facts.
Versions tested. Spring AI 2.1.0 (GA on Maven Central 2026-11-19), Spring Boot 4.2.0 (GA 2026-11-19), MCP Java SDK 2.2.0 (pulled in by Spring AI; published 2026-11-13), JDK 25 (Temurin 25.0.5). The MCP specification revision 2026-07-28 was released on July 28, 2026. Code: the mcp-stateless module of the java-ai-agents repository.

What a session was, and why a second server instance breaks it

An MCP server is a program that tells an AI client which tools it offers and runs them when asked. Before 2026-07-28, a client could not just call a tool. It first sent initialize, the server answered with a session id in an Mcp-Session-Id header, the client confirmed with notifications/initialized, and only then could it call tools, sending that session id every time. The server kept the session in its own memory. This is the first transcript, from the legacy handshake file: a call before any handshake is refused.
## 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"}}
That is fine while one process serves everyone. With two processes behind a balancer that does not understand MCP, the session exists on one of them only. I put two of the old-style servers (L1 and L2) behind a plain round-robin proxy and sent six calls with the same session id. The balancer sends request n to L1 when n is even and to L2 when it is odd, and the initialize that created the session was request 0.
Clientsession s-1 Balancerround-robin L1holds session s-1200 OK L2never saw s-1404 Session not found every calleven requestsodd requests The session lives in one process, so only the calls that happen to reach that process work.
The diagram shows the cause: the session id names state inside one JVM, and the balancer routes without knowing that. The captured result, from the balancer transcript, is that half the calls fail, including the notifications/initialized that completes the handshake:
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
The usual workaround is session affinity: the balancer learns the id from the initialize response and pins the client to that instance. In the same transcript that gives 6 of 6, until the pinned instance is stopped, as in a rolling deploy. The next call then reaches the other instance and gets the same 404, and the client has to start over with a fresh initialize. Affinity hides the problem until an instance disappears.
Going deeper: what else was stateful in the 2025 transport The session id was only the visible part. The 2025 Streamable HTTP transport also let a client open a long-lived GET stream for messages the server starts, and close a session with DELETE. I saw both from the real 2025-era SDK client in the router transcript: one POST for initialize, one GET, a POST for the initialized notification, a POST for the call and a DELETE on close. My test balancer answers the GET with 405, which the client accepts. A real balancer that forwarded it would hold a connection pinned to one instance, which is one more reason affinity became the default advice. One more detail from the same runs: when the 2025-style server rejects a request, the body is a serialised Java exception including a stackTrace array. The transcripts strip it for readability, and the stripping is done by the Transcript helper. I did not find a switch to turn it off.
Going deeper: LegacyBehindLoadBalancerTest (the code behind the three parts), the plain-SDK post for the 2025 handshake without Spring.

The new request carries everything the server needs

The 2026-07-28 revision, announced on the official MCP blog, makes the protocol core stateless. There is no initialize and no Mcp-Session-Id. Each request says which protocol version it speaks and what the client can do, inside params._meta, and two new headers, Mcp-Method and Mcp-Name, repeat the method and the tool name so that a balancer can route on them without parsing JSON. A client that wants to know what the server offers calls server/discover instead of handshaking.
Clientno session Balancersame round-robin M1keeps nothing200 OK M2keeps nothing200 OK each call alone Every request names its own version and capabilities, so any instance can answer any request.
The only difference from the previous diagram is that nothing the server needs lives on the server. This is a real call to the migrated server, from the modern wire transcript. The request body is one long line, so I show the headers and the answer:
## 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
< 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"}}}}
The server checks the headers against the body. Four ways to get it wrong, each with the error the server returned, are in the errors transcript:
What the request didHTTPJSON-RPC error
tools/call without Mcp-Name400-32020 Missing required header: Mcp-Name
Mcp-Method says tools/list, body says tools/call400-32020 Mcp-Method header does not match request method
version header present, params._meta missing400-32602 params._meta is required
a version the server does not speak400-32022 Unsupported protocol version, with data.supported
a 2025 client’s first request, initialize400-32020 Missing required header: Mcp-Method
A leftover session header is not rejected. I sent a modern tools/call with a stray Mcp-Session-Id: left-over-from-a-2025-client and got 200 with the normal result. The spec removes the header, but this server simply ignores it. Do not rely on it to tell you that a client is still living in the old protocol. Another Java implementation, Helidon in an Inside Java walkthrough, chooses to reject it, so check what yours does.
Going deeper: discover, caching hints and other things I observed server/discover returns the versions the server accepts, its capabilities and its instructions, plus two cache fields, ttlMs and cacheScope. In the module they come back as 300000 and public because the modern profile sets discover-ttl and list-ttl to five minutes. The Spring AI defaults are 0 and PRIVATE, so nothing is cacheable until you say so. A listing that differs per caller must stay PRIVATE. The tool list shows something easy to miss. A tool method with no annotations is advertised as readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true. That is the default I saw for the first version of order_status, a harmless lookup, which is why the final code sets the hints explicitly. Clients and gateways use these hints to decide what to confirm. tools/list does not promise an order: cancel_order came before order_status in my runs. GET /mcp on the modern server returns 405 with Allow: POST. It is POST only. A missing required argument is not a protocol error: it comes back as 200 with isError: true and the validator’s message, while an unknown tool name is a -32602 error.
Going deeper: ModernWireTest, the 2026-07-28 specification, and curl-modern.sh to send one yourself.

Spring AI 2.1.0 switches protocols with one property

First, which versions. The official blog says the four Tier 1 SDKs (TypeScript, Python, Go and C#) support the revision. Java is not in that list, and I checked the jars instead of guessing. The MCP Java SDK has a new io.modelcontextprotocol.modern package from 2.2.0-M1 on, and 2.1.0 has none. In Spring AI, the MODERN value of spring.ai.mcp.server.protocol first exists in 2.1.0-RC2. It is absent from 2.0.3 and from 2.1.0-RC1. Spring AI 2.1.0 depends on SDK 2.2.0, so the Spring starter is all you add. The module’s pom.xml overrides the older Spring versions of the parent for this module only:
    <spring-boot.version>4.2.0</spring-boot.version>
    <spring-ai.version>2.1.0</spring-ai.version>
    <dependency>
      <groupId>org.springframework.ai</groupId>
      <artifactId>spring-ai-starter-mcp-server-webmvc</artifactId>
    </dependency>
The tools do not change. This is the whole tool class, OrderTools.java, shared by both generations. The method also reports which instance answered, so a balancer test can see where each call went:
    @McpTool(name = "order_status", description = "Looks up the status of an order by its id",
            annotations = @McpTool.McpAnnotations(readOnlyHint = true, destructiveHint = false,
                    idempotentHint = true, openWorldHint = false))
    public String orderStatus(@McpToolParam(description = "Order id such as A-101") String orderId) {
        String status = ORDERS.getOrDefault(orderId, "UNKNOWN");
        return "order " + orderId + " is " + status + " (answered by instance " + instance + ")";
    }
What differs is a profile file. The 2025 behaviour is protocol: STREAMABLE in application-legacy.yml. The new one is in application-modern.yml:
spring:
  ai:
    mcp:
      server:
        protocol: MODERN
        modern:
          discover-ttl: 5m
          discover-cache-scope: PUBLIC
          list-ttl: 5m
          list-cache-scope: PUBLIC
Now the experiment from the start of the post, repeated on the migrated server. Two instances, M1 and M2, the same round-robin balancer, six calls with no handshake and no session id, then M1 is stopped and four more calls are sent. This is the modern balancer transcript:
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 4 -> M2: 200 order A-102 is DELIVERED (answered by instance M2)
succeeded: 4 of 4
Six of six, where the old protocol gave three of six, and a stopped instance costs the client nothing. That is the migration’s payoff in one result.
Going deeper: what the modern Spring AI server supports, from its reference page I verified the behaviour above by running it. The following comes from the Spring AI 2.1 modern server page, and I have not run it. The modern server is selected for WebMVC, WebFlux and STDIO, and this module tests only WebMVC. The same @McpTool, @McpResource, @McpPrompt and @McpComplete beans are served, with older return types converted to the new schema. Methods that declare the old bidirectional parameters, such as McpSyncServerExchange, are skipped with a warning, and the request context offers no elicit, sample, roots or ping. A method that declares McpSyncNotifier is always answered as text/event-stream so it can send progress; one without it returns plain JSON. The page also lists the other spring.ai.mcp.server.modern.* properties: mcp-endpoint (default /mcp), supported-versions (default 2026-07-28), page-size, keep-alive-interval, max-request-size, request-state-secret and request-state-ttl (default ten minutes). By default a request that carries an Origin header is refused with 403 until you supply your own ServerHttpHeaderValidator.
Going deeper: ModernBehindLoadBalancerTest, Build an MCP Server with Spring AI if you are starting from nothing.

Asking the user a question without holding the connection open

Some tools need an answer from the person mid-call: “cancel this order, are you sure?”. In the 2025 protocol the server asked the client over the open session and waited. A stateless server has nowhere to wait, so the revision replaces that with a multi-round-trip request. The tool returns input_required with the question, the client asks the user, then the client sends the same call again with the answer attached. The server keeps nothing between the two requests. The one thing the server does hand back is requestState, a value it wants returned with the retry. Because the client carries it, the server seals it so it cannot be forged. Here is the tool, CancelOrderTool.java. The first branch asks; a retry takes the answer from ctx.inputResponse:
        ElicitResult confirmation = ctx.inputResponse("confirm", ElicitResult.class);
        if (confirmation == null) {
            // First request: no answer yet. Ask, and seal the order id into requestState.
            return InputRequiredResult.builder()
                    .elicit("confirm", ElicitFormRequest.builder("Cancel order " + orderId + "?", schema()).build())
                    .requestState("orderId=" + orderId)
                    .build();
        }
        boolean confirmed = confirmation.action() == ElicitResult.Action.ACCEPT
                && Boolean.TRUE.equals(confirmation.content().get("ok"));
Client M1 M2 1. cancel_order A-101 2. input_required + requestState 3. user says yes 4. same call + answer + requestState 5. result: order cancelled M2 can only accept step 4 if it can verify the state that M1 sealed.
The diagram ends on the condition that decides whether this works in production. The transcript for it is the multi-round-trip file. With no shared secret configured, each instance seals with its own random key. The retry that comes back to the same instance succeeds, and the one the balancer sends to the other instance is refused:
## A2. retry, answer yes, back on the SAME instance
<   {"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
< 400
<   {"jsonrpc":"2.0","id":2,"error":{"code":-32602,"message":"Invalid or expired requestState"}}
So a stateless server is not automatically safe behind a balancer: this one value is state again. Spring AI even warns at startup that, with no key, the state sealed by one instance cannot be opened by another. The fix is the same secret on every instance, set with spring.ai.mcp.server.modern.request-state-secret (the docs say at least 32 bytes). With it, part B of the transcript has the retry land on M2 and finish:
## B2. retry, answer yes, on M2
< 200
## B3. the user declines, retry on M1
<   {"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"}}}}
Sealed means signed, not secret. The part of requestState before the dot is plain base64url JSON. The test decodes it and the transcript shows what anyone holding it can read: {"v":1,"s":"orderId=A-101","exp":<epoch-millis>,"m":"tools/call","n":"cancel_order"}. A changed byte is rejected (case A4 in the transcript), but nothing is hidden. Never put a secret or personal data in requestState.
Going deeper: what the docs say about the rest of the old server-to-client features The Spring AI page and the Go and Ruby SDK documentation say that roots, sampling and logging are deprecated in this revision, and that the old in-call elicit, sample and ping no longer exist on a modern server. Roots and sampling are reachable only through the same input_required retry, and a tool that cannot work without such a capability can declare it with requiredCapabilities, so the server answers -32021 before running the method. Logging is per request: the client opts in through a _meta key and the tool writes to that request’s own stream. I did not run any of that; I only ran elicitation. If you use sampling or roots today, read MCP Beyond Tools in Java and plan the rewrite. The state also carries an expiry. It was request-state-ttl, ten minutes by default per the docs, and a retry after that is refused with the same “Invalid or expired” message, so a user who walks away from a confirmation prompt has to start the call again.
Going deeper: MultiRoundTripTest, securing an MCP server with Spring Security for who may call what.

You cannot flip every client at once: serve both generations

A modern-only server answers a 2025 client’s first request with the 400 you saw in the table, so every client of yours has to be ready before you switch. In practice you migrate in two steps, and Spring AI picks one protocol per application through that single property. I could not find a way to run both in one Boot application, so the module runs two deployments behind one URL and splits on a header the client already sends. The rule is the MCP-Protocol-Version header. A 2026 client sends 2026-07-28 on every request. A 2025 client sends no version header on its first request (initialize) and its own older version on later ones. So anything that names 2026-07-28 or later goes to the modern pool, and the rest goes to the legacy pool. This is the routing function from BothVersionsTest.java:
    static boolean isModern(Map<String, String> headers) {
        String v = headers.get("mcp-protocol-version");
        return v != null && v.compareTo(Wire.MODERN_VERSION) >= 0;
    }
Through that one router URL, a 2025-style client completes its handshake and call on the legacy instance, and a 2026 client is spread over both modern instances. From the both-versions transcript:
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)
Keep the legacy pool pinned (the module gives it one instance and affinity), because it still has sessions. Shrink it as clients upgrade, and delete it when the router stops seeing 2025 traffic.
Going deeper: how other Java stacks handle both versions Spring AI’s choice of one protocol per application is a design decision, not a law. The Inside Java article on migrating a Helidon MCP server routes inside one process instead: an existing HTTP feature checks MCP-Protocol-Version and hands 2026-07-28 requests to a temporary adapter, while everything else reaches the generated 2025 route unchanged, with the scoring logic shared. The article describes that adapter as temporary and says Helidon’s native support was planned but not yet released when it was written. If you use Helidon, read it before building your own. My router is a 70-line test proxy using the JDK’s built-in HTTP server, standing in for nginx, Envoy or a cloud load balancer. It forwards bytes and does not understand MCP beyond that one header. I did not test a production balancer.
Going deeper: Proxy.java (the stand-in balancer and its pools).

Check it with real SDK clients, not just curl

Hand-written HTTP proves the wire format. I also ran the SDK’s own clients, because those are what your callers will use. The 2.2.0 modern client builds like this (SdkClientsTest.java), with a handler that answers the confirmation question itself:
    static McpSyncClient modernClient(String url) {
        URI uri = URI.create(url);
        return McpClient.sync(HttpClientMcpTransport.builder(uri).build())
                .clientInfo(Implementation.builder("sdk-modern-client", "1").build())
                .formElicitation(req -> ElicitResult.builder(ElicitResult.Action.ACCEPT).content(Map.of("ok", true)).build())
                .build();
    }
Against two instances with a shared secret, behind the round-robin balancer, the client discovered the server, listed tools and ran the confirmation round trip across instances without any session handling. From the SDK client transcript:
discover: supportedVersions=[2026-07-28] ttlMs=300000 cacheScope=PUBLIC
tools: [cancel_order, order_status]
cancel_order (the client answered the confirmation itself): order A-102 cancelled (answered by instance M2)
total requests: 8
Eight requests: a discover, a list and six calls, two of them the cancel round trip. Without the shared secret the same client call fails, and the exception carries the server’s message:
cancel_order: io.modelcontextprotocol.modern.McpException
  Invalid or expired requestState
Mismatched pairs fail in a way that is easy to misread. In the mismatch transcript, a 2025-era client against a modern server reports only a generic failure at the top and hides the real reason one level down:
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"}}
If you get “Client failed to initialize” after upgrading a server, walk the cause chain before you debug anything else. A modern client against an old server gets HTTP 400 with “Session ID missing”. Finally, both clients through the one router URL worked, which is the router transcript:
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)
Going deeper: what I did not test Everything here runs against the Java SDK 2.2.0 clients and a hand-written HTTP client. I did not connect Claude, ChatGPT or any other product client, so I cannot tell you which of them already speak 2026-07-28 against your server. I did not run WebFlux or STDIO servers, authorization, subscriptions/listen, progress streaming from a tool, or a real cloud load balancer. The captured timings are not benchmarks and the post makes no performance claim. The MCP blog describes the revision as released on July 28, 2026 with breaking changes, and the earliest removal window for the deprecated features, per the Inside Java article, is July 2027.
Going deeper: the module README for the full list of transcripts and how to regenerate them with scripts/run-all.sh.
Should you migrate now? If you run more than one instance of a remote MCP server, or you want to deploy without clients losing sessions, yes, and the work is small: one property, a shared secret, and a router while old clients remain. If your server runs over stdio on a developer’s machine, or as a single instance that nobody balances, the old protocol keeps working and there is no urgency. Check first that your own clients can speak 2026-07-28. Spring AI 2.1.0 is a day-old GA at the time of writing, and the stateless features I could not test are in the details above.

Further reading

No Comments yet!

This site uses Akismet to reduce spam. Learn how your comment data is processed.