Releases: modelcontextprotocol/java-sdk
v0.11.2
Bug Fix Release
Server-Sent Events (SSE) Improvements
- Enhanced SSE Comment Handling (#467): Added proper support for SSE comment lines starting with ':' according to SSE specification
- Comment lines are now properly ignored during processing
- Added debug logging for comment line processing
- Improves compatibility with SSE streams that include comment messages
Error Handling Enhancements
- Handler Exception Support (#465): Stateless Server Handlers can now throw
McpError
exceptions for proper RPC error responsesDefaultMcpStatelessServerHandler
now preservesMcpError
exceptions instead of converting them toINTERNAL_ERROR
- Enables handlers to send appropriate error codes (not found, validation errors, etc.) to clients
- Maintains full compatibility with MCP RPC error specification
HTTP Transport Layer
-
Streamable HTTP Session Management (#469): Fixed session reinitialization behavior to comply with MCP specification
- Servers now properly handle session termination with HTTP 404 responses
- Clients correctly detect terminated sessions and start new sessions without session IDs
- Replaced generic
McpError
with specificMcpTransportException
for transport-layer errors - Enhanced error messages with additional context (status codes, response events)
- Breaking Change: Code catching
McpError
for transport errors should now catchMcpTransportException
-
HTTP Request Customization (#466): Fixed
httpRequestCustomizer
usage inHttpClientStreamableHttpTransport
- Resolves configuration issues with HTTP client request customization
Test Infrastructure Improvements
- Test Code Refactoring (#473): Major cleanup of integration test structure
- Extracted common test logic into abstract base classes
WebFluxSseIntegrationTests
andWebFluxStreamableIntegrationTests
now extendAbstractMcpClientServerIntegrationTests
WebFluxStatelessIntegrationTests
andWebMvcStatelessIntegrationTests
now extendAbstractStatelessIntegrationTests
- Eliminated ~1,300+ lines of duplicated test code
- Improved maintainability through centralized, reusable test logic
- Each test class now focuses only on transport-specific setup methods
📋 Summary
This release focuses on improving the robustness and compliance of the MCP implementation with several key enhancements:
- Better SSE specification compliance with comment line handling
- Improved error handling capabilities for custom handlers
- MCP specification-compliant session management for streamable HTTP
- Significant reduction in code duplication through test refactoring
Migration Notes
- Minor Breaking Change: If your code catches
McpError
for transport-related errors, update to catchMcpTransportException
instead - Minor Breaking Change: Error handling logic that assumes all 404/400 responses are session errors may need updates to handle the more specific error handling
All changes maintain backward compatibility except for the specific exception type changes noted above.
Full Changelog: v0.11.1...v0.11.2
v0.11.1
MCP Java SDK Bug-fix Release
🔧 Protocol Compatibility & Transport Improvements
Multi-Protocol Version Support (#444)
- Breaking Change: Replaced
protocolVersion()
method withprotocolVersions()
returningList<String>
- Added backward compatibility for MCP servers returning older protocol versions
- Streamable HTTP clients now support both
2024-11-05
and2025-03-26
protocol versions - Introduced
ProtocolVersions
interface with centralized version constants - Fixes compatibility issues with MCP servers that incorrectly return
2024-11-05
instead of2025-03-26
HTTP Header Standardization (#449, #448)
- Use
Last-Event-ID
instead oflast-event-id
(HTML spec compliance) - Removed duplicate
MCP_PROTOCOL_VERSION
header definitions
🐛 Bug Fixes
Logging Improvements (#457)
- Downgraded unhandled notification logging from error to warning level
- Enhanced logging context by including full notification object instead of just method name
- Affects
McpClientSession
,McpServerSession
, andMcpStreamableServerSession
Client Initialization Fix (#438)
- Fixed "Client failed to initialize by explicit API call" error
- Corrected stream handling in message delivery for empty responses (notify cases)
- Ensured proper
sink.next()
execution in all scenarios
🔍 Completed Changes
- 5 pull requests successfully merged or closed
- Focus on protocol compatibility, bug fixes, and consistency improvements
Note: This release includes important protocol compatibility improvements and some breaking API changes. Please review the migration guide before upgrading.
Full Changelog: v0.11.0...v0.11.1
v0.11.0
MCP Java SDK Release Notes
🚀 Major Features
New Transport Options
- WebMVC and HttpServlet Support (#432) - Added stateless server transports for Spring WebMVC and servlet-based applications with comprehensive integration tests
- Spring WebMVC Streamable Transport (#425) - Non-reactive MCP server support with HTTP/SSE transport, session management, and graceful shutdown
- Streamable HTTP Transport (#420, #290, #292) - Complete HTTP transport abstractions with WebFlux, HttpServlet, and WebClient implementations
- Enhanced WebClient Support - More resilient client transport with dynamic session allocation and improved failure handling
Connection Management
- MCP-Compliant Keep-Alive (#430) - Configurable periodic session pings with
KeepAliveScheduler
utility (disabled by default) - HTTP Request Customization (#388) - New customizer APIs for adding OAuth2 tokens, API keys, and other request modifications
🔧 Protocol & Standards
MCP Protocol Compliance
- Protocol Version Headers (#404) - Added required MCP-Protocol-Version headers (2025-06-18 for streamable HTTP, 2024-11-05 for SSE)
- JSON-RPC Method Filtering (#417) - Gracefully handle unknown methods with configurable ignorable method lists
- Enhanced Error Handling (#423, #413, #391) - Better compatibility with non-compliant servers, improved SSE event handling, and detailed error reporting
🛠️ API Improvements
Tool System Enhancements
- Builder Pattern for Tools (#375) - New
CallToolRequest
handlers replace arguments-only handlers with full request context - Structured Output Support (#357) - Server-side validation with
JsonSchemaValidator
and extended schema support - Duplicate Tool Validation - Automatic validation during server building and runtime registration
Schema & Type Updates
- Progress Token Support (#352) - Meta parameter support for long-running operations with extended Request interface
- Metadata Fields (#368) - Added
_meta
field across MCP schema classes andtitle
fields (#372) for better UX - Resource Enhancements (#331) - Added optional
size
property and improved resource update notifications (#264)
Client & Server Features
- Pagination Support (#336, #306) - Automatic pagination for
listRoots
and other list operations - Ping Functionality (#347) - Added ping methods to server exchanges across all transport types
- Client Initialization (#424) - Exposed client initialization result with better access to state
- Immediate Execution Option (#371) - Disable blocking code offloading for ThreadLocal propagation scenarios
🐛 Key Bug Fixes
- Fixed timeout issues (#350) in server response handling
- Resolved duplicate requests (#333) from concurrent message sending
- Corrected CallToolRequest deserialization (#355) in async servers
- Fixed content annotations modeling (#242) to match specification
- Improved sampling stop reason handling (#327) for arbitrary values
- Return immutable lists (#345) from list methods for better safety
- Added AutoCloseable interface (#397) for try-with-resources support
🔄 Breaking Changes
- Request Interface Extension (#352) - Added
PaginatedRequest
andReadResourceRequest
to sealed interface (update switch statements) - Implementation Title Field (#343) - Added required title parameter to
McpSchema.Implementation
📦 Migration Guide
Deprecated (Still Supported)
- Arguments-only tool handlers → Use
CallToolRequest
handlers - Old transport constructors → Use builder patterns
- Some
McpClientSession
constructors → Use Context-aware versions
Recommended Updates
- Adopt builder patterns for transport providers and tool specifications
- Update exception handling for specific exception types
- Implement new
CallToolRequest
handlers for better tool context
What's Changed
- Refactor package structure and dependencies by @tzolov in #1
- Change license from Apache to MIT by @tzolov in #3
- Remove redundand code by @tzolov in #5
- Reorder StdioServerTransport shutdown procedure to avoid errors by @chemicL in #7
- Change the top domain from org to io by @tzolov in #8
- Convert asciidoc/antora docs to mintlify by @markpollack in #6
- docs: add Spring AI MCP documentation and improve README clarity by @tzolov in #12
- Fix issue, SSE connection will terminate after 30 seconds (DEFAULT). by @zekozhang in #21
- Remove closed sessions from list in WebMvcSseServerTransport by @denniskawurek in #19
- Fix some typos by @CrazyHZM in #22
- Resources and prompts cannot be added after server start by @marianogonzalez in #18
- Add OSGi Metadata Generation by @konczdev in #10
- refactor(client): improve validation and remove server methods by @tzolov in #14
- Update README with Maven wrapper commands and test prerequisites by @tzolov in #23
- refactor(mcp): remove redundant type field from Content implementations by @tzolov in #27
- feat(mcp): relax MCP Schema JSON deserialization constraints by @tzolov in #37
- feat(client): Improve initialization state handling in McpAsyncClient by @tzolov in #39
- chore: Make closeLatch a final. by @He-Pin in #32
- Add CI GitHub Action and rename snapshot publish workflow by @chemicL in #49
- Update README.md by @tzolov in #50
- refactor: improve MCP client timeout handling and reactive testing by @tzolov in #51
- Improve client test reliability and execution time by @chemicL in #52
- Follow-up fix client tests reliability by @chemicL in #54
- Sync async client tests between mcp and mcp-test module by @chemicL in #55
- refactor(McpSchema): convert StopReason enum values to camelCase by @tzolov in #58
- feat(mcp): Add builder for CreateMessageRequest by @tzolov in #60
- (pom) Enable automatic publishing to Maven Central by @tzolov in #63
- refactor(server): Fix StdioServerTransportProvider initialization flow by @tzolov in #74
- fix(tests): Failed to start process with command npx on Windows by @codeboyzhou in #85
- fix: add support to set server instructions by @codezjx in #99
- feat(mcp): Custom context paths in HTTP Servlet SSE server transport by @tzolov in #112
- refactor: change notification params type from Map<String,Object> to Object by @tzolov in #137
- fix: Add null check for session in WebFluxSseServerTransportProvider by @tzolov in #138
- add access to server instructions by @jamesward in #148
- feat(completion): fix the schema about CompleteResult by @DamonBao in #173
- Fix method not found error msg for server by @CrazyHZM in #171
- fix typo in WebFluxSseIntegrationTests by @jitokim in #142
- feat(schema): add support for JSON Schema $defs and definitions by @arcaputo3 in #146
- Fix javadoc errors by @xiaowangzhixiao in #149
- fix: propagate reactor context up till transport by @FH-30 in #154
- feat: Add URI template support for MCP resources by @tzolov in #208
- add isInitialized method to McpSyncClient by @jitokim in #181
- Remove temporary delegate impl from McpAsyncServer by @chemicL in #228
- Fix stdio tests - proper server-everything argument by @chemicL in #237
- Fix flaky WebFluxSse integration test by @chemicL in #238
- Add Contributing Guidelines and Code of Conduct by @chemicL in #236
- WebClient Streamable HTTP support by @chemicL in #292
- Fix Streamable HTTP WebClient GET SSE handling by @chemicL in https://github.com/m...
v0.10.0
MCP Java SDK Release Notes
Features
-
URI Template Support (PR #208): Added URI template functionality for MCP resources, allowing dynamic resource URIs with variables in the format
{variableName}
. This enables:- More flexible resource definitions
- Automatic extraction of variable values from request URIs
- Validation of template arguments in completions
- Matching of request URIs against templates
-
Completion Feature (PR #173): Added support for the completion feature according to the MCP specification, enabling auto-completion suggestions in client applications.
-
JSON Schema Improvements (PR #146): Added support for
$defs
anddefinitions
properties in JsonSchema record to handle JSON Schema references properly, enabling more complex schema structures with reusable components. -
Server Instructions Access (PR #148): Enabled the MCP Client to read the Server instructions, exposing optional instruction data defined in the MCP specification.
Bug Fixes
- Context Propagation (PR #154): Fixed context propagation to transport, ensuring reactor context is properly propagated up to the transport layer.
- Code Cleanup (PR #228): Removed temporary delegate implementation from McpAsyncServer that was left after deprecation.
- Error Messages (PR #171): Fixed "method not found" error message for server, improving error reporting.
- Documentation (PR #149): Fixed javadoc errors for improved API documentation.
Contributors
We'd like to thank the following contributors for their work on this release:
- Christian Tzolov (@tzolov)
- DamonBao
- Richie Caputo (@arcaputo3)
- James Ward (@jamesward)
- Francis Hodianto (@FH-30)
- Dariusz Jędrzejczyk (@chemicL)
- Jermaine Hua (@CrazyHZM)
- wangzhi (@xiaowangzhixiao)
v0.9.0
MCP Java SDK Release Notes
Breaking Changes ⚠️
There is one minor API breaking change that should not cause significant issues:
The type of the McpSchema.JSONRPCNotification
params
field has been changed from Map<String, Object>
to Object
.
This affects the signature of the sendNotification
method in both McpClientSession
and McpServerSession
and
the signature of the notifyClients
method in McpServerTransportProvider
.
New Features
Transport Layer Enhancements
- Custom Context Paths: Enhanced HTTP Servlet SSE server transport to support deployment under non-root context paths (PR #112)
Server Configuration Improvements
- Server Instructions: Added support for setting server instructions, providing consistency with the Python SDK implementation (PR #99)
Developer Experience
- CallToolResult Enhancement: Added a constructor to CallToolResult that accepts a single String parameter for simpler API usage (PR #87)
Bug Fixes
Error Handling & Reliability
- Session Validation: Added error handling to return a 404 NOT_FOUND response when a request is made with a non-existent session ID (PR #138)
- Windows Compatibility: Fixed process startup issues when running tests on Windows systems (PR #85)
Refactoring & Technical Improvements
API Improvements
- Notification Parameters: Changed notification parameters type from Map<String,Object> to Object for more flexible parameter passing (PR #137)
- Refactored logging system to use exchange mechanism (PR #132)
Closed & Merged PRs Without Release Impact
- Various closed PRs related to HTTP protocol handling, typo fixes, and alternative implementations
Contributors
Special thanks to all contributors who helped improve the MCP Java SDK:
- @Aliaksie (Aliaksei)
- @tzolov (Christian Tzolov)
- @chemicL (Dariusz Jędrzejczyk)
- @EvanMi
- @noear (西东)
- @codezjx
- @codeboyzh (codeboyzz)
- @denniskawurek (Dennis Kawurek)
This release includes enhancements to transport mechanisms, improved server configuration options, better cross-platform compatibility, and various other improvements to the MCP Java SDK.
v0.8.1
v0.8.0
MCP Java SDK Release Notes
Breaking Changes ⚠️
Follow the 0.8.0 Migration Guide for the new API changes.
Features & Enhancements
Architecture Improvements
- Introduced session-based architecture for MCP server to better handle multiple concurrent client connections (#31)
- Added McpServerTransportProvider interface to manage client connections
- Introduced exchange objects (McpAsyncServerExchange, McpSyncServerExchange) for client interaction
- Updated handler signatures to include exchange parameter
- Renamed various interfaces and classes for better alignment with MCP specification
- Added migration guide (migration-0.8.0.md) for transitioning to the new architecture
API Improvements
- Added builder pattern for CreateMessageRequest, improving usability and readability when creating message requests (#60)
- Relaxed MCP Schema JSON deserialization constraints by adding
@JsonIgnoreProperties(ignoreUnknown = true)
to all record classes, improving compatibility with third-party implementations (#37)
Client Enhancements
- Improved initialization state handling in McpAsyncClient with proper state tracking using AtomicBoolean and Sinks (#39)
- Added OSGi metadata generation support using bnd-maven-plugin to enable proper OSGi bundle creation (#10)
Build & Deployment
- Enabled automatic publishing to Maven Central when releases are performed (#63)
Bug Fixes
Protocol Compliance
- Fixed CreateMessageRequest includeContext enum values to match MCP specification (changed from snake_case to camelCase) (#44)
- Converted StopReason enum values from snake_case to camelCase for consistency (#58)
Connection & Session Management
- Fixed issue where SSE connection would terminate after 30 seconds (DEFAULT) (#21)
- Removed closed sessions from list in WebMvcSseServerTransport to prevent errors when broadcasting to outdated sessions (#19)
- Fixed issue where resources and prompts could not be added after server start (#18)
Testing & Reliability
- Improved client test reliability and execution time using VirtualTimeScheduler (#52)
- Fixed duplicated connection to testcontainer MCP server in client tests (#54)
- Synced async client tests between mcp and mcp-test modules (#55)
Refactoring & Code Quality
Client Improvements
- Improved MCP client timeout handling with configurable initialization timeout separate from request timeout (#51)
- Enhanced validation and removed server-side notification methods from client (#14)
- Removed redundant type field from Content implementations (#27)
Documentation Updates
- Added Spring AI MCP documentation section with links to client/server starters (#12)
- Updated README with Maven wrapper commands and test prerequisites (#23)
- Fixed build status badge in README (#50)
- Fixed various typos throughout the codebase (#22)
- Made closeLatch a final field (#32)
Contributors
- Christian Tzolov (@tzolov)
- Dariusz Jędrzejczyk (@chemicL)
- Jermaine Hua (@CrazyHZM)
- Piotr Roterski (@roterski)
- Dennis Kawurek (@denniskawurek)
- Mariano Gonzalez (@marianogonzalez)
- zeko zhang (@zekozhang)
- konczdev (@konczdev)
- He-Pin(kerr) (@He-Pin)
What's Changed Log
- Refactor package structure and dependencies by @tzolov in #1
- Change license from Apache to MIT by @tzolov in #3
- Remove redundand code by @tzolov in #5
- Reorder StdioServerTransport shutdown procedure to avoid errors by @chemicL in #7
- Change the top domain from org to io by @tzolov in #8
- Convert asciidoc/antora docs to mintlify by @markpollack in #6
- docs: add Spring AI MCP documentation and improve README clarity by @tzolov in #12
- Fix issue, SSE connection will terminate after 30 seconds (DEFAULT). by @zekozhang in #21
- Remove closed sessions from list in WebMvcSseServerTransport by @denniskawurek in #19
- Fix some typos by @CrazyHZM in #22
- Resources and prompts cannot be added after server start by @marianogonzalez in #18
- Add OSGi Metadata Generation by @konczdev in #10
- refactor(client): improve validation and remove server methods by @tzolov in #14
- Update README with Maven wrapper commands and test prerequisites by @tzolov in #23
- refactor(mcp): remove redundant type field from Content implementations by @tzolov in #27
- feat(mcp): relax MCP Schema JSON deserialization constraints by @tzolov in #37
- feat(client): Improve initialization state handling in McpAsyncClient by @tzolov in #39
- chore: Make closeLatch a final. by @He-Pin in #32
- Add CI GitHub Action and rename snapshot publish workflow by @chemicL in #49
- Update README.md by @tzolov in #50
- refactor: improve MCP client timeout handling and reactive testing by @tzolov in #51
- Improve client test reliability and execution time by @chemicL in #52
- Follow-up fix client tests reliability by @chemicL in #54
- Sync async client tests between mcp and mcp-test module by @chemicL in #55
- refactor(McpSchema): convert StopReason enum values to camelCase by @tzolov in #58
- feat(mcp): Add builder for CreateMessageRequest by @tzolov in #60
- (pom) Enable automatic publishing to Maven Central by @tzolov in #63
Full Changelog: v0.6.0...v0.8.0