SEP-1456: add allowCustom option for enum fields to support custom values

[yadav-prakhar]

SEP description: modelcontextprotocol/modelcontextprotocol#1456

Motivation and Context

Existing implementations face two significant issues:

1. Guidance vs Flexibility – Developers want to provide commonly used options while still allowing custom entries that fall outside predefined values.

2. Inconsistent Workarounds – Current approaches, such as adding an “Other” option and triggering additional elicitation requests, lead to complex, fragmented user experiences. Refer: Elicitation with custom input [ SEP-1456 ] #932 (comment)

The lack of a declarative, schema-driven solution for this use case leads to repetitive development patterns and diverging UX across tools.

This proposal is based on real implementation challenges and has been validated through prototypes built in MCP Server workflows. It avoids speculative enhancements and follows MCP’s principles of simplicity, minimalism, and concrete problem-solving.

How Has This Been Tested?

Added tests for allowCustom enabled and without allowCustom to evaluate fallback flow.

Breaking Changes

• None.

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Documentation update

Checklist

• I have read the MCP Documentation
• My code follows the repository's style guidelines
• New and existing tests pass locally
• I have added appropriate error handling
• I have added or updated documentation as needed

Additional context

Behavior

• If allowCustom is true, users see predefined options but can also enter custom input.
• If unspecified or false, users are limited to selecting from enum options.
• Validation may be extended via other schema properties (e.g., pattern, maxLength).

UI Rendering expectation

• Suggest predefined options.
• Allow free-text input when allowCustom is enabled.
• Display validation feedback if the input violates additional constraints.

Why this approach?

• Declarative – Developers specify their intent via schema, avoiding imperative UI hacks.
• Minimal – Adds only one property without altering existing semantics.
• Concrete – Addresses a widely encountered problem validated by prototypes.
• Backward Compatible – Existing schemas remain valid without changes.

Considered alternatives

Alternative	Reason rejected
Free-text only	No guidance leads to user errors and inconsistent experiences
Multi-step prompting	Adds complexity and interrupts conversational flow

[yadav-prakhar]

Overview of the core logic to manipulate the elicitation schema:

Original Schema
+-------------------------+
| color                   |
|  type: string           |
|  enum: [red,green,blue]|
|  allowCustom: true      |
|  description: ...      |
+-------------------------+

          |
          |  prepareElicitationSchema
          v

Transformed Schema
+-------------------------+
| color                   |
|  type: string           |
|  description: ...       |
|  anyOf: [               |
|    { enum: [red,green,blue] },  <-- original enum
|    { type: string, description: ... }  <-- allows custom value
|  ]                      |
+-------------------------+

[yadav-prakhar]

Scope of improvement I felt so far:

• replace type assertions with generics

Type Assertions in the code:

• https://github.com/modelcontextprotocol/typescript-sdk/pull/1008/files#diff-e4e7a68d82cdfba4e7dab9a32a8f55f3806ffa0cf33f1b8ab64b42941cf68888R281

  const clonedSchema = JSON.parse(JSON.stringify(schema)) as ElicitRequest['params']['requestedSchema'];

• https://github.com/modelcontextprotocol/typescript-sdk/pull/1008/files#diff-e4e7a68d82cdfba4e7dab9a32a8f55f3806ffa0cf33f1b8ab64b42941cf68888R289-R290

  const enumValues = (propertySchema as { enum?: string[] }).enum;
  const allowCustom = (propertySchema as { allowCustom?: boolean }).allowCustom;

• https://github.com/modelcontextprotocol/typescript-sdk/pull/1008/files#diff-e4e7a68d82cdfba4e7dab9a32a8f55f3806ffa0cf33f1b8ab64b42941cf68888R296

  const propertyRecord = propertySchema as Record<string, unknown>;

[yadav-prakhar]

@ochafik, I would request your kind help with this solution to ensure there are no gaps or missed scenarios.