Type the elicitation requested schema on the send side

ElicitRequestedSchema was a TypeAlias for dict[str, Any]; it is now a
Pydantic model of the spec's restricted requested-schema subset, backed
by a new PrimitiveSchemaDefinition union (StringSchema, NumberSchema,
BooleanSchema, and the enum schemas). ServerSession.elicit_form (and the
deprecated elicit alias) and ClientPeer.elicit_form accept only this
model, so a nested-object property, an array-of-objects property, or an
anyOf union is unconstructible at the only place a server author
supplies a schema, rather than silently forwarded to the client.

The spec restricts form-mode requested schemas to flat objects with
primitive-typed properties only ("complex nested structures, arrays of
objects ... are intentionally not supported"). The high-level
Context.elicit / elicit_with_validation path is unchanged in behaviour:
it converts the rendered JSON Schema into the typed model, keeping its
existing per-field TypeError contract and producing value-identical wire
output.

Inbound is deliberately untouched. The wire field
ElicitRequestFormParams.requested_schema stays a plain dict[str, Any],
so older servers that emit anyOf for Optional form fields still reach
the client's elicitation callback. The typed-model-to-wire-dict
conversion lives in one place, ElicitRequestedSchema.to_wire(), which
both send sites call.

The schema family is extra="allow": keys schema.ts does not name (a
top-level title, pattern, exclusiveMinimum, json_schema_extra keys)
still round-trip, because the primitives-only restriction is carried by
the union members' required type literals, not by extra-key rejection.

Author: maxisbey

docs/migration.md

@@ -738,6 +738,42 @@ Positional calls (`await ctx.info("hello")`) are unaffected.
 
 `Context.elicit()` (and `elicit_with_validation()`) now render the schema first and validate each property against the spec's `PrimitiveSchemaDefinition`, raising `TypeError` at the call site for anything outside it. `Optional[T]` fields render as `{"type": ...}` with the field omitted from `required` (previously the non-spec `anyOf` shape). A bare `list[str]` field is rejected because it renders without the required enum items; use `list[Literal[...]]` or `list[str]` with `json_schema_extra` supplying the items. Unions of multiple primitives (e.g. `int | str`) and nested models are rejected.
 
+### `ServerSession.elicit_form()` takes a typed `ElicitRequestedSchema`
+
+`ServerSession.elicit_form()` (and the deprecated `elicit()` alias, and `ClientPeer.elicit_form()`)
+now take an `mcp_types.ElicitRequestedSchema` -- a Pydantic model of the spec's restricted
+requested-schema subset -- instead of an arbitrary `dict[str, Any]`. `ElicitRequestedSchema` was
+previously a `TypeAlias` for `dict[str, Any]`; it is now that model. A schema with a nested-object
+property, an array-of-objects property, or an `anyOf` union is rejected at construction.
+
+**Why:** the spec restricts form-mode requested schemas to flat objects with primitive-typed
+properties only ("complex nested structures, arrays of objects ... are intentionally not
+supported"). Typing the send side makes a non-conforming schema impossible to construct rather
+than silently forwarded.
+
+**How to migrate:** build the model in place of the dict, or validate an existing JSON Schema dict:
+
+```python
+from mcp_types import BooleanSchema, ElicitRequestedSchema, StringSchema
+
+await ctx.session.elicit_form(
+    "Choose a username.",
+    ElicitRequestedSchema(
+        properties={"username": StringSchema(type="string"), "newsletter": BooleanSchema(type="boolean")},
+        required=["username"],
+    ),
+)
+
+# Or, if you already have a JSON Schema dict:
+await ctx.session.elicit_form("Choose a username.", ElicitRequestedSchema.model_validate(my_schema))
+```
+
+The high-level `Context.elicit()` / `elicit_with_validation()` path, which generates the schema
+from a Pydantic model class, is unchanged. The wire type `ElicitRequestFormParams.requested_schema`
+is still a plain `dict[str, Any]`: the client's inbound parsing deliberately tolerates
+non-conforming schemas so older servers (which emit `anyOf` for `Optional` form fields) still
+reach the elicitation callback.
+
 ### Replace `RootModel` by union types with `TypeAdapter` validation
 
 The following union types are no longer `RootModel` subclasses:

examples/stories/legacy_elicitation/server_lowlevel.py

@@ -8,14 +8,13 @@
 from mcp.server.lowlevel import Server
 from stories._hosting import run_server_from_args
 
-REGISTRATION_SCHEMA: types.ElicitRequestedSchema = {
-    "type": "object",
-    "properties": {
-        "username": {"type": "string"},
-        "plan": {"type": "string", "enum": ["free", "pro", "team"]},
+REGISTRATION_SCHEMA = types.ElicitRequestedSchema(
+    properties={
+        "username": types.StringSchema(type="string"),
+        "plan": types.UntitledSingleSelectEnumSchema(type="string", enum=["free", "pro", "team"]),
     },
-    "required": ["username"],
-}
+    required=["username"],
+)
 LINK_INPUT_SCHEMA: dict[str, Any] = {
     "type": "object",
     "properties": {"provider": {"type": "string"}},

examples/stories/stickynotes/server_lowlevel.py

@@ -22,11 +22,10 @@ def claim_id(self) -> str:
         return nid
 
 
-CONFIRM_SCHEMA: dict[str, Any] = {
-    "type": "object",
-    "properties": {"confirm": {"type": "boolean", "title": "Yes, permanently delete every sticky note"}},
-    "required": ["confirm"],
-}
+CONFIRM_SCHEMA = types.ElicitRequestedSchema(
+    properties={"confirm": types.BooleanSchema(type="boolean", title="Yes, permanently delete every sticky note")},
+    required=["confirm"],
+)
 
 TOOLS = [
     types.Tool(

scripts/gen_surface_types.py

@@ -44,7 +44,7 @@
         # Older python-sdk releases emit `anyOf` for Optional fields; the callback's
         # own schema validation is the real gate, so accept any property shape inbound.
         # PrimitiveSchemaDefinition becomes an orphan $def after this patch but
-        # datamodel-codegen still emits it; elicitation.py imports it as the gate type.
+        # datamodel-codegen still emits it; the monolith carries the user-facing family.
         (
             "$defs/ElicitRequestFormParams/properties/requestedSchema/properties/properties/additionalProperties",
             {"$ref": "#/$defs/PrimitiveSchemaDefinition"},

src/mcp-types/mcp_types/__init__.py

@@ -15,6 +15,7 @@
     AudioContent,
     BaseMetadata,
     BlobResourceContents,
+    BooleanSchema,
     CacheableResult,
     CallToolRequest,
     CallToolRequestParams,
@@ -57,6 +58,8 @@
     ElicitResult,
     EmbeddedResource,
     EmptyResult,
+    EnumOption,
+    EnumSchema,
     FormElicitationCapability,
     GetPromptRequest,
     GetPromptRequestParams,
@@ -82,6 +85,7 @@
     InputResponse,
     InputResponseRequestParams,
     InputResponses,
+    LegacyTitledEnumSchema,
     ListPromptsRequest,
     ListPromptsResult,
     ListResourcesRequest,
@@ -101,12 +105,15 @@
     MissingRequiredClientCapabilityErrorData,
     ModelHint,
     ModelPreferences,
+    MultiSelectEnumSchema,
     Notification,
     NotificationParams,
+    NumberSchema,
     PaginatedRequest,
     PaginatedRequestParams,
     PaginatedResult,
     PingRequest,
+    PrimitiveSchemaDefinition,
     ProgressNotification,
     ProgressNotificationParams,
     ProgressToken,
@@ -152,7 +159,9 @@
     ServerTasksRequestsCapability,
     SetLevelRequest,
     SetLevelRequestParams,
+    SingleSelectEnumSchema,
     StopReason,
+    StringSchema,
     SubscribeRequest,
     SubscribeRequestParams,
     SubscriptionFilter,
@@ -175,6 +184,9 @@
     TasksToolsCapability,
     TextContent,
     TextResourceContents,
+    TitledMultiSelectEnumItems,
+    TitledMultiSelectEnumSchema,
+    TitledSingleSelectEnumSchema,
     Tool,
     ToolAnnotations,
     ToolChoice,
@@ -186,6 +198,9 @@
     UnsubscribeRequest,
     UnsubscribeRequestParams,
     UnsupportedProtocolVersionErrorData,
+    UntitledMultiSelectEnumItems,
+    UntitledMultiSelectEnumSchema,
+    UntitledSingleSelectEnumSchema,
     UrlElicitationCapability,
     client_notification_adapter,
     client_request_adapter,
@@ -231,21 +246,37 @@
     "LOG_LEVEL_META_KEY",
     # Type aliases and variables
     "ContentBlock",
-    "ElicitRequestedSchema",
     "ElicitRequestParams",
+    "EnumSchema",
     "IncludeContext",
     "InputRequest",
     "InputRequests",
     "InputResponse",
     "InputResponses",
     "LoggingLevel",
+    "MultiSelectEnumSchema",
+    "PrimitiveSchemaDefinition",
     "ProgressToken",
     "ResultType",
     "Role",
     "SamplingContent",
     "SamplingMessageContentBlock",
+    "SingleSelectEnumSchema",
     "StopReason",
     "TaskStatus",
+    # Elicitation requested-schema models (form-mode property schemas; primitives only)
+    "BooleanSchema",
+    "ElicitRequestedSchema",
+    "EnumOption",
+    "LegacyTitledEnumSchema",
+    "NumberSchema",
+    "StringSchema",
+    "TitledMultiSelectEnumItems",
+    "TitledMultiSelectEnumSchema",
+    "TitledSingleSelectEnumSchema",
+    "UntitledMultiSelectEnumItems",
+    "UntitledMultiSelectEnumSchema",
+    "UntitledSingleSelectEnumSchema",
     # Base classes
     "BaseMetadata",
     "Request",

src/mcp-types/mcp_types/_types.py

@@ -1911,9 +1911,172 @@ class ElicitCompleteNotification(
     params: ElicitCompleteNotificationParams
 
 
-# Kept as a raw JSON Schema dict so callers can hand it straight to a validator;
-# the per-version packages model RequestedSchema/PrimitiveSchemaDefinition strictly.
-ElicitRequestedSchema: TypeAlias = dict[str, Any]
+class _OpenSchemaModel(MCPModel):
+    """Internal base for the elicitation requested-schema family: an open key set.
+
+    Keys schema.ts does not name still round-trip to the wire. The high-level renderer
+    (`model_json_schema`) emits non-spec JSON Schema keys -- a top-level `title`,
+    `exclusiveMinimum` / `pattern` from `Field(gt=...)` / `Field(pattern=...)`, and anything
+    in `json_schema_extra` -- and `extra="allow"` forwards them unchanged. The
+    primitives-only restriction is carried by the union members' required `type` literals
+    and required fields, NOT by extra-key rejection: `forbid` would break the high-level
+    path, and `ignore` would silently rewrite the user's schema.
+    """
+
+    model_config = ConfigDict(alias_generator=to_camel, populate_by_name=True, extra="allow")
+
+
+class StringSchema(_OpenSchemaModel):
+    """A string-typed form field in an elicitation requested schema."""
+
+    type: Literal["string"]
+    title: str | None = None
+    description: str | None = None
+    min_length: int | None = None
+    max_length: int | None = None
+    format: Literal["email", "uri", "date", "date-time"] | None = None
+    default: str | None = None
+
+
+class NumberSchema(_OpenSchemaModel):
+    """A number- or integer-typed form field in an elicitation requested schema."""
+
+    type: Literal["number", "integer"]
+    title: str | None = None
+    description: str | None = None
+    minimum: int | float | None = None
+    maximum: int | float | None = None
+    default: int | float | None = None
+
+
+class BooleanSchema(_OpenSchemaModel):
+    """A boolean-typed form field in an elicitation requested schema."""
+
+    type: Literal["boolean"]
+    title: str | None = None
+    description: str | None = None
+    default: bool | None = None
+
+
+class EnumOption(_OpenSchemaModel):
+    """An enum value paired with the display title clients show for it."""
+
+    const: str
+    title: str
+
+
+class UntitledSingleSelectEnumSchema(_OpenSchemaModel):
+    """Single-selection enum form field whose options have no display titles."""
+
+    type: Literal["string"]
+    title: str | None = None
+    description: str | None = None
+    enum: list[str]
+    default: str | None = None
+
+
+class TitledSingleSelectEnumSchema(_OpenSchemaModel):
+    """Single-selection enum form field with a display title for each option."""
+
+    type: Literal["string"]
+    title: str | None = None
+    description: str | None = None
+    one_of: list[EnumOption]
+    default: str | None = None
+
+
+SingleSelectEnumSchema: TypeAlias = UntitledSingleSelectEnumSchema | TitledSingleSelectEnumSchema
+"""Single-selection enum form field, with or without display titles for its options."""
+
+
+class UntitledMultiSelectEnumItems(_OpenSchemaModel):
+    """The `items` schema of a multi-select enum whose options have no display titles."""
+
+    type: Literal["string"]
+    enum: list[str]
+
+
+class UntitledMultiSelectEnumSchema(_OpenSchemaModel):
+    """Multiple-selection enum form field whose options have no display titles."""
+
+    type: Literal["array"]
+    title: str | None = None
+    description: str | None = None
+    min_items: int | None = None
+    max_items: int | None = None
+    items: UntitledMultiSelectEnumItems
+    default: list[str] | None = None
+
+
+class TitledMultiSelectEnumItems(_OpenSchemaModel):
+    """The `items` schema of a multi-select enum with a display title for each option."""
+
+    any_of: list[EnumOption]
+
+
+class TitledMultiSelectEnumSchema(_OpenSchemaModel):
+    """Multiple-selection enum form field with a display title for each option."""
+
+    type: Literal["array"]
+    title: str | None = None
+    description: str | None = None
+    min_items: int | None = None
+    max_items: int | None = None
+    items: TitledMultiSelectEnumItems
+    default: list[str] | None = None
+
+
+MultiSelectEnumSchema: TypeAlias = UntitledMultiSelectEnumSchema | TitledMultiSelectEnumSchema
+"""Multiple-selection enum form field, with or without display titles for its options."""
+
+
+class LegacyTitledEnumSchema(_OpenSchemaModel):
+    """Enum form field using `enum` / `enumNames`; the spec will remove this in a future version.
+
+    Use `TitledSingleSelectEnumSchema` instead.
+    """
+
+    type: Literal["string"]
+    title: str | None = None
+    description: str | None = None
+    enum: list[str]
+    enum_names: list[str] | None = None
+    default: str | None = None
+
+
+EnumSchema: TypeAlias = SingleSelectEnumSchema | MultiSelectEnumSchema | LegacyTitledEnumSchema
+"""Any of the elicitation enum form-field schemas."""
+
+PrimitiveSchemaDefinition: TypeAlias = StringSchema | NumberSchema | BooleanSchema | EnumSchema
+"""Restricted schema definitions allowed as elicitation form fields: primitives only, no nesting."""
+
+
+class ElicitRequestedSchema(_OpenSchemaModel):
+    """A restricted subset of JSON Schema: a flat object whose properties are all primitive-typed.
+
+    This is the only schema type the typed send methods (`ServerSession.elicit_form`,
+    `ClientPeer.elicit_form`) accept, so a nested-object or array-of-objects property is
+    unconstructible on the send side. The wire field `ElicitRequestFormParams.requested_schema`
+    stays a plain dict so the inbound parse remains lenient (see that field's docstring).
+    """
+
+    schema_: Annotated[str | None, Field(alias="$schema")] = None
+    type: Literal["object"] = "object"
+    properties: dict[str, PrimitiveSchemaDefinition]
+    required: list[str] | None = None
+
+    def to_wire(self) -> dict[str, Any]:
+        """Serialize to the plain dict that `ElicitRequestFormParams.requested_schema` carries.
+
+        This type never appears on the wire itself: the wire field is a deliberately
+        lenient `dict[str, Any]` so the client's inbound parse tolerates non-conforming
+        schemas from older servers. This method is the one place a typed schema becomes
+        that wire dict, and the typed send methods (`ServerSession.elicit_form`,
+        `ClientPeer.elicit_form`) both call it.
+        """
+        # exclude_none, not exclude_unset: a keyword-constructed instance must keep its
+        # defaulted `type` literals on the wire; only the None-valued optionals are dropped.
+        return self.model_dump(by_alias=True, exclude_none=True)
 
 
 class ElicitRequestFormParams(RequestParams):
@@ -1929,10 +2092,16 @@ class ElicitRequestFormParams(RequestParams):
     message: str
     """The message to present to the user describing what information is being requested."""
 
-    requested_schema: ElicitRequestedSchema
+    requested_schema: dict[str, Any]
     """
     A restricted subset of JSON Schema defining the structure of the expected response.
     Only top-level properties are allowed, without nesting.
+
+    Deliberately a plain dict, not `ElicitRequestedSchema`: this field is also the client's
+    inbound parse, and older servers emit `anyOf` for `Optional` form fields, which must
+    still reach the user's elicitation callback. The spec's primitives-only restriction is
+    enforced on the send side, where `ServerSession.elicit_form` and `ClientPeer.elicit_form`
+    only accept `ElicitRequestedSchema`.
     """
 
     task: TaskMetadata | None = None