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