OAuth: 403 responses without insufficient_scope incorrectly retry with same token

[maxisbey]

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

Scenario	Expected	Actual
403 with insufficient_scope	Get new tokens → retry	✅ Correct
403 with different error (e.g., invalid_token)	Raise error immediately	❌ Retries once with same token, then fails
403 with no error field	Raise error immediately	❌ Retries once with same token, then fails

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