Client._disconnect() needs timeout — hangs indefinitely on stale HTTP connections

[godwinbw-egm]

Problem

When using FastMCPToolset with StreamableHttpTransport for long-lived processes (eval suites, test runners), Client._disconnect() can hang indefinitely when the remote MCP server has dropped the HTTP keep-alive connection.

Root Cause

_disconnect() awaits self._session_state.session_task which calls _session_runner. The runner's AsyncExitStack.__aexit__ triggers a POST to the server for session termination. When the server connection is stale (idle timeout after 60-90s), this POST hangs until httpx.ReadTimeout fires — but there's no bounded deadline on the await session_task itself.

Exception Chain

RuntimeError: Client is not connected
  caused by ExceptionGroup: unhandled errors in a TaskGroup (1 sub-exception)
    CancelledError: Cancelled via cancel scope
      WouldBlock

Impact

In our eval suite (15 scenarios, sequential), after a long-running scenario (80-140s), the next call to client._disconnect() hangs. This poisons all subsequent scenarios because:

1. _disconnect() hangs waiting for session_task
2. New client instances share the httpx connection pool with the orphaned client
3. list_tools() / call_tool() fail with "Client is not connected"

Workaround

We wrapped the __aexit__ call in asyncio.wait_for(..., timeout=3.0) and force-null the client on timeout, then gc.collect().

Suggested Fix

Add a timeout parameter to Client._disconnect():

async def _disconnect(self, timeout: float = 10.0) -> None:
    if self._session_state.session_task is not None:
        try:
            await asyncio.wait_for(self._session_state.session_task, timeout=timeout)
        except (TimeoutError, asyncio.TimeoutError):
            self._session_state.session_task.cancel()
            # ... cleanup

Environment

• fastmcp version: latest (via pip)
• Python: 3.13.5
• pydantic-ai: 1.60.0
• Transport: StreamableHttpTransport
• Server: Remote HTTP MCP servers (Fly.io hosted)

[marvin-context-protocol]

Thanks for the report. This issue goes beyond what our contributor guidelines ask for — we just need a short problem description and an MRE. Please see our contributing guidelines and condense this issue. We'll triage it once it's trimmed down.

[reory]

@godwinbw-egm
Hi, this is a great catch. Since the bot flagged this for length. I am happy to help distill this down into a concise MRE and a PR. let me know please.

[jlowin]

Thanks for the report. #4011 should resolve this — the underlying bug is that when _disconnect()'s bounded wait expires, the background session task was being orphaned instead of cancelled, leaving the transport's httpx connection held in the event loop. The fix explicitly cancels the task and shield-awaits its cleanup, so the transport is actually released before we drop the reference.

That said, some of the symptoms you described don't quite line up with current main — the "indefinite hang" (there's already a 5s client_disconnect_timeout in place that bounds the wait) and the "shared httpx connection pool across clients" (each Client instantiates its own transport). If you can still reproduce the eval-suite poisoning after this ships, please open a fresh issue with an MRE so we can chase whatever's left. Closing on merge.

🤖 Generated with Claude Code

---

Generated by Claude Code