Repository navigation
Highlights
This release adds support for the 2026-07-28 MCP specification revision: a stateless server and a client in io.modelcontextprotocol.modern, next to the existing (legacy) client and server, which are unchanged.
The 2026-07-28 specification brought breaking changes to the protocol, and completely revamped the Streamable HTTP. This new protocol is stateless, and drops the concept of session entirely. The Java SDK already has a subset of the older protocol that is stateless (see for example McpStatelessSyncServer and HttpServletStatelessServerTransport). To differentiate this "modern, stateless" protocol from the "legacy, stateless" implementation, the new protocol implementation lives in the io.modelcontextprotocol.modern package, with io.modelcontextprotocol.modern.server.McpServer and io.modelcontextprotocol.modern.client.McpClient as entrypoints.
The modern API may still change in minor releases until 3.0.
- Modern stateless server for MCP 2026-07-28 by @chemicL in #1170
- 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, so features can be written in either style.
- Your own catalogs: tools, resources and prompts come from repositories you implement, so per-tenant, filtered and paginated catalogs are straightforward.
- Stream only when it pays: handlers return plain JSON or SSE, user code decides.
- Passes all required 2026-07-28 server conformance scenarios.
- Modern client for MCP 2026-07-28 by @chemicL in #1325
- No
initializehandshake. A client stands for one user, does no I/O when built, and can share its transport with other clients. - Built with
McpClient.sync(transport)/McpClient.async(transport), with a request spec per operation, e.g.client.tool("create_issue").arguments(args).call(). - Handles the
_metablock, version renegotiation, multi round-tripinput_requiredresults (form and URL elicitation),Mcp-*/Mcp-Param-*headers,subscriptions/listen,server/discoverand tool listing caching based onttlMs. - Streamable HTTP (JDK
HttpClient) and STDIO transports. Sampling, roots, logging and extensions are not supported yet. - Passes the non-auth 2026-07-28 client conformance scenarios.
- No
- Roots, sampling and logging are deprecated following SEP-2577 by @Kehrlann in #1334. This covers the APIs that initiate these features (e.g.
addRoot,setLoggingLevel,createMessage,listRoots,loggingNotificationand the capability builder methods). The handler registration methods are not deprecated, since peers may still use them. Behavior and wire format are unchanged. - New documentation covering legacy and modern clients and servers, with sync and async examples, by @tzolov in #1329 and b8f43af. See MCP Server (2026-07-28) and MCP Client (2026-07-28).
⚠️ Breaking changes
For all users
McpTransportContextno longer has content-basedequals/hashCode. Read entries withget(String)instead, by @chemicL in #1288
For users of the modern server preview (2.2.0-M1 / 2.2.0-M2)
- Repositories return a handler from
findby @chemicL in #1282 - Prompts and resource templates define their own completions.
CompletionsFeatureandMcpSync/AsyncCompletionRepositoryare removed; useMcpSyncPrompt.withCompletionHandler,McpSyncResourceTemplateandsupportsCompletion()on the repository, by @chemicL in #1316 McpParamHeadersis replaced byMcpHeaders, which also carries theMcp-Nameheader, by @Kehrlann in #1335InputResponses.getandRequestStateCodec.openreturnnullinstead of an emptyOptional, by @chemicL in #1325
🚀 New features
Modern server (2026-07-28)
- Enforce required client capabilities by @chemicL in #1283
- Validate SEP-2243
Mcp-Paramheaders by @Kehrlann in #1286 - Forward the
Mcp-Nameheader in theMcpTransportContext, for extension validation, by @Kehrlann in #1335 - Restrict resource subscriptions per caller with
McpServer.Builder#restrictSubscriptionsby @Kehrlann in #1332 - Reject legacy
initializerequests withUnsupportedProtocolVersion, listing the supported versions, by @Kehrlann in #1333 - Reject
Mcp-*headers with more than one value by @Kehrlann in #1323 subscriptions/listenwithoutparamsornotificationsreturns an error by @Kehrlann in #1324
Core
- Add
McpTransportContext#putAll(Map)by @chemicL in #1288 - Use JSpecify for nullability annotations, replacing Reactor's
@Nullable, by @Kehrlann in #1331
🐞 Bug fixes
- Streamable HTTP server: send SSE status and headers as soon as the stream opens, instead of on the first event, by @Kehrlann in #1310
HttpServletStreamableServerTransportProvider: avoid completing the async context twice by @Kehrlann in #1308HttpClientStreamableTransport: fix a race condition on 404 responses that cancelled the request instead of propagating the error, by @Kehrlann in #1306- Require a numeric port in wildcard Host/Origin matching by @anzal1 in #1193
LoggingMessageNotification#dataaccepts non-String payloads by @Kehrlann in #1201- Standardize SSE response headers by @Kehrlann and @Debasishhh in #1204
- Fix race condition in the tools list filter by @Kehrlann in #1260
- Notify resources
list_changedwhen removing a resource template by @subhashpolisetti in #1266 - Modern servlet transport: fix
Content-Typevalidation by @tarun-agarwal1044 in #1207 - Modern server: fix race condition in
subscriptions/listenby @Kehrlann in #1327
📦 Dependency upgrades
io.projectreactor:reactor-bom2024.0.0 → 2026.0.0-RC1 by @chemicL in #1191 and @Kehrlann in #1267org.jspecify:jspecify1.0.0 (new) by @Kehrlann in #1331com.fasterxml.jackson.core:jackson-databind2.21.1 → 2.22.4 andjackson-annotations2.21 → 2.22 by @Kehrlann in #1267 (and #1233)tools.jackson.core:jackson-databind3.1.4 → 3.1.8 in #1238com.networknt:json-schema-validator2.0.4 → 2.0.8 and 3.0.6 → 3.0.8 by @Kehrlann in #1259org.slf4j:slf4j-api2.0.16 → 2.0.20 in #1224mcp-testno longer depends on Spring by @Kehrlann in #1258
Build and test dependencies (JUnit, Mockito, Testcontainers 2, Tomcat, Maven plugins, …) were also updated.
🙏 Contributors
Thanks to everyone who contributed to this release: @chemicL, @Kehrlann, @tzolov, @anzal1, @tarun-agarwal1044, @subhashpolisetti and @Debasishhh.
New Contributors
- @anzal1 made their first contribution in #1193
- @tarun-agarwal1044 made their first contribution in #1207
- @subhashpolisetti made their first contribution in #1266
- @Debasishhh made their first contribution in #1204
Full Changelog: v2.1.0...v2.2.0