---
title: tasks
sidebarTitle: tasks
---
# `fastmcp.client.tasks`
SEP-1686 client Task classes.
## Classes
### `TaskNotificationHandler`
MessageHandler that routes task status notifications to Task objects.
**Methods:**
#### `dispatch`
```python
dispatch(self, message: Message) -> None
```
Dispatch messages, including task status notifications.
### `Task`
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`
```python
task_id(self) -> str
```
Get the task ID.
#### `returned_immediately`
```python
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`
```python
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`
```python
status(self) -> GetTaskResult
```
Get current task status.
If server executed immediately, returns synthetic completed status.
Otherwise queries the server for current status.
#### `result`
```python
result(self) -> TaskResultT
```
Wait for and return the task result.
Must be implemented by subclasses to return the appropriate result type.
#### `wait`
```python
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 ('submitted', 'working', 'completed', 'failed').
If None, waits for any terminal state (completed/failed)
- `timeout`: Maximum time to wait in seconds
**Returns:**
- Final task status
**Raises:**
- `TimeoutError`: If desired state not reached within timeout
#### `cancel`
```python
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`
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`
```python
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`
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`
```python
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`
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`
```python
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