Add support for Elicitation

[ihrpr]

Elicitation Spec PR

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]

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)

[Kludex]

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

[ihrpr]

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:

1. Dynamic context - The same schema can be reused with different messages based on the situation
2. 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]

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.

[Kludex]

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

[ihrpr]

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

[Kludex]

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)

[dsp-ant]

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]

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]

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]

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)

[ihrpr]

oh, this is great!

[Kludex]

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]

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)