When an Unresponsive MCP Server Freezes Your Agent: Separate Timeouts for Connect, List, and Call

A defensive wrapper: a timeout per boundary

First, a minimal wrapper that lets you apply a different timeout to each boundary. I abstract away the concrete MCP client and assume an object with three methods: connect, list_tools, and call_tool. Wrapping each boundary in asyncio.wait_for is the heart of it.

import asyncio
from dataclasses import dataclass
 
 
@dataclass(frozen=True)
class TimeoutBudget:
    connect: float = 15.0      # seconds: up to the handshake
    list_tools: float = 20.0   # seconds: enumerating tools
    call_tool: float = 120.0   # seconds: one invocation
 
 
class BoundaryTimeout(Exception):
    """Carries which boundary timed out."""
 
    def __init__(self, server: str, boundary: str, limit: float):
        self.server = server
        self.boundary = boundary
        self.limit = limit
        super().__init__(f"{server}: {boundary} timed out after {limit}s")
 
 
async def _guard(coro, *, server: str, boundary: str, limit: float):
    try:
        return await asyncio.wait_for(coro, timeout=limit)
    except asyncio.TimeoutError as exc:
        # A bare TimeoutError erases *where* it stalled.
        # The point is to re-raise with the boundary and server attached.
        raise BoundaryTimeout(server, boundary, limit) from exc
 
 
async def open_session(client, server: str, budget: TimeoutBudget):
    await _guard(client.connect(), server=server, boundary="connect", limit=budget.connect)
    tools = await _guard(
        client.list_tools(), server=server, boundary="list_tools", limit=budget.list_tools
    )
    return tools

The key is not letting asyncio.TimeoutError flow straight up. The standard exception only tells you that something timed out. When you later notify or triage, what you need is two facts: which server, and which boundary. Re-raising as BoundaryTimeout keeps both alive to the end. It is the same instinct as 1.1.3 writing the needed detail to stderr — make the failure itself diagnosable.

Adding exponential backoff and a circuit breaker

Timeouts alone still hand an unresponsive server a dutiful 120 seconds every time. If you fire ten tasks at the same server overnight, a persistent no-response burns twenty minutes. This is where exponential backoff plus a circuit breaker earns its place.

Retry only the safe boundaries. Connect and list-tools are reads, so try them freely. Retry a tool call only when it is idempotent; otherwise, give up after one attempt on the safe side.

import asyncio
import time
from dataclasses import dataclass
 
 
@dataclass
class Breaker:
    """After too many consecutive failures, stop trying that server for a while."""
 
    threshold: int = 3
    cooldown: float = 300.0  # seconds: skip while open
    fails: int = 0
    opened_at: float = 0.0
 
    def allow(self) -> bool:
        if self.fails < self.threshold:
            return True
        if time.monotonic() - self.opened_at >= self.cooldown:
            # After cooldown, allow exactly one half-open probe
            self.fails = self.threshold - 1
            return True
        return False
 
    def record(self, ok: bool) -> None:
        if ok:
            self.fails = 0
        else:
            self.fails += 1
            if self.fails == self.threshold:
                self.opened_at = time.monotonic()
 
 
class BreakerOpen(Exception):
    pass
 
 
async def with_retry(make_coro, *, server, boundary, limit, breaker,
                     attempts=3, base_delay=1.0, retryable=True):
    if not breaker.allow():
        raise BreakerOpen(f"{server}: breaker open, skipping {boundary}")
    last = None
    tries = attempts if retryable else 1
    for i in range(tries):
        try:
            result = await _guard(make_coro(), server=server, boundary=boundary, limit=limit)
            breaker.record(ok=True)
            return result
        except BoundaryTimeout as exc:
            last = exc
            breaker.record(ok=False)
            if i < tries - 1:
                # Exponential backoff: 1s, 2s, 4s ... thin out charges at a dead server
                await asyncio.sleep(base_delay * (2 ** i))
    raise last

I take make_coro as a function because each retry needs a fresh coroutine. A coroutine you have already awaited cannot be reused. Pass it by value and the second attempt dies instantly with a RuntimeError. That is the exact trap I hit first — I spent about an hour on a symptom where "I added backoff but it only retries once."

The circuit breaker is the mechanism that leaves an unresponsive server alone for a while. After three consecutive timeouts, it skips that server entirely for the next five minutes, so the rest of the night's jobs do not each donate 120 seconds to a dead server. The half-open probe is there too, so the moment the server revives, it resumes on its own. How to handle something that is stuck but still alive is also worth reading from the agent's side, in Spotting Agents That Are Alive but Stuck: Designing a Progress Heartbeat and Watchdog.

Tell me which server stalled where — but only on failure

The worst thing an automation notification can do is fire on every success. If "succeeded" arrives every night, people stop looking almost immediately. What you want to arrive is: when it stalls, which server stalled at which boundary, and nothing else.

import json
import sys
 
 
def notify_failure(server: str, boundary: str, limit: float, run_id: str) -> None:
    """On failure only, emit one JSON line to stderr for the upstream notifier."""
    payload = {
        "run_id": run_id,
        "server": server,
        "boundary": boundary,     # connect / list_tools / call_tool
        "limit_seconds": limit,
        "kind": "mcp_timeout",
    }
    print(json.dumps(payload, ensure_ascii=False), file=sys.stderr)
 
 
async def run_task(client, server, budget, breaker, run_id):
    try:
        await _guard(client.connect(), server=server, boundary="connect", limit=budget.connect)
        tools = await with_retry(
            client.list_tools, server=server, boundary="list_tools",
            limit=budget.list_tools, breaker=breaker,
        )
        return tools
    except BoundaryTimeout as exc:
        notify_failure(exc.server, exc.boundary, exc.limit, run_id)
        raise
    except BreakerOpen:
        notify_failure(server, "breaker_open", 0.0, run_id)
        raise

I put the boundary name into the JSON so the next-morning triage is a glance. If boundary is connect, the server likely never started. If it stalls at list_tools, the handshake worked, so I suspect init or schema generation. If it is call_tool, I go look at the external API that one tool is hitting. Just knowing where it stopped points the first investigation of the day in minutes. This "emit only the failure, in a diagnosable shape" stance is continuous with the design 1.1.3 took for its headless fix. For the CLI-side handling of soft-deny and allow rules, I wrote it up in Turning Silent Auto-Approvals into Allow Rules, One Soft-Deny at a Time.

Numbers from actually running it

I laid this layer over the MCP calls in an overnight batch that runs six sites, for one week. The numbers are only from my environment, but the shape should be useful.

The count of interrupted jobs did not drop much. This wrapper does not fix the servers being flaky in the first place. What changed is how they stall — from a "silent stop" to a "failure that notifies." As an indie developer, having a state where you notice a problem first thing in the morning is usually worth more than driving the count to zero. The initial connect 15s / call 120s settled to a 90s call budget after a week of measurement, because the 99th percentile of healthy calls landed in the low 70-second range.

Common pitfalls

Passing the coroutine by value. As above, a retry needs a fresh coroutine each time. Call it with parentheses — with_retry(client.list_tools()) — and it is consumed on the first attempt and broken on the second. Pass the function reference (client.list_tools) instead.

asyncio.wait_for cancels the coroutine, but the socket underneath can linger. The timeout cancels the coroutine, but the MCP server's process or socket does not always clean up immediately. In environments where the next connect turns into "port already in use," you need an explicit close after the timeout.

Sharing breaker state across processes. If you launch each overnight job as a separate process, the breaker's fails does not carry across process boundaries. To span them, you need to persist state to SQLite or a small file. Start within a single process and externalize only when you actually need to.

Allowing call retries on non-idempotent tools uniformly. Reads can be tried any number of times, but blindly retrying a tool that writes or charges will run a job twice that merely timed out yet actually succeeded. retryable is a flag to decide per tool, by its nature.

Where I stop trusting automation

Finally, with per-boundary timeouts in place, here is where I stop letting the machine run on its own.

Reads — connect and list-tools — I hand to the machine without hesitation. There are no side effects however many times they fail, so retries and backoff can run automatically. For tool calls that write, I auto-retry only the ones whose idempotency I can guarantee, and let the rest fail on the first attempt and go to the notifier. Servers that keep not responding get cut automatically by the breaker, but the fact that a cut happened always reaches a person. A server being quietly severed, with nobody noticing it was severed, is the scariest state of all.

As a next step, try applying three separate timeouts — connect, list_tools, call_tool — to your own MCP calls. Splitting one blanket number into three is enough to keep the "where" when something stalls. How to tune the budget from there is something a week of measurement will teach you. I am still adjusting the split myself, but just turning silent stops into failures that notify has made overnight automation far easier to delegate.