Skip to content

Releases

v2.2.0

Choose a tag to compare

@Kehrlann Kehrlann released this 16 Nov 10:37

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

v2.2.0-M2

v2.2.0-M2 Pre-release
Pre-release

Choose a tag to compare

@tzolov tzolov released this 13 Nov 18:31

What's Changed

⚠️ Breaking changes

This affects the modern server (2026-07-28 preview).:

  • Return a handler from find in modern server repositories by @chemicL in #1282

🚀 New features

These affect the modern server (2026-07-28 preview).:

  • Enforce required client capabilities in the modern server by @chemicL in #1283
  • Validate SEP-2243 Mcp-Param headers in the modern server by @Kehrlann in #1286
  • Add putAll(Map) to McpTransportContext by @chemicL in #1288
    • McpTransportContext no longer has content-based equals/hashCode.
  • Document the 2026-07-28 modern server preview (b8f43af)

🐞 Bug fixes

📦 Dependency upgrades

  • Bump com.networknt:json-schema-validator 2.0.4 -> 2.0.8 and 3.0.6 -> 3.0.8 by @Kehrlann in #1259
  • Bump com.fasterxml.jackson.core:jackson-annotations from 2.21 to 2.22 @Kehrlann in #1267
  • Bump io.projectreactor:reactor-bom from 2024.0.0 to 2024.0.18 by @dependabot[bot] in #1239
  • Bump com.fasterxml.jackson.core:jackson-databind from 2.21.1 to 2.21.8 by @dependabot[bot] in #1233
  • Bump tools.jackson.core:jackson-databind from 3.1.4 to 3.1.8 by @dependabot[bot] in #1238
  • Bump org.slf4j:slf4j-api from 2.0.16 to 2.0.20 by @dependabot[bot] in #1224
  • Bump ch.qos.logback:logback-classic from 1.6.5 to 1.6.6 by @dependabot[bot] in #1305

New Contributors

Full Changelog: v2.2.0-M1...v2.2.0-M2

v2.2.0-M1

v2.2.0-M1 Pre-release
Pre-release

Choose a tag to compare

@chemicL chemicL released this 16 Oct 12:48
f2aaa76

Highlights

  • Modern stateless server for MCP 2026-07-28: #1170 by @chemicL

    The first step toward the stateless Streamable HTTP paradigm. It is a new server in io.modelcontextprotocol.modern, independent of the legacy McpSchema, and it passes all 37 required 2026-07-28 conformance scenarios.

    • No sessions: each request is handled on its own, which suits horizontally scaled deployments.
    • One server, sync or async: many concepts were simplified and allow the transport to choose whether to offload blocking code or not, freeing the user to use either a synchronous or asynchronous paradigm to implement features.
    • 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.
    • Not yet supported: a modern client, tasks and SEP-2243 custom headers.

Dependencies

Full Changelog: v2.1.0...v2.2.0-M1

v2.1.0

Choose a tag to compare

@chemicL chemicL released this 16 Oct 11:55

Highlights

Enhancements

  • extensions attribute on ClientCapabilities and ServerCapabilities (SEP-2133). #1064 by @YousefHaggy
  • ServerHttpHeaderValidator replaces ServerTransportSecurityValidator. #982 by @neerajbhatt
  • Streamable HTTP server session sweeping and keep-alive. #1130 by @Kehrlann
  • Remove the 2024-11-05 protocol from Streamable HTTP. #1126 by @Kehrlann
  • Reject non-application/json POST requests. #1164 by @Kehrlann

Bug fixes

  • Stream leak when resuming with LAST_EVENT_ID. #1127 by @Kehrlann
  • STDIO sendMessage is now thread-safe. #935 by @nquinquenel
  • Malformed request bodies return 400 INVALID_REQUEST with Jackson 3. #1168 by @Kehrlann
  • listXyz() methods return re-subscribable Monos. #1175 by @kamisheng
  • NPE when changing features on a server with derived capabilities. #1178 by @itzjb
  • NPE in addRoot/removeRoot when roots listChanged is unset. #1179 by @Kehrlann
  • Automatic-Module-Name no longer contains hyphens. #1135 by @Kehrlann
  • Log instead of aggregating exceptions in JSONRPCErrorResponse. #1182 by @Kehrlann

New contributors

@slachiewicz, @YousefHaggy, @kamisheng, @itzjb, @neerajbhatt and @nquinquenel

Full Changelog: v2.0.1...v2.1.0

v1.1.5

Choose a tag to compare

@Kehrlann Kehrlann released this 16 Oct 13:23

What's Changed

  • Fix error behavior on unregistered handlers in stateless server handler by @Kehrlann in #1109
  • Remove aggregate exception from JSONRPCErrorResponse, log instead by @Kehrlann in #1183
  • Streamable HTTP: Add session sweeping and close hanging streams by @Kehrlann in #1185

Full Changelog: v1.1.4...v1.1.5

v0.18.5

Choose a tag to compare

@Kehrlann Kehrlann released this 16 Oct 13:23

What's Changed

  • Fix error behavior on unregistered handlers in stateless server handler by @olsavmic in #1104
  • Reject non application/json POST requests by @Kehrlann in #1169
  • Remove aggregate exception from JSONRPCErrorResponse, log instead by @Kehrlann in #1184
  • Introduce session sweeping by @Kehrlann in #1187

New Contributors

Full Changelog: v0.18.4...v0.18.5

v2.0.1

Choose a tag to compare

@Kehrlann Kehrlann released this 19 Aug 13:47

What's Changed

  • Upgrade conformance suite to 0.1.16, Spring AI conformance to 2.0.0 GA by @Kehrlann in #1032
  • Return empty completion when no handler matches a valid ref by @jstar0 in #996
  • Close response after sending error in McpStreamableServerSession#responseStream by @Kehrlann in #1041
  • Fix error behavior on unregistered handlers in stateless server handler by @maff in #800
  • Remove invalid WARN message for missing notification handler in stateless servers by @bperhaps in #835
  • Fix SSE event classification to follow spec for missing event field by @iaJingda in #913
  • fix: stop pagination on empty cursors by @nanookclaw in #954
  • fix McpTransportContext.create() mutability issue and add tests by @iuliiasobolevska in #1076
  • Bound HTTP server and client reads by @Kehrlann in #1102
  • Bound STDIO server and client reads by @Kehrlann in #1103

Depedency updates

  • Bump json-schema-validator to 2.0.4 / 3.0.6, jackson to 2.21.1 / 3.1.4 by @joaodinissf in #1058

New Contributors

Full Changelog: v2.0.0...v2.0.1

v1.1.4

Choose a tag to compare

@Kehrlann Kehrlann released this 19 Aug 13:45

What's changed

  • Bound HTTP client and server reads (backported from #1102 by @Kehrlann)

Full Changelog: v1.1.3...v1.1.4

v0.18.4

Choose a tag to compare

@Kehrlann Kehrlann released this 19 Aug 13:44

What's changed

  • Bound HTTP client and server reads (backported from #1102 by @Kehrlann)

Full Changelog: v0.18.3...v0.18.4

v2.0.0

Choose a tag to compare

@chemicL chemicL released this 11 Jun 15:43

MCP Java SDK 2.0.0 🎉

We're thrilled to announce the General Availability of the MCP Java SDK 2.0.0 — the first major release since 1.x and the culmination of three milestones (M1, M2, M3) and a release candidate (RC1). It tracks the latest 2025-11-25 MCP specification and lays the groundwork for everything that comes next. Huge thanks to everyone who contributed, tested the milestones, and filed feedback along the way! ❤️

Upgrading from 1.x? See the v2 migration guide and the updated documentation (#1024) for a step-by-step walkthrough of the breaking changes below.

Highlights

  • A new JSON compatibility foundation for consistent forward/backward wire compatibility as the protocol evolves.
  • Spec-accurate schema with enforced required fields and lenient wire deserialization.
  • End-to-end validation of tool inputs and embedded JSON Schema documents (2020-12).
  • Richer elicitation: client-side schema defaults, URL elicitation, and form-based elicitation schemas.
  • Icons & metadata support (SEP-973) across the API.
  • Streamable HTTP first: SSE transports are now deprecated in favor of Streamable HTTP.
  • Cleaner, quieter logging with unified configuration and saner default levels.

⚠️ Breaking Changes

  • feat!: consistent JSON forward/backward compatibility — the 2.0 foundation by @chemicL in #927
  • feat!: enforce required MCP spec fields in McpSchema; lenient wire deserialization by @chemicL in #928
  • feat!: add tool input arguments validation (#697) by @ashakirin in #873
  • fix: Remove JsonSchema and use a Map for inputSchema to support JSON Schema dialects by @bilaloumehdi in #749

✨ New Features

  • feat: validate embedded JSON Schema documents against the 2020-12 meta-schema (SEP-1613) by @chemicL in #949
  • feat: Add SEP-973 icons and metadata support by @sainathreddyb in #912
  • feat: client-side application of elicitation schema defaults (SEP-1034) by @chemicL in #976
  • Add URL elicitation support (SEP-1036) by @Kehrlann in #993
  • Add schemas for form-based elicitation by @Kehrlann in #1020
  • feat: add support for meta parameter in client paginated list queries by @smohite04 in #906
  • Add 2025-11-25 spec version to all transports by @chemicL in #1025

🔌 Transports & Networking

  • Deprecate SSE transports (in favor of Streamable HTTP) by @Kehrlann in #950
  • Client transports: remove deprecated methods from builder by @Kehrlann in #899
  • Server transports: remove deprecated methods from builder by @Kehrlann
  • HttpClientStreamableHttpTransport: handle HTTP 405 by @Kehrlann
  • Validate message endpoint in SSE client transport by @Kehrlann in #943
  • DefaultSseMessageEndpointValidator allows same-origin message endpoints by @Kehrlann in #946
  • Deprecate Builder.customizeRequest() in favor of httpRequestCustomizer() by @gyeo009 in #791
  • Expose request URI in McpHttpClientAuthorizationErrorHandler by @Kehrlann in #980
  • Fix UTF-8 encoding for non-ASCII tool names in HTTP client transports by @rameshreddy-adutla in #850

🪵 Logging

🐛 Fixes & Polish

  • fix: avoid dropped errors when transport is closed or uninitialized by @chemicL in #995
  • fix: Return empty prompt completion result when prompt has no arguments by @chemicL in #934
  • Revert removed builders for Resource and ResourceTemplate by @chemicL in #947
  • Clarify tool validation error messages by @tzolov in #1023
  • Return void from McpStatelessSyncServer#closeGracefully instead of Mono by @tzolov in #1019
  • fix: add missing Export-Package to mcp-json-jackson2 and mcp-json-jackson3 by @joaodinissf in #911

📚 Docs & Conformance

  • Update documentation and migration notes for v2 by @chemicL in #1024
  • conformance-tests: upgrade to MCP-security 0.1.11, implement CIMD by @Kehrlann in #975
  • conformance: update to mcp-security 0.1.5, pass scope-step-up by @Kehrlann in #895
  • docs: document best practice for handling argument errors in MCP tools by @radeshgovind-2005 in #891
  • fix: proper URL links from README.md to 'Java Dependencies', 'Java MCP Client', 'Java MCP Server' pages by @sleepytomcat in #874

New Contributors

Full Changelog: v1.1.0...v2.0.0