Skip to content

v2.2.0

Latest

Choose a tag to compare

@Kehrlann Kehrlann released this 16 Nov 10:37
· 4 commits to main since this release

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 initialize handshake. 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 _meta block, version renegotiation, multi round-trip input_required results (form and URL elicitation), Mcp-* / Mcp-Param-* headers, subscriptions/listen, server/discover and tool listing caching based on ttlMs.
    • 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.
  • 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, loggingNotification and 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

  • McpTransportContext no longer has content-based equals/hashCode. Read entries with get(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 find by @chemicL in #1282
  • Prompts and resource templates define their own completions. CompletionsFeature and McpSync/AsyncCompletionRepository are removed; use McpSyncPrompt.withCompletionHandler, McpSyncResourceTemplate and supportsCompletion() on the repository, by @chemicL in #1316
  • McpParamHeaders is replaced by McpHeaders, which also carries the Mcp-Name header, by @Kehrlann in #1335
  • InputResponses.get and RequestStateCodec.open return null instead of an empty Optional, by @chemicL in #1325

🚀 New features

Modern server (2026-07-28)

  • Enforce required client capabilities by @chemicL in #1283
  • Validate SEP-2243 Mcp-Param headers by @Kehrlann in #1286
  • Forward the Mcp-Name header in the McpTransportContext, for extension validation, by @Kehrlann in #1335
  • Restrict resource subscriptions per caller with McpServer.Builder#restrictSubscriptions by @Kehrlann in #1332
  • Reject legacy initialize requests with UnsupportedProtocolVersion, listing the supported versions, by @Kehrlann in #1333
  • Reject Mcp-* headers with more than one value by @Kehrlann in #1323
  • subscriptions/listen without params or notifications returns 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 #1308
  • HttpClientStreamableTransport: 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#data accepts 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_changed when removing a resource template by @subhashpolisetti in #1266
  • Modern servlet transport: fix Content-Type validation by @tarun-agarwal1044 in #1207
  • Modern server: fix race condition in subscriptions/listen by @Kehrlann in #1327

📦 Dependency upgrades

  • io.projectreactor:reactor-bom 2024.0.0 → 2026.0.0-RC1 by @chemicL in #1191 and @Kehrlann in #1267
  • org.jspecify:jspecify 1.0.0 (new) by @Kehrlann in #1331
  • com.fasterxml.jackson.core:jackson-databind 2.21.1 → 2.22.4 and jackson-annotations 2.21 → 2.22 by @Kehrlann in #1267 (and #1233)
  • tools.jackson.core:jackson-databind 3.1.4 → 3.1.8 in #1238
  • com.networknt:json-schema-validator 2.0.4 → 2.0.8 and 3.0.6 → 3.0.8 by @Kehrlann in #1259
  • org.slf4j:slf4j-api 2.0.16 → 2.0.20 in #1224
  • mcp-test no 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

Full Changelog: v2.1.0...v2.2.0