What
- MCP auth failures are now classified into two distinct kinds:
credential_rejected(a flat, generic rejection) and a newstep_up, which covers a 403 "insufficient_scope" response. This classification is handled by a new shared function/classifier instead of duplicated inline checks. - When an MCP tool call gets a 403 insufficient-scope error, Claude Code now surfaces a specific message asking you to re-authenticate for the additional permissions needed, rather than treating it like a generic expired or rejected credential.
- Whether a step-up is pending is tracked per MCP client connection (via
pendingStepUpScope), and this pending state is now properly cleared: when a fresh 401 (not 403) response is seen, when the underlying credential itself disappears (for example, "no token data found" or "token expired without refresh token"), and it's now only checked/set when the original request actually carried an Authorization header. - The auth-challenge interceptor now also ignores responses to requests that had no Authorization header at all, and parses the
WWW-Authenticateheader's scope through a shared helper instead of inline regular expressions.
Why Previously, an MCP server asking for additional OAuth permissions looked the same as a fully rejected or expired credential, so Claude Code could only tell you to "re-authenticate" without saying why. Now it can tell you specifically that more permissions (scope) are needed, and correctly resets that state once you've re-authenticated or the credential changes.