Update protocol version to 2025-11-25 and ensure backward compatibility

[ezynda3]

Summary

Update the MCP protocol version from 2025-06-18 to 2025-11-25 to align with the latest specification while maintaining backward compatibility with previous versions.

Specification Reference

• Spec URL: https://modelcontextprotocol.io/specification/2025-11-25
• Section: Base Protocol > Lifecycle > Version Negotiation

The spec requires:

In the initialize request, the client MUST send a protocol version it supports. This SHOULD be the latest version supported by the client.

Current Implementation

File: mcp/types.go (lines 111-119)

const (
    LATEST_PROTOCOL_VERSION = "2025-06-18"
)

var ValidProtocolVersions = []string{
    "2025-06-18",
    "2025-03-26", 
    "2024-11-05",
}

Required Changes

1. Update Protocol Version Constants

File: mcp/types.go (lines 111-119)

const (
    LATEST_PROTOCOL_VERSION = "2025-11-25"
)

var ValidProtocolVersions = []string{
    "2025-11-25", // Latest
    "2025-06-18",
    "2025-03-26", 
    "2024-11-05",
}

2. Update Server Version Negotiation

File: server/server.go (lines 734-748)

The current negotiation logic should already handle this correctly:

func (s *MCPServer) handleInitializeRequest(ctx context.Context, request mcp.JSONRPCRequest, session *Session) mcp.JSONRPCResponse {
    // ... parse request ...
    
    // Version negotiation
    negotiatedVersion := params.ProtocolVersion
    if !slices.Contains(mcp.ValidProtocolVersions, params.ProtocolVersion) {
        // If client version not supported, respond with our latest
        negotiatedVersion = mcp.LATEST_PROTOCOL_VERSION
    }
    
    // ... rest of handler ...
}

Verify this logic still works - it should automatically pick up the new version.

3. Update HTTP Transport Header Default

File: server/streamable_http.go (line 740)

The server defaults to 2025-03-26 when no version header is provided:

if protocolVersion == "" {
    protocolVersion = "2025-03-26"
}

Consider: Should this default be updated to 2025-11-25, or should it remain at an older version for backward compatibility?

Recommendation: Keep as 2025-03-26 for now to maintain backward compatibility with clients that don't send the header. Document this behavior.

4. Add Version-Specific Feature Flags (If Needed)

If new features in 2025-11-25 need conditional behavior based on negotiated version:

File: server/server.go

Add helper:

func (s *MCPServer) supportsVersion(minVersion string) bool {
    // Compare negotiated protocol version with minimum required version
    // Only needed if features have version-specific behavior
    return compareVersions(s.negotiatedVersion, minVersion) >= 0
}

Note: This may not be needed if all features are backward compatible or optional via capabilities.

5. Document Breaking Changes

Review the spec changelog for 2025-11-25 and document any breaking changes:

Potential areas to check:

• Icons field (new, non-breaking - optional)
• Elicitation URL mode (new, non-breaking - capability-based)
• Annotations.lastModified (new, non-breaking - optional field)
• Tasks capability (new, non-breaking - capability-based)
• Streamable HTTP changes (check if any breaking changes from earlier versions)

Testing Requirements

Version Negotiation Tests

• Test client sends 2025-11-25, server responds with 2025-11-25
• Test client sends 2025-06-18, server responds with 2025-06-18
• Test client sends unknown version, server responds with 2025-11-25
• Test backward compatibility with 2025-03-26 clients
• Test backward compatibility with 2024-11-05 clients

HTTP Transport Tests

• Test MCP-Protocol-Version header handling with 2025-11-25
• Test default version behavior when header is missing
• Test session management still works

Integration Tests

• Run full test suite to ensure no regressions
• Test all transports (stdio, Streamable HTTP, legacy SSE)
• Verify all examples still work

Related Issues

This version update enables:

• Add Icons support for MCP spec 2025-11-25 compliance #653 - Icons support
• Add lastModified field to Annotations for MCP spec 2025-11-25 #654 - Annotations.lastModified
• Implement Elicitation URL mode for MCP spec 2025-11-25 #655 - Elicitation URL mode
• Implement Tasks capability for MCP spec 2025-11-25 #656 - Tasks capability

These features are part of the 2025-11-25 spec but can be implemented independently.

Implementation Checklist

• Update LATEST_PROTOCOL_VERSION constant
• Add 2025-11-25 to ValidProtocolVersions array
• Review and verify version negotiation logic
• Review HTTP transport default version behavior
• Add/update version negotiation tests
• Update any version-related documentation
• Test backward compatibility with older clients
• Update changelog/release notes

Backward Compatibility Notes

This change should be fully backward compatible:

• Older clients can still negotiate their supported versions
• Server continues to support versions back to 2024-11-05
• New features in 2025-11-25 are:
  • Optional fields (icons, lastModified)
  • Capability-based (elicitation URL mode, tasks)
  • Non-breaking additions

Documentation Updates

File: README.md

Update any references to protocol version:

mcp-go implements the Model Context Protocol specification version 2025-11-25,
with backward compatibility for versions 2025-06-18, 2025-03-26, and 2024-11-05.

Release Notes

When this is merged, add to release notes:

### Protocol Version Update
- Updated to MCP specification version 2025-11-25
- Maintained backward compatibility with 2025-06-18, 2025-03-26, and 2024-11-05
- New optional features available (requires separate implementation):
  - Icons support for visual identifiers
  - Annotations.lastModified for resource timestamps
  - Elicitation URL mode for secure credential handling
  - Tasks capability for async operations

Related Files

• mcp/types.go:111-119 - Version constants
• server/server.go:734-748 - Server version negotiation
• client/client.go:227-229 - Client version validation
• server/streamable_http.go:740 - HTTP default version
• mcp/errors.go:32-50 - UnsupportedProtocolVersionError

Implementation Priority

Priority: High - This is a prerequisite for implementing other 2025-11-25 features and ensures the codebase stays current with the latest spec.

Current implementation status: Needs update - currently at 2025-06-18 (as of commit 670a95a)