fastmcp.server.tasks.elicitation

Background task elicitation support (SEP-1686).

This module provides elicitation capabilities for background tasks running in Docket workers. Unlike regular MCP requests, background tasks don't have an active request context, so elicitation requires special handling:

1. Set task status to "input_required" via Redis
2. Send notifications/tasks/status with elicitation metadata
3. Wait for client to send input via tasks/sendInput
4. Resume task execution with the provided input

This uses the public MCP SDK APIs where possible, with minimal use of internal APIs for background task coordination.

Functions

elicit_for_task ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/tasks/elicitation.py#L47" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

elicit_for_task(task_id: str, session: ServerSession | None, message: str, schema: dict[str, Any], fastmcp: FastMCP) -> mcp.types.ElicitResult

Send an elicitation request from a background task.

This function handles the complexity of eliciting user input when running in a Docket worker context where there's no active MCP request.

Args:

• task_id: The background task ID
• session: The MCP ServerSession for this task
• message: The message to display to the user
• schema: The JSON schema for the expected response
• fastmcp: The FastMCP server instance

Returns:

• ElicitResult containing the user's response

Raises:

• RuntimeError: If Docket is not available
• McpError: If the elicitation request fails

relay_elicitation ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/tasks/elicitation.py#L239" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

relay_elicitation(session: ServerSession, task_scope: str | None, task_id: str, elicitation: dict[str, Any], fastmcp: FastMCP) -> None

Relay elicitation from a background task worker to the client.

Called by the notification subscriber when it detects an input_required notification with elicitation metadata. Sends a standard elicitation/create request to the client session, then uses handle_task_input() to push the response to Redis so the blocked worker can resume.

Args:

• session: MCP ServerSession
• task_scope: Authorization scope for Redis key construction
• task_id: Background task ID
• elicitation: Elicitation metadata (message, requestedSchema)
• fastmcp: FastMCP server instance

handle_task_input ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/tasks/elicitation.py#L295" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

handle_task_input(task_id: str, task_scope: str | None, action: str, content: dict[str, Any] | None, fastmcp: FastMCP) -> bool

Handle input sent to a background task via tasks/sendInput.

This is called when a client sends input in response to an elicitation request from a background task.

Args:

• task_id: The background task ID
• task_scope: Authorization scope for Redis key construction
• action: The elicitation action ("accept", "decline", "cancel")
• content: The response content (for "accept" action)
• fastmcp: The FastMCP server instance

Returns:

• True if the input was successfully stored, False otherwise