OAuth: 403 responses without insufficient_scope incorrectly retry with same token

Đọc src/mcp/client/auth/oauth2.py quanh các dòng 662-681, tập trung vào cách các phản hồi 403 được xử lý sau khi trường error được trích xuất. Xác nhận hành vi đối với insufficient_scope, một lỗi khác và không có trường error; hoàn tất khi chỉ có đường dẫn scope-challenge thử lại còn các phản hồi 403 khác lập tức ném ra một exception.

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