Aident AI
Claude Code MCP Unauthorized? Reauthenticate One Session
If a remote MCP server suddenly returns Unauthorized after two Claude Code sessions start together, stop the overlapping Claude processes, keep one interactive session open, and reauthenticate that server once. In Claude Code, run /mcp, select the affected server, and choose Re-authenticate. From a terminal, the equivalent command is:
This restores the current connection. It does not permanently fix a client-side refresh race, so verify one read-only request before restarting other sessions.
Do not edit Claude's credential files, paste tokens between machines, or repeatedly log every process back in at the same time. Those actions can recreate the race or expose a reusable secret.
Confirm the Concurrent Refresh Signature
The strongest signature is not simply an MCP login failure. It is a server that worked, followed by an access-token refresh while multiple Claude Code processes were active.
Look for these conditions:
The same remote MCP server is configured in two or more Claude Code sessions, scheduled jobs, terminal tabs, or headless processes.
The sessions start or resume close together.
One session reconnects, while another reports
Unauthorized, HTTP401,invalid_grant, or a rejected refresh token.Reauthenticating restores access temporarily, but the error returns when concurrent sessions resume.
On macOS or Linux, use a read-only process listing to find overlapping Claude processes:
On Windows, check Task Manager for multiple Claude Code processes and any scheduled task that launches Claude. Close sessions normally after saving their work. Do not terminate an unknown process just because it contains claude in its command line.
Observation | More likely cause | Next step |
|---|---|---|
One server fails just after concurrent sessions resume | Refresh-token race | Keep one session, reauthenticate once, then test one read-only request |
Every server fails before the browser ever reaches authorization | Callback, proxy, or redirect configuration | Use the MCP OAuth callback guide |
A server always requires a fresh login in one environment | Credential storage or scope mismatch | Compare the server configuration and supported auth flow without copying tokens |
A headless session cannot open the browser | Interactive authorization is unavailable | Use the documented |
Reauth works until a second long-running process starts | Recurring coordination problem | Give one process ownership of the rotating credential or use a provider-supported alternative |
Why One Refresh Can Invalidate Every Session
OAuth access tokens are intentionally short-lived. A refresh token lets a client obtain a new access token without asking the user to authorize again. Current MCP security guidance recommends refresh-token rotation for public clients: after a successful refresh, the authorization server returns a replacement refresh token and retires the one that was just used.
That is safe when one client owns the sequence. It can fail when two independent processes read the same stored token:
Process A and process B both load refresh token R1.
Process A exchanges R1 and receives R2.
Process B sends the now-retired R1.
The authorization server rejects the stale token and may revoke the token family as a reuse defense.
Other sessions that shared the family begin returning
Unauthorized.
Anthropic issue 85236 reports this exact MCP pattern in Claude Code 2.1.222 and 2.1.226: concurrent processes started within seconds, one refresh succeeded, another received invalid_grant, and every session needed authorization again. A separate, older Claude account OAuth issue collected independent reports of similar multi-process refresh failures across macOS, Linux, and Windows. The older issue concerns Claude account OAuth rather than MCP OAuth, so it is corroborating evidence for the concurrency pattern, not proof that both paths use the same implementation.
Recover the MCP Connection Safely
1. Pause new launches
Temporarily pause scheduled jobs, background agents, and scripts that start Claude Code. Save work in interactive sessions, then close all but one normally. The objective is to leave one process capable of owning the next refresh.
2. Identify the affected server
List configured MCP servers:
Record the exact server name and connection state. Do not log out unrelated servers.
3. Reauthenticate from one session
In the remaining interactive Claude Code session, run:
Select the affected server and choose Re-authenticate. Anthropic's current documentation says Claude Code points users to this flow when a rejected token needs fresh authorization.
You can instead use the CLI:
For an SSH session where the remote machine cannot open a browser, use the documented device-style flow:
Complete that flow in one place. Do not run the login command simultaneously in every terminal.
4. Verify a read-only request
Check the server state again, then make one harmless read-only request through the server. Success means the server shows connected and the read succeeds without another authentication prompt.
If the request is still unauthorized, confirm that no scheduled process restarted Claude during the login. Close the extra process normally and repeat the single-session reauthentication once. Avoid clearing all Claude state or deleting credential directories.
5. Restart only the sessions you need
Restart other sessions gradually. If the next token refresh invalidates them again, treat the single-session procedure as a recovery, not a durable fix. Preserve the Claude Code version, server name, operating system, sanitized error, and timing between process starts for an upstream report.
Reduce Recurrence in Long-Running Workflows
Until Claude Code coordinates refreshes across processes, avoid giving many long-lived processes ownership of the same rotating MCP credential.
Practical boundaries include:
Keep one persistent Claude process responsible for the remote MCP connection and serialize work that depends on it.
Stagger scheduled Claude launches so they do not all resume and refresh together.
Prefer a provider-supported non-OAuth credential only when the provider officially offers it and your secrets manager can inject it without exposing the value.
Do not convert a managed OAuth connection to a copied API key merely to hide the symptom. The API key versus OAuth guide explains the security tradeoff.
Update Claude Code when Anthropic ships a release that explicitly addresses the issue, then repeat the concurrent-session test before removing the boundary.
There is no evidence in the cited reports that deleting project files, reinstalling every MCP server, or editing stored token JSON repairs the coordination problem.
Check the Connection Without Exposing Credentials
Aident Loadout can inspect connection readiness and preflight a read-only Action while keeping provider credentials in Vault.
Start with this setup phrase:
Follow https://aident.ai/SETUP.md
Then ask:
Check Aident Loadout authentication and Vault status. Search the staging capability catalog for the current read-only Action backed by my affected service, inspect its schema, and preflight one minimal read. If the input is valid and the estimate is free, execute it and return only the connection result and non-sensitive response fields. Do not write, reconnect, disconnect, reveal tokens, or bypass the integration layer.
Success is measurable: Vault reports the intended connection ready, the preflight is valid, one read-only request succeeds, and no credential appears in the prompt or output.
Set up Aident Loadout and verify an MCP-backed connection.
Sources
Anthropic issue 24317: concurrent Claude OAuth refresh failures
Model Context Protocol authorization security considerations
Refresh this guide when Anthropic closes issue 85236 with a released fix, changes the /mcp reauthentication flow, or documents cross-process refresh coordination.
The one tool
for every tool
your agent needs.
Give any AI agent real capabilities in seconds. Connect 1,000+ tools once, skip the setup headache, and let your agents execute.