# Source: https://gofastmcp.com/python-sdk/fastmcp-client-tasks.md

> ## Documentation Index
> Fetch the complete documentation index at: https://gofastmcp.com/llms.txt
> Use this file to discover all available pages before exploring further.

# tasks

# `fastmcp.client.tasks`

SEP-1686 client Task classes.

## Classes

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

MessageHandler that routes task status notifications to Task objects.

**Methods:**

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

```python  theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
dispatch(self, message: Message) -> None
```

Dispatch messages, including task status notifications.

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

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` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/tasks.py#L105" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python  theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
task_id(self) -> str
```

Get the task ID.

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

```python  theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
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` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/tasks.py#L145" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python  theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
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` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/tasks.py#L171" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python  theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
status(self) -> GetTaskResult
```

Get current task status.

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

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

```python  theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
result(self) -> TaskResultT
```

Wait for and return the task result.

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

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

```python  theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
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` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/tasks.py#L272" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python  theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
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` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/tasks.py#L294" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

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` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/tasks.py#L336" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python  theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
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` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/tasks.py#L396" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

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` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/tasks.py#L427" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python  theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
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` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/tasks.py#L461" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

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` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/client/tasks.py#L497" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python  theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
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