Why Your Internal MCP Server Keeps Losing Its Connection: OAuth Token Lifecycle Failures

The single most common root cause is not a bug in your server at all. It is that the MCP client sitting between your agent and your server never actually refreshes the access token on the client's own initiative. Anthropic's own Claude Code has shipped this exact defect twice against real users: one report describes MCP OAuth tokens for HTTP-based servers not auto-refreshing despite a valid refresh token already stored locally, and a separate, later report describes a daily "Connection expired" banner appearing even though the stored refresh token is still valid, meaning the client is choosing to surface a re-auth prompt instead of quietly using the refresh token it already has. Google's Gemini CLI has reported the same underlying gap from a different angle: once the access token expires (commonly after one hour), every subsequent MCP tool call fails, there is no recovery mechanism built into the CLI, and the documented workaround is to restart the CLI process entirely, which forces a fresh OAuth flow. None of these are configuration mistakes on the server side. They are gaps in the client's session-management code, and industry write-ups from mid-2026 describe this as a pattern across MCP clients broadly, not an isolated defect in any one product.

A second, more subtle cause is a client that does attempt to refresh, but sends a refresh request the authorization server rejects. OpenAI's Codex hit a specific version of this: its MCP OAuth refresh flow omitted the RFC 8707 resource parameter that the MCP authorization specification requires on token requests, which meant that after the access token expired, the refresh attempt itself failed, the MCP server became unreachable, and in Codex's case a required MCP server could block creation of a new task entirely with an "OAuth authorization required" error. This is diagnosable specifically because the failure happens at the refresh step, not at the point the original access token expires: the client is trying to do the right thing and getting a rejection back from the authorization server.

Many identity providers used behind MCP servers, and Atlassian and Asana are commonly cited examples, rotate the refresh token on every use: each refresh both issues a new access token and invalidates the refresh token that was just spent, issuing a new one in its place. That is a reasonable security control on its own, but it creates a specific failure mode when more than one request hits an expired access token at the same moment, which happens naturally when an agent fires several tool calls in quick succession. The first refresh request succeeds and rotates the token. Every other in-flight request, which captured the same now-spent refresh token before the first one completed, then presents it and gets back invalid_grant. Under RFC 6819's replay-detection guidance, some authorization servers respond to that reuse by revoking the entire token family, which is worse than a transient failure: it forces a full manual re-authentication, not just a retry. This exact defect has been filed directly against the MCP TypeScript SDK, where a race condition in the client's auth() function causes refresh token invalidation specifically when the identity provider uses rotating refresh tokens, confirming this is not merely a generic OAuth footgun but one that has already reached MCP's own reference client implementation.

JWT-based access tokens are validated in part by checking the exp (expiration) and nbf (not-before) claims against the verifier's own local clock. If the MCP server's clock and the authorization server's clock have drifted, a token that is genuinely still valid by the issuer's clock can be rejected as expired or not-yet-valid by the verifier's clock, or the reverse. This is a materially bigger risk in containerized MCP server deployments than on a stable host, because a container's clock can drift from its host's clock independently, and container restarts do not always re-sync time immediately. The practical signal here is that the failure looks intermittent and does not correlate cleanly with the token's actual configured lifetime; some implementations mitigate this with a roughly 60-second grace period on expiration checks specifically to absorb ordinary clock drift, which is a strong hint at what is missing if your own server enforces exp and nbf with zero tolerance.

The last major cause is not an OAuth problem at all, even though it produces an identical symptom from the user's seat. MCP's Streamable HTTP transport uses a session, tracked via an MCP-Session-Id header, that is logically separate from the OAuth access token. The specification is explicit that a server may terminate a session at any time and must respond with HTTP 404 to any further request carrying that session ID, at which point a compliant client is supposed to start an entirely new session by sending a fresh InitializeRequest without a session ID. In practice, this handoff is where clients without robust reconnection logic fail outright, and even clients that do attempt to reconnect can cycle through repeated "session not found" errors before they succeed. Docker's MCP Gateway has documented Streamable HTTP sessions being terminated after roughly sixty seconds in some configurations, and the MCP TypeScript SDK has an open report specifically about idle session timeout behavior on this transport. The tell here is a 404 with a session-not-found style message in your server logs, as opposed to a 401 pointing at the OAuth layer, and it means the fix belongs in session lifetime and reconnection handling, not in token refresh logic at all.

Before applying any fix, pull the actual failure response your server returned at the moment the connection dropped, because the five causes above leave distinguishable fingerprints. A 401 at the moment the access token's own lifetime expired, with no refresh attempt visible in the authorization server's logs at all, points to cause 1, a client that never tries to refresh. A refresh attempt that the authorization server itself rejects as malformed, visible in the authorization server's own request logs, points to cause 2. An invalid_grant response specifically on the refresh call, especially one that correlates with a burst of concurrent tool calls, points to cause 3. A rejection that does not line up with the token's configured lifetime at all, and that clears up after a container restart or an NTP resync, points to cause 4. And a 404 carrying a session-not-found message, distinct from any 401, points to cause 5, the transport session, not the token. Reproducing the failure deliberately, by forcing a token to sit past expiry and then firing several tool calls at once, is the fastest way to separate cause 3 from the others, since it will not show up under a single serialized request.

Each cause above has a distinct fix; applying the wrong one will not resolve the loop even though it might feel like progress.

A fix that looks like it worked for the next ten minutes is not validated. Run a soak test that deliberately spans at least two full token-expiry boundaries, not just one, since single-boundary tests miss failures that only show up on the second refresh cycle. Separately, fire a burst of concurrent tool calls timed to land exactly at an access token's expiry to specifically re-trigger the refresh-rotation race from cause 3; a single-flight lock that works under a serialized test can still fail under real concurrency if the lock scope was set incorrectly. Restart the MCP server process mid-session to confirm the transport-session fix actually produces a clean reconnect rather than a stuck client, and check your authorization server's own audit log after 24 to 48 hours of normal traffic for zero token-family revocations and zero repeated invalid_grant responses, which is the clearest sign the loop is actually gone rather than just less frequent.

Some instances of this problem do not have a full technical fix available on your side today. If the client you are integrating against has no reconnection logic whatsoever, as opposed to buggy reconnection logic, patching your server cannot compensate; the honest options are switching clients, wrapping the client in a supervising process that restarts it on failure, or accepting the manual re-auth cadence until the client ships a fix. If an authorization server has already revoked a refresh token family due to confirmed reuse, that family is gone; the user has to complete a fresh OAuth authorization, and no retry or backoff strategy recovers it. And if the identity provider behind your MCP server enforces a short, non-negotiable session or token lifetime as a platform policy, for example a compliance-driven one-hour cap that cannot be extended, then proactive refresh reduces how often users notice the boundary but does not eliminate the requirement to cross it correctly every time.

Escalate to the MCP client vendor, rather than continuing to iterate on your own server, once you have confirmed through the diagnostics above that the failure originates in the client's session or refresh handling and not in anything your server controls; cite the specific upstream issue if one already exists, since several of the causes in this guide are already tracked against Claude Code, Gemini CLI, Codex, and the MCP TypeScript SDK directly. Escalate to your identity provider's support channel when a token family has been revoked repeatedly for the same user or service account, since that pattern usually means the rotation-race fix on your side is incomplete rather than the user doing anything wrong. Escalate to your own security or platform leadership, separate from a vendor ticket, when the workaround in place is "restart the client on a timer" or "issue very long-lived tokens to avoid frequent refresh," since both are operational patches that quietly widen your actual exposure window and deserve a real risk conversation rather than living on indefinitely as the fix.