Test Failure Analysis

(This comment was updated with a new analysis for workflow run 22525457770.)

Summary: A single SSE timeout test fails on Python 3.10/ubuntu-latest due to a timing-sensitive race condition during session initialization — this is unrelated to the PR's changes (which only touch auth code).

Root Cause: TestTimeout::test_timeout_client_timeout_does_not_override_tool_call_timeout_if_lower in tests/client/test_sse.py creates a Client with timeout=0.1 (100ms). This timeout is passed as read_timeout_seconds to ClientSession and is also applied as the httpx connection timeout in SSETransport.connect_session(). On a loaded CI runner, the SSE connection + MCP initialize handshake takes longer than 100ms, so the session throws a McpError: Timed out while waiting for response to ClientRequest. Waited 0.1 seconds. during __aenter__ — before any tool call is ever made. The test is designed to verify that a per-tool-call timeout=2 overrides the client-level timeout=0.1, but it never reaches that point.

This test passes on Python 3.13/ubuntu and Python 3.10/windows in this same run, and consistently passes on main. The PR itself only modifies src/fastmcp/server/auth/, tests/server/auth/, and docs — completely unrelated to the SSE client transport.

Suggested Solution: This is a pre-existing flaky test. Two options:

1. Re-run the workflow — this is the simplest fix since the failure is intermittent and the PR is unrelated. The test should pass on a retry.

2. Fix the test's fragility in tests/client/test_sse.py (separate PR): the test should use a larger init_timeout or separate the connection phase from the timeout-under-test. For example, connect first (without a tight timeout), then apply the short timeout only to the tool call:

   # In tests/client/test_sse.py lines 188-200
   # Connect without short timeout, then verify per-call timeout takes precedence
   async with Client(transport=SSETransport(sse_server), timeout=0.1, init_timeout=5) as client:
       await client.call_tool("sleep", {"seconds": 0.03}, timeout=2)

mcp.shared.exceptions.McpError: Timed out while waiting for response to ClientRequest. Waited 0.1 seconds.

tests/client/test_sse.py:196: in test_...
  async with Client(transport=SSETransport(sse_server), timeout=0.1) as client:
src/fastmcp/client/client.py:482: in __aenter__
  return await self._connect()
src/fastmcp/client/client.py:635: in _session_runner
  await stack.enter_async_context(self._context_manager())
src/fastmcp/client/transports/sse.py:94: in connect_session
  # -> ClientSession.initialize() called here
.venv/lib/python3.10/site-packages/mcp/shared/session.py:294: McpError

Analysis by Marvin (Claude Code)

gtg

It would be nice to provide a mechanism to see which verifier out of [server] + verifiers the current AuthenticatedUser belongs to, I guess that can be worked around by comparing metadata in the tokens.

Something that's missing for my use case as well is the ability to have simultaneous authentication of the agent that is forwarding the request, as well as the end-user.

For example:

• I would like to deny tools/call by the agent.
• The end-user would be allowed to do anything FastMCP supports.

with this MultiAuth, I would have an MCP middleware, but then I would have to compare what I would expect to see in a JWT for the agent, with what I would expect to see in a JWT for an end-user, and deny tool calls based on that.

and also, I would only be able to authenticate either the agent or the end-user.

I have a hand-crafted application-code solution that solves the simultaneous auth of agent and end-user by separating the tokens into different headers, I also have an upstream WIP that attempts to do the same: https://github.com/PrefectHQ/fastmcp/compare/main...joar:fastmcp:multi-auth?expand=1

The requirement to list tools before end-user is authenticated is a common source of friction between agent frameworks (ADK, langchain) and the MCP standard, adding a separate Service-Authorization header in the agent with e.g., a Google Service Account OIDC JWT, and allowing tools/list on the MCP side given that the Service-Authorization JWT is valid is a solution to that problem.

@joar thanks for the detailed writeup! I took a look at your branch — the MultiHeaderAuthProvider approach is clever, and it's nice to see it working through the existing get_middleware() extension point without needing SDK changes.

That said, I think this is fighting against the MCP spec in a way that's hard to support at a framework level. MCP doesn't distinguish between list and execute authorization, and maintaining that split (where a client can discover tools it can't call) is something we actively try to avoid in FastMCP. Your require_user_for_execution check is a reasonable workaround, but it's inherently application-specific policy.

I think MultiAuth (multiple verifiers for a single identity) and what you're building (multiple simultaneous identities with different authorization policies) are different enough that they don't belong in the same abstraction. For now I'd suggest keeping your multi-header approach as application-level customization — the extension points are there for exactly this kind of thing.

Re: knowing which verifier authenticated the user — happy to consider that separately.