Overhaul design to handle changes between spec versions

[stephentoub]

We're already seeing breaking changes finding their way into the spec. For example, the 06-18 spec declares "declined" as an elicitation response, whereas the current draft changes that to "rejected". The current sampling result contains only a single content whereas there's a plan to change it to be an array. Etc. We need to find a way to keep the APIs as free from breaking changes as possible while supporting correctly working with any negotiated protocol with the current remote endpoint.

[jeffhandley]

Potentially related:

• Expose negotiated protocol version after MCP client initialisation #668

[PederHP]

Have the python and typescript sdks taken a stance on how to handle this? Last I checked they didn't have any backwards compatibility.

If it's possible it would be sensible to have a unified approach to this in the SDKs.

I think there's a risk the ecosystem could end up with a lot of servers and client hosts that support one version only.

Maybe an adapter based approach at the very outer layer mapping back and forth so there's not really two schemas in the SDK? Should work for this batch of breaking changes.

[eiriktsarpalis]

If it's possible it would be sensible to have a unified approach to this in the SDKs.

I think that's a reasonable point. If we unilaterly decided to build a stable abstraction layer based on today's snapshot of the spec chances are our APIs would appear idiosyncratic months down the line.

[PederHP]

Of relevance to this discussion:
modelcontextprotocol/modelcontextprotocol#1309

[eiriktsarpalis]

There are two independent concerns to be contended with here:

1. Backward compatibility of the C# SDK using older versions of the spec, and
2. API compatibility of the C# SDK as it adapts to newer breaking versions of the spec.

I think both can be addressed using either of the following two approaches:

1. The quick and dirty approach, which involves patching the impacted DTO using a custom converter:

   [JsonPropertyName("content"), JsonConverter(typeof(SingleOrArrayContentConverter))]
   public required List<ContentBlock> Contents { get; init; }
   
   [JsonIgnore] // Old property kept for API compatibility
   public ContentBlock? Content { get => Contents?.FirstOrDefault() ; init => Contents = [value]; }

   The SingleOrArrayContentConverter should support deserializing contents both as single values and arrays, and additionally should be configurable such that it writes either single values or arrays based on the negotiated protocol.

   For the case of the breaking elicitation response, this could similarly be bridged using a custom converter for string that performs appropriate mappings to and from the wire.

2. The more involved approach of implementing an intermediate "domain layer" for all user-accessible types, which map to spec level DTOs that are used for serialization. The DTOs would be kept as implementation detail and ideally auto-generated from the specification's JSON schema (using a third party library like Corvus.JsonSchema or a tool of our own creation).

The first approach is cheaper, but it creates problems with maintainability as breaking changes accrue over time. The second approach is more sustainable longer-term, but requires substantial refactoring of the codebase and will bring about massive breaking changes on its release.

In either approach, we should try to enforce an obsoletion strategy so that public APIs corresponding to older versions of the spec are eventually deleted. On the other hand, removing support for older versions of the spec is going to be tricky -- we would probably need to make such decisions taking the overall state of the MCP ecosystem into account.

I propose then, that for the breaking changes specifically expected for the September release that we stick to approach (1) so that we can gauge its inherent limits and to avoid delay. We can later make a determination on whether approach (2) is worth our investment.

[jeffhandley]

The SingleOrArrayContentConverter should support deserializing contents both as single values and arrays, and additionally should be configurable such that it writes either single values or arrays based on the negotiated protocol.

@eiriktsarpalis To make sure I understand this statement correctly, this would allow the Initialize call to negotiate the protocol version to the highest supported by both client and server, and then the server could both receive (deserialize) and send (serialize) the Contents either as a single value or as an array of values. Correct?

(Setting the code maintainability concerns aside for the moment)... Would the custom converter approach have any gaps in the client/server compatibility? It might be helpful to capture a table that illustrates all of the affected scenarios, and what the results would be for each of them given table columns of:

1. Scenario (such as client serializing X request, server deserializing X request, server serializing Y response, client deserializing Y response)
2. Client NuGet package version's highest-supported specification version
3. Server NuGet package version's highest-supported specification version
4. DTO object state
5. JSON payload

[eiriktsarpalis]

To make sure I understand this statement correctly, this would allow the Initialize call to negotiate the protocol version to the highest supported by both client and server, and then the server could both receive (deserialize) and send (serialize) the Contents either as a single value or as an array of values. Correct?

Deserialization should support both variants regardless of the negotiated protocol version (in the spirit of Postel's law), whereas what variant gets picked on serialization should be pinned to the negotiated version.

Would the custom converter approach have any gaps in the client/server compatibility?

Assuming older versions of the SDK implement version negotiation properly, I can't think of any apparent issues right now.

It might be helpful to capture a table that illustrates all of the affected scenarios, and what the results would be for each of them given table columns of:

Given the bidirectional nature of JSON-RPC and MCP, and for the sake of simplicity I think we should aim for the same band of supported versions for both client and server for a given NuGet package version.

[eiriktsarpalis]

We're already seeing breaking changes finding their way into the spec. For example, the 06-18 spec declares "declined" as an elicitation response, whereas the current draft changes that to "rejected". The current sampling result contains only a single content whereas there's a plan to change it to be an array. Etc.

Having researched this a bit more, as of today neither of the two breaking changes have been committed into the current draft specification:

• The change proposing the update of the sampling result is still open, and has been open for a while without any recent activity.
• I (or copilot) couldn't find any proposals to rename the declined elicitation response to rejected.

I had copilot search for other potential breaking changes in the upcoming spec release, but couldn't find any that specifically introduce ramifications to model serialization.

[eiriktsarpalis]

Here's a PoC PR showing how this could be achieved: eiriktsarpalis#2

[stephentoub]

I (or copilot) couldn't find any proposals to rename the declined elicitation response to rejected.

Read through this thread:
modelcontextprotocol/modelcontextprotocol#897

[eiriktsarpalis]

Ah I see, so it was renamed from rejected to declined and we already incorporated that change in the first iteration of the feature.

[mikekistler]

I think it was originally named "declined" and there was a proposal to change it to "rejected", but this was missed when the final version of the 2025-06-18 spec was published. And once it was published as "declined" the decision was to leave it that way.

[jeffhandley]

@eiriktsarpalis For the POC for DTO adapters, let's illustrate the scalar result changing to an array of values.

[eiriktsarpalis]

New PR showcasing use of DTO mapping for both client and server: eiriktsarpalis#3