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 responses
  • DefaultMcpStatelessServerHandler now preserves McpError exceptions instead of converting them to INTERNAL_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 specific McpTransportException for transport-layer errors
  • Enhanced error messages with additional context (status codes, response events)
  • Breaking Change: Code catching McpError for transport errors should now catch McpTransportException

• HTTP Request Customization (#466): Fixed httpRequestCustomizer usage in HttpClientStreamableHttpTransport

  • 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 and WebFluxStreamableIntegrationTests now extend AbstractMcpClientServerIntegrationTests
  • WebFluxStatelessIntegrationTests and WebMvcStatelessIntegrationTests now extend AbstractStatelessIntegrationTests
  • 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 catch McpTransportException 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 with protocolVersions() returning List<String>
• Added backward compatibility for MCP servers returning older protocol versions
• Streamable HTTP clients now support both 2024-11-05 and 2025-03-26 protocol versions
• Introduced ProtocolVersions interface with centralized version constants
• Fixes compatibility issues with MCP servers that incorrectly return 2024-11-05 instead of 2025-03-26

HTTP Header Standardization (#449, #448)

• Use Last-Event-ID instead of last-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, and McpStreamableServerSession

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 and title 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

1. Request Interface Extension (#352) - Added PaginatedRequest and ReadResourceRequest to sealed interface (update switch statements)
2. 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 and definitions 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

MCP Java SDK Bug Fix Release

Fix StdioServerTransportProvider initialization flow #74

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