MCPSessionManager pools a server-terminated streamable-HTTP session forever: `_is_session_disconnected` only checks local stream flags (scope of closed #3321, still broken in v2.7.1)

[anshulcha]

** Please make sure you read the contribution guide and file the issues in the right place. **

Describe the bug

When a streamable-HTTP MCP server terminates a session server-side (session eviction, server restart, or any condition that makes the server answer HTTP 404 "Session not found" for the stored mcp-session-id), MCPSessionManager never detects it. _is_session_disconnected() checks only the local stream flags:

return session._read_stream._closed or session._write_stream._closed

A server-side termination arrives as a JSONRPCError ("Session terminated") delivered into the request's read stream — the local streams stay open and the background task stays alive, so the pooled session still looks healthy. retry_on_errors then retries the call through the same dead session, which fails identically. From that point every tool call on the toolset fails forever; the session is never re-created.

With _MCP_GRACEFUL_ERROR_HANDLING (experimental, default on), the effect is worse in practice: McpTool.run_async converts the raised McpError into a returned dict {"error": "MCP tool execution failed: Session terminated"}. Callers get no exception, so application code cannot distinguish a permanent transport failure from an ordinary tool result, and nothing upstream can trigger a reconnect. In our production system this combination caused a silent multi-day outage: every call "succeeded" with an error dict and no signal fired.

Issue #3321 described this exact scenario (server restart) and named _is_session_disconnected; it was closed in Nov 2025, but the promised handling of McpError/"Session terminated" never landed — the method is byte-identical in v2.7.1. Related: the MCP Python SDK does not re-initialize on the 404 either (modelcontextprotocol/python-sdk#1676, PR #1818 pending), so an ADK-side fix is needed regardless.

To Reproduce

Steps to reproduce the behavior:

1. Run any MCP server over streamable HTTP with stateful sessions. Two easy ways to kill the session server-side: (a) use a server that evicts idle sessions (e.g. Apollo MCP Server v1.17 evicts after ~5 idle minutes), or (b) simply restart the server container between calls.
2. Create an McpToolset with StreamableHTTPConnectionParams, fetch tools, and make one successful run_async call.
3. Terminate the session server-side (wait past the idle eviction, or restart the server).
4. Call run_async again — and any number of times after.

import asyncio
from google.adk.tools.mcp_tool.mcp_toolset import McpToolset, StreamableHTTPConnectionParams

async def main():
    ts = McpToolset(connection_params=StreamableHTTPConnectionParams(
        url="http://localhost:5000/mcp"))
    tools = await ts.get_tools()
    tool = tools[0]

    print(await tool.run_async(args={}, tool_context=None))   # works

    input("Now restart the MCP server (or wait past its idle-session eviction), then press Enter...")

    print(await tool.run_async(args={}, tool_context=None))   # {'error': 'MCP tool execution failed: Session terminated'}
    print(await tool.run_async(args={}, tool_context=None))   # same, forever — never recovers

asyncio.run(main())

Expected behavior

The session pool detects the server-side termination (the McpError/404 on a pooled session) and re-creates the session, so the retry_on_errors retry runs against a fresh session and succeeds. At minimum, the error-dict result produced by graceful error handling should be distinguishable as a transport-level failure so callers can force a reconnect themselves.

Observed behavior

The dead session is returned from the pool indefinitely; every retry goes through it; every call returns {"error": "MCP tool execution failed: Session terminated"} (or raises McpError with ADK_DISABLE_MCP_GRACEFUL_ERROR_HANDLING=1). The only recovery is tearing down and re-creating the whole McpToolset from application code.

Environment

• ADK version: reproduced on 2.2.0; code unchanged on v2.7.1 and current main (mcp_session_manager.py)
• mcp (python-sdk): 1.29.0
• Python: 3.12
• OS: Linux (Cloud Run) and macOS, identical behavior
• Transport: streamable HTTP, stateful server sessions

Additional context

• McpToolset does not handle MCP server restart #3321 (closed): same failure mode via server restart; the fix discussed there (invalidate on McpError: Session terminated) does not appear in the codebase.
• McpToolset connection failure (HTTP 401/403/5xx) causes ASGI crash instead of graceful error #4300: the origin of graceful error handling — the swallow is intentional there; this report is about the session pool never recovering, with the swallow as the reason the failure is also invisible to callers.
• MCP client doesn't not initialize new session when getting 404 session not found modelcontextprotocol/python-sdk#1676 / PR Using Gemma 3n e4B or e2B in google ADK #1818: client-side re-init on 404 is also missing at the SDK layer.

[guiyangyuan]

Hi maintainers — I'd like to work on this if the direction is welcome.

My proposed scope is:

1. Add an isolated regression test that reproduces a pooled streamable-HTTP session remaining locally open after the server terminates it.
2. Trace the McpError / JSON-RPC error path through MCPSessionManager and McpTool to identify the narrowest invalidation boundary.
3. Invalidate only the terminated pooled session and let the existing retry path acquire a fresh session, without reconnecting for ordinary tool errors.
4. Cover both successful recovery and the graceful-error-handling path, and document the exact pytest commands and results in the PR.

I'll keep the change focused on ADK session-pool recovery rather than broad MCP SDK behavior. Could you confirm that this is the preferred direction before I open a PR?

[llalitkumarrr]

Hello @anshulcha,

Could you please try this patch to mcp_tool.py (lines 467–504) in google-adk==2.7.1? Please let us know if it resolves the issue and share your feedback:

    try:
      if is_feature_enabled(FeatureName._MCP_GRACEFUL_ERROR_HANDLING):  # pylint: disable=protected-access
        # Race the tool call against the background session task so that
        # transport crashes (e.g. non-2xx HTTP responses from an AGW with
        # Model Armor) surface immediately instead of hanging until
        # sse_read_timeout (default 5 minutes) expires. ConnectionError is
        # intentionally NOT caught here; it propagates to retry_on_errors,
        # which will create a fresh session and retry once before finally
        # surfacing the failure to the agent (where the run_async wrapper
        # converts it into an `{"error": ...}` dict).
        #
        # The isinstance check is intentional: tests and external subclasses
        # may inject mock session managers whose `_get_session_context`
        # returns a Mock instead of a real SessionContext (or None). Falling
        # back to the direct await keeps those callers working.
        session_context = self._mcp_session_manager._get_session_context(  # pylint: disable=protected-access
            headers=final_headers
        )
        if isinstance(session_context, SessionContext):
          response = await session_context._run_guarded(call_coro)  # pylint: disable=protected-access
        else:
          response = await call_coro
      else:
        # Pre-fix behavior: await the call directly. This is what causes the
        # ~300s hang when the underlying transport crashes.
        response = await call_coro
    except Exception as e:
      # If an error occurs (e.g., McpError "Session terminated"), invalidate
      # this specific session so that the @retry_on_errors decorator gets
      # a fresh session on its retry attempt, instead of reusing the dead one.
      session_key = self._mcp_session_manager._session_key_for(final_headers)  # pylint: disable=protected-access
      async with self._mcp_session_manager._session_lock:  # pylint: disable=protected-access
        if session_key in self._mcp_session_manager._sessions:  # pylint: disable=protected-access
          _, exit_stack, stored_loop = self._mcp_session_manager._sessions[session_key]  # pylint: disable=protected-access
          await self._mcp_session_manager._cleanup_session(session_key, exit_stack, stored_loop)  # pylint: disable=protected-access
      raise

    result = response.model_dump(exclude_none=True, mode="json")