fix: only retry 403 responses for insufficient_scope error

Move retry logic inside the insufficient_scope branch so that 403
responses with other errors (e.g. invalid_token, access_denied) raise
OAuthFlowError immediately instead of making a doomed retry with the
same token.

Fixes #1602

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: Varun Sharma

src/mcp/client/auth/oauth2.py

@@ -612,12 +612,12 @@ async def async_auth_flow(self, request: httpx.Request) -> AsyncGenerator[httpx.
                 # Retry with new tokens
                 self._add_auth_header(request)
                 yield request
-            elif response.status_code == 403:
+            elif response.status_code == 403:  # pragma: no branch
                 # Step 1: Extract error field from WWW-Authenticate header
                 error = extract_field_from_www_auth(response, "error")
 
                 # Step 2: Check if we need to step-up authorization
-                if error == "insufficient_scope":  # pragma: no branch
+                if error == "insufficient_scope":
                     try:
                         # Step 2a: Update the required scopes
                         self.context.client_metadata.scope = get_client_metadata_scopes(
@@ -631,6 +631,8 @@ async def async_auth_flow(self, request: httpx.Request) -> AsyncGenerator[httpx.
                         logger.exception("OAuth flow error")
                         raise
 
-                # Retry with new tokens
-                self._add_auth_header(request)
-                yield request
+                    # Retry with new tokens
+                    self._add_auth_header(request)
+                    yield request
+                else:
+                    raise OAuthFlowError(f"Access forbidden: {error or 'insufficient permissions'}")

tests/client/test_auth.py

@@ -1410,6 +1410,52 @@ async def mock_callback() -> tuple[str, str | None]:
         except StopAsyncIteration:
             pass  # Expected
 
+    @pytest.mark.anyio
+    @pytest.mark.parametrize(
+        ("www_authenticate", "expected_error_substring"),
+        [
+            ('Bearer error="invalid_token"', "invalid_token"),
+            ("Bearer", "insufficient permissions"),
+            ('Bearer error="access_denied"', "access_denied"),
+        ],
+    )
+    async def test_403_non_insufficient_scope_raises_error(
+        self,
+        oauth_provider: OAuthClientProvider,
+        mock_storage: MockTokenStorage,
+        valid_tokens: OAuthToken,
+        www_authenticate: str,
+        expected_error_substring: str,
+    ):
+        """Test that 403 without insufficient_scope raises OAuthFlowError instead of retrying."""
+        client_info = OAuthClientInformationFull(
+            client_id="test_client_id",
+            client_secret="test_client_secret",
+            redirect_uris=[AnyUrl("http://localhost:3030/callback")],
+        )
+        await mock_storage.set_tokens(valid_tokens)
+        await mock_storage.set_client_info(client_info)
+        oauth_provider.context.current_tokens = valid_tokens
+        oauth_provider.context.token_expiry_time = time.time() + 1800
+        oauth_provider.context.client_info = client_info
+        oauth_provider._initialized = True
+
+        test_request = httpx.Request("GET", "https://api.example.com/mcp")
+        auth_flow = oauth_provider.async_auth_flow(test_request)
+
+        # First request with auth header
+        request = await auth_flow.__anext__()
+
+        # Send 403 with non-insufficient_scope error
+        response_403 = httpx.Response(
+            403,
+            headers={"WWW-Authenticate": www_authenticate},
+            request=request,
+        )
+
+        with pytest.raises(OAuthFlowError, match=expected_error_substring):
+            await auth_flow.asend(response_403)
+
 
 @pytest.mark.parametrize(
     (