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

@@ -812,6 +812,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/mrtr/server.py

@@ -1,15 +1,21 @@
 """Multi-round tool result (2026 era): a tool returns input_required and resumes from echoed state."""
 
-from mcp_types import ElicitRequest, ElicitRequestedSchema, ElicitRequestFormParams, ElicitResult, InputRequiredResult
+from mcp_types import (
+    BooleanSchema,
+    ElicitRequest,
+    ElicitRequestedSchema,
+    ElicitRequestFormParams,
+    ElicitResult,
+    InputRequiredResult,
+)
 
 from mcp.server.mcpserver import Context, MCPServer
 from stories._hosting import run_server_from_args
 
-CONFIRM_SCHEMA: ElicitRequestedSchema = {
-    "type": "object",
-    "properties": {"confirm": {"type": "boolean", "description": "Proceed with the deployment?"}},
-    "required": ["confirm"],
-}
+CONFIRM_SCHEMA = ElicitRequestedSchema(
+    properties={"confirm": BooleanSchema(type="boolean", description="Proceed with the deployment?")},
+    required=["confirm"],
+)
 
 
 def build_server() -> MCPServer:
@@ -22,7 +28,7 @@ async def deploy(env: str, ctx: Context) -> str | InputRequiredResult:
             # First round: ask the client to elicit confirmation. request_state is opaque
             # to the client; here it carries the step name so the retry can verify the echo.
             ask = ElicitRequest(
-                params=ElicitRequestFormParams(message=f"Deploy to {env}?", requested_schema=CONFIRM_SCHEMA)
+                params=ElicitRequestFormParams(message=f"Deploy to {env}?", requested_schema=CONFIRM_SCHEMA.to_wire())
             )
             return InputRequiredResult(input_requests={"confirm": ask}, request_state="awaiting-confirm")
         # Retry round: the client echoed request_state byte-exact and supplied the answer.

examples/stories/mrtr/server_lowlevel.py

@@ -8,11 +8,10 @@
 from mcp.server.lowlevel import Server
 from stories._hosting import run_server_from_args
 
-CONFIRM_SCHEMA: types.ElicitRequestedSchema = {
-    "type": "object",
-    "properties": {"confirm": {"type": "boolean", "description": "Proceed with the deployment?"}},
-    "required": ["confirm"],
-}
+CONFIRM_SCHEMA = types.ElicitRequestedSchema(
+    properties={"confirm": types.BooleanSchema(type="boolean", description="Proceed with the deployment?")},
+    required=["confirm"],
+)
 DEPLOY_INPUT_SCHEMA: dict[str, Any] = {
     "type": "object",
     "properties": {"env": {"type": "string"}},
@@ -42,7 +41,9 @@ async def call_tool(
         responses = params.input_responses
         if responses is None or "confirm" not in responses:
             ask = types.ElicitRequest(
-                params=types.ElicitRequestFormParams(message=f"Deploy to {env}?", requested_schema=CONFIRM_SCHEMA)
+                params=types.ElicitRequestFormParams(
+                    message=f"Deploy to {env}?", requested_schema=CONFIRM_SCHEMA.to_wire()
+                )
             )
             return types.InputRequiredResult(input_requests={"confirm": ask}, request_state="awaiting-confirm")
         assert params.request_state == "awaiting-confirm", params.request_state

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",