@chughtapan thanks for this! he current schema.json actually comes close, using const + title, but with only a oneOf proposition. But a wrinkle is that schema needs to support use of oneOf or anyOf.

For instance, when eliciting user input, with an enum of colors, you might say "Choose your favorite color" OR "Choose your favorite colors".

The actual JSON schema for an enum with title and optional description of its purpose would look something like this:

"EnumSchema": {
  "oneOf": [
    {
      "type": "object",
      "required": ["type", "oneOf"],
      "properties": {
        "type": { "const": "string" },
        "title": { "type": "string" },
        "description": { "type": "string" },
        "oneOf": {
          "type": "array",
          "items": {
            "type": "object",
            "required": ["const", "title"],
            "properties": {
              "const": { "type": "string" },
              "title": { "type": "string" }
            },
            "additionalProperties": false
          }
        }
      },
      "additionalProperties": false
    },
    {
      "type": "object",
      "required": ["type", "anyOf"],
      "properties": {
        "type": { "const": "array" },
        "title": { "type": "string" },
        "description": { "type": "string" },
        "anyOf": {
          "type": "array",
          "items": {
            "type": "object",
            "required": ["const", "title"],
            "properties": {
              "const": { "type": "string" },
              "title": { "type": "string" }
            },
            "additionalProperties": false
          }
        }
      },
      "additionalProperties": false
    }
  ]
}

Which would allow single selection...

{
 "type": "string",
 "title": "Color Selection",
 "description": "Choose your favorite color",
 "oneOf": [
   { "const": "#FF0000", "title": "Red" },
   { "const": "#00FF00", "title": "Green" },
   { "const": "#0000FF", "title": "Blue" }
 ]
}

or multi-selection...

{
  "type": "array",
  "title": "Color Selection",
  "description": "Choose your favorite colors",
  "items": {
    "oneOf": [
      { "const": "#FF0000", "title": "Red" },
      { "const": "#00FF00", "title": "Green" },
      { "const": "#0000FF", "title": "Blue" }
    ]
  }
}

as valid enums sent to the client for elicitation (or whatever purpose).

@cliffhall I like your proposal, but I guess that means it's a broader change around the semantics of enums in MCP. IIUC the current expectation matches the proposed oneOf semantics. I think the current docs state that

Note that complex nested structures, arrays of objects, and other advanced JSON Schema features are intentionally not supported to simplify client implementation.

But maybe it is a valid proposal to change that only for enums and support anyOf semantics as well. Thoughts?

Note that complex nested structures, arrays of objects, and other advanced JSON Schema features are intentionally not supported to simplify client implementation.

@chughtapan For context, where in the spec did you find this particular note?

But maybe it is a valid proposal to change that only for enums and support anyOf semantics as well. Thoughts?

I think it is worthwhile running this up the flagpole. Enums are equally useful for multi-select as they are for single selection. Certainly in elicitation, it would be nice to have.

For rigor, I decided to test the EnumSchema meta-schema I defined above, against single and multiple color selection instance schemas, and use those instance schemas to validate expected inputs.

• EnumSchema validating the single color selection instance schema:

• The single color selection instance schema validating a single color selection.

• The single color selection instance schema invalidating an incorrect single color selection

• EnumSchema validating the multiple color selection instance schema.

• The multiple color selection instance schema validating a multiple color selection.

• The multiple color selection instance schema invalidating an incorrect multiple color selection

@cliffhall Thanks!

@chughtapan For context, where in the spec did you find this particular note?

Here: https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/docs/specification/draft/client/elicitation.mdx?plain=1#L282

But maybe it is a valid proposal to change that only for enums and support anyOf semantics as well. Thoughts?

I think it is worthwhile running this up the flagpole. Enums are equally useful for multi-select as they are for single selection. Certainly in elicitation, it would be nice to have.

Yeah, I think I agree with you on that. Thanks for validating the schema - I'll try to implement the client logic whenever I get a moment. I think it should be trivial to automatically switch between a checkbox or a radio selection based on the schema type.

For rigor, I decided to test the EnumSchema meta-schema I defined above, against single and multiple color selection instance schemas, and use those instance schemas to validate expected inputs.

Another thought is that multi-selection enums can have far more complex validators than single choice selection. For example, choose upto two colors or can't choose black and blue together - things like that. IIUC we want to keep the elicitation schemas simple enough that clients can do the syntactic validation atleast. Do you think it's possible to add things like choose at max two or exactly two or things like that in the schema as well or we will have to fallback to server side code for that.

@cliffhall Thanks!

@chughtapan For context, where in the spec did you find this particular note?

Here: https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/docs/specification/draft/client/elicitation.mdx?plain=1#L282

Ah, yes. We pushed back on the complex objects in the UI because generating forms of nested objects is hard and can be ugly at render time. But this is an enum as a single or multi-select dropdown (or checkboxes vs radio buttons). That won't degrade UX, and opens up possibilities for elicitation, e.g, "Choose all that apply".

Yeah, I think I agree with you on that. Thanks for validating the schema - I'll try to implement the client logic whenever I get a moment. I think it should be trivial to automatically switch between a checkbox or a radio selection based on the schema type.
👍

Another thought is that multi-selection enums can have far more complex validators than single choice selection. For example, choose upto two colors or can't choose black and blue together - things like that. IIUC we want to keep the elicitation schemas simple enough that clients can do the syntactic validation atleast. Do you think it's possible to add things like choose at max two or exactly two or things like that in the schema as well or we will have to fallback to server side code for that.

It would be possible to allow choosing up to some limit with EnumSchema as above and an instance schema that adds constraints.

{
  "type": "array",
  "title": "Color Selection",
  "description": "Choose one or two colors",
  "minItems": 1,
  "maxItems": 2,
  "items": {
    "oneOf": [
      { "const": "#FF0000", "title": "Red" },
      { "const": "#00FF00", "title": "Green" },
      { "const": "#0000FF", "title": "Blue" }
    ]
  }
}

• EnumSchema validating the constrained multiple color selection instance schema.

• The constrained multiple color selection instance schema validating 1 entry

• The constrained multiple color selection instance schema validating 2 entries.

• The constrained multiple color selection instance schema invalidating 0 entries

• The constrained multiple color selection instance schema invalidating 3 entries

@cliffhall I did some more digging: for choices without titles, we should always prefer to use enum instead of oneOf/anyOf because that's default serialization would create.

I created a basic script to validate the default serialization from Python to JSON: https://gist.github.com/chughtapan/2f8738f69098f35f877d1cb3de38aeb2

The outputs are here: https://gist.github.com/chughtapan/c80f175b880f0badc40b133611ab4956

I guess the current schema is pretty clean that way: enums with title just have the additional enumNames field, while the default enums dont. In our current proposal we would have to support both enums (for without title) and one/anyOf for enums with titles. Does that seem reasonable or would it make the schema too complex?

The other thought (related to multi-choice): currently we serialize enums with type: string - but that doesn't make sense for the multi-choice, they should be serialized to Arrays. So maybe those should be two independent elicitation types instead of trying to overload the same enum type?

@cliffhall Working demo: https://asciinema.org/a/anBvJdqEmTjw0JkKYOooQa5Ta

Proof-of-concept implementation: https://github.com/evalstate/fast-agent/pull/324/files
I'm thinking we should start a SEP to discuss more broadly about the exact schema?

I'm thinking we should start a SEP to discuss more broadly about the exact schema?

@chughtapan In order to head off an SEP that ends up with a winding discussion, let's start in this thread in the MCP Contributors Discord.

@chughtapan @cliffhall hey guys, thanks for all this work! any updates on where this might land?

@chughtapan @cliffhall hey guys, thanks for all this work! any updates on where this might land?

We have moved this into SEP-1330 which is currently under an async review by core maintainers. We're hoping for a vote this week.

@cliffhall -- good catch. fixed this

@chughtapan @cliffhall

👋 just as a reminder, we're aiming to ensure that all SEPs that are on-deck for the 2025-11-25 spec release are verbiage-ready and merged by Friday, November 14, 2025. Please prioritize making the required changes (given that this is accepted with changes, per Core Maintainer review meeting) before then.

@chughtapan @cliffhall

👋 just as a reminder, we're aiming to ensure that all SEPs that are on-deck for the 2025-11-25 spec release are verbiage-ready and merged by Friday, November 14, 2025. Please prioritize making the required changes (given that this is accepted with changes, per Core Maintainer review meeting) before then.

I believe all the comments (primarily about removing reference to "deprecation") have been implemented.

👋 just as a reminder, we're aiming to ensure that all SEPs that are on-deck for the 2025-11-25 spec release are verbiage-ready and merged by Friday, November 14, 2025. Please prioritize making the required changes (given that this is accepted with changes, per Core Maintainer review meeting) before then.

I believe all the comments (primarily about removing reference to "deprecation")

@localden @felixweinberger done. We've replaced the "deprecation" wording with the term "legacy". We still don't want to encourage the use of the old schema.

👋 just as a reminder, we're aiming to ensure that all SEPs that are on-deck for the 2025-11-25 spec release are verbiage-ready and merged by Friday, November 14, 2025. Please prioritize making the required changes (given that this is accepted with changes, per Core Maintainer review meeting) before then.

I believe all the comments (primarily about removing reference to "deprecation")

@localden @felixweinberger done. We've replaced the "deprecation" wording with the term "legacy". We still don't want to encourage the use of the old schema.

Apologies, hadn't finished my sentence there - "all comments have been implemented" is what I meant to say there.

Looks like we're good to go and this is merged - reviewing modelcontextprotocol/typescript-sdk#1077 atm