v0.15.0

What's Changed

• define explicitely that values should always be included in code completions by @sdelamo in #601
• fix remove name when using @JsonTypeInfo(use = JsonTypeInfo.Id.DEDUCTION) by @sdelamo in #600
• refactor: change int to Integer for optional numeric fields by @tzolov in #604
• fix: allow additional properties by default per JSON Schema spec by @tzolov in #617
• Close McpTransportSession on transport close by @Kehrlann in #632
• Fix: McpAsyncClient#listTools prevent infinite recursion by @leehaut in #631
• chore: standardize client/server implementation names and version by @tzolov in #642
• Update dependencies minor versions to fix build on JDK 25 by @bedrin in #640
• Support o.s.h.HttpHeaders from both 6.x and 7.x Spring branches by @bedrin in #639

New Contributors

• @leehaut made their first contribution in #631
• @bedrin made their first contribution in #640

Full Changelog: v0.14.1...v0.15.0

v0.14.1

Full Changelog: v0.14.0...v0.14.1

v0.14.0

What's Changed

• refactor: Improve resource template management and API consistency by @tzolov @pascalconfluent #576
• fix: handle resource not found according to spec by @sdelamo in #567
• feat: add optional lastModified field to Annotations record by @tzolov in #568
• fix: typo MCP_SESSION_ID, keep consistent style with other identifiers by @JunJieLiu51520 in #564
• refactor: improve MCP server resilience and error handling by @tzolov in #579
• fix: when using JsonTypeInfo.DEDUCTION don’t add include by @sdelamo in #587
• Client: handle server responses with Content-Length: 0 by @Kehrlann in #588
• fix: Handle non-compliant notification responses by @tzolov in #589
• feat(client): add client tool output schema validation and caching by @pantanurag555 @tzolov @chemicL @Kehrlann #302

New Contributors

• @JunJieLiu51520 made their first contribution in #564

Full Changelog: v0.13.1...v0.14.0

v0.13.1

Full Changelog: v0.13.0...v0.13.1

v0.13.0

Release Notes

🚀 Major Features & Enhancements

Protocol Version Support

• Added MCP protocol version 2025-06-18 support for streamable-http and stateless transports (#558)
  • Set MCP_2025_06_18 as upper supported protocol version
  • Updated LATEST_PROTOCOL_VERSION constant to reflect new upper bound

Module Restructuring

• Extracted mcp-core module (#557) - ⚠️ BREAKING CHANGE

  • Created new mcp-core module free of Jackson dependencies
  • mcp module now serves as an umbrella module bringing together mcp-json-jackson2 and mcp-core
  • Classes are now in different JARs, which may affect classpath dependencies

• Jackson decoupling (#543) - Related to (#557)

  • Abstract away Jackson usage with SPI interfaces
    Creates two modules, mcp-json and mcp-json-jackson. It removes the com.fasterxml.jackson.core:jackson-databind and com.networknt:json-schema-validator dependencies from the mcp (now mcp-core) module. The mcp-core (mcp previously) module now only depends on com.fasterxml.jackson.core:jackson-annotations.
    To use Jackson, you have to add mcp-jackson to your dependencies in addition to mcp-core. I added the dependency mcp-jackson to both mcp-spring-mvc and mcp-spring-webflux to avoid a breaking change in those modules.

Enhanced Tool Output Support

• Support for array-type structured content in tools (#551) - ⚠️ BREAKING CHANGE
  • Changed CallToolResult.structuredContent type from Map<String,Object> to Object
  • Now supports both objects and arrays as structured content output
  • Updated JsonSchemaValidator to validate any Object type
  • Deprecated CallToolResult constructors in favor of builder pattern
  • Aligns with MCP specification requirements for array-type output schemas

🐛 Bug Fixes

Session Management

• Fixed LifecycleInitializer error recovery (#549)
  • Initializer can now recover from errors during doInitialize (e.g., HTTP errors)
  • Prevents getting stuck in error state and allows subsequent initialization calls to work
  • Particularly beneficial for OAuth2 token fetch scenarios

Serialization Improvements

• Added JsonInclude annotation to notification records (#552)
  • Enhanced proper JSON serialization for ResourcesUpdatedNotification and LoggingMessageNotification
  • Excludes absent (null/Optional.empty()) fields from serialized output
  • Ensures consistent serialization behavior across all notification types

Test Infrastructure

• Standardized test parameterization (#556)
  • Replaced @valuesource with @MethodSource for parameterized tests
  • Added consistent clientsForTesting() methods
  • Removed hardcoded Spring-related labels from framework-agnostic mcp-test module
  • Minor breaking change: moved utility classes from io.modelcontextprotocol.utils to io.modelcontextprotocol.util

⚠️ Breaking Changes Summary

1. Module Structure Changes (#557 and #543))

   • Classes previously in mcp are now in mcp-core. mcp module now serves as an umbrella module bringing together mcp-json-jackson2 and mcp-core.
   • May require classpath adjustments

2. Tool Result API Changes (#551)

   • CallToolResult.structuredContent() now returns Object instead of Map<String,Object>
   • Requires explicit casting when accessing map-like content: ((Map<String,Object>) result.structuredContent()).get("key")
   • Deprecated constructors - use builder pattern instead
   • Custom JsonSchemaValidator implementations need signature updates

3. Package Name Changes (#556)

   • Utility classes moved from io.modelcontextprotocol.utils to io.modelcontextprotocol.util

📝 Migration Guide

For Tool Result Changes

// Before
result.structuredContent().get("key")

// After  
((Map<String,Object>) result.structuredContent()).get("key")

// Use builder pattern instead of deprecated constructors
CallToolResult.builder()
  .content(content)
  .isError(isError)
  .structuredContent(structuredContent)
  .build()

For Module Dependencies

Ensure your dependencies account for the new module structure:

• mcp-core for Jackson-free core functionality
• mcp continues to work as umbrella module with Jackson support

New Contributors

• @sdelamo made their first contribution in #557
• @graemerocher made their first contribution in #543
• @valuesource made their first contribution in #556

Full Changelog: v0.12.1...v0.13.0

v0.12.1

Release Notes

• Skip structured output validation for error tool results (#540) - ensures that when a tool handler returns an error result, the structured
  output schema validation is skipped, preventing validation failures on error responses that don't conform to the expected output schema.
• Add null check for response ID to prevent memory leaks (#509) - The missing null check could lead to memory leaks as pending requests
  would never be completed when responses lack session IDs. This fix ensures proper handling of such cases with appropriate error logging.

Full Changelog: v0.12.0...v0.12.1

v0.12.0

Release Notes

❗ Breaking Changes

• Re-purposed McpTransportContext to reuse in server and client packages and made immutable - more details below
• Updated (Async|Sync)HttpRequestCustomizer class signatures as part of transport context implementation
• Users relying on template resources in resources/list should migrate to using resources/templates/list

🚀 New Features

Transport Context Support (#522)

• Added McpTransportContext to MCP Clients - Provides a unified API for reading context in which MCP Client requests are issued, regardless of sync/async implementation
• Enhanced HttpRequestCustomizer support - Context is now available to both McpAsyncHttpRequestCustomizer and McpSyncHttpRequestCustomizer
• Improved thread-local handling - Addresses limitations with thread local usage in request customizers
• Breaking Change: Updated signatures for (Async|Sync)HttpRequestCustomizer classes
• Breaking Change: McpTransportContext io.modelcontextprotocol.server -> io.modelcontextprotocol.common package change, void put(String key, Object value), and McpTransportContext copy() method removal.
• Breaking Change: DefaultMcpTransportContext class made package private and changed package to io.modelcontextprotocol.common
• Changed McpTransportContext usage patterns - it is now immutable and can be created via a static factory method McpTransportContext create(Map<String, Object> metadata)

🐛 Bug Fixes

Resource Listing Compliance (#528)

• Fixed resource template filtering - Template resources containing {} parameters are now properly excluded from standard resources/list responses
• MCP Specification compliance - Ensures proper separation between regular resources (resources/list) and resource templates (resources/templates/list)
• Issue: Fixes #319 where template resources were incorrectly appearing in both endpoints

Test Stability Improvements (#535)

• Fixed flaky test - Resolved intermittent failures in HttpClientStreamableHttpTransportErrorHandlingTest

🔧 Testing & Infrastructure Improvements

Resource Cleanup & Test Reliability (#537)

• Enhanced resource management - Added try-finally blocks to guarantee server cleanup on test completion
• Synchronous shutdown - Implemented closeGracefully().block() for proper synchronous shutdown
• Resource leak prevention - Added try-with-resources for client lifecycle management
• Reduced test flakiness - Prevents resource leaks that could cause test instability

Test Performance Optimization (#531)

• Significant performance boost - Static container reuse across all client and transport tests
• ~10x speed improvement - Containerized MCP server is now shared within test classes rather than recreated per test

Docker Infrastructure Updates (#536)

• Updated test dependencies - Upgraded mcp-everything-server Docker image from v2 to v3 across all integration tests

Comprehensive Context Testing (#529)

• Expanded test coverage - Added integration tests for transport context propagation between MCP clients and servers
• Multi-environment testing - Coverage for both Spring WebFlux and WebMVC environments
• Transport type coverage - Tests across stateless, streamable, and SSE transport types
• Context validation - Verifies proper flow of authentication tokens, correlation IDs, and metadata through HTTP headers

📋 Technical Details

Compatibility

• All changes maintain backward compatibility except for the noted breaking changes
• Spring WebFlux and WebMVC environments fully supported
• Docker image updates require no user action

🧪 Testing

• 103 async server tests passing
• Comprehensive integration test coverage added
• Resource cleanup and lifecycle management improved
• Test execution time significantly reduced through container optimization

---

Contributors:

• Christian Tzolov (@tzolov)
• Daniel Garnier-Moiroux (@Kehrlann)
• Richie Caputo (@arcaputo3)

Full Changelog: v0.11.0...v0.12.0

v0.11.3

🐛 Bug Fixes

HTTP Transport Improvements

• Fixed SSE endpoint Content-Type header issue (#489)

  • Removed incorrect Content-Type header from GET requests to SSE endpoints
  • Resolves compatibility issues with MCP servers that validate HTTP headers strictly
  • Content-Type header is now only included for POST requests as per HTTP specifications

• Added configurable connection timeout (#511)

  • Fixed intermittent connection timeout issues in HttpClientStreamableHttpTransport and HttpClientSseClientTransport
  • Replaced hard-coded 10-second timeout with configurable parameter
  • Allows users to set appropriate timeouts based on network conditions and latency requirements

Reactive Streams Compliance

• Fixed SseLineSubscriber request handling (#507)
  • Resolved missing request implementation in SseLineSubscriber
  • Improves reactive streams compliance and stability

Demand-Based Processing

• Implemented demand-based request handling in ResponseSubscribers (#516)
  • Added hasRequestedDemand tracking to prevent unnecessary data processing
  • Improved backpressure handling and resource efficiency
  • Guards event emission with demand checks to avoid processing when no downstream demand exists
  • Maintains same public API while improving internal resource management

Server Configuration Optimization

• Disabled logging capabilities for stateless servers (#517)
  • Removed LoggingCapabilities from stateless server features to align with actual functionality
  • Stateless servers don't support setLogging operations, so capabilities are now correctly advertised
  • Prevents client confusion and aligns async implementation with sync implementation

🔧 API Enhancements

Object Identity & Equality

• Implemented proper equals/hashCode for PromptReference (#514)
  • Added identifier-based equality comparison (ignores descriptive fields like title)
  • Enables proper use in collections (HashMap, HashSet, etc.)
  • Maintains standard Java object contracts with comprehensive test coverage
  • Two PromptReference objects with same identifier and type are now considered equal

📊 Summary

This release focuses on improving HTTP transport reliability, reactive streams compliance, and resource efficiency. Key highlights include:

• Better HTTP compatibility with proper header handling for SSE endpoints
• Configurable timeouts to handle varying network conditions
• Improved reactive streams handling with proper backpressure and demand management
• Enhanced object equality semantics for better collection usage
• Optimized server configurations that accurately reflect capabilities

All changes are backward compatible and maintain existing public APIs while improving internal behavior and compliance with specifications.

Contributors

Thanks to the following contributors for their work on this release:

• Christian Tzolov (@tzolov) - 3 contributions
• Zizo (@Zizo-Vi) - 1 contribution
• He-Pin(kerr) (@He-Pin) - 1 contribution
• shaoyin.zj (@zhangjingcn) - 1 contribution

Full Changelog: v0.11.2...v0.11.3

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