π The fast, Pythonic way to build MCP servers and clients.
fix: snapshot access token for background tasks (#3095) (#3138)
Guillaume FORTAINE263e0bf6e026
diff --git a/src/fastmcp/server/context.py b/src/fastmcp/server/context.pyindex d65e87c43..9889aaee9 100644--- a/src/fastmcp/server/context.py+++ b/src/fastmcp/server/context.py@@ -318,6 +318,10 @@ class Context:Returns an empty dict if no lifespan was configured or if the MCPsession is not yet established.+ In background tasks (Docket workers), where request_context is not+ available, falls back to reading from the FastMCP server's lifespan+ result directly.+Example:```python@server.tool@@ -330,6 +334,11 @@ class Context:"""rc = self.request_contextif rc is None:+ # In background tasks, request_context is not available.+ # Fall back to the server's lifespan result directly (#3095).+ result = self.fastmcp._lifespan_result+ if result is not None:+ return resultreturn {}return rc.lifespan_contextdiff --git a/src/fastmcp/server/dependencies.py b/src/fastmcp/server/dependencies.pyindex 97cf4fbef..acd7fea19 100644--- a/src/fastmcp/server/dependencies.py+++ b/src/fastmcp/server/dependencies.py@@ -9,11 +9,13 @@ from __future__ import annotationsimport contextlibimport inspect+import loggingimport weakreffrom collections.abc import AsyncGenerator, Callablefrom contextlib import AsyncExitStack, asynccontextmanager-from contextvars import ContextVar+from contextvars import ContextVar, Tokenfrom dataclasses import dataclass+from datetime import datetime, timezonefrom functools import lru_cachefrom typing import TYPE_CHECKING, Any, Protocol, cast, get_type_hints, runtime_checkable@@ -33,6 +35,8 @@ from fastmcp.server.http import _current_http_requestfrom fastmcp.utilities.async_utils import call_sync_fn_in_threadpoolfrom fastmcp.utilities.types import find_kwarg_by_type, is_class_member_of_type+_logger = logging.getLogger(__name__)+if TYPE_CHECKING:from docket import Docketfrom docket.worker import Worker@@ -166,6 +170,9 @@ _current_server: ContextVar[weakref.ref[FastMCP] | None] = ContextVar()_current_docket: ContextVar[Docket | None] = ContextVar("docket", default=None)_current_worker: ContextVar[Worker | None] = ContextVar("worker", default=None)+_task_access_token: ContextVar[AccessToken | None] = ContextVar(+ "task_access_token", default=None+)# --- Docket availability check ---@@ -479,7 +486,8 @@ def get_access_token() -> AccessToken | None: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_varmay become stale after token refresh. Falls back to the SDK's context var if no- request is available.+ request is available. In background tasks (Docket workers), falls back to the+ token snapshot stored in Redis at task submission time.Returns:The access token if an authenticated user is available, None otherwise.@@ -502,6 +510,19 @@ def get_access_token() -> AccessToken | None:if access_token is None:access_token = _sdk_get_access_token()+ # Fall back to background task snapshot (#3095)+ # In Docket workers, neither HTTP request nor SDK context var are available.+ # The token was snapshotted in Redis at submit_to_docket() time and restored+ # into this ContextVar by _CurrentContext.__aenter__().+ if access_token is None:+ task_token = _task_access_token.get()+ if task_token is not None:+ # Check expiration: if expires_at is set and past, treat as expired+ if task_token.expires_at is not None:+ if task_token.expires_at < int(datetime.now(timezone.utc).timestamp()):+ return None+ return task_token+if access_token is None or isinstance(access_token, AccessToken):return access_token@@ -719,14 +740,49 @@ async def resolve_dependencies(# so that get_dependency_parameters can detect them.+async def _restore_task_access_token(+ session_id: str, task_id: str+) -> Token[AccessToken | None] | None:+ """Restore the access token snapshot from Redis into a ContextVar.++ Called when setting up context in a Docket worker. The token was stored at+ submit_to_docket() time. The token is restored regardless of expiration;+ get_access_token() checks expiry when reading from the ContextVar.++ Returns:+ The ContextVar token for resetting, or None if nothing was restored.+ """+ docket = _current_docket.get()+ if docket is None:+ return None++ token_key = docket.key(f"fastmcp:task:{session_id}:{task_id}:access_token")+ try:+ async with docket.redis() as redis:+ token_data = await redis.get(token_key)+ if token_data is not None:+ restored = AccessToken.model_validate_json(token_data)+ return _task_access_token.set(restored)+ except Exception:+ _logger.warning(+ "Failed to restore access token for task %s:%s",+ session_id,+ task_id,+ exc_info=True,+ )+ return None++class _CurrentContext(Dependency): # type: ignore[misc]"""Async context manager for Context dependency.In foreground (request) mode: returns the active context from _current_context.- In background (Docket worker) mode: creates a task-aware Context with task_id.+ In background (Docket worker) mode: creates a task-aware Context with task_id+ and restores the access token snapshot from Redis."""_context: Context | None = None+ _access_token_cv_token: Token[AccessToken | None] | None = Noneasync def __aenter__(self) -> Context:from fastmcp.server.context import Context, _current_context@@ -751,6 +807,12 @@ class _CurrentContext(Dependency): # type: ignore[misc])# Enter the context to set up ContextVarsawait self._context.__aenter__()++ # Restore access token snapshot from Redis (#3095)+ self._access_token_cv_token = await _restore_task_access_token(+ task_info.session_id, task_info.task_id+ )+return self._context# Neither foreground nor background context available@@ -762,6 +824,10 @@ class _CurrentContext(Dependency): # type: ignore[misc])async def __aexit__(self, *args: object) -> None:+ # Clean up access token ContextVar+ if self._access_token_cv_token is not None:+ _task_access_token.reset(self._access_token_cv_token)+ self._access_token_cv_token = None# Clean up if we created a context for background taskif self._context is not None:await self._context.__aexit__(*args)@@ -1130,8 +1196,22 @@ class Progress(Dependency): # type: ignore[misc]class _CurrentAccessToken(Dependency): # type: ignore[misc]"""Async context manager for AccessToken dependency."""+ _access_token_cv_token: Token[AccessToken | None] | None = None+async def __aenter__(self) -> AccessToken:token = get_access_token()++ # If no token found and we're in a Docket worker, try restoring from+ # Redis. This handles the case where ctx: Context is not in the+ # function signature, so _CurrentContext never ran the restoration.+ if token is None:+ task_info = get_task_context()+ if task_info is not None:+ self._access_token_cv_token = await _restore_task_access_token(+ task_info.session_id, task_info.task_id+ )+ token = get_access_token()+if token is None:raise RuntimeError("No access token found. Ensure authentication is configured "@@ -1140,7 +1220,9 @@ class _CurrentAccessToken(Dependency): # type: ignore[misc]return tokenasync def __aexit__(self, *args: object) -> None:- pass+ if self._access_token_cv_token is not None:+ _task_access_token.reset(self._access_token_cv_token)+ self._access_token_cv_token = Nonedef CurrentAccessToken() -> AccessToken:diff --git a/src/fastmcp/server/tasks/handlers.py b/src/fastmcp/server/tasks/handlers.pyindex fa8ba3ce4..be7bddd61 100644--- a/src/fastmcp/server/tasks/handlers.py+++ b/src/fastmcp/server/tasks/handlers.py@@ -14,7 +14,7 @@ import mcp.typesfrom mcp.shared.exceptions import McpErrorfrom mcp.types import INTERNAL_ERROR, ErrorData-from fastmcp.server.dependencies import _current_docket, get_context+from fastmcp.server.dependencies import _current_docket, get_access_token, get_contextfrom fastmcp.server.tasks.config import TaskMetafrom fastmcp.server.tasks.keys import build_task_keyfrom fastmcp.utilities.logging import get_logger@@ -99,10 +99,21 @@ async def submit_to_docket(f"fastmcp:task:{session_id}:{server_task_id}:poll_interval")poll_interval_ms = int(component.task_config.poll_interval.total_seconds() * 1000)++ # Snapshot the current access token (if any) for background task access (#3095)+ access_token = get_access_token()+ access_token_key = docket.key(+ f"fastmcp:task:{session_id}:{server_task_id}:access_token"+ )+async with docket.redis() as redis:await redis.set(task_meta_key, task_key, ex=ttl_seconds)await redis.set(created_at_key, created_at.isoformat(), ex=ttl_seconds)await redis.set(poll_interval_key, str(poll_interval_ms), ex=ttl_seconds)+ if access_token is not None:+ await redis.set(+ access_token_key, access_token.model_dump_json(), ex=ttl_seconds+ )# Register session for Context access in background workers (SEP-1686)# This enables elicitation/sampling from background tasks via weakrefdiff --git a/tests/server/tasks/test_context_background_task.py b/tests/server/tasks/test_context_background_task.pyindex 2b5a1efa9..c7eb9e90c 100644--- a/tests/server/tasks/test_context_background_task.py+++ b/tests/server/tasks/test_context_background_task.py@@ -14,7 +14,9 @@ from mcp import ServerSessionfrom fastmcp import FastMCPfrom fastmcp.client import Clientfrom fastmcp.client.elicitation import ElicitResult+from fastmcp.server.auth import AccessTokenfrom fastmcp.server.context import Context+from fastmcp.server.dependencies import get_access_tokenfrom fastmcp.server.elicitation import AcceptedElicitation, DeclinedElicitationfrom fastmcp.server.tasks.elicitation import handle_task_input@@ -317,3 +319,124 @@ class TestBackgroundTaskIntegration:fastmcp=mcp,)assert success is False+++class TestAccessTokenInBackgroundTasks:+ """Tests for access token availability in background tasks (#3095).++ Integration tests use Client(mcp) with the real memory:// Docket backend.+ The token snapshot/restore round-trip flows through actual Redis (fakeredis).++ Note: async tests run in isolated asyncio tasks, so ContextVar changes+ are automatically scoped β no cleanup required.+ """++ async def test_token_round_trips_through_background_task(self):+ """E2E: token set at submit time is available inside the worker."""+ from mcp.server.auth.middleware.auth_context import auth_context_var+ from mcp.server.auth.middleware.bearer_auth import AuthenticatedUser++ mcp = FastMCP("token-roundtrip")++ @mcp.tool(task=True)+ async def check_token(ctx: Context) -> str:+ token = get_access_token()+ if token is None:+ return "no-token"+ return f"{token.token}|{token.client_id}"++ test_token = AccessToken(+ token="roundtrip-jwt",+ client_id="test-client",+ scopes=["read"],+ claims={"sub": "user-1"},+ )+ auth_context_var.set(AuthenticatedUser(test_token))++ async with Client(mcp) as client:+ task = await client.call_tool("check_token", {}, task=True)+ result = await task.result()+ assert result.data == "roundtrip-jwt|test-client"++ async def test_no_token_when_unauthenticated(self):+ """E2E: background task gets no token when nothing was set."""+ mcp = FastMCP("no-auth")++ @mcp.tool(task=True)+ async def check_token(ctx: Context) -> str:+ token = get_access_token()+ return "no-token" if token is None else token.token++ async with Client(mcp) as client:+ task = await client.call_tool("check_token", {}, task=True)+ result = await task.result()+ assert result.data == "no-token"++ async def test_expired_token_returns_none(self):+ """get_access_token() returns None when task token has expired."""+ from datetime import datetime, timezone++ from fastmcp.server.dependencies import _task_access_token++ expired = AccessToken(+ token="expired-jwt",+ client_id="test-client",+ scopes=["read"],+ expires_at=int(datetime.now(timezone.utc).timestamp()) - 3600,+ )+ _task_access_token.set(expired)+ assert get_access_token() is None++ async def test_valid_token_with_future_expiry(self):+ """get_access_token() returns token when expiry is in the future."""+ from datetime import datetime, timezone++ from fastmcp.server.dependencies import _task_access_token++ valid = AccessToken(+ token="valid-jwt",+ client_id="test-client",+ scopes=["read"],+ expires_at=int(datetime.now(timezone.utc).timestamp()) + 3600,+ )+ _task_access_token.set(valid)+ result = get_access_token()+ assert result is not None+ assert result.token == "valid-jwt"++ async def test_token_without_expiry_always_valid(self):+ """get_access_token() returns token when no expires_at is set."""+ from fastmcp.server.dependencies import _task_access_token++ no_expiry = AccessToken(+ token="eternal-jwt",+ client_id="test-client",+ scopes=["read"],+ )+ _task_access_token.set(no_expiry)+ result = get_access_token()+ assert result is not None+ assert result.token == "eternal-jwt"+++class TestLifespanContextInBackgroundTasks:+ """Tests for lifespan_context availability in background tasks (#3095)."""++ def test_lifespan_context_falls_back_to_server_result(self):+ """lifespan_context reads from server when request_context is None."""+ mcp = FastMCP("test")+ mcp._lifespan_result = {"db": "mock-db-connection", "cache": "mock-cache"}++ ctx = Context(mcp, task_id="test-task")+ assert ctx.request_context is None+ assert ctx.lifespan_context == {+ "db": "mock-db-connection",+ "cache": "mock-cache",+ }++ def test_lifespan_context_returns_empty_dict_when_no_lifespan(self):+ """lifespan_context returns {} when no lifespan is configured."""+ mcp = FastMCP("test")+ ctx = Context(mcp, task_id="test-task")+ assert ctx.request_context is None+ assert ctx.lifespan_context == {}