[BUG] MCP 'needs-auth cache' blocks reconnection to claudeai-proxy servers even after successful re-authentication for SDK processes

Preflight Checklist

• [x] I have searched existing issues and this hasn't been reported yet
• [x] This is a single bug report (please file separate reports for different bugs)
• [x] I am using the latest version of Claude Code

What's Wrong?

When a claudeai-proxy MCP server (managed by claude.ai) fails to connect due to an expired OAuth token, Claude Code writes an entry to ~/.claude/mcp-needs-auth-cache.json with a 15-minute TTL. During that window, all new Claude Code processes skip the connection attempt entirely — even if the user has since re-authenticated and the Keychain contains a valid token.

This is particularly problematic for SDK consumers like claude-agent-acp, where each session spawns a fresh Claude Code child process. The user cannot run /mcp to authenticate interactively in these environments, so the workflow is:

1. Authenticate in a terminal Claude Code session (via /mcp)
2. Restart the SDK-based session

Step 2 fails if done within 15 minutes of the original failure, because the new process reads the stale cache and never attempts a connection.

Steps to reproduce

1. Start a Claude Code session via claude-agent-acp (or any SDK consumer) with claudeai-proxy MCP servers (e.g. GitHub)
2. Let the OAuth token expire — servers are marked needs-auth and cached in mcp-needs-auth-cache.json
3. Authenticate in a separate terminal Claude Code session via /mcp
4. Restart the SDK-based session within 15 minutes

Expected: The new session reads the refreshed token from the Keychain and connects successfully.

Actual: The new session reads mcp-needs-auth-cache.json, sees entries younger than 15 minutes, logs "Skipping connection (cached needs-auth)", and never attempts a connection.d

Verified behavior

We confirmed this experimentally:

| Scenario | Result |
|----------|--------|
| Fresh cache entries (<15 min) + valid Keychain token | Connection skipped, only authenticate stubs available |
| Cache file deleted + valid Keychain token | Servers connect successfully |

Root cause

In cli.js, the connection logic for claudeai-proxy, http, and sse servers checks the file-based cache before attempting any connection:

if (await isInNeedsAuthCache(serverName)) {
    log("Skipping connection (cached needs-auth)");
    return { type: "needs-auth" };
}

The cache TTL is 900,000ms (15 minutes). The cache is shared across all Claude Code processes on the machine and has no invalidation mechanism tied to token refresh.

Suggested fixes

Any of these would resolve the issue:

1. Invalidate cache on token refresh — When the Keychain token is updated (e.g. after /mcp authentication), clear or invalidate the corresponding entries in the cache file.
2. Scope cache to process lifetime — Use in-memory caching instead of a shared file, so new processes always attempt a fresh connection.
3. Check token freshness before using cache — Before skipping a connection, compare the cache timestamp against the Keychain token's last-modified time. If the token is newer, ignore the cache.
4. Expose cache clearing via SDK — Allow SDK consumers like claude-agent-acp to signal "auth state changed, retry connections" (the getOAuthToken callback infrastructure already exists).

Workaround

Deleting the cache file after re-authenticating and before restarting the session:

rm -f ~/.claude/mcp-needs-auth-cache.json

Environment

• Claude Code v2.1.108
• @agentclientprotocol/claude-agent-acp v0.27.0
• @anthropic-ai/claude-agent-sdk v0.2.104
• macOS (Keychain-based credential storage)

What Should Happen?

after successfully authenticated via/mcp in claude-code, SDK based applications reads the refreshed token from the Keychain and connects successfully.

Error Messages/Logs

Steps to Reproduce

1. Start a Claude Code session via claude-agent-acp (or any SDK consumer) with claudeai-proxy MCP servers (e.g. GitHub)
2. Let the OAuth token expire — servers are marked needs-auth and cached in mcp-needs-auth-cache.json
3. Authenticate in a separate terminal Claude Code session via /mcp
4. Restart the SDK-based session within 15 minutes

Claude Model

None

Is this a regression?

No, this never worked

Last Working Version

_No response_

Claude Code Version

v2.1.108

Platform

Anthropic API

Operating System

macOS

Terminal/Shell

Terminal.app (macOS)

Additional Information

_No response_