[BUG] MCPClient timeout causes connection corruption when tool response arrives later

[AnirudhKonduru]

Checks

• I have updated to the lastest minor and patch version of Strands
• I have checked the documentation and this is not expected behavior
• I have searched ./issues and there are no duplicates of my issue

Strands Version

1.17.1

Python Version

3.12.5

Operating System

Macos Tahoe 26.1

Installation Method

pip (uv)

Steps to Reproduce

script to reproduce (uv run <script.py>)

#!/usr/bin/env -S uv run --script
# /// script
# dependencies = ["fastmcp", "strands-agents"]
# ///

import asyncio
from datetime import timedelta
from strands.tools.mcp import MCPClient
from mcp.client.stdio import stdio_client, StdioServerParameters

SERVER_CODE = '''#!/usr/bin/env -S uv run --script
# /// script
# dependencies = ["fastmcp"]
# ///
import asyncio
from fastmcp import FastMCP

mcp = FastMCP("test-server")

@mcp.tool()
async def slow_tool() -> str:
    """A tool that takes 3 seconds"""
    await asyncio.sleep(3)
    return "completed"

if __name__ == "__main__":
    mcp.run()
'''

async def main():
    with open("/tmp/test_server.py", "w") as f:
        f.write(SERVER_CODE)

    client = MCPClient(
        lambda: stdio_client(StdioServerParameters(
            command="uv",
            args=["run", "--script", "/tmp/test_server.py"]
        ))
    )

    with client:
        for i in range(5):
            print(f"\n{'='*20} Attempt {i+1} {'='*20}")
            try:
                result = await client.call_tool_async(
                    tool_use_id=f"test_{i}",
                    name="slow_tool",
                    arguments={},
                    read_timeout_seconds=timedelta(seconds=1)
                )
                print(f"Success: {result}")
            except Exception as e:
                print(f"Error: {type(e).__name__}: {e}")

if __name__ == "__main__":
    asyncio.run(main())

Sample output: output.txt

Expected Behavior

All tool calls should either complete successfully or timeout.

Actual Behavior

First few tools calls timeout, and the ones that arrive later receive a anyio.ClosedResourceError.

Additional Context

In the output I see that it appears to receive the response for the timed out tool call right before it seems to close the connection:

ERROR:root:Unhandled exception in receive loop: Received response with an unknown request ID: SessionMessage(message=JSONRPCMessage(root=JSONRPCResponse(jsonrpc='2.0', id=1, result={'content': [{'type': 'text', 'text': 'completed'}], 'structuredContent': {'result': 'completed'}, 'isError': False})), metadata=None)
Traceback (most recent call last):
  File "/Users/akondu/Library/Caches/uv/environments-v2/test-timeout-bug-96e18d7890cb4991/lib/python3.12/site-packages/mcp/shared/session.py", line 420, in _receive_loop
    await self._handle_incoming(
  File "/Users/akondu/Library/Caches/uv/environments-v2/test-timeout-bug-96e18d7890cb4991/lib/python3.12/site-packages/mcp/client/session.py", line 546, in _handle_incoming
    await self._message_handler(req)
  File "/Users/akondu/Library/Caches/uv/environments-v2/test-timeout-bug-96e18d7890cb4991/lib/python3.12/site-packages/strands/tools/mcp/mcp_client.py", line 565, in _handle_error_message
    raise message
RuntimeError: Received response with an unknown request ID: SessionMessage(message=JSONRPCMessage(root=JSONRPCResponse(jsonrpc='2.0', id=1, result={'content': [{'type': 'text', 'text': 'completed'}], 'structuredContent': {'result': 'completed'}, 'isError': False})), metadata=None)
ERROR:strands.tools.mcp.mcp_client:tool execution failed

[dbschmigelski]

Hi,

I believe what is happening is the following

• Tool calls timeout after Ns - this is expected
• MCP server responds late - the actual response arrives after the timeout
• "Unknown request ID" error - the late response has an ID that the client no longer recognizes
• Connection collapse - this error triggers the connection to close

We added the following to propagate these errors like these in #922. This prevented server side timeouts from hanging the client.

sdk-python/src/strands/tools/mcp/mcp_client.py

Lines 561 to 566 in 93997f0

	# Raise an exception if the underlying client raises an exception in a message
	# This happens when the underlying client has an http timeout error
	async def _handle_error_message(self, message: Exception | Any) -> None:
	if isinstance(message, Exception):
	raise message
	await anyio.lowlevel.checkpoint()

After testing with the following I believe we can special case this

    async def _handle_error_message(self, message: Exception | Any) -> None:
        if isinstance(message, Exception):
            if "unknown request id" in str(message).lower():
                logger.debug("Non-fatal MCP session error: %s", message)
                return
            raise message
        await anyio.lowlevel.checkpoint()

We likely will want a better way both a) not relying on strings and b) supporting a broader set of client side exceptions. But, I believe we can solve this in the immediate term.

[AnirudhKonduru]

The patch seems to fix it for now, thanks for looking into this quickly!

[dbschmigelski]

It looks like there may be more we can contribute directly to the underlying MCP client. There are various "terminal" exceptions which close the connections as called out here modelcontextprotocol/python-sdk#1144