Skip to main content

Documentation Index

Fetch the complete documentation index at: https://gofastmcp.com/llms.txt

Use this file to discover all available pages before exploring further.

​
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 

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 

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 

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 

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 

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 

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 

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 

get_task_server(task_id: str) -> FastMCP | None
Get the registered server for a background task, if still alive.

​
Classes

​
TaskContextInfo

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

All context data snapshotted at task-submission time. Stored as a single Redis key per task, restored once in the worker. Methods:

​
capture 

capture(cls) -> TaskContextSnapshot
Capture current context for background task execution.

​
from_json 

from_json(cls, raw: str | bytes) -> TaskContextSnapshot
Deserialize from JSON stored in Redis.

​
to_json 

to_json(self) -> str
Serialize to JSON for Redis storage.

​
save 

save(self, docket: Docket, task_scope: str | None, task_id: str, ttl_seconds: int) -> None
Store this snapshot as a single Redis key.