fastmcp.server.dependencies

Dependency injection for FastMCP.

DI features (Depends, CurrentContext, CurrentFastMCP) work without pydocket using the uncalled-for DI engine. The docket-specific dependencies (CurrentDocket, CurrentWorker) and background task execution live in the fastmcp-tasks package.

Functions

bind_request_context ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/server/dependencies.py#L104" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

bind_request_context(ctx: ServerRequestContext) -> Generator[FastMCPRequestContext, None, None]

Bind a FastMCPRequestContext for the duration of a handler.

Constructs the wrapper from the SDK's per-request context and sets/resets the fastmcp_request_ctx ContextVar. Every request adapter and the initialize middleware enters this so Context and dependency helpers can read the active request from the ContextVar.

extract_version_spec ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/server/dependencies.py#L131" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

extract_version_spec(meta: dict[str, Any] | None) -> str | None

Extract the FastMCP component version from a lifted _meta block.

set_background_context_factory ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/server/dependencies.py#L185" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

set_background_context_factory(factory: Callable[[], Awaitable[Context | None]] | None) -> None

Install (or clear) the background-task Context factory.

The factory returns an already-entered Context (so _current_context is set for cleanup) when called inside a worker, or None when there is no task context. Passing None restores core's no-worker-fallback behavior.

set_worker_server_resolver ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/server/dependencies.py#L207" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

set_worker_server_resolver(resolver: Callable[[], FastMCP | None] | None) -> None

Install (or clear) the worker-server resolver used by get_server().

is_docket_available ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/server/dependencies.py#L244" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

is_docket_available() -> bool

Check if a compatible pydocket (>= 0.19.0) is installed and importable.

Three things have to be true for fastmcp's task features to work:

1. pydocket distribution metadata is discoverable
2. its version is at least _MIN_DOCKET_VERSION (older versions are missing symbols like docket.dependencies.current_execution, which fastmcp imports on the request hot path)
3. the package actually imports — guards against broken/partial installs where metadata exists but import docket blows up

Any of those failing means we treat docket as unavailable and fall back to the no-tasks code paths instead of crashing deep inside a request.

transform_context_annotations ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/server/dependencies.py#L276" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

transform_context_annotations(fn: Callable[..., Any]) -> Callable[..., Any]

Transform injected-by-type params into Dependency-defaulted params.

Transforms ALL params typed as Context (into = CurrentContext()) and as UserSession (into = CurrentSession()) to use Docket's DI system, unless they already have a Dependency-based default.

This unifies the legacy type annotation DI with Docket's Depends() system, allowing both patterns to work through a single resolution path.

Note: Only POSITIONAL_OR_KEYWORD parameters are reordered (params with defaults after those without). KEYWORD_ONLY parameters keep their position since Python allows them to have defaults in any order.

Args:

• fn: Function to transform

Returns:

• Function with modified signature (same function object, updated signature)

get_context ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/server/dependencies.py#L442" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

get_context() -> Context

Get the current FastMCP Context instance directly.

get_server ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/server/dependencies.py#L452" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

get_server() -> FastMCP

Get the current FastMCP server instance directly.

In a background-task worker the tasks extension's resolver is consulted first, so a mounted-child task resolves to the child server rather than the root that started the worker (#3571).

Returns:

• The active FastMCP server

Raises:

• RuntimeError: If no server in context

get_session ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/server/dependencies.py#L480" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

get_session(session_id: str) -> Session

Resolve and validate a Session for an explicit session_id.

Pair with a session_id: SessionId tool argument (the agent obtains an id from create_session and passes it back). For a single per-user bucket with nothing for the agent to pass, inject session: UserSession instead.

State is keyed by (principal, session_id): the authenticated principal is the isolation wall and session_id organizes sessions within it. The id must have been minted by create_session under the current principal; an id that was never created, or created under a different principal, raises InvalidSession rather than resolving to a fresh empty bucket (the specific reason is logged at debug level, never returned to the caller).

Like get_server(), this resolves through the task-aware server, so it needs no foreground context — it works from a task=True tool's Docket worker as well as a normal request.

get_http_request ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/server/dependencies.py#L515" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

get_http_request() -> Request

Get the current HTTP request.

Tries MCP SDK's request_ctx first, then falls back to FastMCP's HTTP context.

get_http_headers ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/server/dependencies.py#L536" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

get_http_headers(include_all: bool = False, include: set[str] | None = None) -> dict[str, str]

Extract headers from the current HTTP request if available.

Never raises an exception, even if there is no active HTTP request (in which case an empty dict is returned).

By default, strips problematic headers like content-length and authorization that cause issues if forwarded to downstream services. If include_all is True, all headers are returned.

The include parameter allows specific headers to be included even if they would normally be excluded. This is useful for proxy transports that need to forward authorization headers to upstream MCP servers.

get_access_token ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/server/dependencies.py#L600" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

get_access_token() -> AccessToken | None

Get the FastMCP access token from the current context.

This function first tries to get the token from the current HTTP request's scope, which is more reliable for long-lived connections where the SDK's auth_context_var may become stale after token refresh. Falls back to the SDK's context var if no request is available.

Returns:

• The access token if an authenticated user is available, None otherwise.

without_injected_parameters ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/server/dependencies.py#L659" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

without_injected_parameters(fn: Callable[..., Any]) -> Callable[..., Any]

Create a wrapper function without injected parameters.

Returns a wrapper that excludes Context and Docket dependency parameters, making it safe to use with Pydantic TypeAdapter for schema generation and validation. The wrapper internally handles all dependency resolution and Context injection when called.

Handles:

• Legacy Context injection (always works)
• Depends() injection (always works - uses docket or vendored DI engine)

Args:

• fn: Original function with Context and/or dependencies
• run_in_thread: For sync fn, whether to dispatch the call to a worker thread after resolving dependencies. Defaults to True. Set to False to call fn inline on the event loop thread — required for thread-affinity libraries (e.g. Windows COM). Ignored for async fns.

Returns:

• Async wrapper function without injected parameters

resolve_dependencies ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/server/dependencies.py#L820" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

resolve_dependencies(fn: Callable[..., Any], arguments: dict[str, Any]) -> AsyncGenerator[dict[str, Any], None]

Resolve dependencies for a FastMCP function.

This function:

1. Filters out any dependency parameter names from user arguments (security)
2. Resolves Depends() parameters via the DI system

The filtering prevents external callers from overriding injected parameters by providing values for dependency parameter names. This is a security feature.

Note: Context injection is handled via transform_context_annotations() which converts ctx: Context to ctx: Context = Depends(get_context) at registration time, so all injection goes through the unified DI system.

Args:

• fn: The function to resolve dependencies for
• arguments: User arguments (may contain keys that match dependency names, which will be filtered out)

CurrentContext ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/server/dependencies.py#L945" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

CurrentContext() -> Context

Get the current FastMCP Context instance.

This dependency provides access to the active FastMCP Context for the current MCP operation (tool/resource/prompt call).

Returns:

• A dependency that resolves to the active Context instance

Raises:

• RuntimeError: If no active context found (during resolution)

OptionalCurrentContext ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/server/dependencies.py#L970" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

OptionalCurrentContext() -> Context | None

Get the current FastMCP Context, or None when no context is active.

CurrentFastMCP ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/server/dependencies.py#L990" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

CurrentFastMCP() -> FastMCP

Get the current FastMCP server instance.

This dependency provides access to the active FastMCP server.

Returns:

• A dependency that resolves to the active FastMCP server

Raises:

• RuntimeError: If no server in context (during resolution)

CurrentRequest ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/server/dependencies.py#L1030" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

CurrentRequest() -> Request

Get the current HTTP request.

This dependency provides access to the Starlette Request object for the current HTTP request. Only available when running over HTTP transports (SSE or Streamable HTTP).

Returns:

• A dependency that resolves to the active Starlette Request

Raises:

• RuntimeError: If no HTTP request in context (e.g., STDIO transport)

CurrentHeaders ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/server/dependencies.py#L1071" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

CurrentHeaders() -> dict[str, str]

Get the current HTTP request headers.

This dependency provides access to the HTTP headers for the current request, including the authorization header. Returns an empty dictionary when no HTTP request is available, making it safe to use in code that might run over any transport.

Returns:

• A dependency that resolves to a dictionary of header name -> value

CurrentAccessToken ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/server/dependencies.py#L1289" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

CurrentAccessToken() -> AccessToken

Get the current access token for the authenticated user.

This dependency provides access to the AccessToken for the current authenticated request. Raises an error if no authentication is present.

Returns:

• A dependency that resolves to the active AccessToken

Raises:

• RuntimeError: If no authenticated user (use get_access_token() for optional)

TokenClaim ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/server/dependencies.py#L1346" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

TokenClaim(name: str) -> str

Get a specific claim from the access token.

This dependency extracts a single claim value from the current access token. It's useful for getting user identifiers, roles, or other token claims without needing the full token object.

Args:

• name: The name of the claim to extract (e.g., "oid", "sub", "email")

Returns:

• A dependency that resolves to the claim value as a string

Raises:

• RuntimeError: If no access token is available or claim is missing

Classes

FastMCPRequestContext ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/server/dependencies.py#L55" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

FastMCP-owned wrapper around the SDK's per-request context.

The SDK v2 runner hands each handler a fresh ServerRequestContext as an argument rather than exposing it through a ContextVar. FastMCP owns this ContextVar (fastmcp_request_ctx) and each request adapter binds a FastMCPRequestContext at the top of the handler (and the initialize middleware binds it too).

A wrapper rather than the raw context because the SDK's ServerRequestContext.meta is a bare RequestParamsMeta TypedDict that only carries progress_token — it does not carry _meta.fastmcp or the distributed-trace parent. Those live in the raw params dict under _meta, which this wrapper lifts once so downstream consumers have a stable surface.

ProgressLike ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/server/dependencies.py#L1099" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

Protocol for progress tracking interface.

Defines the common interface between InMemoryProgress (server context) and Docket's Progress (worker context).

Methods:

current ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/server/dependencies.py#L1107" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

current(self) -> int | None

Current progress value.

total ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/server/dependencies.py#L1112" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

total(self) -> int

Total/target progress value.

message ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/server/dependencies.py#L1117" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

message(self) -> str | None

Current progress message.

set_total ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/server/dependencies.py#L1121" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

set_total(self, total: int) -> None

Set the total/target value for progress tracking.

increment ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/server/dependencies.py#L1125" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

increment(self, amount: int = 1) -> None

Atomically increment the current progress value.

set_message ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/server/dependencies.py#L1129" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

set_message(self, message: str | None) -> None

Update the progress status message.

InMemoryProgress ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/server/dependencies.py#L1134" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

In-memory progress tracker for immediate tool execution.

Provides the same interface as Docket's Progress but stores state in memory instead of Redis. Useful for testing and immediate execution where progress doesn't need to be observable across processes.

Methods:

current ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/server/dependencies.py#L1159" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

current(self) -> int | None

total ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/server/dependencies.py#L1163" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

total(self) -> int

message ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/server/dependencies.py#L1167" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

message(self) -> str | None

set_total ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/server/dependencies.py#L1170" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

set_total(self, total: int) -> None

Set the total/target value for progress tracking.

increment ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/server/dependencies.py#L1176" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

increment(self, amount: int = 1) -> None

Atomically increment the current progress value.

set_message ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/server/dependencies.py#L1185" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

set_message(self, message: str | None) -> None

Update the progress status message.

Progress ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/server/dependencies.py#L1190" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

Progress dependency that works in both server and worker contexts.

In a Docket worker, delegates to the execution's Redis-backed progress (observable across processes). Otherwise, uses in-memory tracking.

The shared default instance acts as a stateless factory — __aenter__ creates a fresh Progress per invocation so concurrent tasks never share mutable state.

Methods:

current ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/server/dependencies.py#L1231" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

current(self) -> int | None

Current progress value.

total ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/server/dependencies.py#L1237" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

total(self) -> int

Total/target progress value.

message ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/server/dependencies.py#L1243" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

message(self) -> str | None

Current progress message.

set_total ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/server/dependencies.py#L1248" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

set_total(self, total: int) -> None

Set the total/target value for progress tracking.

increment ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/server/dependencies.py#L1253" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

increment(self, amount: int = 1) -> None

Atomically increment the current progress value.

set_message ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/server/dependencies.py#L1258" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

set_message(self, message: str | None) -> None

Update the progress status message.