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