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)

** 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:

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.
Create an McpToolset with StreamableHTTPConnectionParams, fetch tools, and make one successful run_async call.
Terminate the session server-side (wait past the idle eviction, or restart the server).
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.

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

My proposed scope is:

Add an isolated regression test that reproduces a pooled streamable-HTTP session remaining locally open after the server terminates it.
Trace the McpError / JSON-RPC error path through MCPSessionManager and McpTool to identify the narrowest invalidation boundary.
Invalidate only the terminated pooled session and let the existing retry path acquire a fresh session, without reconnecting for ordinary tool errors.
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?

@anshulcha

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")

This issue has been automatically marked as stale because it has not had recent activity for 7 days after a maintainer requested clarification. It will be closed if no further activity occurs within 7 days.

@guiyangyuan

@guiyangyuan Apologies for overlapping.
I saw your claim after finishing a tested fix and opened a PR. Your review there would be very welcome!

@anshulcha

Hello @anshulcha,

Could you please confirm if the shared patch worked or not? Also it would be great if you could share your feedback on linked PR.

This issue has been automatically marked as stale because it has not had recent activity for 7 days after a maintainer requested clarification. It will be closed if no further activity occurs within 7 days.

It's still valid, I created a PR to solve this.

@gioboa

Hello @gioboa,

Thank you for your contribution, it seems there are several conflicts. Could you please take a look at them?

I fixed the conflicts 🤞

@gioboa

Hello @gioboa,

Thank you for your prompt response. We will review this PR and reach out if any additional details are required. In the meantime we request your patience.

@gioboa

Hey @gioboa thanks for contributing to this! An internal team will be taking over and your work will be credited.

@gioboa

Hey @gioboa thanks for contributing to this! An internal team will be taking over and your work will be credited.

Thanks 🙏 ☺️

Navigation Menu

Repository navigation

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) #6822

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

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) #6822

Description

Activity

guiyangyuan commented on Aug 20, 2026

llalitkumarrr commented on Aug 21, 2026

adk-bot commented on Aug 28, 2026

gioboa commented on Aug 28, 2026

llalitkumarrr commented on Sep 10, 2026

adk-bot commented on Sep 17, 2026

gioboa commented on Sep 17, 2026

llalitkumarrr commented on Sep 28, 2026

gioboa commented on Sep 28, 2026

llalitkumarrr commented on Sep 28, 2026

willie3838 commented on Oct 29, 2026

gioboa commented on Oct 29, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions

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) #6822