Bug: anyio.Lock in async_auth_flow causes RuntimeError under concurrent OAuth MCP connections

[EnGassa]

Summary

Confirmed production occurrence of the bug described in #2644 (self-closed by the original reporter before they could follow through). Filing to provide a second validated repro and draw attention to the existing draft fix in #2660.

Environment

• mcp==1.26.0
• anyio==4.13.0
• httpx==0.28.1
• Python 3.11.14, macOS

What happens

When a gateway session starts and connects to multiple OAuth-authenticated MCP servers concurrently (Notion + TinyFish, both OAuth 2.1 PKCE), Notion fails intermittently:

ERROR asyncio: Task exception was never retrieved
RuntimeError: The current task is not holding this lock
  File ".../mcp/client/auth/oauth2.py", line 503, in async_auth_flow
  File ".../mcp/client/auth/oauth2.py", line 484, in async_auth_flow
    raise RuntimeError("The current task is not holding this lock")

WARNING tools.mcp_tool: MCP server 'notion' connection lost (attempt 1/5), reconnecting in 1s
WARNING tools.mcp_tool: Failed to connect to MCP server 'notion': CancelledError
INFO tools.mcp_tool: MCP: registered 114 tool(s) from 4 server(s) (1 failed)

Notion is affected more often than TinyFish because its OAuth token refreshes frequently (~every 15–60 min), consistently triggering the refresh yield path in async_auth_flow. TinyFish tokens expire less often and typically take the happy path (add header, yield once).

Root cause

OAuthContext.lock is anyio.Lock, which records task identity at acquire() and enforces same-task release(). async_auth_flow is an async generator that holds this lock across yield points. When httpx drives the generator from a different task during concurrent connections, anyio.Lock.release() throws.

Existing draft fix

PR #2660 addresses this correctly by narrowing lock scope so no lock is held across yields — GET SSE long-polls and token refresh yields both run outside any lock. It has full test coverage (100% on oauth2.py, 1177 passed) and no breaking changes, but has been sitting as a draft without maintainer review since May 22.

Workaround applied locally

Replacing anyio.Lock with asyncio.Lock in OAuthContext stops the error since asyncio.Lock does not enforce task identity on release. This is a bandaid — it loses trio portability — but unblocks asyncio deployments. Note: this is a mechanical fix and has not been load-tested to exhaustion; the intermittent nature of the bug means full verification requires sustained concurrent load.

Request

Could a maintainer review and merge PR #2660? The fix is principled and well-tested.

[Bartok9]

Confirmed the root-cause analysis here is correct and the existing fix is the right one.

Verified on current main: OAuthContext.lock is anyio.Lock (records task identity at acquire(), enforces same-task release()), and async_auth_flow holds it across yield points (oauth2.py — the async with self.context.lock: wraps the yield refresh_request / yield request / full 401 flow). When httpx drives the generator from a different task during concurrent connections, release() raises RuntimeError: The current task is not holding this lock — exactly the trace here and in #2644.

PR #2660 fixes this correctly by narrowing lock scope (no HTTP yield runs while holding context.lock) plus a single-flight refresh_lock. It was sitting CONFLICTING since May 27; I rebased it onto current main — conflict is small and isolated to the refresh block, and the rebased branch is green (108 auth tests pass, ruff clean). Details + branch on #2660. The asyncio.Lock swap mentioned here works for asyncio-only deployments but loses trio portability, so #2660's narrow-the-scope approach is preferable.

[Bartok9]

Opened #2858 with a ready-to-merge fix: a conflict-free rebase of @peisuke's #2660 onto current main (all credit to @peisuke for the fix). Narrows context.lock scope so no HTTP yield runs while the lock is held, with a single-flight refresh_lock — keeps trio portability. Green: 108 auth tests pass, ruff clean. This should unblock the concurrent-OAuth RuntimeError reported here.

[Bartok9]

@Ben-Home — this is really valuable production data, thank you. The "~15% failures → zero after jitter" number is exactly the kind of real-world signal worth acting on, and we did: I just opened #2859 to bring proactive refresh + jitter into the SDK, motivated directly by your comment.

A couple of clarifications on the current architecture, since they shape where each fix belongs:

On lock sharing across connectors: In this SDK the lock isn't actually shared between connectors. OAuthContext (which owns the lock) is instantiated per OAuthClientProvider, and there's one provider per server connection — so Notion and Shopify already have independent locks. There's no global/module-level lock; it's field(default_factory=anyio.Lock) on a per-instance context. So "Notion refresh blocks Shopify" shouldn't occur from lock contention today — the per-connector isolation you'd want is already the structure.

On auth vs refresh lock (your point #3): #2858 already does this. It keeps context.lock for short state reads/writes only, adds a dedicated single-flight refresh_lock, and runs all HTTP yields (including the long-poll GET SSE) outside both locks. So the initial PKCE flow and token refresh no longer contend, and a slow refresh round-trip doesn't block unrelated requests. (#2858 fixes the RuntimeError correctness bug; it isn't a Lock→Semaphore swap.)

On your jitter idea (#2) — this is the genuinely new lever, so I built it: #2859 adds calculate_token_refresh_time() — refresh at ~80% of TTL minus bounded random jitter (≤30s, always subtracted so it can never overshoot hard expiry), tracked as token_refresh_time with a should_refresh_token() predicate. async_auth_flow now refreshes proactively when past the jittered window (not only reactively at hard expiry). Because each provider's refresh point is independently jittered, a fleet's tokens stop clustering into the same ~60s window — which is precisely the thundering-herd you described. Fully backward-compatible (no expires_in → stays purely reactive). 12 new tests, full auth suite green, ruff + pyright clean.

Would genuinely love to see your refresh-stagger implementation — if your approach differs (e.g. different fraction/jitter bounds, or per-fleet coordination rather than per-connector), that's worth folding in or discussing on #2859. Thanks again for pushing on this.

[diaanhw]

Independent production confirmation on a long-running gateway (hermes-agent 0.16.0), with an escalation path worth noting for long-lived processes.

Environment: mcp==1.26.0, anyio==4.12.1, httpx==0.28.1, Python 3.11.14, macOS arm64. Four OAuth 2.1/PKCE streamable-HTTP MCP servers (Reportify) connected concurrently from one process.

Trace (verbatim; three separate incidents on 2026-07-04/06/07):

ERROR asyncio: Task exception was never retrieved
future: <Task finished name='Task-6716' coro=<<async_generator_athrow without __name__>()> exception=RuntimeError('The current task is not holding this lock')>
Traceback (most recent call last):
  File ".../mcp/client/auth/oauth2.py", line 503, in async_auth_flow
    response = yield request
GeneratorExit

During handling of the above exception, another exception occurred:

Traceback (most recent call last):
  File ".../mcp/client/auth/oauth2.py", line 484, in async_auth_flow
    async with self.context.lock:
  File ".../anyio/_core/_synchronization.py", line 166, in __aexit__
    self.release()
  File ".../anyio/_backends/_asyncio.py", line 1854, in release
    raise RuntimeError("The current task is not holding this lock")
RuntimeError: The current task is not holding this lock

This is the generator being closed (GeneratorExit delivered at the yield) from a task other than the one that entered async with self.context.lock: — so it reproduces without retries or redirects; connection teardown during a suspended auth flow is enough. Immediately followed by:

WARNING tools.mcp_tool: MCP server 'reportify-agent' connection lost (attempt 1/5), reconnecting in 2s: unhandled errors in a TaskGroup (1 sub-exception)

Why this is worse than an aborted request in long-lived deployments: after the RuntimeError the server's connection is dead inside the still-running gateway, so periodic token refresh for it stops. Our provider's refresh token has a bounded lifetime (~25 h); once it ages past that, refresh is rejected (Token refresh failed: 400) and the only way back is a full interactive browser re-auth. An "intermittent" failure escalates into credential loss whenever the process outlives the refresh-token lifetime.

Also confirming the earlier comment about current state: v1.28.1 and main still hold context.lock across the yields (oauth2.py:493 on v1.28.1), so no released version avoids this today. +1 for maintainer review of #2858.