[BUG] Agent Hangs Indefinitely on Fatal MCP Server Errors (HTTP 4xx/5xx)

[LanaSokolova]

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](./issues?q=) and there are no duplicates of my issue

Strands Version

1.10.0

Python Version

3.13

Operating System

Windows

Installation Method

pip

Steps to Reproduce

1. Configure the MCP Server Response
   MCP server hosted on an AWS Lambda function behind an API Gateway, using Lambda Proxy Integration.

   Example response from API Gateway:

   Content-Type: application/json
   MCP-Version: 0.6
   MCP-Session-Id: <sessionId>
   {
    "jsonrpc": "2.0",
    "id": 2,
    "error": {
      "code": -32603,
      "message": "Error executing tool: Simulated unexpected error"
    }
   }

2. Run the Strands Agent

   from datetime import timedelta
   from mcp.client.streamable_http import streamablehttp_client
   from strands.tools.mcp.mcp_client import MCPClient
   from strands import Agent
   from strands.session.file_session_manager import FileSessionManager
   
   Assume other variables (model, session_id, system_prompt, prompt etc.) are defined
   
   streamable_http_mcp_client = MCPClient(lambda: streamablehttp_client(
       "https://your-api-gateway-endpoint/prod/",
       timeout=timedelta(seconds=30),
       headers={"Authorization": "your_jwt_token"}
   ))
   
   with streamable_http_mcp_client:
       tools = streamable_http_mcp_client.list_tools_sync()
       session_manager = FileSessionManager(session_id=session_id)
       agent = Agent(model=model, tools=tools, system_prompt=system_prompt, session_manager=session_manager)
       print("Attempting to call the agent...")
       # This line will hang
   ​    response = agent(prompt="prompt)
   ​    print("This line is never reached.")

Expected Behavior

The agent call should fail fast by raising an exception. Given that the underlying httpx library raises an httpx.HTTPStatusError when response.raise_for_status() is called on a non-2xx response, it is expected that this error (or a wrapper around it) should propagate up to the caller.

Actual Behavior

The agent(prompt=...) call hangs indefinitely. The program does not exit, raise an exception, or proceed past this line.

Debugging indicates the sequence of events is as follows:

1. The underlying httpx client receives the 500 status code from the API Gateway.
2. A call to response.raise_for_status() is made within the transport layer, which raises an httpx.HTTPStatusError.  
3. Immediately after the HTTPStatusError is raised, the agent's execution hangs.

The same behavior is for 400 status code.

Additional Context

No response

Possible Solution

No response

Related Issues

#922

[LanaSokolova]

Maybe the problem is in this method in the mcp_client

async def _async_background_thread(self) -> None:
    """Asynchronous method that runs in the background thread to manage the MCP connection.

    This method establishes the transport connection, creates and initializes the MCP session,
    signals readiness to the main thread, and waits for a close signal.
    """
    self._log_debug_with_thread("starting async background thread for MCP connection")
    try:
        async with self._transport_callable() as (read_stream, write_stream, *_):
            self._log_debug_with_thread("transport connection established")
            async with ClientSession(
                read_stream, write_stream, message_handler=self._handle_error_message
            ) as session:
                self._log_debug_with_thread("initializing MCP session")
                await session.initialize()

                self._log_debug_with_thread("session initialized successfully")
                # Store the session for use while we await the close event
                self._background_thread_session = session
                # Signal that the session has been created and is ready for use
                self._init_future.set_result(None)

                self._log_debug_with_thread("waiting for close signal")
                # Keep background thread running until signaled to close.
                # Thread is not blocked as this is an asyncio.Event not a threading.Event
                await self._close_event.wait()
                self._log_debug_with_thread("close signal received")
    except Exception as e:
        # If we encounter an exception and the future is still running,
        # it means it was encountered during the initialization phase.
        if not self._init_future.done():
            self._init_future.set_exception(e)
        else:
            self._log_debug_with_thread(
                "encountered exception on background thread after initialization %s", str(e)
            )

==> exception returned from MCP server is logged ""encountered exception on background thread after initialization %s", str(e)", but not processed further.

[Unshure]

Hi @LanaSokolova , curious if you can try using the latest strands version and seeing if this issue still persists. I pushed a fix for a similar issue here: https://github.com/strands-agents/sdk-python/pull/922/files, which was released in strands version 1.10.0. I see that this is the version you are using, but this will be easier to debug if you try using the latest version. Thanks in advance!

[LanaSokolova]

Hi @Unshure , I tried with strands-agents 1.14.0, the issue still persists.

[zastrowm]

I was able to reproduce this by adding a proxy in front of our existing test:

Code snippet to reproduce

def start_proxy(**kwargs):
    import aiohttp
    from aiohttp import web

    print("Starting server")

    TARGET_URL = "http://127.0.0.1:8001"

    async def proxy_handler(request):
        url = f"{TARGET_URL}{request.path_qs}"

        async with aiohttp.ClientSession() as session:
            data = await request.read()

            if "tools/call" in f"{data}":
               print("This is a tool call!")
               return web.Response(status=500, text="Internal Server Error")

            async with session.request(
                    method=request.method,
                    url=url,
                    headers=request.headers,
                    data=data,
                    allow_redirects=False
            ) as resp:
                print(f"Got request to {url} {data}")
                response = web.StreamResponse(
                    status=resp.status,
                    headers=resp.headers
                )
                await response.prepare(request)

                async for chunk in resp.content.iter_chunked(8192):
                    await response.write(chunk)

                return response

    app = web.Application()
    app.router.add_route('*', '/{path:.*}', proxy_handler)

    print("Running proxy server")
    web.run_app(app, host='127.0.0.1', port=8002)
    print("Running")

@pytest.mark.asyncio
async def test_streamable_http_mcp_client_with_500_error():
    """Test comprehensive MCP client with streamable HTTP transport."""
    server_thread = threading.Thread(
        target=start_comprehensive_mcp_server, kwargs={"transport": "streamable-http", "port": 8001}, daemon=True
    )
    server_thread.start()
    
    proxy_process = multiprocessing.Process(
        target=start_proxy, kwargs={"transport": "streamable-http", "port": 8002}
    )
    proxy_process.start()

    time.sleep(2)  # wait for server to startup completely

    def transport_callback() -> MCPTransport:
        return streamablehttp_client(url="http://127.0.0.1:8002/mcp", sse_read_timeout=2)
    streamable_http_client = MCPClient(transport_callback, startup_timeout=3)
    with streamable_http_client:
        # Test tools
        result = await streamable_http_client.call_tool_async(tool_use_id="123", name="calculator", arguments={"x": 3, "y": 4})
        assert result["status"] == "error"
        assert result["content"][0]["text"] == "Tool execution failed: Connection closed"
    
    proxy_process.terminate()
    proxy_process.join()

Working to root-cause/fix now

[zastrowm]

It looks like we're hanging because the background thread (that MCP is running on) is being terminated due to the 5XX.

The flow is that a tool_call makes a new request:

1. A new request is started to the server
2. The server returns a 500
3. Our underlying MCP Client raises on 5XX exception errors
4. As a result, the entire thread-group is taken down, resulting in the entire async-io background thread being torn down

The bug is that our implementation of MCP Tool isn't paying attention to (4) and thus the hang occurs. There's a longer-term follow-up question of whether or not a 5XX should take down the entire connection, but going to scope the fix to the hanging issue.

[zastrowm]

Per @dbschmigelski, this might be related/similar to modelcontextprotocol/python-sdk/issues/1577

[zastrowm]

Fix for the server hanging is at #1169