[BUG] MCP Client Doesn't Recover from a Timeout

[wt-bryan]

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.4.0

Python Version

3.12.11

Operating System

macOS 15.6

Installation Method

pip

Steps to Reproduce

Code:

import asyncio
from dotenv import load_dotenv
from fastmcp.client.auth import OAuth
from mcp.client.sse import sse_client
import os
from strands import Agent
from strands.models.litellm import LiteLLMModel
from strands.tools.mcp import MCPClient

load_dotenv()

atlassian_mcp_url = "https://mcp.atlassian.com/v1/sse"


model = LiteLLMModel(
    client_args={"api_key": os.getenv("LITE_LLM_KEY")},
    # **model_config
    model_id="claude-4-sonnet",
    params={
        "max_tokens": 1000,
        "temperature": 0.7,
    },
)


async def test_strands_agents_mcp_sse(prompt: str, sse_mcp_client: MCPClient):
    try:
        # First run: Don't approve or deny OAuth permissions - wait for 30 seconds to get the timeout
        # Second run: This and all subsequent attempt to connect will immediately fail
        with sse_mcp_client:
            tools = sse_mcp_client.list_tools_sync()
            agent = Agent(model=model, tools=tools)
            agent(prompt)
    except Exception as e:
        print(f"Error connecting to Strands MCP server: {e}")
        return


async def main():
    #### Atlassian MCP setup ####
    oauth = OAuth(mcp_url=atlassian_mcp_url)

    sse_mcp_client_oauth = MCPClient(
        lambda: sse_client(url=atlassian_mcp_url, auth=oauth)
    )

    await test_strands_agents_mcp_sse("Which tickets are open?", sse_mcp_client_oauth)

    await test_strands_agents_mcp_sse(
        "Which tickets are in progress?", sse_mcp_client_oauth
    )


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

1. Run the code snippet
2. When the OAuth screen appears, do nothing for 30+ seconds

Expected Behavior

The next request attempts the OAuth flow again

Actual Behavior

Subsequent requests fail immediately when attempting to connect to MCP Server with Error connecting to Strands MCP server: the client session is currently running error.

Additional Context

This shouldn't be specific to the Atlassian MCP server, it's just the only one that I know of that I have access to and requires OAuth. It also isn't specific to FastMCP. The issue should also be reproducible if some other process caused a timeout after the _background_thread is started in MCPClient.start()

This might be related to #625 but I opened a separate issue since that issue states that no exception is thrown. It also states that the agent gets frozen waiting for a response and I don't observe that happening here.

Possible Solution

The issue seems to be within MCPClient.start(). The background thread is started but isn't closed/cleaned up if an error occurs.

Related Issues

No response

[pgrayy]

Thank you for raising this issue. I went ahead and simplified the reproduction script:

import time
import unittest.mock

from strands.tools.mcp import MCPClient

def transport():
    time.sleep(3)
    return unittest.mock.Mock(), unittest.mock.Mock()
    
client = MCPClient(transport_callable=transport, startup_timeout=2)

try:
    client.start()
except Exception as e:
    print(f"error=<{e}> | first attempt failed")

try:
    client.start()
except Exception as e:
    print(f"error=<{e}> | second attempt failed")

# results in the following output:
# error=<background thread did not start in 2 seconds> | first attempt failed
# error=<the client session is currently running> | second attempt failed

I'll start working on a fix.

[dbschmigelski]

Hi, regarding the following I'm not sure I agree with this being a valid example. We implement the a context manager. This handles the closing of the resource. We will update comments to make this clearer that when you opt to use start and stop directly the onus is on the user to call stop

try:
client.start()
except Exception as e:
print(f"error=<{e}> | first attempt failed")

try:
client.start()
except Exception as e:
print(f"error=<{e}> | second attempt failed")

Meaning the valid test case will be

import time
import unittest.mock

from strands.tools.mcp import MCPClient

def transport():
    time.sleep(3)
    return unittest.mock.Mock(), unittest.mock.Mock()
    
client = MCPClient(transport_callable=transport, startup_timeout=2)

try:
    client.start()
except Exception as e:
    print(f"error=<{e}> | first attempt failed")
    client.stop(None, None, None)  # <----- NEW

try:
    client.start()
except Exception as e:
    print(f"error=<{e}> | second attempt failed")

Note, this still fails, but I want to be as specific as possible to address the fix.

[wt-bryan]

Hey @dbschmigelski. I might be misreading your comment but the example in the bug I reported did use a context manager; the simplified reproduction script posted by @pgrayy directly called .start(). The latter example can be rewritten using a context manager and you'll get the same result:

import time
import unittest.mock

from strands.tools.mcp import MCPClient

def transport():
    time.sleep(3)
    return unittest.mock.Mock(), unittest.mock.Mock()
    
client = MCPClient(transport_callable=transport, startup_timeout=2)

try:
    with client:
      print("MCP client started successfully")

except Exception as e:
    print(f"error=<{e}> | first attempt failed")

try:
    with client:
      print("MCP client started successfully")
except Exception as e:
    print(f"error=<{e}> | second attempt failed")

# results in the following output:
# error=<background thread did not start in 2 seconds> | first attempt failed
# error=<the client session is currently running> | second attempt failed

Running your script gave me a multiple errors that are different than the one I reported here. Does your PR address both these cases or only the issue arising from calling .stop() after there was a failure in .start()?

[dbschmigelski]

It will handle both as enter simply calls start() under the hood. Thanks for raising this and apologies that it took so long to get to.

The test case added here matches your original example

https://github.com/dbschmigelski/sdk-python/blob/12e3037608fb70b67e10b45aec4e260082198b67/tests_integ/test_mcp_client.py#L274-L299

def test_mcp_client_timeout_integration():
    import threading

    from mcp import StdioServerParameters, stdio_client

    def slow_transport():
        time.sleep(4)  # Longer than timeout
        return stdio_client(StdioServerParameters(command="python", args=["tests_integ/echo_server.py"]))

    client = MCPClient(slow_transport, startup_timeout=2)
    initial_threads = threading.active_count()

    # First attempt should timeout
    with pytest.raises(MCPClientInitializationError, match="background thread did not start in 2 seconds"):
        with client:
            pass

    time.sleep(1)  # Allow cleanup
    assert threading.active_count() == initial_threads  # No thread leak

    # Should be able to recover by increasing timeout
    client._startup_timeout = 60
    with client:
        tools = client.list_tools_sync()
        assert len(tools) >= 0  # Should work now

[dbschmigelski]

Hi, with #833 merged this should now be resolved. Thanks for raising the issue and let us know if you still encounter problems here!