Overview

This issue tracks the implementation of support for the Model Context Protocol revision 2025-06-18. This includes all transient changes from the original 2024-11-05 specification through the intermediate 2025-03-26 revision to the final 2025-06-18 specification.

📋 Complete Revision History

2024-11-05 → 2025-03-26 → 2025-06-18

Original: 2024-11-05 (HTTP+SSE transport, basic features)
Intermediate: 2025-03-26 (StreamableHTTP, OAuth 2.1, JSON-RPC batching)
Target: 2025-06-18 (Structured output, elicitation, resource links, removed batching)

🎯 Implementation Plan

The upgrade is organized into 6 phases covering all transient changes:

Phase 1: Core Protocol Updates (Critical) ⚠️ Breaking Changes

• Protocol Version Update (Phase 1.1: Update MCP protocol version to 2025-06-18 #108)
• Enhanced _meta Field Support (Phase 1.2: Enhanced _meta Field Support #118) ✅ COMPLETED

Phase 2: Transport Layer Modernization (Critical) ⚠️ Breaking Changes

• StreamableHTTP Transport Implementation #119
• Deprecate Legacy HTTP+SSE Transport (#TBD)
• OAuth 2.1 Authorization Framework (#TBD)

Phase 3: Enhanced Tool System (High Priority)

• Structured Tool Output (Phase 2.1: Tool Result Structure Enhancement #111)
• Resource Links in Tool Results (Phase 2.2: Resource Links in Tool Results #112)
• Comprehensive Tool Annotations (#TBD)

Phase 4: Interactive Features (High Priority)

• Elicitation Framework - Message Types (Phase 3.1: Elicitation Message Types #113)
• Elicitation Framework - Server Support (Phase 3.2: Server Elicitation Support #114)

Phase 5: Security & Enterprise Features (Medium Priority)

• OAuth Resource Server Classification (Phase 4: OAuth Resource Server Framework #115)
• Resource Indicators Support (RFC 8707) (#TBD)
• Security Best Practices Implementation (#TBD)

Phase 6: Quality of Life Improvements (Low Priority)

• Enhanced Features and Refinements (Phase 5: Enhanced Features and Refinements #116)
• Audio Content Type Support (#TBD)
• Completions Capability (#TBD)

⚠️ Major Breaking Changes Required

From 2024-11-05 → 2025-03-26

1. Transport Architecture: HTTP+SSE → StreamableHTTP
2. Authorization: Basic auth → OAuth 2.1 framework
3. Batching: Single requests → JSON-RPC batching support
4. Content Types: Text/Image → + Audio support

From 2025-03-26 → 2025-06-18

1. JSON-RPC Batching: REMOVED (was added in 2025-03-26)
2. Tool Output: Text responses → Structured output format
3. Protocol Headers: Optional → REQUIRED MCP-Protocol-Version
4. Lifecycle: SHOULD → MUST for lifecycle operations

🚀 Timeline

• Phase 1: ✅ COMPLETED (Protocol updates)
• Phase 2: Week 2-3 (Transport modernization)
• Phase 3: Week 4-5 (Enhanced tools)
• Phase 4: Week 6 (Interactive features)
• Phase 5: Week 7 (Security & enterprise)
• Phase 6: Week 8 (Quality of life)

🔄 Migration Strategy

Backward Compatibility Windows

1. 2024-11-05 Transport: Maintain during Phase 2 implementation
2. JSON-RPC Batching: Implement in Phase 2, remove in Phase 3
3. Legacy Tool Output: Support during Phase 3 transition
4. Feature Flags: Enable gradual migration

Deprecation Timeline

• HTTP+SSE Transport: Deprecated in Phase 2, removed in Phase 6
• JSON-RPC Batching: Added Phase 2, removed Phase 3 (per 2025-06-18)
• Simple Tool Responses: Deprecated Phase 3, removed Phase 6

📊 Success Criteria

• Full MCP 2025-06-18 specification compliance
• All transient changes properly implemented
• Smooth migration path through all revisions
• 100% test coverage for new features ✅ Phase 1 Complete
• Complete documentation for all revision changes
• No significant performance degradation
• Updated examples demonstrating all capabilities

🔗 Related Issues & PRs

Phase 1 (Completed)

• Phase 1.1: Protocol Version Update (Phase 1.1: Update MCP protocol version to 2025-06-18 #108) ✅
• Phase 1.2: Enhanced _meta Field Support (Phase 1.2: Enhanced _meta Field Support #118) ✅

Phase 2 (Transport Modernization)

• StreamableHTTP Transport Implementation (#TBD)
• OAuth 2.1 Authorization Framework (#TBD)
• JSON-RPC Batching Support (#TBD)

Phase 3 (Enhanced Tools)

• Structured Tool Output (Phase 2.1: Tool Result Structure Enhancement #111)
• Resource Links in Tool Results (Phase 2.2: Resource Links in Tool Results #112)

Phase 4 (Interactive Features)

• Elicitation Framework (Phase 3.1: Elicitation Message Types #113, Phase 3.2: Server Elicitation Support #114)

Phase 5 (Security & Enterprise)

• OAuth Resource Server Framework (Phase 4: OAuth Resource Server Framework #115)

Phase 6 (Quality of Life)

• Enhanced Features and Refinements (Phase 5: Enhanced Features and Refinements #116)

⚠️ Risk Assessment

High Risk

• Transport layer replacement may break existing integrations
• OAuth 2.1 implementation has security implications

Medium Risk

• Structured tool output requires significant refactoring
• Elicitation framework adds complexity to tool execution

Low Risk

• Enhanced logging and metadata features are additive
• Audio content support is optional enhancement

📚 Documentation Updates Required

Revision-Specific Guides

• 2024-11-05 → 2025-06-18 migration guide
• Transport layer migration documentation
• OAuth 2.1 setup and configuration guide

Technical Documentation

• StreamableHTTP implementation guide
• Structured tool output examples
• Elicitation framework usage guide