Skip to content

Define handling for protocol-incompatible result properties set by applications #1754

Description

@halter73

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

  1. 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.
  2. Strip the unsupported properties and log a warning. This preserves a valid legacy wire shape while making the application misuse visible to server operators.
  3. 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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    P2Moderate issues, valuable feature requestsenhancementNew feature or requestready for workHas enough information to start

    Type

    No type

    Projects

    No projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions