fastmcp.client.tasks

SEP-1686 client Task classes.

Classes

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

MessageHandler that routes task status notifications to Task objects.

Methods:

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

dispatch(self, message: Message) -> None

Dispatch messages, including task status notifications.

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

Abstract base class for MCP background tasks (SEP-1686).

Provides a uniform API whether the server accepts background execution or executes synchronously (graceful degradation per SEP-1686).

Methods:

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

task_id(self) -> str

Get the task ID.

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

returned_immediately(self) -> bool

Check if server executed the task immediately.

Returns:

• True if server executed synchronously (graceful degradation or no task support)
• False if server accepted background execution

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

on_status_change(self, callback: Callable[[GetTaskResult], None | Awaitable[None]]) -> None

Register callback for status change notifications.

The callback will be invoked when a notifications/tasks/status is received for this task (optional server feature per SEP-1686 lines 436-444).

Supports both sync and async callbacks (auto-detected).

Args:

• callback: Function to call with GetTaskResult when status changes. Can return None (sync) or Awaitable[None] (async).

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

status(self) -> GetTaskResult

Get current task status.

If server executed immediately, returns synthetic completed status. Otherwise queries the server for current status.

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

result(self) -> TaskResultT

Wait for and return the task result.

Must be implemented by subclasses to return the appropriate result type.

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

wait(self) -> GetTaskResult

Wait for task to reach a specific state or complete.

Uses event-based waiting when notifications are available (fast), with fallback to polling (reliable). Optimally wakes up immediately on status changes when server sends notifications/tasks/status.

Args:

• state: Desired state ('working', 'input_required', 'completed', 'failed', 'cancelled'). If None, waits until the task exits the 'working' state (completed, failed, cancelled, input_required, etc.)
• timeout: Maximum time to wait in seconds

Returns:

• Final task status

Raises:

• TimeoutError: If desired state not reached within timeout

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

cancel(self) -> None

Cancel this task, transitioning it to cancelled state.

Sends a tasks/cancel protocol request. The server will attempt to halt execution and move the task to cancelled state.

Note: If server executed immediately (graceful degradation), this is a no-op as there's no server-side task to cancel.

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

Represents a tool call that may execute in background or immediately.

Provides a uniform API whether the server accepts background execution or executes synchronously (graceful degradation per SEP-1686).

Methods:

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

result(self) -> CallToolResult

Wait for and return the tool result.

If server executed immediately, returns the immediate result. Otherwise waits for background task to complete and retrieves result.

Returns:

• The parsed tool result (same as call_tool returns)

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

Represents a prompt call that may execute in background or immediately.

Provides a uniform API whether the server accepts background execution or executes synchronously (graceful degradation per SEP-1686).

Methods:

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

result(self) -> mcp.types.GetPromptResult

Wait for and return the prompt result.

If server executed immediately, returns the immediate result. Otherwise waits for background task to complete and retrieves result.

Returns:

• The prompt result with messages and description

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

Represents a resource read that may execute in background or immediately.

Provides a uniform API whether the server accepts background execution or executes synchronously (graceful degradation per SEP-1686).

Methods:

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

result(self) -> list[mcp.types.TextResourceContents | mcp.types.BlobResourceContents]

Wait for and return the resource contents.

If server executed immediately, returns the immediate result. Otherwise waits for background task to complete and retrieves result.

Returns:

• list[ReadResourceContents]: The resource contents