Handling MCPClient timeouts in an agent

[ben-gineer]

MCPClient SSE Timeout - Help Needed!

What We're Experiencing

We're using strands.tools.mcp.MCPClient with SSE connections in a long-running agent, and we're running into a challenge. After the SSE connection times out (configured via sse_read_timeout), all subsequent tool calls fail and the MCPClient doesn't automatically reconnect.

Important context: We're wrapping our Strands agent with the AG-UI Strands wrapper (StrandsAgent from ag_ui_strands), which might be part of the issue. Not sure if this affects how the MCP tools behave or if we're missing something in our setup.

Current Behavior

Here's what happens:

1. Initial MCP tool calls work perfectly
2. After sse_read_timeout period of inactivity, the SSE connection times out
3. Subsequent tool calls fail with connection errors (httpx.ReadTimeout, "SSE connection closed", etc.)
4. No automatic reconnection occurs
5. The agent becomes unusable until we manually restart the server

What We're Hoping For

We'd love to have the MCPClient:

1. Detect connection errors (timeout, broken pipe, etc.)
2. Automatically create a new SSE connection
3. Retry the failed tool call
4. Continue working seamlessly

But we're not sure if this is the right approach or if we're missing something! How do others handle SSE timeouts with MCPClient in long-running agents?

How to Reproduce

If you'd like to see what we're experiencing, here's how to reproduce it:

1. Setup Environment

# Set required environment variables
export MCP_SERVER_URL="https://your-mcp-server.example.com/sse"
export MCP_BEARER_TOKEN="your-oauth-token"
export MCP_SSE_TIMEOUT="30"  # 30 seconds for quick testing

2. Run the Test Agent

cd apps/agentic-backend
uv run python mcp_timeout_issue.py

3. Make Initial Request (Works)

curl -X POST http://localhost:8080/invocations \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "role": "user",
        "content": "Use the MCP tools to search for something"
      }
    ]
  }'

Result: ✅ Works - MCP tools are called successfully

4. Wait for Timeout

# Wait 30+ seconds for SSE connection to timeout
sleep 35

5. Make Second Request (Fails)

curl -X POST http://localhost:8080/invocations \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "role": "user",
        "content": "Use the MCP tools to search for something else"
      }
    ]
  }'

Result: ❌ Fails with connection error like:

• httpx.ReadTimeout
• SSE connection closed
• Connection reset by peer
• etc.

6. Subsequent Requests Continue to Fail

All future requests will continue to fail until the server is restarted.

Our Current Setup

Here's how we're creating and using the MCPClient:

def create_mcp_client(tool_filters: Optional[dict] = None):
    """Create MCP client with fresh OAuth token."""
    mcp_url = os.getenv("MCP_SERVER_URL", "https://your-mcp-server.example.com/sse")
    sse_read_timeout = float(os.getenv("MCP_SSE_TIMEOUT", "30"))
    
    return MCPClient(lambda: sse_client(
        url=mcp_url,
        auth=BearerAuth(token=get_bearer_token()),
        sse_read_timeout=sse_read_timeout,
    ), tool_filters=tool_filters)


# In the agent creation:

mcp_client = create_mcp_client()

agent = Agent(
    model=model,
    tools=[mcp_client],
    system_prompt=system_prompt,
)

# Then we wrap it with AG-UI Strands:
agui_agent = StrandsAgent(
    agent=agent,
    name="our_agent",
    description="Our agent with MCP tools",
)

Is there something we should be doing differently here?

What We've Tried

We attempted to implement a ReconnectingMCPClient wrapper that would:

1. Wrap MCPClient with reconnection logic
2. Catch connection errors
3. Create a fresh MCPClient instance
4. Retry the failed operation

However, this approach failed because MCPClient doesn't properly initialize when wrapped. The wrapper pattern doesn't work with how MCPClient's internals are structured, and the tools don't become available to the agent.

Questions for the Community

1. Is this expected behavior? Should MCPClient handle reconnection automatically, or is there a pattern we should be following?

2. AG-UI Strands wrapper issue? Could wrapping the Strands agent with StrandsAgent from ag_ui_strands be interfering with how MCP tools maintain their connections?

3. How do others handle this? For those running long-running agents with MCP tools, how do you handle SSE connection timeouts?

4. Alternative approaches? Should we be creating the MCP client differently, or is there a way to detect and handle connection failures we're missing?

Any insights or suggestions would be greatly appreciated!

Environment Details

• Python Version: 3.13.0
• Strands Version: strands-agents >= 1.20.0
• Strands Tools Version: strands-agents-tools >= 0.2.18
• AG-UI Strands Version: ag-ui-strands >= 0.1.0
• FastMCP Version: fastmcp >= 2.14.2
• SSE Timeout: 30 seconds (for testing), 600s+ (production)

Impact

This issue affects any long-running agent that uses MCPClient with SSE connections. In production:

• Agents become unusable after idle periods
• Requires manual restarts
• Poor user experience
• Defeats the purpose of persistent SSE connections

Files

• mcp_timeout_issue.py - Minimal reproduction script
• test_mcp_timeout.py - Simple test script demonstrating the issue

test_mcp_timeout.py
mcp_timeout_issue.py

[strands-agent]

Hi @ben-gineer! 👋

Thank you for this incredibly detailed writeup! This is a known issue that several users have encountered.

Related Issues & Work

Your issue is related to:

• Issue [BUG] Agent hanging on 5xx #1334: MCPClient hang when session closes
• PR fix(mcp): prevent agent hang by checking session closure state #1396: fix(mcp): prevent agent hang by checking session closure state by @Ratish1

The PR addresses part of this problem by checking the session state before making calls, which prevents hangs when the connection is closed.

Current Status

PR #1396 is in progress and adds session state checking. However, as you've identified, there's still a gap around automatic reconnection after timeout.

Potential Workarounds

1. Recreate MCPClient per request

For now, the most reliable pattern is to recreate the MCPClient for each agent invocation:

async def handle_request(messages):
    # Create fresh MCP client per request
    with create_mcp_client() as mcp_client:
        agent = Agent(
            model=model,
            tools=[mcp_client],
            system_prompt=system_prompt,
        )
        return agent(messages)

2. Increase SSE timeout significantly

If your use case allows, increase sse_read_timeout to match your expected session duration:

sse_read_timeout=3600  # 1 hour

3. Use a connection health check

Before invoking the agent, check if the MCP client is still connected:

try:
    # Quick health check
    await mcp_client.list_tools()
except Exception:
    # Recreate client
    mcp_client = create_mcp_client()

Feature Request

Your suggestion for automatic reconnection is valuable! Would you consider filing a separate feature request for "Automatic reconnection support for MCPClient"? This would help track and prioritize the work.

Key requirements:

1. Detect connection errors
2. Automatic reconnection with backoff
3. Transparent retry of failed tool calls

I'll keep an eye on this discussion and PR #1396. Let us know if the workarounds help! 🦆

---

🤖 This is an experimental AI agent response from the Strands team, powered by Strands Agents. We're exploring how AI agents can help with community support and development. Your feedback helps us improve! If you'd prefer human assistance, please let us know.

[ben-gineer]

It was suggested that this might be an issue with the deprecated SSE client. However, I see the same behaviour with the Streamable HTTP transport.