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 JsonSchema and use a Map for inputSchema to 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 meta parameter 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 of httpRequestCustomizer() by @gyeo009 in #791
• Expose request URI in McpHttpClientAuthorizationErrorHandler by @Kehrlann in #980
• Fix UTF-8 encoding for non-ASCII tool names in HTTP client transports by @rameshreddy-adutla in #850

🪵 Logging

• Unify logging config by @chemicL in #984
• Reduce logging levels by @chemicL in #985

🐛 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 Resource and ResourceTemplate by @chemicL in #947
• Clarify tool validation error messages by @tzolov in #1023
• Return void from McpStatelessSyncServer#closeGracefully instead of Mono by @tzolov in #1019
• fix: add missing Export-Package to 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

v0.18.3

What's changed

Fix for GHSA-hv2w-8mjj-jw22

Full Changelog: v0.18.2...v0.18.3

v2.0.0-RC1

What's Changed

• feat: client-side application of elicitation schema defaults (SEP-1034) by @chemicL in #976
• Expose request URI in McpHttpClientAuthorizationErrorHandler by @Kehrlann in #980
• Unify logging config by @chemicL in #984
• Reduce logging levels by @chemicL in #985
• fix: add missing Export-Package to mcp-json-jackson2 and mcp-json-jackson3 by @joaodinissf in #911
• Add URL elicitation support (SEP-1036) by @Kehrlann in #993
• fix: avoid dropped errors when transport is closed or uninitialized by @chemicL in #995

New Contributors

• @joaodinissf made their first contribution in #911

Full Changelog: v2.0.0-M3...v2.0.0-RC1

v2.0.0-M3

What's Changed

• feat!: enforce required MCP spec fields in McpSchema; lenient wire deserialization by @chemicL #928
• Validate message endpoint in SSE client transport by @Kehrlann in #943
• DefaultSseMessageEndpointValidator allows same-origin message endpoints by @Kehrlann in #946
• feat: validate embedded JSON Schema documents against 2020-12 meta-schema (SEP-1613) by @chemicL in #949
• Deprecate SSE transports by @Kehrlann in #950
• feat: Add SEP-973 icons and metadata support by @sainathreddyb in #912

Breaking changes

• PromptReference.equals/hashCode now key on name only (previously derived from identifier()+type()). Two refs with the same name but different titles now compare equal — code using PromptReference as a map/set key should be audited.
• PromptReference's compact constructor pins type to "ref/prompt" and logs a WARN if the caller supplies a different non-null value. The legacy two-arg PromptReference(String type, String name) constructor remains deprecated.
• ResourceReference's record components are reduced from (type, uri) to (uri) — positional construction breaks. The legacy ResourceReference(String type, String uri) constructor stays deprecated and ignores type.
• CompleteReference.identifier() is deprecated and now returns null via a default method on the interface.

New Contributors

• @sainathreddyb made their first contribution in #912

Full Changelog: v2.0.0-M2...v2.0.0-M3

v1.1.3

What's changed

• Validate message endpoint in SSE client transport by @Kehrlann in #943 (backport)
• DefaultSseMessageEndpointValidator allows same-origin message endpoints by @Kehrlann in #946 (backport)

Full Changelog: v1.1.2...v1.1.3

v1.0.2

What's changed

• Validate message endpoint in SSE client transport by @Kehrlann in #943 (backport)
• DefaultSseMessageEndpointValidator allows same-origin message endpoints by @Kehrlann in #946 (backport)

Full Changelog: v1.0.1...v1.0.2

v0.18.2

What's Changed

• Validate message endpoint in SSE client transport by @Kehrlann in #945

Full Changelog: v0.18.1...v0.18.2

v2.0.0-M2

What's Changed

• fix: Return empty prompt completion result when prompt has no arguments by @chemicL in #934

Full Changelog: v2.0.0-M1...v2.0.0-M2

v1.1.2

What's Changed

• HttpClientStreamableHttpTransport: handle HTTP 405 by @Kehrlann in #900

Full Changelog: v1.1.1...v1.1.2

v2.0.0-M1

MCP Java SDK 2.0.0-M1

The 2.0.0-M1 release introduces foundational changes for the 2.x line, focusing on flexibility, spec compliance, and robust validation. The primary themes driving this major release include:

1. Breaking API Changes in McpSchema for Forward/Backward Compatibility

The 1.x line was constrained by sealed interfaces, which made it impossible to add permitted subtypes without breaking exhaustive pattern-match switch expressions in caller code. In v2.0.0, these constraints are lifted:

• Removal of Sealed Interfaces: Sealed interfaces have been removed from JSONRPCMessage, Request, Result, Notification, ResourceContents, CompleteReference, and Content. This allows domain types to absorb new fields and subtypes without breaking existing clients or servers.
• Lenient Deserialization: All domain records now tolerate unknown JSON fields, ensuring that a client built against an older SDK version won't fail when a newer server sends unrecognized fields.
• Dialect Support: JsonSchema was removed and replaced with a Map for inputSchema to properly support various JSON Schema dialects.

2. Incorporating Breaking Changes for the 2025-11-25 MCP Specification

The release aligns with the 2025-11-25 MCP specification updates:

• Tool Input Validation: Tool input arguments validation is now activated by default. Invalid inputs will now cause a tool execution error, enforcing stricter compliance with the spec.
• Spec-Required Fields: Adjustments to how nulls and absent fields are handled on the wire (e.g., CompleteCompletion.total and .hasMore are now absent from the wire when not set, rather than being emitted as null).

3. API Cleanup and Modernization

As a major version bump, v2.0.0 takes the opportunity to clean up the API surface:

• Removal of Deprecated Methods: Deprecated methods from the Server transports builder have been removed entirely.
• Transport Improvements: Added proper handling for HTTP 405 in HttpClientStreamableHttpTransport and fixed UTF-8 encoding for non-ASCII tool names.
• Pagination Support: Added support for the meta parameter in client paginated list queries.

---

Detailed Commit Log (v1.1.0 to v2.0.0-M1)

• 4c85963 feat!: consistent JSON forward/backward compatibility - 2.0 foundation (#972) by @chemicL
• d182338 feat!: #697 added tool input arguments validation (#873) by @ashakirin
• 9520323 fix: Remove JsonSchema and use a Map for inputSchema to support json schemas dialect (#749) by @bilaloumehdi
• eaa0c69 feat: add support for meta parameter in client paginated list queries (#906) by @smohite04
• 8fd9903 Fix UTF-8 encoding for non-ASCII tool names in HTTP client transports (#850) by @rameshreddy-adutla
• 8c7774a Client transports: remove deprecated methods from builder (#899) by @Kehrlann
• 301dbe4 Deprecate Builder.customizeRequest() in favor of httpRequestCustomizer() (#791) by @gyeo009
• cd2c21c docs: document best practice for handling argument errors in MCP tools (#891) by @radeshgovind-2005
• 22e7bd4 conformance: update to mcp-security 0.1.5, pass scope-step-up (#895) by @Kehrlann
• 3a78182 fix: proper URL links from README.md to 'Java Dependencies', 'Java MCP Client', 'Java MCP Server' pages (#874) by @sleepytomcat

---

New contributors

A big thank you to the following contributors who made their first commit in this release:

• @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

Full Changelog: v1.1.0...v2.0.0-M1