fastmcp/docs/python-sdk/fastmcp-server-tasks-context.mdx

---
title: context
sidebarTitle: context
---

# `fastmcp.server.tasks.context`


Task context and scoping for background task execution.

Determines authorization scope (``get_task_scope``), manages the context
snapshot that is captured at task submission and restored in workers
(``TaskContextSnapshot``), and maintains in-process registries for live
sessions and servers.


## Functions

### `get_task_scope` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/tasks/context.py#L42" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_task_scope() -> str | None
```


Get the authorization scope for task isolation.

Returns the raw scope identifier for the current access token, or
``None`` when no auth context is present (anonymous tasks).

The scope is composed as ``client_id|sub`` when the token carries a
``sub`` claim — necessary for fixed-OAuth servers where ``client_id`` is
shared across all users — and falls back to ``client_id`` alone for
DCR/CIMD flows where the client identity is already per-user.

Encoding for Redis/Docket keys happens at the boundary in ``keys.py``;
this function returns the raw value.


### `get_task_context` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/tasks/context.py#L82" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_task_context() -> TaskContextInfo | None
```


Get the current task context if running inside a background task worker.

This function extracts task information from the Docket execution context.
Returns None if not running in a task context (e.g., foreground execution).

**Returns:**
- TaskContextInfo with task_id and task_scope, or None if not in a task.


### `get_task_session_id` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/tasks/context.py#L220" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_task_session_id() -> str | None
```


Get the session_id for the current background task, if available.

Reads the cached snapshot set by the worker-level restore dependency.
Returns None if not in a task context or the snapshot wasn't restored.


### `restore_task_snapshot` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/tasks/context.py#L233" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
restore_task_snapshot(key: str = TaskKey()) -> None
```


Worker-level Docket dependency that restores the task-context snapshot.

Runs before each fastmcp-owned task, populating the snapshot ContextVar
so user code — and any task-scoped dependency like ``_CurrentContext`` —
sees a ready snapshot without touching Redis itself.  All Redis I/O
goes through Docket's async client, so cluster URLs and the memory://
backend work transparently (#3897).  Failures are non-fatal: the task
still runs, and sync helpers return ``None`` as they would have before
the snapshot was captured.


### `register_task_session` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/tasks/context.py#L286" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
register_task_session(session_id: str, session: ServerSession) -> None
```


Register a session for in-process background task access.

Called automatically when a task is submitted to Docket. The session is
stored as a weakref so it doesn't prevent garbage collection when the
client disconnects.


### `get_task_session` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/tasks/context.py#L296" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_task_session(session_id: str) -> ServerSession | None
```


Get a registered session by ID if still alive.

Returns None in distributed workers where the session lives in another
process — callers must handle this gracefully.


### `register_task_server` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/tasks/context.py#L315" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
register_task_server(task_id: str, server: FastMCP) -> None
```


Register the server for a background task.

Called at task-submission time so that background workers can resolve
the correct (child) server for mounted tasks.


### `get_task_server` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/tasks/context.py#L326" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_task_server(task_id: str) -> FastMCP | None
```


Get the registered server for a background task, if still alive.


## Classes

### `TaskContextInfo` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/tasks/context.py#L68" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>


Information about the current background task context.

Returned by ``get_task_context()`` when running inside a Docket worker.
Contains identifiers needed to communicate with the MCP session.


### `TaskContextSnapshot` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/tasks/context.py#L112" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>


All context data snapshotted at task-submission time.

Stored as a single Redis key per task, restored once in the worker.


**Methods:**

#### `capture` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/tasks/context.py#L124" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
capture(cls) -> TaskContextSnapshot
```

Capture current context for background task execution.


#### `from_json` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/tasks/context.py#L151" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
from_json(cls, raw: str | bytes) -> TaskContextSnapshot
```

Deserialize from JSON stored in Redis.


#### `to_json` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/tasks/context.py#L166" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
to_json(self) -> str
```

Serialize to JSON for Redis storage.


#### `save` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/tasks/context.py#L177" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
save(self, docket: Docket, task_scope: str | None, task_id: str, ttl_seconds: int) -> None
```

Store this snapshot as a single Redis key.