mcp-retry

Tiny, opinionated retry/backoff decorators for MCP servers and other API clients. A thin preset layer over tenacity: exponential backoff + jitter, retry on 429/5xx/network errors, log before each retry, re-raise on exhaustion.

Extracted from a fleet of production MCP servers (TikTok Shop, TikTok Ads, and others) so every server retries the same way instead of re-implementing tenacity incantations.

Install

pip install mcp-retry            # core (tenacity only)
pip install "mcp-retry[httpx]"   # + httpx preset

Usage

httpx-based MCP servers (async)

from mcp_retry import httpx_retry

@httpx_retry()
async def _do_request(self, url):
    response = await client.get(url)
    if response.status_code == 429 or response.status_code >= 500:
        response.raise_for_status()  # triggers retry
    return response

Retries on httpx.RequestError (connection errors, timeouts, DNS failures) and httpx.HTTPStatusError. Only call raise_for_status() for status codes you want retried (429/5xx) — 4xx client errors should surface immediately.

requests-based projects (sync)

from mcp_retry import requests_retry

@requests_retry()
def fetch(url):
    r = requests.get(url)
    if r.status_code == 429 or r.status_code >= 500:
        r.raise_for_status()
    return r

Custom exceptions / tuning

from mcp_retry import api_retry

@api_retry(max_attempts=5, min_wait=2, retryable_exceptions=(MyTransientError,))
def fragile_call():
    ...

Defaults: 3 attempts, exponential wait 1–30 s plus 0–2 s random jitter, warning-level log before each sleep, reraise=True.

Why not just tenacity?

You should use tenacity — this is tenacity. mcp-retry just freezes one sane configuration (and the httpx/requests exception sets) behind a one-line decorator, so a dozen MCP servers stay consistent and a retry-policy change is a single-package bump instead of a dozen edits.

License

MIT