Fix ContextVar propagation for ASGI-mounted servers with tasks

[chrisguidry]

Summary

Fixes background tasks failing with "Background tasks require a running FastMCP server context" when FastMCP is mounted to another ASGI application (FastAPI, Starlette, etc.) or deployed to serverless environments (Lambda, Cloud Run).

Root cause: ContextVars set during lifespan don't propagate to request handlers in ASGI environments because they run in sibling async contexts, not parent-child.

Fix: Context.__aenter__ now sets _current_docket and _current_worker from server instance attributes at request time, ensuring they're available regardless of async context hierarchy.

Changes

• context.py: Set docket/worker ContextVars from server._docket/server._worker in __aenter__
• server.py: Store _worker on server instance (was already storing _docket)
• pyproject.toml: Bump pydocket to >=0.16.6 (includes Redis ACL and py-key-value fixes)

Closes #2671

🤖 Generated with Claude Code

[coderabbitai]

Walkthrough

The changes extend the per-request context manager to capture and propagate docket and worker context via ContextVars, enabling dependency injection for these resources across async context boundaries. A new internal worker reference is added to the FastMCP server instance and populated during the docket lifecycle. A guard is also introduced to the lifespan manager to prevent re-entrance. Error messages are updated to reference the broader server context requirement, and logging in subscription handlers is adjusted from warning to error level.

Possibly related PRs

• Make pydocket optional and unify DI systems #2835: Modifies the same context/lifespan code paths by adding/using _current_docket and _current_worker ContextVars and adjusting server/docket lifespan to set/reset those tokens, making it directly related at the code level.
• Remove enable_docket setting; Docket is now always on #2558: Modifies the server lifecycle and ContextVar-based docket/worker context management, sharing the same server/context lifecycle and worker/docket management code paths.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately summarizes the main change: fixing ContextVar propagation for ASGI-mounted servers with tasks, which is the core issue addressed in the PR.
Description check	✅ Passed	The PR description covers the root cause, the fix, and references the relevant issue #2671. However, the checklist items are incomplete and unchecked despite the PR being ready for review.
Linked Issues check	✅ Passed	The PR successfully addresses issue #2671 by implementing the ContextVar fix to enable tasks in ASGI-mounted scenarios. The context.py and server.py changes set _current_docket and _current_worker at request time from server instance attributes, ensuring availability regardless of async context hierarchy.
Out of Scope Changes check	✅ Passed	All changes are directly related to fixing the ContextVar propagation issue. The modifications to context.py, server.py, and the pydocket version bump in pyproject.toml are all necessary and scoped to the stated objective.
Docstring Coverage	✅ Passed	Docstring coverage is 81.82% which is sufficient. The required threshold is 80.00%.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

• 📝 Generate docstrings

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 0

🧹 Nitpick comments (1)

src/fastmcp/server/tasks/subscriptions.py (1)

72-73: Consider using logger.exception() to preserve stack traces.

Switching from warning to error is appropriate for subscription failures. However, removing the traceback (previously exc_info=True) loses valuable debugging information. Using logger.exception() logs at ERROR level while automatically including the traceback.

♻️ Suggested fix

     except Exception as e:
-        logger.error(f"subscribe_to_task_updates failed for {task_id}: {e}")
+        logger.exception(f"subscribe_to_task_updates failed for {task_id}: {e}")

📜 Review details

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between df5765c and c127dd9.

⛔ Files ignored due to path filters (2)

• pyproject.toml is excluded by none and included by none
• uv.lock is excluded by !**/*.lock and included by none

📒 Files selected for processing (4)

• src/fastmcp/server/context.py
• src/fastmcp/server/server.py
• src/fastmcp/server/tasks/handlers.py
• src/fastmcp/server/tasks/subscriptions.py

🧰 Additional context used

📓 Path-based instructions (1)

src/fastmcp/**/*.py

📄 CodeRabbit inference engine (AGENTS.md)

src/fastmcp/**/*.py: Python ≥ 3.10 with full type annotations required
Prioritize readable, understandable code - clarity over cleverness. Avoid obfuscated or confusing patterns even if shorter
Follow existing patterns and maintain consistency in code implementation
Be intentional about re-exports - don't blindly re-export everything to parent namespaces. Core types defining a module's purpose should be exported. Specialized features can live in submodules. Only re-export to fastmcp.* for most fundamental types
Never use bare except - be specific with exception types

Files:

• src/fastmcp/server/tasks/subscriptions.py
• src/fastmcp/server/context.py
• src/fastmcp/server/tasks/handlers.py
• src/fastmcp/server/server.py

🧬 Code graph analysis (2)

src/fastmcp/server/tasks/handlers.py (2)

src/fastmcp/server/server.py (1)

• docket (379-384)

src/fastmcp/server/dependencies.py (1)

• message (405-406)

src/fastmcp/server/server.py (1)

src/fastmcp/cli/tasks.py (1)

• worker (61-110)

🪛 Ruff (0.14.10)

src/fastmcp/server/tasks/subscriptions.py

73-73: Use logging.exception instead of logging.error

Replace with exception

(TRY400)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (4)

• GitHub Check: Run tests: Python 3.13 on ubuntu-latest
• GitHub Check: Run tests: Python 3.10 on ubuntu-latest
• GitHub Check: Run tests: Python 3.10 on windows-latest
• GitHub Check: Run tests with lowest-direct dependencies

🔇 Additional comments (8)

src/fastmcp/server/tasks/handlers.py (3)

59-67: LGTM!

The updated comment accurately documents the new behavior where Docket is retrieved from a ContextVar set at request time by Context.__aenter__. The error message change to "running FastMCP server context" is more descriptive and aligns with the broader context propagation fix.

---

171-179: Consistent with other handlers.

The same comment and error message pattern applied here maintains consistency across handle_tool_as_task, handle_prompt_as_task, and handle_resource_as_task.

---

281-289: Consistent error messaging across all task handlers.

All three task handlers now share the same pattern for retrieving Docket from ContextVar and reporting the same user-friendly error message when the server context is unavailable.

src/fastmcp/server/server.py (3)

200-202: LGTM - Proper initialization of cross-context attributes.

Initializing _worker = None alongside _docket = None maintains symmetry and enables Context.__aenter__ to check and propagate these values at request time.

---

471-486: Worker lifecycle properly managed on server instance.

Storing the worker reference during the docket lifespan and clearing it on completion enables cross-context access via server._worker. This pairs well with the existing server._docket pattern.

---

567-571: Key fix for ASGI-mounted server context propagation.

This guard correctly short-circuits when the lifespan has already run (e.g., when http_app() is mounted into FastAPI/Starlette). The comment accurately explains that Context.__aenter__ will set the ContextVars at request time, solving the sibling async context problem.

src/fastmcp/server/context.py (2)

188-205: Core fix for ContextVar propagation - well implemented.

This is the authoritative fix for the ASGI-mounted server issue. By setting _current_docket and _current_worker from server._docket and server._worker at request entry time, ContextVars are properly available regardless of async context hierarchy (child vs. sibling contexts).

The conditional checks (if server._docket is not None) correctly handle:

• Servers with tasks enabled (docket/worker available)
• Servers without tasks (docket/worker are None)
• Mounted servers that skip their own docket lifecycle

---

208-228: Proper token cleanup in aexit.

The LIFO reset order (worker → docket → server) correctly mirrors the set order. Using hasattr() guards before reset handles cases where tokens weren't set (e.g., docket disabled). Deleting attributes after reset prevents stale references.

[marvin-context-protocol]

Test Failure Analysis

Summary: Test (line 572 in ) is timing out after 5 seconds on Windows (Python 3.10).

Root Cause: The PR changes to remove the background notification flusher ( task) that was running in a task group. This background task was responsible for periodically flushing notifications during long-running operations.

The timeout is happening because:

1. The test spawns stdio subprocesses (Python servers) that need to communicate with the client
2. The removed background flusher was handling periodic notification flushes during these long operations
3. Without it, the test may be hanging waiting for notifications or responses that aren't being properly flushed

Detailed Analysis:

In src/fastmcp/server/context.py:

• Before: __aenter__ created a task group and started _periodic_flush in the background
• After: The task group and background flusher are removed entirely
• The PR only flushes notifications on __aexit__, which may be too late for multi-server stdio scenarios

Relevant Code Changes

# REMOVED:
self._exit_stack = AsyncExitStack()
await self._exit_stack.__aenter__()
tg = await self._exit_stack.enter_async_context(anyio.create_task_group())
self._cancel_scope = anyio.CancelScope()
tg.start_soon(self._periodic_flush)

The _periodic_flush method was handling background notification flushing throughout the context lifetime, not just at exit.

Suggested Solution:

The ContextVar fix (setting _current_docket and _current_worker from server instance) is correct for the ASGI issue. However, you need to restore some form of periodic flushing for stdio transport scenarios. Options:

1. Keep the background flusher but make it conditional - only start it when not in ASGI/serverless environments
2. Manual flush points - Add explicit flush calls at key points in the stdio transport/client code
3. Different approach - Consider if notifications need to be flushed differently for stdio vs HTTP transports

Related Files:

• src/fastmcp/server/context.py (lines 162-210) - Context lifecycle changes
• tests/test_mcp_config.py (line 572) - Failing test
• Issue Background tasks fail with 'require a running FastMCP server context' when using http_app() mounted to FastAPI #2671 - The ASGI ContextVar propagation issue this PR fixes

Why Windows-Specific?

The test file has a marker at line 42:

pytestmark = pytest.mark.skipif(
    sys.platform.startswith("win32"),
    reason="Windows has process lifecycle issues with stdio subprocesses",
)

However, this marker should skip ALL tests in the file on Windows, but the test is still running. This suggests the skip marker isn't working as expected, OR this specific failure is exposing a real Windows-specific timing issue with stdio subprocesses.

[marvin-context-protocol]

Test Failure Analysis

Summary: Test test_multi_client_with_transforms (line 572 in tests/test_mcp_config.py) is timing out after 5 seconds on Windows (Python 3.10).

Root Cause: The PR changes Context.__aenter__ to remove the background notification flusher (_periodic_flush task) that was running in a task group. This background task was responsible for periodically flushing notifications during long-running operations.

The timeout is happening because:

1. The test spawns stdio subprocesses (Python servers) that need to communicate with the client
2. The removed background flusher was handling periodic notification flushes during these long operations
3. Without it, the test may be hanging waiting for notifications or responses that aren't being properly flushed

Detailed Analysis:

In src/fastmcp/server/context.py:

• Before: __aenter__ created a task group and started _periodic_flush in the background
• After: The task group and background flusher are removed entirely
• The PR only flushes notifications on __aexit__, which may be too late for multi-server stdio scenarios

Relevant Code Changes

# REMOVED:
self._exit_stack = AsyncExitStack()
await self._exit_stack.__aenter__()
tg = await self._exit_stack.enter_async_context(anyio.create_task_group())
self._cancel_scope = anyio.CancelScope()
tg.start_soon(self._periodic_flush)

The _periodic_flush method was handling background notification flushing throughout the context lifetime, not just at exit.

Suggested Solution:

The ContextVar fix (setting _current_docket and _current_worker from server instance) is correct for the ASGI issue. However, you need to restore some form of periodic flushing for stdio transport scenarios. Options:

1. Keep the background flusher but make it conditional - only start it when not in ASGI/serverless environments
2. Manual flush points - Add explicit flush calls at key points in the stdio transport/client code
3. Different approach - Consider if notifications need to be flushed differently for stdio vs HTTP transports

Related Files:

• src/fastmcp/server/context.py (lines 162-210) - Context lifecycle changes
• tests/test_mcp_config.py (line 572) - Failing test
• Issue Background tasks fail with 'require a running FastMCP server context' when using http_app() mounted to FastAPI #2671 - The ASGI ContextVar propagation issue this PR fixes

Why Windows-Specific?

The test file has a marker at line 42:

pytestmark = pytest.mark.skipif(
    sys.platform.startswith("win32"),
    reason="Windows has process lifecycle issues with stdio subprocesses",
)

However, this marker should skip ALL tests in the file on Windows, but the test is still running. This suggests the skip marker isn't working as expected, OR this specific failure is exposing a real Windows-specific timing issue with stdio subprocesses.

[marvin-context-protocol]

Update: Additional Finding

I discovered something important - the test should not be running on Windows at all!

The test file tests/test_mcp_config.py has this marker at the top (line 42):

pytestmark = pytest.mark.skipif(
    sys.platform.startswith("win32"),
    reason="Windows has process lifecycle issues with stdio subprocesses",
)

This should skip ALL tests in that file on Windows, but the tests are clearly running (they're passing up until the timeout).

This means:

1. Either the skipif condition is not working correctly
2. OR sys.platform is not returning "win32" on the Windows CI runner

Let me investigate the actual platform string on Windows GitHub Actions runners...

Actually, looking at Python docs: on Windows, sys.platform returns "win32" even on 64-bit Windows. So the condition should work.

Hypothesis: The skipif might be evaluated at collection time with the wrong environment, or there's been a change in how pytest handles module-level pytestmark in recent versions.

Immediate Fix:
Rather than debugging the marker issue, you could add a @pytest.mark.skipif(sys.platform.startswith("win32"), ...) decorator directly to the failing test test_multi_client_with_transforms as a workaround. But the root cause (background flusher removal) still needs to be addressed.