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 ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/tasks/context.py#L30" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

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 ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/tasks/context.py#L70" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

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 ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/tasks/context.py#L245" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

get_task_session_id() -> str | None

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

Loads the task snapshot (from cache or Redis) and returns the session_id that was captured at task submission time. Returns None if not in a task context or if the snapshot isn't available.

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

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 ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/tasks/context.py#L351" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

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 ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/tasks/context.py#L370" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

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 ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/tasks/context.py#L381" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

get_task_server(task_id: str) -> FastMCP | None

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

Classes

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

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 ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/tasks/context.py#L100" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

All context data snapshotted at task-submission time.

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

Methods:

capture ^{<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>}

capture(cls) -> TaskContextSnapshot

Capture current context for background task execution.

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

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

Deserialize from JSON stored in Redis.

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

to_json(self) -> str

Serialize to JSON for Redis storage.

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

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

Store this snapshot as a single Redis key.