Repository navigation
Releases
v2.2.0
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
v2.2.0-M2
What's Changed
⚠️ Breaking changes
This affects the modern server (2026-07-28 preview).:
🚀 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-Paramheaders in the modern server by @Kehrlann in #1286 - Add
putAll(Map)toMcpTransportContextby @chemicL in #1288McpTransportContextno longer has content-basedequals/hashCode.
- Document the 2026-07-28 modern server preview (b8f43af)
🐞 Bug fixes
- Require a numeric port in wildcard Host/Origin matching by @anzal1 in #1193
LoggingMessageNotification#dataaccepts non-String payload by @Kehrlann in #1201- Standardize SSE response headers by @Kehrlann in #1204
- Fix modern servlet transport Content-Type validation by @tarun-agarwal1044 in #1207
- Fix race condition in tools list filter by @Kehrlann in #1260
- Notify resources
list_changedwhen removing a resource template by @subhashpolisetti in #1266
📦 Dependency upgrades
- Bump
com.networknt:json-schema-validator2.0.4 -> 2.0.8 and 3.0.6 -> 3.0.8 by @Kehrlann in #1259 - Bump
com.fasterxml.jackson.core:jackson-annotationsfrom 2.21 to 2.22 @Kehrlann in #1267 - Bump
io.projectreactor:reactor-bomfrom 2024.0.0 to 2024.0.18 by @dependabot[bot] in #1239 - Bump
com.fasterxml.jackson.core:jackson-databindfrom 2.21.1 to 2.21.8 by @dependabot[bot] in #1233 - Bump
tools.jackson.core:jackson-databindfrom 3.1.4 to 3.1.8 by @dependabot[bot] in #1238 - Bump
org.slf4j:slf4j-apifrom 2.0.16 to 2.0.20 by @dependabot[bot] in #1224 - Bump
ch.qos.logback:logback-classicfrom 1.6.5 to 1.6.6 by @dependabot[bot] in #1305
New Contributors
- @anzal1 made their first contribution in #1193
- @tarun-agarwal1044 made their first contribution in #1207
- @subhashpolisetti made their first contribution in #1266
Full Changelog: v2.2.0-M1...v2.2.0-M2
v2.2.0-M1
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 legacyMcpSchema, 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
Highlights
- Tool list filtering #1108 by @Kehrlann
- HTTP client transport rework:
HttpClient-based transports are nowPublisher-based, and request customizers compose on the builders.
Enhancements
- extensions attribute on
ClientCapabilitiesandServerCapabilities(SEP-2133). #1064 by @YousefHaggy ServerHttpHeaderValidatorreplacesServerTransportSecurityValidator. #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
sendMessageis 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/removeRootwhen rootslistChangedis 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
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
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
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
- @jstar0 made their first contribution in #996
- @ammbra made their first contribution in #1044
- @maff made their first contribution in #800
- @bperhaps made their first contribution in #835
- @iaJingda made their first contribution in #913
- @nanookclaw made their first contribution in #954
- @iuliiasobolevska made their first contribution in #1076
Full Changelog: v2.0.0...v2.0.1
v1.1.4
v0.18.4
v2.0.0
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
JsonSchemaand use aMapforinputSchemato 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
metaparameter 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 ofhttpRequestCustomizer()by @gyeo009 in #791 - Expose request URI in
McpHttpClientAuthorizationErrorHandlerby @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
ResourceandResourceTemplateby @chemicL in #947 - Clarify tool validation error messages by @tzolov in #1023
- Return void from
McpStatelessSyncServer#closeGracefullyinstead ofMonoby @tzolov in #1019 - fix: add missing
Export-Packageto 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
- @sleepytomcat made their first contribution in #874
- @radeshgovind-2005 made their first contribution in #891
- @gyeo009 made their first contribution in #791
- @rameshreddy-adutla made their first contribution in #850
- @smohite04 made their first contribution in #906
- @bilaloumehdi made their first contribution in #749
- @sainathreddyb made their first contribution in #912
- @joaodinissf made their first contribution in #911
Full Changelog: v1.1.0...v2.0.0