Skip to content

render_elicitation_schema rejects StrEnum and (str, Enum) fields because Pydantic emits $defs/$ref #3883

Open

Description

@0718lol

Initial Checks

Release line

2.x (current stable)

Description

render_elicitation_schema() in src/mcp/server/elicitation.py rejects Pydantic models whose fields use StrEnum or (str, Enum) — both single-select (color: Color, color: Color | None = None) and multi-select (colors: list[Color]) — even though the equivalent Literal["red", "blue"] and list[Literal["red", "blue"]] fields are accepted and MCP elicitation explicitly supports string enums and multi-select enums.

Root cause: Pydantic emits a $defs entry and a {"$ref": "#/$defs/Color"} property for Enum subclasses, and _ElicitationJsonSchema does not inline enum schemas before _validate_rendered_properties() validates each property against PrimitiveSchemaDefinition. As a result, ctx.elicit() and Resolve(..., Elicit(...)) both raise TypeError before sending the request.

Example Code

from enum import StrEnum
from typing import Literal
from pydantic import BaseModel
from mcp.server.elicitation import render_elicitation_schema


class Color(StrEnum):
    RED = "red"
    BLUE = "blue"


class LiteralForm(BaseModel):
    color: Literal["red", "blue"]
    colors: list[Literal["red", "blue"]]


class EnumForm(BaseModel):
    color: Color


class MultiEnumForm(BaseModel):
    colors: list[Color]


print("LiteralForm OK:", render_elicitation_schema(LiteralForm)["properties"]["color"])
for cls in (EnumForm, MultiEnumForm):
    try:
        render_elicitation_schema(cls)
    except TypeError as exc:
        print(f"{cls.__name__} TypeError: {exc}")

Observed output:

LiteralForm OK: {'enum': ['red', 'blue'], 'title': 'Color', 'type': 'string'}
EnumForm TypeError: Elicitation schema field 'color' rendered as {'$ref': '#/$defs/Color'}, which is not a valid PrimitiveSchemaDefinition
MultiEnumForm TypeError: Elicitation schema field 'colors' rendered as {'items': {'$ref': '#/$defs/Color'}, 'title': 'Colors', 'type': 'array'}, which is not a valid PrimitiveSchemaDefinition

Expected behavior: StrEnum / string Enum fields (single, optional, and list[Enum] multi-select) should render inline {"type": "string", "enum": [...]} (or array-of-enum) schemas matching Literal without emitting $defs/$ref, while non-primitive models still get rejected.

I would be happy to submit a PR with regression tests if assigned.

Python & MCP Python SDK

  • Python: 3.14.8
  • mcp: 2.3.1.dev20+77001c96 (main @ 77001c9)

AI disclosure: AI assistance was used to help investigate and draft this issue; the reproduction and observed output were verified locally.

Activity

  1. added
    bugSomething isn't working
    v2Affects the v2 line (2.x on main)
    on Nov 21, 2026
  2. Shanmukh-l33t commented on Nov 21, 2026

    @Shanmukh-l33t

    Branch with a fix and a regression test: main...Shanmukh-l33t:python-sdk:fix/elicitation-string-enum

    Root cause: pydantic emits a $defs entry plus a $ref property for every Enum subclass, and PrimitiveSchemaDefinition has no $ref form, so _validate_rendered_properties rejects the field before anything is sent. The renderer now inlines the string enums pydantic hoisted (member values all str), which produces the same shape as Literal, and still rejects non-string enums and nested models.

    Test evidence:

    • RED on main (77001c9): pytest tests/server/mcpserver/test_elicitation.py -k string_enum -q fails, the tool raises UnexpectedToolError from Elicitation schema field 'color' rendered as {'$ref': '#/$defs/Color'}.
    • GREEN with the fix: 160 passed across tests/server/mcpserver/test_elicitation.py, test_resolve.py, test_url_elicitation.py, test_url_elicitation_error_throw.py and tests/docs_src/test_elicitation.py.
    • Coverage for the touched module, from coverage report filtered to src/mcp/server/elicitation.py: 81 statements, 24 branches, 0 missed, 0 partial branches, 100.00%, exit 0. ruff check, ruff format check and pyright are clean.

    Cases covered: StrEnum single select, (str, Enum) optional, list[StrEnum] multi select, and a plain Enum of ints that must stay rejected.

    AI assistance was used to prepare this branch.

  3. 0718lol commented on Nov 21, 2026

    @0718lol
    Author

    One design question for maintainers on the fix direction: would you prefer preventing $defs/$ref hoisting for string enums inside _ElicitationJsonSchema (via Pydantic's GenerateJsonSchema hooks), or post-processing $defs/$ref in render_elicitation_schema() after model_json_schema()?

    As noted in the OP (and per CONTRIBUTING.md), I'd be happy to own the PR and regression tests once a maintainer confirms the preferred approach.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    bugSomething isn't workingv2Affects the v2 line (2.x on main)

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions