OAuth: 403 responses without insufficient_scope incorrectly retry with same token

Summary

The OAuth client unconditionally retries all 403 responses, even when the error is not insufficient_scope. This causes an unnecessary retry attempt with the same token that will fail for the same reason.

Location

src/mcp/client/auth/oauth2.py, lines 662-681

The Bug

elif response.status_code == 403:
    error = self._extract_field_from_www_auth(response, "error")
    
    # Only performs step-up if error == "insufficient_scope"
    if error == "insufficient_scope":
        self._select_scopes(response)
        token_response = yield await self._perform_authorization()
        await self._handle_token_response(token_response)
    
    # BUG: Retries unconditionally, even when no new tokens were obtained
    self._add_auth_header(request)
    yield request

Lines 679-681 execute regardless of whether step-up authorization occurred, causing a retry with the same credentials.

Expected vs Actual Behavior

Impact

• Wasted network round-trip: Client makes doomed retry request that will fail for the same reason
• Poor error feedback: Delays error reporting by one request cycle
• Spec non-compliance: MCP Authorization Spec implies retry only for insufficient_scope
• Resource waste: Unnecessary load on server and client

Fix

Move the retry logic inside the if error == "insufficient_scope": block and raise an error otherwise:

elif response.status_code == 403:
    error = self._extract_field_from_www_auth(response, "error")
    
    if error == "insufficient_scope":
        try:
            self._select_scopes(response)
            token_response = yield await self._perform_authorization()
            await self._handle_token_response(token_response)
            
            # Retry with new tokens
            self._add_auth_header(request)
            yield request
        except Exception:
            logger.exception("OAuth flow error")
            raise
    else:
        # Permanent authorization failure - cannot be resolved by retry
        raise OAuthFlowError(
            f"Access forbidden: {error or 'insufficient permissions'}"
        )

References

• RFC 6750 Section 3.1 - Defines insufficient_scope as the only 403 error code
• MCP Authorization Spec - Scope challenge handling

Authored by Claude, reviewed by @maxisbey

Leggi src/mcp/client/auth/oauth2.py intorno alle righe 662-681, concentrandoti su come vengono gestite le risposte 403 dopo l’estrazione del campo error. Conferma il comportamento per insufficient_scope, un altro errore e l’assenza del campo error; il lavoro è completato quando solo il percorso scope-challenge riprova e le altre risposte 403 sollevano immediatamente un’eccezione.