An alternative to the breaking change could be to use a new name for the field or to add the array of content as a new type of content. Not saying either is better than a breaking change. Just worth considering, as in practice many clients/servers will likely not support multiple protocol versions, which means that non-backwards compatible schema changes will break compatibility. Maybe that's ok, but thought I mention this anyway.

I did think on this one quite hard, but I think mitigating are:

• Relatively low take-up of Prompts/Sampling Features reduce the risk. Those using the features will likely be in a position to adapt. It would be nice to know if others had similar feedback.
• Conversion for the general case is quite straightforward
• A new name/field would introduce duplication and tech debt - it might make sense as a migration path, but internally I'm now coding to the assumption that Messages have multiple content blocks.

I did think on this one quite hard, but I think mitigating are:

• Relatively low take-up of Prompts/Sampling Features reduce the risk. Those using the features will likely be in a position to adapt. It would be nice to know if others had similar feedback.
• Conversion for the general case is quite straightforward
• A new name/field would introduce duplication and tech debt - it might make sense as a migration path, but internally I'm now coding to the assumption that Messages have multiple content blocks.

I agree, but I think it makes sense to have articulated and considered the alternatives.

Well, it's put here as a draft to provoke the conversation - and get input from the Maintainers. I'm happy to put the work in to a solution of any type (compatibility preserving etc.) if we agree this is something worth doing - but there will be a lot of documentation etc. to write if we proceed with any option. Thank you.

Curious what @jspahrsummers and @jerome3o-anthropic have to say, but I think this approach makes sense. It'll be a bit painful for clients to update, but I think that's probably okay. Luckily the protocol is versioned and so we can deal with different result types.

On this one, I am planning on writing a discussion thread showing examples of this, and potential workarounds with sample code.

Yep, no objections from me.

Well, it's put here as a draft to provoke the conversation - and get input from the Maintainers.

Here's a possible alternative: The content field could be one of the types OR an array of them.

"content": {
    "anyOf": [
        {
            "$ref": "#/definitions/TextContent"
            ...
        },
        {
            "type": "array",
            "items": {
                "anyOf": [
                    {
                        "$ref": "#/definitions/TextContent"
                        ...
                    }
                ]
            }
        }
    ]
}

Probably not the right solution, but I thought I'd throw it out there.

Makes consuming the content more complex since you have to account for the either/or. And devs who are already using sampling would still need to update their code.

Realizing its essentially @PederHP's suggestion:

add the array of content as a new type of content.

I appreciate this discussion and just wanted to weigh regarding use cases. I can think of two scenarios where this would be useful. As previously mentioned, (a) when sampling responses are asking for n>1 is certainly valid. I also wanted to add a (perhaps?) more common scenario where (b) MCP servers need to run multiple sampling requests in parallel.

I ran into this yesterday when I wanted to run parallel summary requests at the MCP server level on a list of search results. For this specific situation, I can certainly summarize at the client level however I feel strongly that enough new scenarios will continue to arise for (a) and (b) over time to justify a protocol change.

Yes, I understand it is a breaking change, and was proposed as such. Given the changes for StructuredOutput for the next protocol revision I'm not sure that this is worse (as there is a non-breaking SDK interface path to introduce it).

Claude suggested that several documentation files in docs/ need updates to reflect the breaking changes in this PR:

Files needing updates:

• docs/docs/concepts/sampling.mdx - Message format examples show content as single object instead of array
• docs/tutorials/building-a-client-node.mdx - Client tutorial examples use old single content format
• docs/sdk/java/mcp-server.mdx - Java SDK sampling examples need to use content arrays

Why: Since this changes message content from content: {...} to content: [{...}], the documentation examples will mislead developers and cause implementation errors.

Okay coming back to this. I think we, while we are all happy with the change, on the SDK side this is a true test for how we handle version negotiation and it revealed that we need much more work and coordination on this. While it is quite annoying for everyone involved, I believe it's best if we not include it in this revision and give SDK developers a chance to figure out how to best deal with different versions of an interface in their SDK.

I'm slightly worried about allowing message content array w/o requiring a strict message role alternance.
And very worried about the breaking change.

Most inference APIs (OpenAI's chat completions, Claude's, but also OSS in HF transformers and llama.cpp) require or assume a strict assistant / user alternance in messages, with message content being a single string or an array of typed parts.

The current sampling API amounts to flattened version of this & allows consecutive repeated roles, but is currently trivial and unambiguous to unflatten, by just grouping by role:

// Sampling messages

[
  {"role": "user", "content": {"type": "text", "text": "Describe and enhance this pic:"}},
  {"role": "user", "content": {"type": "image", "mimeType": "image/png", "data": "base64..."}},
  {"role": "assistant", "content": {"type": "text", "text": "It's dull. I've spiced it up"}},
  {"role": "assistant", "content": {"type": "image", "mimeType": "image/png", "data": "base64..."}},
  {"role": "user", "content": {"type": "text", "text": "And then?"}}
]

Converted to OpenAI / HF-style format (content: string | ({type: "text", text: string} | ...)[]):

// OpenAI- / HF-style messages

[
  {"role": "user", "content": [
    {"type": "text", "text": "Describe and enhance this pic:"},
    {"type": "image", "mimeType": "image/png", "data": "base64..."}
  ]},
  {"role": "assistant", "content": [
    {"type": "text", "text": "It's dull. I've spiced it up"},
    {"type": "image", "mimeType": "image/png", "data": "base64..."}
  ]},
  {"role": "user", "content": {"type": "text", "text": "And then?"}}
]

Now if we allow this:

[
  {"role": "user", "content": [{"type": "text", "text": "content1.1"}, {"type": "text", "text": "content1.2"}]},
  {"role": "user", "content": [{"type": "text", "text": "content2"}]}
]

The only way to implement it w/ actual inference APIs will be to coalesce these, loosing the kinda-implied semantic grouping of content1.1 and content1.2:

[
  {"role": "user", "content": [
    {"type": "text", "text": "content1.1"},
    {"type": "text", "text": "content1.2"},
    {"type": "text", "text": "content2"}
  ]}
]

My take is we should:

• Have content accept a single MessageContent or an array of it, to avoid backwards-incompatibility:

  type MessageContent = TextContent | ImageContent | AudioContent | EmbeddedResource;
  export interface PromptMessage {
    role: Role;
    content: MessageContent | MessageContent[];
  }

• Introduce backward-compatible message role alternance: maybe something like:

  Consecutive sub-sequences of messages with the same role MUST either all have a content with a single MessageContent, or be of length 1.

Most inference APIs (OpenAI's chat completions, Claude's, but also OSS in HF transformers and llama.cpp) require or assume a strict assistant / user alternance in messages, with message content being a single string or an array of typed parts.

This is no longer the case. OpenAI and Claude both allow arbitrary ordering, and I think Gemini does too.

If a client has a need for strict turn ordering they can insert dummy message or merge consecutive user / assistant messages. This is a relatively trivial change to make in those few host who need it (probably only open source inference), and it avoids a lot of complexity in the protocol.

This is no longer the case. OpenAI and Claude both allow arbitrary ordering, and I think Gemini does too.

Came here to say same (I explicitly test fast-agent handling of that case as well). I did previously used to have to divide document blocks out for Anthropic but that's been fixed too: https://github.com/anthropics/anthropic-sdk-python/releases/tag/v0.66.0 :)

I agree with @PederHP that concerns about presentation to the inference API should be handled by the Host, and that the intermediate MCP format should allow maximum expressiveness.

#1577 partially solves this, new SEP to be considered for PromptMessage types.