modelcontextprotocol · Kehrlann · Aug 19, 2026 · Aug 17, 2026
diff --git a/.github/workflows/conformance.yml b/.github/workflows/conformance.yml
@@ -27,7 +27,7 @@ jobs:
           timeout 30 bash -c 'until curl -s http://localhost:8080/mcp > /dev/null 2>&1; do sleep 0.5; done'
 
       - name: Run conformance tests
-        uses: modelcontextprotocol/conformance@v0.1.11
+        uses: modelcontextprotocol/conformance@v0.1.16
         with:
           mode: server
           url: http://localhost:8080/mcp
@@ -54,7 +54,7 @@ jobs:
         run: mvn clean install -DskipTests
 
       - name: Run conformance test
-        uses: modelcontextprotocol/conformance@v0.1.11
+        uses: modelcontextprotocol/conformance@v0.1.16
         with:
           mode: client
           command: 'java -jar conformance-tests/client-jdk-http-client/target/client-jdk-http-client-*-SNAPSHOT.jar'

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -0,0 +1,64 @@
+# Changelog
+
+All notable changes to the MCP Java SDK are documented in the
+[GitHub Releases](https://github.com/modelcontextprotocol/java-sdk/releases),
+which serve as the canonical, detailed changelog for every version. This file
+summarizes the release history and the currently maintained release lines.
+
+Versioning follows [Semantic Versioning](https://semver.org/); see
+[VERSIONING.md](VERSIONING.md) for the breaking-change policy and
+[SECURITY.md](SECURITY.md) for the supported-versions security policy.
+
+## Release lines
+
+| Line | Latest | Spec revision | Status |
+|------|--------|---------------|--------|
+| 2.x  | [2.0.0](https://github.com/modelcontextprotocol/java-sdk/releases/tag/v2.0.0) (2026-06-11) | 2025-11-25 | Active development |
+| 1.1.x | [1.1.3](https://github.com/modelcontextprotocol/java-sdk/releases/tag/v1.1.3) (2026-05-21) | 2025-06-18 | Security patches only |
+| 1.0.x | [1.0.2](https://github.com/modelcontextprotocol/java-sdk/releases/tag/v1.0.2) (2026-05-21) | 2025-06-18 | Security patches only |
+| 0.18.x | [0.18.3](https://github.com/modelcontextprotocol/java-sdk/releases/tag/v0.18.3) (2026-06-09) | 2025-06-18 | Security patches only |
+
+## 2.0.0 — 2026-06-11
+
+First major release since 1.x, tracking the **2025-11-25** MCP specification.
+Upgrading from 1.x? See the [v2 migration guide](MIGRATION-2.0.md).
+
+- New JSON compatibility foundation for forward/backward wire compatibility,
+  with pluggable Jackson 2 / Jackson 3 serialization modules
+- Spec-accurate schema: enforced required fields, lenient wire deserialization
+- End-to-end validation of tool inputs and embedded JSON Schema documents
+  (JSON Schema 2020-12, SEP-1613)
+- Richer elicitation: client-side schema defaults (SEP-1034), URL elicitation
+  (SEP-1036), form-based elicitation schemas
+- Icons and metadata support (SEP-973)
+- Streamable HTTP first: SSE transports deprecated in favor of Streamable HTTP
+- Module restructuring: `mcp-core`, `mcp-json-jackson2`, `mcp-json-jackson3`,
+  `mcp-bom`
+
+Full notes: [v2.0.0 release](https://github.com/modelcontextprotocol/java-sdk/releases/tag/v2.0.0)
+(preceded by milestones [M1](https://github.com/modelcontextprotocol/java-sdk/releases/tag/v2.0.0-M1),
+[M2](https://github.com/modelcontextprotocol/java-sdk/releases/tag/v2.0.0-M2),
+[M3](https://github.com/modelcontextprotocol/java-sdk/releases/tag/v2.0.0-M3),
+[RC1](https://github.com/modelcontextprotocol/java-sdk/releases/tag/v2.0.0-RC1)).
+
+## 1.x
+
+- [1.1.3](https://github.com/modelcontextprotocol/java-sdk/releases/tag/v1.1.3) /
+  [1.0.2](https://github.com/modelcontextprotocol/java-sdk/releases/tag/v1.0.2) — 2026-05-21:
+  SSE client transport message-endpoint validation (backports)
+- [1.1.2](https://github.com/modelcontextprotocol/java-sdk/releases/tag/v1.1.2) — 2026-04-25
+- [1.1.1](https://github.com/modelcontextprotocol/java-sdk/releases/tag/v1.1.1) /
+  [1.0.1](https://github.com/modelcontextprotocol/java-sdk/releases/tag/v1.0.1) — 2026-03-27
+- [1.1.0](https://github.com/modelcontextprotocol/java-sdk/releases/tag/v1.1.0) — 2026-03-13
+- [1.0.0](https://github.com/modelcontextprotocol/java-sdk/releases/tag/v1.0.0) — 2026-02-23:
+  first stable release; see the [1.0 migration guide](MIGRATION-1.0.md)
+
+## 0.x
+
+- [0.18.3](https://github.com/modelcontextprotocol/java-sdk/releases/tag/v0.18.3) — 2026-06-09:
+  security fix for GHSA-hv2w-8mjj-jw22
+- [0.18.0](https://github.com/modelcontextprotocol/java-sdk/releases/tag/v0.18.0) –
+  [0.18.2](https://github.com/modelcontextprotocol/java-sdk/releases/tag/v0.18.2) — 2026-02 to 2026-05
+- [0.8.0](https://github.com/modelcontextprotocol/java-sdk/releases/tag/v0.8.0) –
+  [0.17.2](https://github.com/modelcontextprotocol/java-sdk/releases/tag/v0.17.2) — 2025-03 to 2026-01:
+  see the [full release list](https://github.com/modelcontextprotocol/java-sdk/releases)
diff --git a/ROADMAP.md b/ROADMAP.md
@@ -6,40 +6,35 @@ The SDK tracks implementation of MCP spec components via GitHub Projects, with a
 
 ## Current Focus Areas
 
-### 2025-11-25 Spec Implementation
+### 2.x — Stable Line (2025-11-25 spec)
 
-The Java SDK is actively implementing the [2025-11-25 MCP specification revision](https://github.com/orgs/modelcontextprotocol/projects/26/views/1).
+The current stable release line is **2.x** ([2.0.0](https://github.com/modelcontextprotocol/java-sdk/releases/tag/v2.0.0), June 2026), implementing the [2025-11-25 MCP specification revision](https://modelcontextprotocol.io/specification/2025-11-25), including:
 
-Key features in this revision include:
+- **Spec-accurate schema**: enforced required fields with lenient wire deserialization, and a JSON compatibility foundation for forward/backward wire compatibility
+- **Enhanced schemas**: JSON Schema 2020-12 validation of tool inputs and embedded schema documents (SEP-1613)
+- **Richer elicitation**: client-side schema defaults (SEP-1034), URL mode elicitation (SEP-1036), form-based elicitation schemas
+- **Icons metadata** (SEP-973): icons for tools, resources, resource templates, and prompts
+- **Streamable HTTP first**: SSE transports deprecated in favor of Streamable HTTP
+- **Pluggable JSON serialization**: Jackson 2 and Jackson 3 modules
 
-- **Tasks**: Experimental support for tracking durable requests with polling and deferred result retrieval
-- **Tool calling in sampling**: Support for `tools` and `toolChoice` parameters
-- **URL mode elicitation**: Client-side URL elicitation requests
-- **Icons metadata**: Servers can expose icons for tools, resources, resource templates, and prompts
-- **Enhanced schemas**: JSON Schema 2020-12 as default, improved enum support, default values for elicitation
-- **Security improvements**: Updated security best practices, enhanced authorization flows, enabling OAuth integrations
+2.x development continues with patch and minor releases for bug fixes, conformance improvements, and non-breaking features. See [CHANGELOG.md](CHANGELOG.md) for the release history.
 
-See the full [changelog](https://modelcontextprotocol.io/specification/2025-11-25/changelog) for details.
+The earlier **1.x and 0.x release lines receive security patches only** — no feature or bug-fix backports. Users on those lines are encouraged to upgrade via the [v2 migration guide](MIGRATION-2.0.md).
 
-### Tier 1 SDK Support
+### 3.x — 2026-07-28 Spec Support
 
-Once we catch up on the most recent MCP specification revision we aim to fully support all the upcoming specification features on the day of its release.
+The next major version, **3.x**, will implement the [2026-07-28 MCP specification revision](https://modelcontextprotocol.io/specification/2026-07-28), including `server/discover` and the SEP-2575 stateless lifecycle. The first 3.0.0 milestone releases are planned for **September 2026**, tracked via a dedicated spec revision project board.
 
-### v1.x Development
+### SDK Tiering
 
-The Java SDK is currently in active development as v1.x, following a recent stable 1.0.0 release. The SDK provides:
+The Java SDK is an official [Tier 2 SDK](https://modelcontextprotocol.io/community/sdk-tiers) committed to full protocol support: new spec revisions are implemented within the Tier 2 six-month window, with conformance continuously verified against the [MCP conformance suite](https://github.com/modelcontextprotocol/conformance) in CI. Once caught up on the most recent specification revision, we aim for Tier 1: fully supporting new specification features on the day of their release.
 
-- MCP protocol implementation
-- Synchronous and asynchronous programming models
-- Multiple transport options (STDIO, HTTP/SSE, Servlet)
-- Pluggable JSON serialization (Jackson 2 and Jackson 3)
-
-Development is tracked via [GitHub Issues](https://github.com/modelcontextprotocol/java-sdk/issues) and [GitHub Projects](https://github.com/orgs/modelcontextprotocol/projects).
-
-### Future Versions
+### Future Directions
 
 Major version updates will align with MCP specification changes and breaking API changes as needed. The SDK is designed to evolve with the Java ecosystem, including:
 
 - Virtual Threads and Structured Concurrency support
 - Additional transport implementations
 - Performance optimizations
+
+Development is tracked via [GitHub Issues](https://github.com/modelcontextprotocol/java-sdk/issues) and [GitHub Projects](https://github.com/orgs/modelcontextprotocol/projects).
diff --git a/conformance-tests/VALIDATION_RESULTS.md b/conformance-tests/VALIDATION_RESULTS.md
@@ -1,127 +1,110 @@
 # MCP Java SDK Conformance Test Validation Results
 
+Last validated: **2026-08-17** against conformance suite
+**`@modelcontextprotocol/conformance@0.2.0-alpha.11`** (SDK at `main`, 2.0.1-SNAPSHOT), targetting
+version 2025-11-25 (`--spec-version 2025-11-25`).
+
 ## Summary
 
-**Server Tests (active suite):** 44/44 passed (31 scenarios, 100%)
-**Server Tests (spec 2025-11-25):** 4/4 passed — SEP-1613 `json-schema-2020-12` scenario ✨
-**Client Tests:** 3/4 scenarios passed (9/10 checks passed)
-**Auth Tests:** 15/15 scenarios fully passing (195 passed, 0 failed, 0 warnings, 100% scenarios, 100% checks)
+**Server Tests (active suite):** 73/73 checks passed (31 scenarios, 100%)
+**Server Tests (SEP-1613 `json-schema-2020-12`):** 5/5 checks passed (SEP-2106 checks skipped — post-2025-11-25 spec additions)
+**Client Tests:** 3/4 scenarios passed; `sse-retry` fails (tracked in `conformance-baseline.yml`)
+**Auth Tests:** 14/14 scenarios passing (193 checks, 0 failed, 0 warnings)
+
+Baseline check passed on every run: all failures are expected per
+[`conformance-baseline.yml`](conformance-baseline.yml).
 
 ## Server Test Results
 
-### Active Suite — Passing (31/31 scenarios, 44/44 checks)
+### Active Suite — Passing (31/31 scenarios, 73/73 checks)
 
-- **Lifecycle & Utilities (4/4):** initialize, ping, logging-set-level, completion-complete
-- **Tools (13/13):** All scenarios including progress notifications, sampling, elicitation ✨
-- **Elicitation (10/10):** SEP-1034 defaults (5 checks), SEP-1330 enums (5 checks)
-- **Resources (7/7):** list, read-text, read-binary, templates-read, subscribe, unsubscribe, SEP-2164 resource-not-found
-- **Prompts (5/5):** list, simple, with-args, embedded-resource, with-image
-- **SSE Transport (2/2):** Multiple streams
-- **Security (2/2):** Localhost validation passes, DNS rebinding protection
+- **Lifecycle & Utilities:** initialize, ping, logging-set-level, completion-complete
+- **Tools (13/13):** all scenarios including progress notifications, sampling, elicitation
+- **Elicitation:** SEP-1034 defaults (6 checks), SEP-1330 enums (6 checks)
+- **Resources:** list, read-text, read-binary, templates-read, subscribe, unsubscribe
+- **Prompts:** list, simple, with-args, embedded-resource, with-image
+- **SSE Transport:** multiple streams
+- **Security:** DNS rebinding protection
 
-### Spec 2025-11-25 Scenarios — Passing (1/1 scenario, 4/4 checks)
+### SEP-1613 — JSON Schema 2020-12 (5/5 checks)
 
-- **JSON Schema 2020-12 (SEP-1613) (4/4):** ✨
-  - `json_schema_2020_12_tool` found
-  - `inputSchema.$schema` field preserved
-  - `inputSchema.$defs` field preserved
-  - `inputSchema.additionalProperties` field preserved
+- `json_schema_2020_12_tool` found; `$schema`, `$defs`, and `additionalProperties`
+  fields preserved; every JSON-RPC message valid per the spec JSON schema for the
+  negotiated spec version (`wire-schema-valid`)
+- SEP-2106 checks (composition/conditional/anchor keywords) reported SKIPPED:
+  they postdate the 2025-11-25 spec release and are excluded from scoring
 
 ## Client Test Results
 
-### Passing (3/4 scenarios, 9/10 checks)
-
-- **initialize (1/1):** Protocol negotiation, clientInfo, capabilities
-- **tools_call (1/1):** Tool discovery and invocation
-- **elicitation-sep1034-client-defaults (5/5):** Default values for string, integer, number, enum, boolean
+### Passing (3/4 scenarios)
 
-### Partially Passing (1/4 scenarios, 1/2 checks)
+- **initialize (1/1):** protocol negotiation, clientInfo, capabilities
+- **tools_call (2/2):** tool discovery and invocation
+- **elicitation-sep1034-client-defaults (5/5):** default values for string, integer, number, enum, boolean
 
-- **sse-retry (1/2 + 1 warning):**
-  - ✅ Reconnects after stream closure
-  - ❌ Does not respect retry timing
-  - ⚠️ Does not send Last-Event-ID header (SHOULD requirement)
+### Failing — in baseline (1/4 scenarios)
 
-**Issue:** Client treats `retry:` SSE field as invalid instead of parsing it for reconnection timing.
+- **sse-retry:** client does not parse/respect the `retry:` SSE field timing and
+  does not send the `Last-Event-ID` header (SHOULD requirement). Expected failure,
+  listed in `conformance-baseline.yml`.
 
 ## Auth Test Results (Spring HTTP Client)
 
-**Status: 195 passed, 0 failed, 0 warnings across 15 scenarios**
+**Status: 193 checks passed, 0 failed, 0 warnings across 14 scenarios**
 
-Uses the `client-spring-http-client` module with Spring Security OAuth2 and the [mcp-client-security](https://github.com/springaicommunity/mcp-client-security) library.
+Uses the `client-spring-http-client` module with Spring Security OAuth2 and the
+[mcp-client-security](https://github.com/springaicommunity/mcp-client-security) library.
 
-### Fully Passing (15/15 scenarios)
+Fully passing: metadata-default, metadata-var1/2/3, basic-cimd,
+scope-from-www-authenticate, scope-from-scopes-supported, scope-omitted-when-undefined,
+scope-step-up, scope-retry-limit, token-endpoint-auth-basic/post/none, pre-registration.
 
-- **auth/metadata-default (13/13):** Default metadata discovery
-- **auth/metadata-var1 (13/13):** Metadata discovery variant 1
-- **auth/metadata-var2 (13/13):** Metadata discovery variant 2
-- **auth/metadata-var3 (13/13):** Metadata discovery variant 3
-- **auth/basic-cimd (12/12):** Basic Client-Initiated Metadata Discovery
-- **auth/scope-from-www-authenticate (14/14):** Scope extraction from WWW-Authenticate header
-- **auth/scope-from-scopes-supported (14/14):** Scope extraction from scopes_supported
-- **auth/scope-omitted-when-undefined (14/14):** Scope omitted when not defined
-- **auth/scope-step-up (16/16):** Scope step-up challenge
-- **auth/scope-retry-limit (11/11):** Scope retry limit handling
-- **auth/token-endpoint-auth-basic (18/18):** Token endpoint with HTTP Basic auth
-- **auth/token-endpoint-auth-post (18/18):** Token endpoint with POST body auth
-- **auth/token-endpoint-auth-none (18/18):** Token endpoint with no client auth
-- **auth/resource-mismatch (2/2):** Resource mismatch handling
-- **auth/pre-registration (6/6):** Pre-registered client credentials flow
+Note: `auth/resource-mismatch` (present in earlier suite versions) is no longer part
+of the 0.2.0-alpha auth suite.
 
 ## Known Limitations
 
-1. **Client SSE Retry:** Client doesn't parse or respect the `retry:` field, reconnects immediately, and doesn't send Last-Event-ID header
+1. **Client SSE Retry:** client doesn't parse or respect the `retry:` field,
+   reconnects immediately, and doesn't send the `Last-Event-ID` header
 
 ## Running Tests
 
 ### Server (active suite)
 ```bash
-# Start server
-./mvnw compile -pl conformance-tests/server-servlet -am exec:java
-
-# Run tests (in another terminal)
-npx @modelcontextprotocol/conformance server --url http://localhost:8080/mcp --suite active
+# Build and start server
+./mvnw clean install -DskipTests
+mvn exec:java -pl conformance-tests/server-servlet \
+  -Dexec.mainClass="io.modelcontextprotocol.conformance.server.ConformanceServlet"
+
+# Run tests (in another terminal, from the repo root)
+npx @modelcontextprotocol/conformance@0.2.0-alpha.11 server \
+  --url http://localhost:8080/mcp --suite active \
+  --expected-failures ./conformance-tests/conformance-baseline.yml
 ```
 
-### Server (spec 2025-11-25 scenarios — SEP-1613)
+### Server (SEP-1613 scenario)
 ```bash
-# Start server (if not already running)
-./mvnw compile -pl conformance-tests/server-servlet -am exec:java
-
-# Run json-schema-2020-12 scenario
-cd ../conformance && node --import tsx/esm src/index.ts server \
-  --url http://localhost:8080/mcp \
-  --scenario json-schema-2020-12
+npx @modelcontextprotocol/conformance@0.2.0-alpha.11 server \
+  --url http://localhost:8080/mcp --scenario json-schema-2020-12
 ```
 
 ### Client
 ```bash
-# Build
-cd conformance-tests/client-jdk-http-client
-../../mvnw clean package -DskipTests
-
-# Run all scenarios
 for scenario in initialize tools_call elicitation-sep1034-client-defaults sse-retry; do
-  npx @modelcontextprotocol/conformance client \
-    --command "java -jar target/client-jdk-http-client-1.1.0-SNAPSHOT.jar" \
-    --scenario $scenario
+  npx @modelcontextprotocol/conformance@0.2.0-alpha.11 client \
+    --command "java -jar conformance-tests/client-jdk-http-client/target/client-jdk-http-client-*.jar" \
+    --scenario $scenario \
+    --expected-failures ./conformance-tests/conformance-baseline.yml
 done
 ```
 
 ### Auth (Spring HTTP Client)
-
-Ensure you run with the conformance testing suite `0.1.15` or higher.
-
 ```bash
-# Build
-cd conformance-tests/client-spring-http-client
-../../mvnw clean package -DskipTests
-
-# Run auth suite
-npx @modelcontextprotocol/conformance@0.1.15 client \
+npx @modelcontextprotocol/conformance@0.2.0-alpha.11 client \
   --spec-version 2025-11-25 \
-  --command "java -jar target/client-spring-http-client-1.1.0-SNAPSHOT.jar" \
-  --suite auth
+  --command "java -jar conformance-tests/client-spring-http-client/target/client-spring-http-client-*.jar" \
+  --suite auth \
+  --expected-failures ./conformance-tests/conformance-baseline.yml
 ```
 
 ## Recommendations

diff --git a/conformance-tests/conformance-baseline.yml b/conformance-tests/conformance-baseline.yml
@@ -7,3 +7,6 @@ client:
   # - Client does not parse or respect retry: field timing
   # - Client does not send Last-Event-ID header
   - sse-retry
+  # Not supporting versions > 1 year old
+  - auth/2025-03-26-oauth-metadata-backcompat
+  - auth/2025-03-26-oauth-endpoint-fallback