Add support for Elicitation #625

ihrpr · 2025-05-04T17:58:24Z

Overview

Adding support for the elicitation feature, allowing servers to interactively request additional information from clients during tool execution. The implementation follows a layered approach with both low-level protocol support and a high-level API through FastMCP.

Key Changes

1. Protocol Layer (`src/mcp/types.py`)

Added ElicitRequest, ElicitRequestParams, and ElicitResult types to support the elicitation protocol
Extended ServerRequest and ClientResult to handle elicitation messages
Follows the MCP specification for elicitation support

2. Low-Level Server/Client (`src/mcp/server/session.py`, `src/mcp/client/session.py`)

Added elicit() method to ServerSession for sending elicitation requests
Added elicit() method to ClientSession for handling server elicitation requests
Design decision: Uses raw dictionaries instead of Pydantic models - this maintains consistency with the low-level API design which provides direct protocol access without data modeling abstractions

3. FastMCP High-Level API (`src/mcp/server/fastmcp/server.py`)

Added Context.elicit() method that returns an ElicitationResult object
Design decision: Returns a result object instead of raising exceptions for decline/cancel actions. This treats user declining or cancelling as expected outcomes rather than error conditions
Enforces MCP specification requirement that elicitation schemas only contain primitive types (str, int, float, bool)
Validates schemas at runtime with descriptive error messages

FastMCP Interface Design

The FastMCP elicitation interface prioritizes type safety and explicit result handling:

@server.tool()
async def book_table(date: str, party_size: int, ctx: Context) -> str:
    class ConfirmBooking(BaseModel):
        confirm: bool = Field(description="Confirm booking?")
        notes: str = Field(default="", description="Special requests")

    result = await ctx.elicit(
        message=f"Confirm booking for {party_size} on {date}?",
        schema=ConfirmBooking
    )

    if result.action == "accept" and result.data:
        # result.data is typed as ConfirmBooking
        if result.data.confirm:
            return f"Booked! Notes: {result.data.notes}"
    elif result.action == "decline":
        return "User declined"
    else:  # cancel
        return "User cancelled"

Interface characteristics:

result.data is typed according to the provided schema
All three user actions (accept/decline/cancel) are handled explicitly
Validation errors are captured in result.validation_error when user input doesn't match schema
Schema validation happens before sending the request, failing fast if non-primitive types are used

Kludex · 2025-06-11T17:10:41Z

src/mcp/server/fastmcp/server.py

+        requestedSchema: dict[str, Any],
+    ) -> dict[str, Any]:


I think what you want would be something like this:

async def elicit(self, schema: type[T], message: str | None = None) -> T: ...

And then it can be used inside the tools as:

from mcp.server.fastmcp import FastMCP from typing_extensions import TypedDict app = FastMCP() class MyServerSchema(TypedDict): name: str @app.tool() async def potato_tool(ctx: Context): content = await ctx.elicit(MyServerSchema)

I added message as optional because I can imagine us extracting the message from the docstring of MyServerSchema. For the best user experience.

Thank you! I,plemented elicit, looks nice and typesafa now!

Re message in the schema:

The message and schema serve distinct purposes in the elicitation flow:

The message is the contextual question or prompt that explains why we're asking for information (e.g., "No tables available at 7 PM. Would you like to try 8 PM instead?")

The schema defines what information we're collecting and its structure (e.g., fields for confirmation, alternative time, etc.)

This separation allows for:

Dynamic context - The same schema can be reused with different messages based on the situation

Clearer intent - The message can provide specific context that wouldn't make sense as a docstring (like "Your session will expire in 5 minutes. Save your work?")

Kludex · 2025-06-12T11:11:06Z

README.md

+    result = await ctx.elicit(
+        message=f"Confirm booking for {party_size} on {date}?", schema=ConfirmBooking
+    )


I think it gives us a better API and user experience if ctx.elicit(schema=SchemaT) always return an instance of SchemaT, or an exception.

My comment implies that an exception would be raised if user rejects.

then the problem will be how to distinguish between cancel and reject?

Suggested change

result = await ctx.elicit(

message=f"Confirm booking for {party_size} on {date}?", schema=ConfirmBooking

)

try:

result = await ctx.elicit(

message=f"Confirm booking for {party_size} on {date}?",

schema=ConfirmBooking

)

except ElicitError as exc:

print(exc.reason)

Wouldn't this imply that we use exceptions for control flow? We should reserve exceptions for handling exceptional circumstances. I don't think decline fits into this.

I do prefer having a return value that indicates if it was accepted,declined,etc.

Kludex · 2025-06-16T16:06:32Z

README.md

+The `elicit()` method returns an `ElicitationResult` with:
+- `action`: "accept", "decline", or "cancel" 
+- `data`: The validated response (only when accepted)
+- `validation_error`: Any validation error message


I think this should just bubble.

dsp-ant

I think this PR is missing the implementation for mcp/server/lowlevel/server.py.

I decline this for now mostly because of elicitation being implement in FastMCP, but I believe it belongs at a lower level such that lowlevel server implementations have access to it.

For the tagged union appraoch, I would prefer it, but I am okay if it's not.

dsp-ant · 2025-06-16T16:21:54Z

README.md

+    result = await ctx.elicit(
+        message=f"Confirm booking for {party_size} on {date}?", schema=ConfirmBooking
+    )


Wouldn't this imply that we use exceptions for control flow? We should reserve exceptions for handling exceptional circumstances. I don't think decline fits into this.

I do prefer having a return value that indicates if it was accepted,declined,etc.

dsp-ant · 2025-06-16T16:30:32Z

src/mcp/server/fastmcp/server.py

+class ElicitationResult(BaseModel, Generic[ElicitSchemaModelT]):
+    """Result of an elicitation request."""
+
+    action: Literal["accept", "decline", "cancel"]
+    """The user's action in response to the elicitation."""
+
+    data: ElicitSchemaModelT | None = None
+    """The validated data if action is 'accept', None otherwise."""
+
+    validation_error: str | None = None
+    """Validation error message if data failed to validate."""
+


Okay, I think I can be fine with this, but the FP person in me really doesn't like that this is not very typesafe, because data and validation_error depends on action.

An alternative, and something I probably prefer is using a tagged union:

from typing import Literal class AcceptedElicitation(BaseModel, Generic[T]): action: Literal["accept"] data: T class DeclinedElicitation(BaseModel): action: Literal["decline"] class CancelledElicitation(BaseModel): action: Literal["cancel"] class ValidationFailedElicitation(BaseModel): action: Literal["accept"] validation_error: str ElicitationResult = AcceptedElicitation[T] | DeclinedElicitation | CancelledElicitation | ValidationFailedElicitation

You can then do:

match result: case AcceptedElicitation(data=data): # data is guaranteed to exist and be typed process(data) case DeclinedElicitation(): handle_decline() case CancelledElicitation(): handle_cancel() case ValidationFailedElicitation(validation_error=error): handle_validation_error(error)

oh, this is great!

I don't think we want to have validation_error as a str, it should bubble up. User may want to handle it differently.

dsp-ant · 2025-06-16T16:41:59Z

src/mcp/server/fastmcp/server.py

+    async def elicit(
+        self,
+        message: str,
+        schema: type[ElicitSchemaModelT],
+    ) -> ElicitationResult[ElicitSchemaModelT]:
+        """Elicit information from the client/user.
+
+        This method can be used to interactively ask for additional information from the
+        client within a tool's execution. The client might display the message to the
+        user and collect a response according to the provided schema. Or in case a
+        client is an agent, it might decide how to handle the elicitation -- either by asking
+        the user or automatically generating a response.
+
+        Args:
+            schema: A Pydantic model class defining the expected response structure, according to the specification,
+                    only primive types are allowed.
+            message: Optional message to present to the user. If not provided, will use
+                    a default message based on the schema
+
+        Returns:
+            An ElicitationResult containing the action taken and the data if accepted
+
+        Note:
+            Check the result.action to determine if the user accepted, declined, or cancelled.
+            The result.data will only be populated if action is "accept" and validation succeeded.
+        """
+
+        # Validate that schema only contains primitive types and fail loudly if not
+        _validate_elicitation_schema(schema)
+
+        json_schema = schema.model_json_schema()
+
+        result = await self.request_context.session.elicit(
+            message=message,
+            requestedSchema=json_schema,
+            related_request_id=self.request_id,
+        )
+
+        if result.action == "accept" and result.content:
+            # Validate and parse the content using the schema
+            try:
+                validated_data = schema.model_validate(result.content)
+                return ElicitationResult(action="accept", data=validated_data)
+            except ValidationError as e:
+                return ElicitationResult(action="accept", validation_error=str(e))
+        else:
+            return ElicitationResult(action=result.action)
+


This should not be defined here. This should be in the ServerSession and be called from request_context.session.

The SDK is layered in such a way that FastMCP should always only contain convenience wrapping server/lowlevel or server/session, but never implement functionality itself.

ihrpr

thank you @dsp-ant, types LGTM

(note, there is a conflict in readme)

ihrpr mentioned this pull request May 6, 2025

[feat] Introduce elcitation as new client capability modelcontextprotocol/modelcontextprotocol#382

Merged

LucaButBoring mentioned this pull request May 27, 2025

feat: implement support for elicitation modelcontextprotocol/java-sdk#271

Closed

9 tasks

Kludex reviewed Jun 11, 2025

View reviewed changes

ihrpr changed the title ~~Elicitation prototype~~ Add support for Elicitation Jun 12, 2025

ihrpr requested review from dsp-ant and bhosmer-ant June 12, 2025 10:16

ihrpr marked this pull request as ready for review June 12, 2025 10:17

ihrpr linked an issue Jun 12, 2025 that may be closed by this pull request

Introduce elicitation as new client capability #920

Closed

Kludex reviewed Jun 12, 2025

View reviewed changes

Kludex reviewed Jun 16, 2025

View reviewed changes

dsp-ant requested changes Jun 16, 2025

View reviewed changes

dsp-ant force-pushed the ihrpr/elicitation-prototype branch 2 times, most recently from 0359e94 to 150f839 Compare June 17, 2025 10:03

ihrpr commented Jun 17, 2025

View reviewed changes

dsp-ant and others added 10 commits June 17, 2025 11:46

Elicitation

6597f30

add elicitation test using create_client_server_memory_streams

40470d6

field rename

427a634

adjust types after the spec revision

3a2d915

add ElicitationResult to fastMCP

a75afd4

add readme

4603e89

add validation for primitive types

653c057

cleanup

d4ae036

format

67bfd9a

Update

51b5ee8

dsp-ant force-pushed the ihrpr/elicitation-prototype branch from 150f839 to 51b5ee8 Compare June 17, 2025 10:49

dsp-ant merged commit 69e6572 into main Jun 17, 2025
12 checks passed

dsp-ant deleted the ihrpr/elicitation-prototype branch June 17, 2025 10:54

samuelcolvin mentioned this pull request Jun 20, 2025

Tool Injection for mcp-run-python: Enable Python code to call back to agent tools with request/response flow pydantic/pydantic-ai#2037

Open

Add support for Elicitation #625

Add support for Elicitation #625

Uh oh!

Conversation

ihrpr commented May 4, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Overview

Key Changes

1. Protocol Layer (src/mcp/types.py)

2. Low-Level Server/Client (src/mcp/server/session.py, src/mcp/client/session.py)

3. FastMCP High-Level API (src/mcp/server/fastmcp/server.py)

FastMCP Interface Design

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Kludex Jun 16, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dsp-ant left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ihrpr left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

ihrpr commented May 4, 2025 •

edited

Loading

1. Protocol Layer (`src/mcp/types.py`)

2. Low-Level Server/Client (`src/mcp/server/session.py`, `src/mcp/client/session.py`)

3. FastMCP High-Level API (`src/mcp/server/fastmcp/server.py`)

Kludex Jun 16, 2025 •

edited

Loading