Java SDK 1.0.0 — Tier 1 Remediation

java-sdk-tier1-remediation.md

Remediation Guide: modelcontextprotocol/java-sdk

Date: 2026-02-23 Branch: main (SDK version: 1.1.0-SNAPSHOT, latest release: 1.0.0 GA) Current Tier: 2

The SDK now meets all Tier 2 requirements. The path to Tier 1 has three remaining blockers.

---

Path to Tier 2

All Tier 2 requirements are already met. No action needed for Tier 2.

---

Path to Tier 1

Three requirements block Tier 1.

#	Action	Requirement	Effort	Where
1	Implement resource subscriptions	Server conformance 100% (full suite)	Large	Implement resources/subscribe + resources/unsubscribe handlers + notifications/resources/updated emission in McpServer/session layer
2	Fix auth/scope-step-up	Client conformance 100% (full suite)	Medium	client-spring-http-client: handle WWW-Authenticate scope upgrade after initial token has been issued; retry auth flow with elevated scope
3	Add code examples for ~20 undocumented features	All features documented with examples	Medium	docs/server.md and docs/client.md

sse-retry status (not a blocker)

On main, sse-retry passes (1/1 check) with 2 warnings:

• ClientRespectsRetryField: WARN (timing measurement inconclusive on main, not a hard FAIL as on 1.0.x)
• ClientSendsLastEventId: WARN (SHOULD requirement)

These are SHOULD-level issues. The scenario passes for Tier 1 purposes.

Documentation Gaps (for item #3)

Features in docs/server.md or docs/client.md that need code examples added:

Feature	Type	Gap	Suggested Location
Tools - image results	Core	No ImageContent example	docs/server.md (tool results)
Tools - audio results	Core	No AudioContent example	docs/server.md (tool results)
Tools - embedded resources	Core	No EmbeddedResource in tool result	docs/server.md (tool results)
Tools - error handling	Core	Prose exists, no code showing isError: true	docs/server.md (error handling)
Resources - reading binary	Core	No blob/base64 example	docs/client.md (resource access)
Resources - subscribing	Core	Only capability flag; not implemented → note it	docs/server.md or dedicated section
Resources - unsubscribing	Core	Only capability flag; not implemented → note it	docs/server.md
Prompts - embedded resources	Core	No EmbeddedResource in prompt result	docs/server.md (prompt spec)
Prompts - image content	Core	No ImageContent in prompt result	docs/server.md (prompt spec)
Elicitation - schema validation	Core	Only requestedSchema field mentioned	docs/client.md (elicitation)
Elicitation - default values	Core	No example using default in schema	docs/server.md + client.md
Elicitation - enum values	Core	No example using enum in schema	docs/server.md + client.md
Elicitation - complete notif.	Core	notifications/elicitation/complete not shown	docs/server.md
Ping	Protocol	No explicit ping example	docs/client.md or server.md
Cancellation	Protocol	Not documented at all	docs/client.md
Pagination	Protocol	Not documented at all	docs/client.md (list methods)
JSON Schema 2020-12 support	Protocol	Only validator mention; no prose on what changed	docs/server.md + client.md
Resources - change notifications	Core	Has prose; example is comment-only (resources(false, true)) — improve with consumer example	docs/client.md
Tools - error handling (example)	Core	McpError mentioned but no CallToolResult.builder().isError(true) example	docs/server.md

---

Recommended Next Steps

1. Implement resource subscriptions — The only server-side gap to Tier 1. The ROADMAP.md already tracks this as part of the 2025-11-25 spec implementation. Completing it moves server conformance from 93.3% → 100%.

2. Fix auth/scope-step-up — Medium effort. The Spring HTTP client needs to handle the case where the server returns WWW-Authenticate with an elevated scope after the client already has a token. This is the last hard client failure.

3. Add documentation examples for ~17 features — Systematic but achievable in 1-2 sprints. Priority: (a) tool result types (image, audio, embedded — conformance-tested and implemented), (b) elicitation schema/default/enum (conformance-tested), (c) pagination and cancellation (fundamental protocol features), (d) resource subscriptions when implemented. Consider adding a dedicated "Advanced Topics" section in docs/server.md covering content types.

4. Address sse-retry warnings (optional, improves robustness) — Even though not blocking Tier 1, the retry: field parsing issue (McpTransportException: Invalid SSE response. Status code: 200 Line: retry: 500) indicates the JDK transport still throws instead of parsing the field. Fixing it fully would give clean green conformance results and improve reconnection resilience.