Summary
PR #1753 fixes #1721 by stopping the SDK from automatically adding the 2026-07-28-only resultType, ttlMs, and cacheScope properties to legacy results. Applications can still set those properties explicitly from handlers or filters, which can produce a wire shape that is invalid for the negotiated protocol version.
We should define and consistently enforce the server behavior for protocol-version-specific result properties supplied by application code.
Protocol detection
The effective protocol version is already available at the shared post-handler boundary:
- Use
RequestContext.JsonRpcRequest.Context.ProtocolVersion for per-request metadata protocols.
- Fall back to
McpServer.NegotiatedProtocolVersion for stateful sessions.
McpServerImpl.IsJuly2026OrLaterProtocolRequest already implements this resolution.
Possible policies
- Fail the request before serialization with an InternalError and a useful server-side diagnostic. This gives application developers the strongest signal, but turns an otherwise valid client request into an error. Ordinary application exceptions currently produce a generic
"An error occurred." response, so we would also need to decide whether the client receives a specific message.
- Strip the unsupported properties and log a warning. This preserves a valid legacy wire shape while making the application misuse visible to server operators.
- Strip the unsupported properties silently. This maximizes compatibility but can hide application bugs.
Scope
The selected policy should:
- Be applied once at a typed response-emission boundary after handlers and filters.
- Cover
Result.ResultType and both ICacheableResult properties.
- Cover normal, cacheable, and immediate alternate results.
- Avoid mutating shared response instances in a way that can affect later requests using another protocol version.
- Preserve explicit values and add required defaults for 2026-07-28 and later responses.
- Be extensible to future protocol-version-specific result properties.
Tests
Add exact serialized wire-shape coverage for:
- Legacy handlers and filters that explicitly set each unsupported property.
- 2026-07-28 handlers and filters with explicit values.
- Normal, cacheable, and immediate alternate results.
- Session-negotiated and per-request HTTP protocol contexts.
- Reused or shared result instances across requests with different protocol versions.
Summary
PR #1753 fixes #1721 by stopping the SDK from automatically adding the 2026-07-28-only
resultType,ttlMs, andcacheScopeproperties to legacy results. Applications can still set those properties explicitly from handlers or filters, which can produce a wire shape that is invalid for the negotiated protocol version.We should define and consistently enforce the server behavior for protocol-version-specific result properties supplied by application code.
Protocol detection
The effective protocol version is already available at the shared post-handler boundary:
RequestContext.JsonRpcRequest.Context.ProtocolVersionfor per-request metadata protocols.McpServer.NegotiatedProtocolVersionfor stateful sessions.McpServerImpl.IsJuly2026OrLaterProtocolRequestalready implements this resolution.Possible policies
"An error occurred."response, so we would also need to decide whether the client receives a specific message.Scope
The selected policy should:
Result.ResultTypeand bothICacheableResultproperties.Tests
Add exact serialized wire-shape coverage for: