On November 16, MCP's Java SDK released 2.2.0. This version supports a new spec that "removes sessions": there is no initialize handshake, every request carries its own context, and the server no longer remembers anything on your behalf. For people writing Spring Boot, this is not a minor change—deploying an MCP Server with multiple replicas and rolling updates in K8s goes from "handle with care" to "naturally works."
1. Why We Used to Worry About Sessions
Older MCP had sessions. When a client connected, it first performed the initialize handshake, the two sides exchanged capabilities, the server remembered the context of that session, and subsequent calls were all attached to that session.
This design has a direct consequence: whichever process the session is stuck to, the request has to go back to that same process.
So all the old deployment-level questions came back:
- How do we do multiple replicas? What should the load balancer use for stickiness?
- What happens to old sessions during rolling updates? Disconnect and the context is gone
- If a client times out and reconnects, does it have to go through the handshake again from scratch?
- Should session state be externalized? If storing it in Redis, what gets serialized?
If your MCP Server is just a local tool (STDIO transport, one-to-one), none of this is a problem. But as soon as you want to use it as a service—multiple replicas, horizontal scaling, rolling releases—sessions become that thorn you can't get around.
2. The New Spec Pulls Out That Thorn
The latest version of the MCP spec (2026-07-28, marked as latest on the docs site) states it clearly:
Stateless, self-contained requests — stateless, self-contained requests
Per-request capability negotiation — capability negotiation per request
In practical terms:
| Old model | New model |
|---|---|
| Handshake once, reuse capabilities within the session | Each request carries its own capability declaration |
| Server remembers session context | Server stores no session state at all |
| Requests have to stick to a specific instance via the session | Any instance can handle any request |
| Rolling updates need to account for old sessions | Stateless, so rolling updates are naturally safe |
And the official notes for Java SDK 2.2.0 describe these changes more concretely:
- No sessions: each request is handled on its own, which suits horizontally scaled deployments
- One server, sync or async: the transport decides whether to offload blocking code; business code can be written in either style
- Your own catalogs: tools/resources/prompts come from repositories you implement yourself, making tenant-based filtering and pagination straightforward
- Stream only when it pays: whether the handler returns plain JSON or SSE is up to your code
- No initialize handshake on the client side
The two items "no sessions" and "stream only when it pays" are the most practical changes this time. The former solves deployment, and the latter solves the waste of "forcing an SSE layer onto a query that returns thirty bytes."
3. How to Use It: Two Packages, Two Sets of APIs
The SDK puts the new protocol in separate packages and leaves the old ones untouched:
- New:
io.modelcontextprotocol.modern.server.McpServer,io.modelcontextprotocol.modern.client.McpClient - Old: the original package paths, unchanged
The official docs explicitly include a caveat worth noting: the modern API may still change in minor versions before 3.0.
So the upgrade strategy is clear: new projects can use modern, and old projects shouldn't rush to migrate. The coexistence of the two API sets means you can migrate gradually: use the new protocol for newly written servers first, and let the old ones keep running as they are.
The dependencies look like this:
<dependency>
<groupId>io.modelcontextprotocol.sdk</groupId>
<artifactId>mcp</artifactId>
<version>2.2.0</version>
</dependency>
<dependency>
<groupId>io.modelcontextprotocol.sdk</groupId>
<artifactId>mcp-json-jackson2</artifactId>
<version>2.2.0</version>
</dependency>
mcp is the aggregate entry point, and mcp-json-jackson2 is the JSON binding implementation. You need to specify versions for both; don't count on the BOM to cover you.
4. After Going Stateless, You Have to Manage the Tool Catalog Yourself
This is the most easily underestimated point in the new version.
In the old model, you registered tools once, and the server remembered them in the session. In the new model, every request is independent, so the tool list can no longer rely on "what was registered last time"—it has to be computable on every request.
The official phrasing is "Your own catalogs ... come from repositories you implement." In Spring Boot terms, that means writing your own tool repository:
package com.example.mcp.server;
import java.util.List;
import java.util.Map;
import java.util.function.Supplier;
import org.springframework.stereotype.Component;
@Component
public class OrderToolCatalog {
public record ToolSpec(String name, String description, Supplier<String> handler) {
}
private final Map<String, ToolSpec> all = Map.of(
"get_order",
new ToolSpec("get_order", "按订单号查询订单状态",
() -> "{\"status\":\"PAID\"}"),
"list_orders",
new ToolSpec("list_orders", "列出当前用户的订单",
() -> "[]"));
public List<ToolSpec> toolsFor(String tenantId, String userId) {
if ("vip".equals(tenantId)) {
return List.copyOf(all.values());
}
return List.of(all.get("get_order"));
}
}
Here, toolsFor is exactly the benefit brought by "statelessness": the catalog is recomputed on every request, so filtering by tenant or by permission becomes a natural way to write it.
The trade-off is the corresponding mental requirement: don't cache anything user-related in this class. Caching tool definitions (static descriptions) is fine; caching "which tools this user can see" will cross-contaminate.
5. Three pitfalls I've run into
1. Treating stateless as "nothing can be stored."
Stateless means the protocol layer doesn't keep sessions; it doesn't mean your service can't have caches. Tool definitions, configuration, and dictionary data should be cached when appropriate—they're independent of the caller. The test is simple: does this data vary by request?
2. Taking "only stream when it's worth it" too far.
The new version lets handlers return JSON directly. It's tempting to switch every endpoint to one-shot responses—but for long-running tasks (say, a batch retrieval), streaming makes a noticeable difference in perceived responsiveness. Use JSON for short requests and SSE for long tasks; don't apply a one-size-fits-all rule.
3. Changing only the dependency version in old code.
Don't do that. In 2.2.0 the old and new APIs coexist. If you only bump the dependency version without changing your imports, you may still be running the old protocol while thinking you've finished the upgrade. The first thing to do after upgrading is confirm that you're importing classes under io.modelcontextprotocol.modern.
6. What this means for architecture
Zoom out, and this change points in the same direction as another trend:
MCP is shrinking its own "protocol presence"—moving from "a stateful middle layer with sessions and handshakes" toward "a thin layer of description + standard requests."
To judge whether this direction is right, look at another approach: UTCP does away with the middle layer entirely, giving the Agent a spec and letting it call your API directly. MCP hasn't gone that far, but once sessions are removed, the two are clearly much closer.
The practical takeaway for Java teams:
| Scenario | Recommendation |
|---|---|
| A newly written MCP Server to be deployed with multiple replicas | Use the modern stateless API |
| Local tools, single-machine STDIO | The old API is more than enough; don't bother |
| An existing Server running stably | No rush to migrate; wait for the 3.0 API to be finalized |
| Need to filter tools by tenant/permission | The modern catalog mode is a more natural fit |
7. A Complete Minimal Example
We've broken things down so far; here's a skeleton you can actually run. Use Spring Boot to spin up an HTTP service that exposes a stateless MCP endpoint.
First, the project setup. Use the latest GA version of Spring Boot and JDK 21:
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<parent>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-parent</artifactId>
<version>4.1.2</version>
<relativePath/>
</parent>
<groupId>com.example</groupId>
<artifactId>mcp-stateless-demo</artifactId>
<version>1.0.0</version>
<properties>
<java.version>21</java.version>
</properties>
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
<version>4.1.2</version>
</dependency>
<dependency>
<groupId>io.modelcontextprotocol.sdk</groupId>
<artifactId>mcp</artifactId>
<version>2.2.0</version>
</dependency>
<dependency>
<groupId>io.modelcontextprotocol.sdk</groupId>
<artifactId>mcp-json-jackson2</artifactId>
<version>2.2.0</version>
</dependency>
</dependencies>
<build>
<plugins>
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
<version>4.1.2</version>
</plugin>
</plugins>
</build>
</project>
Put only the two necessary items in the config file:
server:
port: 8080
shutdown: graceful
spring:
application:
name: mcp-stateless-demo
Add graceful shutdown to the main application class—just right for rolling updates with a stateless endpoint:
package com.example.mcp.server;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
@SpringBootApplication
public class McpStatelessDemoApplication {
public static void main(String[] args) {
SpringApplication.run(McpStatelessDemoApplication.class, args);
}
}
Then comes the key part—wiring the tool catalog to the HTTP endpoint. Note the key implementation point here: compute the catalog per request, with no dependence on any session state.
package com.example.mcp.server;
import java.util.List;
import java.util.Map;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.http.MediaType;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestHeader;
import org.springframework.web.bind.annotation.RestController;
import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;
@RestController
public class McpEndpointController {
private static final Logger log = LoggerFactory.getLogger(McpEndpointController.class);
private final OrderToolCatalog catalog;
private final ObjectMapper mapper;
public McpEndpointController(OrderToolCatalog catalog, ObjectMapper mapper) {
this.catalog = catalog;
this.mapper = mapper;
}
@PostMapping(path = "/mcp/{toolName}", produces = MediaType.APPLICATION_JSON_VALUE)
public ResponseEntity<String> invoke(@PathVariable String toolName,
@RequestHeader(value = "X-Tenant-Id", defaultValue = "default") String tenantId,
@RequestHeader(value = "X-User-Id", defaultValue = "anonymous") String userId,
@RequestBody(required = false) JsonNode body) {
List<OrderToolCatalog.ToolSpec> visible = catalog.toolsFor(tenantId, userId);
OrderToolCatalog.ToolSpec spec = visible.stream()
.filter(t -> t.name().equals(toolName))
.findFirst()
.orElse(null);
if (spec == null) {
log.warn("工具不可见或不存在 tool={} tenant={} user={}", toolName, tenantId, userId);
return ResponseEntity.status(404)
.contentType(MediaType.APPLICATION_JSON)
.body("{\"error\":\"tool not found\"}");
}
log.info("调用工具 tool={} tenant={} user={} args={}", toolName, tenantId, userId, body);
String result = spec.handler().get();
return ResponseEntity.ok().contentType(MediaType.APPLICATION_JSON).body(result);
}
}
Next, add an endpoint for querying the tool catalog that emulates the standard server/discover semantics:
package com.example.mcp.server;
import java.util.List;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestHeader;
import org.springframework.web.bind.annotation.RestController;
@RestController
public class McpDiscoveryController {
private final OrderToolCatalog catalog;
public McpDiscoveryController(OrderToolCatalog catalog) {
this.catalog = catalog;
}
@GetMapping("/mcp/discover")
public List<OrderToolCatalog.ToolSpec> discover(
@RequestHeader(value = "X-Tenant-Id", defaultValue = "default") String tenantId,
@RequestHeader(value = "X-User-Id", defaultValue = "anonymous") String userId) {
return catalog.toolsFor(tenantId, userId);
}
}
This code is deliberately plain, because it only needs to demonstrate one thing:
No session object, no Map holding state, no initialize. Each request comes in with its own identity, the catalog is computed on the fly, and the result is returned immediately.
This is what "stateless" actually looks like in code. A real SDK's modern API will be more standardized than this hand-written layer (it handles transport framing, error codes, and SSE switching for you), but the skeleton has exactly this shape.
To verify adaptivity, start two instances (8081 and 8082), put a round-robin load balancer in front, and call /mcp/discover twice in a row—you'll find the two calls land on different instances—whereas in the old session-based model, this would fail outright.
8. Upgrade Checklist
When you actually upgrade, go through this order once and you'll save most of the rework:
-
First, confirm the imported packages: after upgrading, check whether anything still references
io.modelcontextprotocol.modern. Just changing the dependency version number doesn't count as a completed upgrade—you may still be running the old protocol - Check for implicit session dependencies: anything stored in a member variable that changes based on the caller must move to the request context. A typical example is implementations like "the mode set by the previous call"
- Compute the tool catalog per request: if there's filtering logic in the catalog (by tenant, by role), make sure it's a pure function that doesn't read static mutable state
- Switch short requests back to JSON: for endpoints that previously wrapped everything in SSE for compatibility, decide one by one whether they can go back to a one-shot response
- Load test two dimensions: single-instance throughput, and the success rate under multi-instance round-robin. The latter is the core benefit of this upgrade—not testing it means you haven't verified anything
- Watch the logs for cross-contamination of tenant/user: the biggest fear with statelessness isn't performance—it's data crossing identities
One more thing to add about point 6. The cost of statelessness is this: the framework no longer manages context for you, so you have to make sure it isn't lost. And the consequence of losing it isn't an error — it's silently running as someone else. That's the hardest kind of bug to track down.
9. Should You Wait for 3.0?
Some people will ask: is it safer to wait until 3.0 is stable before upgrading?
It depends:
- New projects should go straight to modern. The official stateless server has already passed all required conformance scenarios as of 2026-07-28 — this isn't a paper feature
- Older projects don't need to wait, but there's no rush either. The old APIs haven't been removed or marked deprecated, so they'll keep running just fine
- The one case worth acting on now: if your MCP Server is being tortured by multi-replica deployments, this release is here to solve exactly that, and it's worth scheduling a dedicated migration
The official line that "the modern API may still change before 3.0" isn't a warning, it's a reminder — don't pile heavy abstractions on top of it until the API is finalized.
Top comments (0)