From 409d12b7a5e3abf88d726621562fc6f591f78c11 Mon Sep 17 00:00:00 2001
From: yuneng-jiang <yuneng.jiang@gmail.com>
Date: Mon, 9 Feb 2026 14:40:51 -0800
Subject: [PATCH 1/6] Add alert about email notifications

---
 .../src/components/CreateUserButton.test.tsx  | 297 ++++++++++++++++++
 ...e_user_button.tsx => CreateUserButton.tsx} | 141 +++++----
 .../components/create_user_button.test.tsx    |  35 ---
 .../organisms/create_key_button.tsx           |   4 +-
 .../src/components/view_users.tsx             |   4 +-
 5 files changed, 373 insertions(+), 108 deletions(-)
 create mode 100644 ui/litellm-dashboard/src/components/CreateUserButton.test.tsx
 rename ui/litellm-dashboard/src/components/{create_user_button.tsx => CreateUserButton.tsx} (81%)
 delete mode 100644 ui/litellm-dashboard/src/components/create_user_button.test.tsx

diff --git a/ui/litellm-dashboard/src/components/CreateUserButton.test.tsx b/ui/litellm-dashboard/src/components/CreateUserButton.test.tsx
new file mode 100644
index 00000000000..bfaddacc319
--- /dev/null
+++ b/ui/litellm-dashboard/src/components/CreateUserButton.test.tsx
@@ -0,0 +1,297 @@
+import { render, screen, waitFor, within } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { CreateUserButton } from "./CreateUserButton";
+import * as networking from "./networking";
+import NotificationsManager from "./molecules/notifications_manager";
+
+vi.mock("./networking", () => ({
+  userCreateCall: vi.fn(),
+  modelAvailableCall: vi.fn().mockResolvedValue({ data: [] }),
+  invitationCreateCall: vi.fn(),
+  getProxyUISettings: vi.fn().mockResolvedValue({
+    PROXY_BASE_URL: null,
+    PROXY_LOGOUT_URL: null,
+    DEFAULT_TEAM_DISABLED: false,
+    SSO_ENABLED: false,
+  }),
+  getProxyBaseUrl: vi.fn().mockReturnValue("http://localhost"),
+}));
+
+vi.mock("./bulk_create_users_button", () => ({
+  default: () => <div data-testid="bulk-create-users">Bulk Create Users</div>,
+}));
+
+const mockUserCreateCall = vi.mocked(networking.userCreateCall);
+const mockInvitationCreateCall = vi.mocked(networking.invitationCreateCall);
+const mockGetProxyUISettings = vi.mocked(networking.getProxyUISettings);
+const mockNotificationsManager = vi.mocked(NotificationsManager);
+
+const createQueryClient = () =>
+  new QueryClient({
+    defaultOptions: { queries: { retry: false, gcTime: 0 } },
+  });
+
+const defaultProps = {
+  userID: "123",
+  accessToken: "token",
+  teams: [],
+  possibleUIRoles: null as Record<string, Record<string, string>> | null,
+};
+
+function renderWithProviders(ui: React.ReactElement) {
+  const qc = createQueryClient();
+  return render(<QueryClientProvider client={qc}>{ui}</QueryClientProvider>);
+}
+
+describe("CreateUserButton", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockGetProxyUISettings.mockResolvedValue({
+      PROXY_BASE_URL: null,
+      PROXY_LOGOUT_URL: null,
+      DEFAULT_TEAM_DISABLED: false,
+      SSO_ENABLED: false,
+    });
+  });
+
+  it("should render the create user form when embedded", () => {
+    renderWithProviders(
+      <CreateUserButton {...defaultProps} isEmbedded />,
+    );
+    expect(screen.getByRole("button", { name: /create user/i })).toBeInTheDocument();
+  });
+
+  it("should render the invite user button when not embedded", async () => {
+    renderWithProviders(<CreateUserButton {...defaultProps} />);
+    await waitFor(() => {
+      expect(screen.getByRole("button", { name: /\+ invite user/i })).toBeInTheDocument();
+    });
+  });
+
+  it("should open the invite modal when invite user button is clicked", async () => {
+    const user = userEvent.setup();
+    renderWithProviders(<CreateUserButton {...defaultProps} />);
+    await waitFor(() => {
+      expect(screen.getByRole("button", { name: /\+ invite user/i })).toBeInTheDocument();
+    });
+    await user.click(screen.getByRole("button", { name: /\+ invite user/i }));
+    const dialog = screen.getByRole("dialog", { name: /invite user/i });
+    expect(dialog).toBeInTheDocument();
+    expect(within(dialog).getByRole("button", { name: /invite user/i })).toBeInTheDocument();
+  });
+
+  it("should display email invitations info message in embedded mode", () => {
+    renderWithProviders(<CreateUserButton {...defaultProps} isEmbedded />);
+    expect(screen.getByText("Email invitations")).toBeInTheDocument();
+  });
+
+  it("should display user role options when possibleUIRoles is provided", async () => {
+    const possibleUIRoles = {
+      proxy_admin: { ui_label: "Admin", description: "Full access" },
+      proxy_user: { ui_label: "User", description: "Limited access" },
+    };
+    renderWithProviders(
+      <CreateUserButton {...defaultProps} possibleUIRoles={possibleUIRoles} isEmbedded />,
+    );
+    await userEvent.click(screen.getByRole("combobox", { name: /user role/i }));
+    expect(screen.getByText("Admin")).toBeInTheDocument();
+    expect(screen.getByText("User")).toBeInTheDocument();
+  });
+
+  it("should call userCreateCall when form is submitted in embedded mode", async () => {
+    const user = userEvent.setup();
+    mockUserCreateCall.mockResolvedValue({ data: { user_id: "new-user-123" } });
+    mockInvitationCreateCall.mockResolvedValue({
+      id: "inv-1",
+      user_id: "new-user-123",
+      has_user_setup_sso: false,
+    } as any);
+
+    renderWithProviders(
+      <CreateUserButton {...defaultProps} possibleUIRoles={{ proxy_user: { ui_label: "User", description: "" } }} isEmbedded />,
+    );
+
+    await user.type(screen.getByLabelText(/user email/i), "test@example.com");
+    await user.click(screen.getByRole("combobox", { name: /user role/i }));
+    await user.click(screen.getByText("User"));
+    await user.click(screen.getByRole("button", { name: /create user/i }));
+
+    await waitFor(() => {
+      expect(mockUserCreateCall).toHaveBeenCalledWith("token", null, expect.objectContaining({
+        user_email: "test@example.com",
+        user_role: "proxy_user",
+      }));
+    });
+  });
+
+  it("should call onUserCreated callback when user is created in embedded mode", async () => {
+    const user = userEvent.setup();
+    const onUserCreated = vi.fn();
+    mockUserCreateCall.mockResolvedValue({ data: { user_id: "new-user-456" } });
+
+    renderWithProviders(
+      <CreateUserButton {...defaultProps} onUserCreated={onUserCreated} possibleUIRoles={{ proxy_user: { ui_label: "User", description: "" } }} isEmbedded />,
+    );
+
+    await user.type(screen.getByLabelText(/user email/i), "embedded@example.com");
+    await user.click(screen.getByRole("combobox", { name: /user role/i }));
+    await user.click(screen.getByText("User"));
+    await user.click(screen.getByRole("button", { name: /create user/i }));
+
+    await waitFor(() => {
+      expect(onUserCreated).toHaveBeenCalledWith("new-user-456");
+    });
+  });
+
+  it("should show success notification when user is created successfully in standalone mode", async () => {
+    const user = userEvent.setup();
+    mockUserCreateCall.mockResolvedValue({ data: { user_id: "new-user-789" } });
+    mockInvitationCreateCall.mockResolvedValue({
+      id: "inv-2",
+      user_id: "new-user-789",
+      has_user_setup_sso: false,
+    } as any);
+
+    renderWithProviders(
+      <CreateUserButton {...defaultProps} possibleUIRoles={{ proxy_user: { ui_label: "User", description: "" } }} />,
+    );
+
+    await waitFor(() => {
+      expect(screen.getByRole("button", { name: /\+ invite user/i })).toBeInTheDocument();
+    });
+    await user.click(screen.getByRole("button", { name: /\+ invite user/i }));
+
+    const dialog = screen.getByRole("dialog", { name: /invite user/i });
+    await user.type(within(dialog).getByLabelText(/user email/i), "standalone@example.com");
+    await user.click(within(dialog).getByRole("combobox", { name: /global proxy role/i }));
+    await user.click(screen.getByText("User"));
+    await user.click(within(dialog).getByRole("button", { name: /invite user/i }));
+
+    await waitFor(() => {
+      expect(mockNotificationsManager.success).toHaveBeenCalledWith("API user Created");
+    });
+  });
+
+  it("should show error notification when user creation fails", async () => {
+    const user = userEvent.setup();
+    mockUserCreateCall.mockRejectedValue({ response: { data: { detail: "Email already exists" } } });
+
+    renderWithProviders(
+      <CreateUserButton {...defaultProps} possibleUIRoles={{ proxy_user: { ui_label: "User", description: "" } }} isEmbedded />,
+    );
+
+    await user.type(screen.getByLabelText(/user email/i), "duplicate@example.com");
+    await user.click(screen.getByRole("combobox", { name: /user role/i }));
+    await user.click(screen.getByText("User"));
+    await user.click(screen.getByRole("button", { name: /create user/i }));
+
+    await waitFor(() => {
+      expect(mockNotificationsManager.fromBackend).toHaveBeenCalledWith("Email already exists");
+    });
+  });
+
+  it("should show info notification when making API call", async () => {
+    const user = userEvent.setup();
+    mockUserCreateCall.mockResolvedValue({ data: { user_id: "new-user" } });
+    mockInvitationCreateCall.mockResolvedValue({
+      id: "inv-3",
+      user_id: "new-user",
+      has_user_setup_sso: false,
+    } as any);
+
+    renderWithProviders(
+      <CreateUserButton {...defaultProps} possibleUIRoles={{ proxy_user: { ui_label: "User", description: "" } }} isEmbedded />,
+    );
+
+    await user.type(screen.getByLabelText(/user email/i), "info@example.com");
+    await user.click(screen.getByRole("combobox", { name: /user role/i }));
+    await user.click(screen.getByText("User"));
+    await user.click(screen.getByRole("button", { name: /create user/i }));
+
+    await waitFor(() => {
+      expect(mockNotificationsManager.info).toHaveBeenCalledWith("Making API Call");
+    });
+  });
+
+  it("should close modal when cancel is clicked in standalone mode", async () => {
+    const user = userEvent.setup();
+    renderWithProviders(<CreateUserButton {...defaultProps} />);
+
+    await waitFor(() => {
+      expect(screen.getByRole("button", { name: /\+ invite user/i })).toBeInTheDocument();
+    });
+    await user.click(screen.getByRole("button", { name: /\+ invite user/i }));
+    expect(screen.getByRole("dialog", { name: /invite user/i })).toBeInTheDocument();
+
+    const dialog = screen.getByRole("dialog", { name: /invite user/i });
+    await user.click(within(dialog).getByRole("button", { name: /close/i }));
+    expect(screen.queryByRole("dialog")).not.toBeInTheDocument();
+  });
+
+  it("should show onboarding modal when user is created and SSO is disabled", async () => {
+    const user = userEvent.setup();
+    mockUserCreateCall.mockResolvedValue({ data: { user_id: "sso-user" } });
+    mockInvitationCreateCall.mockResolvedValue({
+      id: "inv-sso",
+      user_id: "sso-user",
+      has_user_setup_sso: false,
+    } as any);
+
+    renderWithProviders(
+      <CreateUserButton {...defaultProps} possibleUIRoles={{ proxy_user: { ui_label: "User", description: "" } }} />,
+    );
+
+    await waitFor(() => {
+      expect(screen.getByRole("button", { name: /\+ invite user/i })).toBeInTheDocument();
+    });
+    await user.click(screen.getByRole("button", { name: /\+ invite user/i }));
+
+    const dialog = screen.getByRole("dialog", { name: /invite user/i });
+    await user.type(within(dialog).getByLabelText(/user email/i), "sso@example.com");
+    await user.click(within(dialog).getByRole("combobox", { name: /global proxy role/i }));
+    await user.click(screen.getByText("User"));
+    await user.click(within(dialog).getByRole("button", { name: /invite user/i }));
+
+    await waitFor(() => {
+      expect(mockInvitationCreateCall).toHaveBeenCalledWith("token", "sso-user");
+    });
+    await waitFor(() => {
+      expect(mockNotificationsManager.success).toHaveBeenCalledWith("API user Created");
+    });
+  });
+
+  it("should use SSO flow without invitationCreateCall when SSO is enabled", async () => {
+    const user = userEvent.setup();
+    mockUserCreateCall.mockResolvedValue({ data: { user_id: "sso-enabled-user" } });
+    mockGetProxyUISettings.mockResolvedValue({
+      PROXY_BASE_URL: "http://localhost",
+      PROXY_LOGOUT_URL: null,
+      DEFAULT_TEAM_DISABLED: false,
+      SSO_ENABLED: true,
+    });
+
+    renderWithProviders(
+      <CreateUserButton {...defaultProps} possibleUIRoles={{ proxy_user: { ui_label: "User", description: "" } }} />,
+    );
+
+    await waitFor(() => {
+      expect(screen.getByRole("button", { name: /\+ invite user/i })).toBeInTheDocument();
+    });
+    await user.click(screen.getByRole("button", { name: /\+ invite user/i }));
+
+    const dialog = screen.getByRole("dialog", { name: /invite user/i });
+    await user.type(within(dialog).getByLabelText(/user email/i), "sso-enabled@example.com");
+    await user.click(within(dialog).getByRole("combobox", { name: /global proxy role/i }));
+    await user.click(screen.getByText("User"));
+    await user.click(within(dialog).getByRole("button", { name: /invite user/i }));
+
+    await waitFor(() => {
+      expect(mockInvitationCreateCall).not.toHaveBeenCalled();
+    });
+    await waitFor(() => {
+      expect(mockNotificationsManager.success).toHaveBeenCalledWith("API user Created");
+    });
+  });
+});
diff --git a/ui/litellm-dashboard/src/components/create_user_button.tsx b/ui/litellm-dashboard/src/components/CreateUserButton.tsx
similarity index 81%
rename from ui/litellm-dashboard/src/components/create_user_button.tsx
rename to ui/litellm-dashboard/src/components/CreateUserButton.tsx
index da155b042a3..3a15fbd5055 100644
--- a/ui/litellm-dashboard/src/components/create_user_button.tsx
+++ b/ui/litellm-dashboard/src/components/CreateUserButton.tsx
@@ -1,33 +1,29 @@
-import React, { useState, useEffect } from "react";
-import { Button, Modal, Form, Input, Select, Select as Select2 } from "antd";
-import {
-  Button as Button2,
-  Text,
-  TextInput,
-  SelectItem,
-  Accordion,
-  AccordionHeader,
-  AccordionBody,
-  Title,
-} from "@tremor/react";
-import OnboardingModal from "./onboarding_link";
-import { InvitationLink } from "./onboarding_link";
-import {
-  userCreateCall,
-  modelAvailableCall,
-  invitationCreateCall,
-  getProxyUISettings,
-  getProxyBaseUrl,
-} from "./networking";
-import BulkCreateUsers from "./bulk_create_users_button";
-const { Option } = Select;
-import { Tooltip } from "antd";
-import { InfoCircleOutlined } from "@ant-design/icons";
-import { getModelDisplayName } from "./key_team_helpers/fetch_available_models_team_key";
+import { InfoCircleOutlined, UserAddOutlined } from "@ant-design/icons";
 import { useQueryClient } from "@tanstack/react-query";
-import NotificationsManager from "./molecules/notifications_manager";
+import {
+  Accordion,
+  AccordionBody,
+  AccordionHeader,
+  Button as Button2,
+  SelectItem,
+  TextInput,
+} from "@tremor/react";
+import { Alert, Button, Form, Input, Modal, Select, Select as Select2, Space, Tooltip, Typography } from "antd";
+import React, { useEffect, useState } from "react";
+import BulkCreateUsers from "./bulk_create_users_button";
 import TeamDropdown from "./common_components/team_dropdown";
-
+import { getModelDisplayName } from "./key_team_helpers/fetch_available_models_team_key";
+import NotificationsManager from "./molecules/notifications_manager";
+import {
+  getProxyBaseUrl,
+  getProxyUISettings,
+  invitationCreateCall,
+  modelAvailableCall,
+  userCreateCall,
+} from "./networking";
+import OnboardingModal, { InvitationLink } from "./onboarding_link";
+const { Option } = Select;
+const { Text, Link, Title } = Typography;
 // Helper function to generate UUID compatible across all environments
 const generateUUID = (): string => {
   if (typeof crypto !== "undefined" && crypto.randomUUID) {
@@ -58,14 +54,8 @@ interface UISettings {
   SSO_ENABLED: boolean;
 }
 
-const Createuser: React.FC<CreateuserProps> = ({
-  userID,
-  accessToken,
-  teams,
-  possibleUIRoles,
-  onUserCreated,
-  isEmbedded = false,
-}) => {
+export const CreateUserButton: React.FC<CreateuserProps> = ({
+  userID, accessToken, teams, possibleUIRoles, onUserCreated, isEmbedded = false }) => {
   const queryClient = useQueryClient();
   const [uiSettings, setUISettings] = useState<UISettings | null>(null);
   const [form] = Form.useForm();
@@ -75,28 +65,18 @@ const Createuser: React.FC<CreateuserProps> = ({
   const [isInvitationLinkModalVisible, setIsInvitationLinkModalVisible] = useState(false);
   const [invitationLinkData, setInvitationLinkData] = useState<InvitationLink | null>(null);
   const [baseUrl, setBaseUrl] = useState<string | null>(null);
-  // get all models
   useEffect(() => {
     const fetchData = async () => {
       try {
-        const userRole = "any"; // You may need to get the user role dynamically
+        const userRole = "any";
         const modelDataResponse = await modelAvailableCall(accessToken, userID, userRole);
-        // Assuming modelDataResponse.data contains an array of model objects with a 'model_name' property
         const availableModels = [];
         for (let i = 0; i < modelDataResponse.data.length; i++) {
           const model = modelDataResponse.data[i];
           availableModels.push(model.id);
         }
-        console.log("Model data response:", modelDataResponse.data);
-        console.log("Available models:", availableModels);
-
-        // Assuming modelDataResponse.data contains an array of model names
         setUserModels(availableModels);
-
-        // get ui settings
         const uiSettingsResponse = await getProxyUISettings(accessToken);
-        console.log("uiSettingsResponse:", uiSettingsResponse);
-
         setUISettings(uiSettingsResponse);
       } catch (error) {
         console.error("Error fetching model data:", error);
@@ -104,9 +84,8 @@ const Createuser: React.FC<CreateuserProps> = ({
     };
 
     setBaseUrl(getProxyBaseUrl());
-
-    fetchData(); // Call the function to fetch model data when the component mounts
-  }, []); // Empty dependency array to run only once
+    fetchData();
+  }, []);
 
   const handleOk = () => {
     setIsModalVisible(false);
@@ -126,25 +105,19 @@ const Createuser: React.FC<CreateuserProps> = ({
         setIsModalVisible(true);
       }
       if ((!formValues.models || formValues.models.length === 0) && formValues.user_role !== "proxy_admin") {
-        console.log("formValues.user_role", formValues.user_role);
-        // If models is empty or undefined, set it to "no-default-models"
         formValues.models = ["no-default-models"];
       }
-      console.log("formValues in create user:", formValues);
       const response = await userCreateCall(accessToken, null, formValues);
       await queryClient.invalidateQueries({ queryKey: ["userList"] });
-      console.log("user create Response:", response);
       setApiuser(true);
       const user_id = response.data?.user_id || response.user_id;
 
-      // Call the callback if provided (for embedded mode)
       if (onUserCreated && isEmbedded) {
         onUserCreated(user_id);
         form.resetFields();
-        return; // Skip the invitation flow when embedded
+        return;
       }
 
-      // only do invite link flow if sso is not enabled
       if (!uiSettings?.SSO_ENABLED) {
         invitationCreateCall(accessToken, user_id).then((data) => {
           data.has_user_setup_sso = false;
@@ -184,6 +157,21 @@ const Createuser: React.FC<CreateuserProps> = ({
   if (isEmbedded) {
     return (
       <Form form={form} onFinish={handleCreate} labelCol={{ span: 8 }} wrapperCol={{ span: 16 }} labelAlign="left">
+        <Alert
+          message="Email invitations"
+          description={
+            <>
+              New users receive an email invite only when an email integration (SMTP, Resend, or SendGrid) is configured.
+              {" "}
+              <Link href="https://docs.litellm.ai/docs/proxy/email" target="_blank">
+                Learn how to set up email notifications
+              </Link>
+            </>
+          }
+          type="info"
+          showIcon
+          className="mb-4"
+        />
         <Form.Item label="User Email" name="user_email">
           <TextInput placeholder="" />
         </Form.Item>
@@ -194,9 +182,9 @@ const Createuser: React.FC<CreateuserProps> = ({
                 <SelectItem key={role} value={role} title={ui_label}>
                   <div className="flex">
                     {ui_label}{" "}
-                    <p className="ml-2" style={{ color: "gray", fontSize: "12px" }}>
+                    <Text className="ml-2" style={{ color: "gray", fontSize: "12px" }}>
                       {description}
-                    </p>
+                    </Text>
                   </div>
                 </SelectItem>
               ))}
@@ -234,16 +222,33 @@ const Createuser: React.FC<CreateuserProps> = ({
         onOk={handleOk}
         onCancel={handleCancel}
       >
-        <Text className="mb-1">Create a User who can own keys</Text>
+        <Space direction="vertical" size="middle">
+          <Text className="mb-1">Create a User who can own keys</Text>
+          <Alert
+            message="Email invitations"
+            description={
+              <>
+                New users receive an email invite only when an email integration (SMTP, Resend, or SendGrid) is configured.
+                {" "}
+                <Link href="https://docs.litellm.ai/docs/proxy/email" target="_blank">
+                  Learn how to set up email notifications
+                </Link>
+              </>
+            }
+            type="info"
+            showIcon
+            className="mb-4"
+          />
+        </Space>
         <Form form={form} onFinish={handleCreate} labelCol={{ span: 8 }} wrapperCol={{ span: 16 }} labelAlign="left">
           <Form.Item label="User Email" name="user_email">
-            <TextInput placeholder="" />
+            <Input />
           </Form.Item>
           <Form.Item
             label={
               <span>
                 Global Proxy Role{" "}
-                <Tooltip title="This is the role that the user will globally on the proxy. This role is independent of any team/org specific roles.">
+                <Tooltip title="This role is independent of any team/org specific roles. Configure Team / Organization Admins in the Settings">
                   <InfoCircleOutlined />
                 </Tooltip>
               </span>
@@ -256,9 +261,9 @@ const Createuser: React.FC<CreateuserProps> = ({
                   <SelectItem key={role} value={role} title={ui_label}>
                     <div className="flex">
                       {ui_label}{" "}
-                      <p className="ml-2" style={{ color: "gray", fontSize: "12px" }}>
+                      <Text className="ml-2" style={{ color: "gray", fontSize: "12px" }}>
                         {description}
-                      </p>
+                      </Text>
                     </div>
                   </SelectItem>
                 ))}
@@ -279,7 +284,7 @@ const Createuser: React.FC<CreateuserProps> = ({
           </Form.Item>
           <Accordion>
             <AccordionHeader>
-              <Title>Personal Key Creation</Title>
+              <Text strong>Personal Key Creation</Text>
             </AccordionHeader>
             <AccordionBody>
               <Form.Item
@@ -312,7 +317,7 @@ const Createuser: React.FC<CreateuserProps> = ({
             </AccordionBody>
           </Accordion>
           <div style={{ textAlign: "right", marginTop: "10px" }}>
-            <Button htmlType="submit">Create User</Button>
+            <Button type="primary" icon={<UserAddOutlined />} htmlType="submit">Invite User</Button>
           </div>
         </Form>
       </Modal>
@@ -326,6 +331,4 @@ const Createuser: React.FC<CreateuserProps> = ({
       )}
     </div>
   );
-};
-
-export default Createuser;
+};
\ No newline at end of file
diff --git a/ui/litellm-dashboard/src/components/create_user_button.test.tsx b/ui/litellm-dashboard/src/components/create_user_button.test.tsx
deleted file mode 100644
index e40a1e0ac3c..00000000000
--- a/ui/litellm-dashboard/src/components/create_user_button.test.tsx
+++ /dev/null
@@ -1,35 +0,0 @@
-import React from "react";
-import { render } from "@testing-library/react";
-import { describe, it, expect, vi } from "vitest";
-import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
-import Createuser from "./create_user_button";
-
-vi.mock("./networking", () => ({
-  userCreateCall: vi.fn(),
-  modelAvailableCall: vi.fn().mockResolvedValue({ data: [] }),
-  invitationCreateCall: vi.fn(),
-  getProxyUISettings: vi.fn().mockResolvedValue({
-    PROXY_BASE_URL: null,
-    PROXY_LOGOUT_URL: null,
-    DEFAULT_TEAM_DISABLED: false,
-    SSO_ENABLED: false,
-  }),
-  getProxyBaseUrl: vi.fn().mockReturnValue("http://localhost"),
-}));
-
-const createQueryClient = () =>
-  new QueryClient({
-    defaultOptions: { queries: { retry: false, gcTime: 0 } },
-  });
-
-describe("Create User Button", () => {
-  it("should render the create user button", () => {
-    const qc = createQueryClient();
-    const { getByText } = render(
-      <QueryClientProvider client={qc}>
-        <Createuser userID="123" accessToken="123" teams={[]} possibleUIRoles={{}} isEmbedded />
-      </QueryClientProvider>,
-    );
-    expect(getByText("Create User")).toBeInTheDocument();
-  });
-});
diff --git a/ui/litellm-dashboard/src/components/organisms/create_key_button.tsx b/ui/litellm-dashboard/src/components/organisms/create_key_button.tsx
index 80037280b63..abadbe10590 100644
--- a/ui/litellm-dashboard/src/components/organisms/create_key_button.tsx
+++ b/ui/litellm-dashboard/src/components/organisms/create_key_button.tsx
@@ -21,7 +21,7 @@ import PremiumLoggingSettings from "../common_components/PremiumLoggingSettings"
 import RateLimitTypeFormItem from "../common_components/RateLimitTypeFormItem";
 import RouterSettingsAccordion, { RouterSettingsAccordionValue } from "../common_components/RouterSettingsAccordion";
 import TeamDropdown from "../common_components/team_dropdown";
-import Createuser from "../create_user_button";
+import { CreateUserButton } from "../CreateUserButton";
 import { getModelDisplayName } from "../key_team_helpers/fetch_available_models_team_key";
 import { Team } from "../key_team_helpers/key_list";
 import MCPServerSelector from "../mcp_server_management/MCPServerSelector";
@@ -1347,7 +1347,7 @@ const CreateKey: React.FC<CreateKeyProps> = ({ team, teams, data, addKey }) => {
           footer={null}
           width={800}
         >
-          <Createuser
+          <CreateUserButton
             userID={userID}
             accessToken={accessToken}
             teams={teams}
diff --git a/ui/litellm-dashboard/src/components/view_users.tsx b/ui/litellm-dashboard/src/components/view_users.tsx
index 8a09c6d1f97..576a1a84be3 100644
--- a/ui/litellm-dashboard/src/components/view_users.tsx
+++ b/ui/litellm-dashboard/src/components/view_users.tsx
@@ -3,7 +3,7 @@ import React, { useEffect, useState } from "react";
 
 import { Button } from "@tremor/react";
 import BulkEditUserModal from "./BulkEditUsers";
-import CreateUser from "./create_user_button";
+import { CreateUserButton } from "./CreateUserButton";
 import EditUserModal from "./edit_user";
 import {
   getPossibleUserRoles,
@@ -301,7 +301,7 @@ const ViewUserDashboard: React.FC<ViewUserDashboardProps> = ({ accessToken, toke
             </>
           ) : userID && accessToken ? (
             <>
-              <CreateUser userID={userID} accessToken={accessToken} teams={teams} possibleUIRoles={possibleUIRoles} />
+              <CreateUserButton userID={userID} accessToken={accessToken} teams={teams} possibleUIRoles={possibleUIRoles} />
 
               <Button
                 onClick={handleToggleSelectionMode}

From cbcbbff604e5d5ef496fdf1ef4b2f5e342e40fb3 Mon Sep 17 00:00:00 2001
From: yuneng-jiang <yuneng.jiang@gmail.com>
Date: Mon, 9 Feb 2026 14:45:08 -0800
Subject: [PATCH 2/6] fixing tests

---
 .../src/components/CreateUserButton.test.tsx  | 33 -------------------
 1 file changed, 33 deletions(-)

diff --git a/ui/litellm-dashboard/src/components/CreateUserButton.test.tsx b/ui/litellm-dashboard/src/components/CreateUserButton.test.tsx
index bfaddacc319..9e5f2eb1444 100644
--- a/ui/litellm-dashboard/src/components/CreateUserButton.test.tsx
+++ b/ui/litellm-dashboard/src/components/CreateUserButton.test.tsx
@@ -261,37 +261,4 @@ describe("CreateUserButton", () => {
       expect(mockNotificationsManager.success).toHaveBeenCalledWith("API user Created");
     });
   });
-
-  it("should use SSO flow without invitationCreateCall when SSO is enabled", async () => {
-    const user = userEvent.setup();
-    mockUserCreateCall.mockResolvedValue({ data: { user_id: "sso-enabled-user" } });
-    mockGetProxyUISettings.mockResolvedValue({
-      PROXY_BASE_URL: "http://localhost",
-      PROXY_LOGOUT_URL: null,
-      DEFAULT_TEAM_DISABLED: false,
-      SSO_ENABLED: true,
-    });
-
-    renderWithProviders(
-      <CreateUserButton {...defaultProps} possibleUIRoles={{ proxy_user: { ui_label: "User", description: "" } }} />,
-    );
-
-    await waitFor(() => {
-      expect(screen.getByRole("button", { name: /\+ invite user/i })).toBeInTheDocument();
-    });
-    await user.click(screen.getByRole("button", { name: /\+ invite user/i }));
-
-    const dialog = screen.getByRole("dialog", { name: /invite user/i });
-    await user.type(within(dialog).getByLabelText(/user email/i), "sso-enabled@example.com");
-    await user.click(within(dialog).getByRole("combobox", { name: /global proxy role/i }));
-    await user.click(screen.getByText("User"));
-    await user.click(within(dialog).getByRole("button", { name: /invite user/i }));
-
-    await waitFor(() => {
-      expect(mockInvitationCreateCall).not.toHaveBeenCalled();
-    });
-    await waitFor(() => {
-      expect(mockNotificationsManager.success).toHaveBeenCalledWith("API user Created");
-    });
-  });
 });

From 145ef7d388c112ebea633cdd94bce7150fb6a425 Mon Sep 17 00:00:00 2001
From: yuneng-jiang <yuneng.jiang@gmail.com>
Date: Mon, 9 Feb 2026 15:02:47 -0800
Subject: [PATCH 3/6] extending timeout for long running tests

---
 ui/litellm-dashboard/src/components/CreateUserButton.test.tsx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/ui/litellm-dashboard/src/components/CreateUserButton.test.tsx b/ui/litellm-dashboard/src/components/CreateUserButton.test.tsx
index 9e5f2eb1444..829b73734dc 100644
--- a/ui/litellm-dashboard/src/components/CreateUserButton.test.tsx
+++ b/ui/litellm-dashboard/src/components/CreateUserButton.test.tsx
@@ -45,7 +45,7 @@ function renderWithProviders(ui: React.ReactElement) {
   return render(<QueryClientProvider client={qc}>{ui}</QueryClientProvider>);
 }
 
-describe("CreateUserButton", () => {
+describe("CreateUserButton", { timeout: 20000 }, () => {
   beforeEach(() => {
     vi.clearAllMocks();
     mockGetProxyUISettings.mockResolvedValue({

From a41a4b41f52a4b21eb29f765c56b75f4d19d4869 Mon Sep 17 00:00:00 2001
From: yuneng-jiang <yuneng.jiang@gmail.com>
Date: Mon, 9 Feb 2026 15:20:39 -0800
Subject: [PATCH 4/6] Text changes

---
 .../src/components/CreateUserButton.tsx              | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/ui/litellm-dashboard/src/components/CreateUserButton.tsx b/ui/litellm-dashboard/src/components/CreateUserButton.tsx
index 3a15fbd5055..d463ced08f6 100644
--- a/ui/litellm-dashboard/src/components/CreateUserButton.tsx
+++ b/ui/litellm-dashboard/src/components/CreateUserButton.tsx
@@ -259,12 +259,12 @@ export const CreateUserButton: React.FC<CreateuserProps> = ({
               {possibleUIRoles &&
                 Object.entries(possibleUIRoles).map(([role, { ui_label, description }]) => (
                   <SelectItem key={role} value={role} title={ui_label}>
-                    <div className="flex">
-                      {ui_label}{" "}
-                      <Text className="ml-2" style={{ color: "gray", fontSize: "12px" }}>
-                        {description}
-                      </Text>
-                    </div>
+                    <Text>
+                      {ui_label}
+                    </Text>
+                    <Text type="secondary">
+                      {" - "}{description}
+                    </Text>
                   </SelectItem>
                 ))}
             </Select2>

From 35eb3030982e17b945e9905c15a88280b3f4ec88 Mon Sep 17 00:00:00 2001
From: michelligabriele <gabriele.michelli@icloud.com>
Date: Tue, 10 Feb 2026 00:48:59 +0100
Subject: [PATCH 5/6] fix(prometheus): sanitize label values to prevent metric
 scrape failures (#20600)

* fix(prometheus): sanitize label values to prevent metric scrape failures

Unicode characters like U+2028 (Line Separator) in Prometheus label values
break the text exposition format, causing scrapers (e.g. Datadog) to fail
parsing the entire /metrics endpoint. One bad label value causes ALL metrics
to be lost, not just the affected metric.

Add _sanitize_prometheus_label_value() and apply it in prometheus_label_factory()
and all direct .labels() call sites.

* fix(prometheus): handle non-string label values in sanitization

Coerce non-string values (int, bool, float) to str before applying
sanitization, preventing AttributeError on .replace() calls.

* fix(prometheus): run sanitization on coerced non-string values

Non-string values should be coerced to str and then sanitized (not
returned early), so their string representations also get cleaned.

* fix(prometheus): widen type hint to Optional[Any] for label value sanitization
---
 litellm/integrations/prometheus.py            | 46 ++++++----
 litellm/types/integrations/prometheus.py      | 34 +++++++-
 .../integrations/test_prometheus_labels.py    | 85 +++++++++++++++++++
 3 files changed, 148 insertions(+), 17 deletions(-)

diff --git a/litellm/integrations/prometheus.py b/litellm/integrations/prometheus.py
index 0a61dab0680..1675201f1f1 100644
--- a/litellm/integrations/prometheus.py
+++ b/litellm/integrations/prometheus.py
@@ -29,7 +29,10 @@ from litellm.proxy._types import (
     UserAPIKeyAuth,
 )
 from litellm.types.integrations.prometheus import *
-from litellm.types.integrations.prometheus import _sanitize_prometheus_label_name
+from litellm.types.integrations.prometheus import (
+    _sanitize_prometheus_label_name,
+    _sanitize_prometheus_label_value,
+)
 from litellm.types.utils import StandardLoggingPayload
 
 if TYPE_CHECKING:
@@ -1276,11 +1279,17 @@ class PrometheusLogger(CustomLogger):
         )
 
         self.litellm_remaining_api_key_requests_for_model.labels(
-            user_api_key, user_api_key_alias, model_group, model_id
+            _sanitize_prometheus_label_value(user_api_key),
+            _sanitize_prometheus_label_value(user_api_key_alias),
+            _sanitize_prometheus_label_value(model_group),
+            _sanitize_prometheus_label_value(model_id),
         ).set(remaining_requests)
 
         self.litellm_remaining_api_key_tokens_for_model.labels(
-            user_api_key, user_api_key_alias, model_group, model_id
+            _sanitize_prometheus_label_value(user_api_key),
+            _sanitize_prometheus_label_value(user_api_key_alias),
+            _sanitize_prometheus_label_value(model_group),
+            _sanitize_prometheus_label_value(model_id),
         ).set(remaining_tokens)
 
     def _set_latency_metrics(
@@ -1401,14 +1410,14 @@ class PrometheusLogger(CustomLogger):
 
         try:
             self.litellm_llm_api_failed_requests_metric.labels(
-                end_user_id,
-                user_api_key,
-                user_api_key_alias,
-                model,
-                user_api_team,
-                user_api_team_alias,
-                user_id,
-                standard_logging_payload.get("model_id", ""),
+                _sanitize_prometheus_label_value(end_user_id),
+                _sanitize_prometheus_label_value(user_api_key),
+                _sanitize_prometheus_label_value(user_api_key_alias),
+                _sanitize_prometheus_label_value(model),
+                _sanitize_prometheus_label_value(user_api_team),
+                _sanitize_prometheus_label_value(user_api_team_alias),
+                _sanitize_prometheus_label_value(user_id),
+                _sanitize_prometheus_label_value(standard_logging_payload.get("model_id", "")),
             ).inc()
             self.set_llm_deployment_failure_metrics(kwargs)
         except Exception as e:
@@ -2354,7 +2363,11 @@ class PrometheusLogger(CustomLogger):
         increment metric when litellm.Router / load balancing logic places a deployment in cool down
         """
         self.litellm_deployment_cooled_down.labels(
-            litellm_model_name, model_id, api_base, api_provider, exception_status
+            _sanitize_prometheus_label_value(litellm_model_name),
+            _sanitize_prometheus_label_value(model_id),
+            _sanitize_prometheus_label_value(api_base),
+            _sanitize_prometheus_label_value(api_provider),
+            _sanitize_prometheus_label_value(exception_status),
         ).inc()
 
     def increment_callback_logging_failure(
@@ -3074,9 +3087,10 @@ def prometheus_label_factory(
     # Extract dictionary from Pydantic object
     enum_dict = enum_values.model_dump()
 
-    # Filter supported labels
+    # Filter supported labels and sanitize values to prevent breaking
+    # the Prometheus text format (e.g. U+2028 Line Separator in label values)
     filtered_labels = {
-        label: value
+        label: _sanitize_prometheus_label_value(value)
         for label, value in enum_dict.items()
         if label in supported_enum_labels
     }
@@ -3094,14 +3108,14 @@ def prometheus_label_factory(
             # check sanitized key
             sanitized_key = _sanitize_prometheus_label_name(key)
             if sanitized_key in supported_enum_labels:
-                filtered_labels[sanitized_key] = value
+                filtered_labels[sanitized_key] = _sanitize_prometheus_label_value(value)
 
     # Add custom tags if configured
     if enum_values.tags is not None:
         custom_tag_labels = get_custom_labels_from_tags(enum_values.tags)
         for key, value in custom_tag_labels.items():
             if key in supported_enum_labels:
-                filtered_labels[key] = value
+                filtered_labels[key] = _sanitize_prometheus_label_value(value)
 
     for label in supported_enum_labels:
         if label not in filtered_labels:
diff --git a/litellm/types/integrations/prometheus.py b/litellm/types/integrations/prometheus.py
index 146c390363b..fd788af9ac1 100644
--- a/litellm/types/integrations/prometheus.py
+++ b/litellm/types/integrations/prometheus.py
@@ -1,7 +1,7 @@
 import re
 from dataclasses import dataclass
 from enum import Enum
-from typing import Dict, List, Literal, Optional, Tuple
+from typing import Any, Dict, List, Literal, Optional, Tuple
 
 from pydantic import BaseModel, Field
 from typing_extensions import Annotated
@@ -41,6 +41,38 @@ def _sanitize_prometheus_label_name(label: str) -> str:
     return sanitized
 
 
+def _sanitize_prometheus_label_value(value: Optional[Any]) -> Optional[str]:
+    """
+    Sanitize a label value for Prometheus text format compatibility.
+
+    Removes or replaces characters that break the Prometheus exposition format:
+    - U+2028 (Line Separator) and U+2029 (Paragraph Separator) are removed
+    - Carriage returns are removed
+    - Newlines are replaced with spaces
+    - Backslashes and double quotes are escaped per Prometheus spec
+    """
+    if value is None:
+        return None
+
+    # Coerce non-string values (int, bool, etc.) to str before sanitizing
+    if not isinstance(value, str):
+        value = str(value)
+
+    # Remove Unicode line/paragraph separators that break text format
+    value = value.replace("\u2028", "").replace("\u2029", "")
+
+    # Remove carriage returns
+    value = value.replace("\r", "")
+
+    # Replace newlines with spaces
+    value = value.replace("\n", " ")
+
+    # Escape backslashes and double quotes per Prometheus exposition format
+    value = value.replace("\\", "\\\\").replace('"', '\\"')
+
+    return value
+
+
 @dataclass
 class MetricValidationError:
     """Error for invalid metric name"""
diff --git a/tests/test_litellm/integrations/test_prometheus_labels.py b/tests/test_litellm/integrations/test_prometheus_labels.py
index 9d4626b88a5..2553eb06271 100644
--- a/tests/test_litellm/integrations/test_prometheus_labels.py
+++ b/tests/test_litellm/integrations/test_prometheus_labels.py
@@ -292,6 +292,87 @@ def test_prometheus_metrics_use_normalized_routes():
     print("✅ Prometheus metrics use normalized routes in labels")
 
 
+def test_prometheus_label_value_sanitization():
+    """
+    Test that Prometheus label values are sanitized to prevent breaking
+    the Prometheus text format.
+
+    Issue: Unicode Line Separator (U+2028) in label values (e.g. from a
+    malformed model name) breaks the Prometheus exposition format, causing
+    scrapers like Datadog to fail parsing the entire /metrics endpoint.
+    """
+    from litellm.integrations.prometheus import (
+        PrometheusLogger,
+        UserAPIKeyLabelValues,
+        prometheus_label_factory,
+    )
+    from unittest.mock import MagicMock
+
+    prometheus_logger = MagicMock()
+    prometheus_logger.get_labels_for_metric = (
+        PrometheusLogger.get_labels_for_metric.__get__(prometheus_logger)
+    )
+
+    # Simulate a model name with U+2028 (Unicode Line Separator) appended
+    # and an api_key_alias with newlines and quotes
+    enum_values = UserAPIKeyLabelValues(
+        requested_model="claude-haiku-4-5-20251001\u2028",
+        api_key_alias='My Key "test"\nwith newline',
+        route="/v1/chat/completions",
+        status_code="400",
+    )
+
+    labels = prometheus_label_factory(
+        supported_enum_labels=prometheus_logger.get_labels_for_metric(
+            metric_name="litellm_proxy_total_requests_metric"
+        ),
+        enum_values=enum_values,
+    )
+
+    # U+2028 must be stripped
+    assert "\u2028" not in labels["requested_model"], (
+        f"U+2028 should be removed from label value, got: {repr(labels['requested_model'])}"
+    )
+    assert labels["requested_model"] == "claude-haiku-4-5-20251001"
+
+    # Newlines must be replaced with spaces, quotes must be escaped
+    assert "\n" not in labels["api_key_alias"]
+    assert labels["api_key_alias"] == 'My Key \\"test\\" with newline'
+
+    print("✅ Prometheus label values are properly sanitized")
+
+
+def test_prometheus_label_value_sanitization_unicode_paragraph_separator():
+    """Test that U+2029 (Paragraph Separator) is also stripped."""
+    from litellm.types.integrations.prometheus import _sanitize_prometheus_label_value
+
+    result = _sanitize_prometheus_label_value("model\u2029name")
+    assert result == "modelname"
+    assert "\u2029" not in result
+
+    print("✅ U+2029 Paragraph Separator is stripped")
+
+
+def test_prometheus_label_value_sanitization_none():
+    """Test that None values pass through unchanged."""
+    from litellm.types.integrations.prometheus import _sanitize_prometheus_label_value
+
+    assert _sanitize_prometheus_label_value(None) is None
+
+    print("✅ None values pass through unchanged")
+
+
+def test_prometheus_label_value_sanitization_non_string_types():
+    """Test that non-string values (int, bool, etc.) are coerced to str."""
+    from litellm.types.integrations.prometheus import _sanitize_prometheus_label_value
+
+    assert _sanitize_prometheus_label_value(200) == "200"
+    assert _sanitize_prometheus_label_value(True) == "True"
+    assert _sanitize_prometheus_label_value(3.14) == "3.14"
+
+    print("✅ Non-string values are coerced to str")
+
+
 if __name__ == "__main__":
     test_user_email_in_required_metrics()
     test_user_email_label_exists()
@@ -301,4 +382,8 @@ if __name__ == "__main__":
     test_route_normalization_preserves_static_routes()
     test_route_normalization_other_dynamic_apis()
     test_prometheus_metrics_use_normalized_routes()
+    test_prometheus_label_value_sanitization()
+    test_prometheus_label_value_sanitization_unicode_paragraph_separator()
+    test_prometheus_label_value_sanitization_none()
+    test_prometheus_label_value_sanitization_non_string_types()
     print("\n✅ All prometheus label tests passed!")

From 19024e06029c247abdbfdf0342dae6af23bd7a23 Mon Sep 17 00:00:00 2001
From: Ishaan Jaff <ishaanjaffer0324@gmail.com>
Date: Mon, 9 Feb 2026 17:35:11 -0800
Subject: [PATCH 6/6] [Feat] MCP Oauth2 Fixes - Add support for MCP M2M Oauth2
 support (#20788)

* add has_client_credentials

* MCPOAuth2TokenCache

* init MCP Oauth2 constants

* MCPOAuth2TokenCache

* resolve_mcp_auth

* test fixes

* docs fix

* address greptile review: min TTL, env-configurable constants, tests, docs

- Fix zero-TTL edge case: floor at MCP_OAUTH2_TOKEN_CACHE_MIN_TTL (10s)
- Make all MCP OAuth2 constants env-configurable via os.getenv()
- Move test file to follow 1:1 mapping convention (test_oauth2_token_cache.py)
- Add MCP OAuth doc page (mcp_oauth.md) with M2M and PKCE sections
- Update FAQ in mcp.md to reflect M2M support
- Add E2E test script and config

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix mypy lint

* fix oauth2

* remove old files

* docs fix

* address greptile comments

* fix: atomic lock creation + validate JSON response shape

- Use dict.setdefault() for atomic per-server lock creation
- Add isinstance(body, dict) check before accessing token response fields

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix: replace asserts with proper guards, wrap HTTP errors with context

- Replace `assert` statements with `if/raise ValueError` (asserts can be
  disabled with python -O in production)
- Wrap `httpx.HTTPStatusError` to provide a clear error message with
  server_id and status code
- Add tests for HTTP error and non-dict JSON response error paths
- Remove unused imports

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
---
 docs/my-website/docs/mcp.md                   |  13 +-
 docs/my-website/docs/mcp_oauth.md             | 192 ++++++++++++++++++
 docs/my-website/sidebars.js                   |   1 +
 litellm/constants.py                          |  14 ++
 .../mcp_server/mcp_server_manager.py          |  44 ++--
 .../mcp_server/oauth2_token_cache.py          | 163 +++++++++++++++
 .../mcp_server/rest_endpoints.py              |   2 +-
 .../types/mcp_server/mcp_server_manager.py    |  11 +
 tests/mcp_tests/test_mcp_auth_priority.py     |   7 +-
 .../mcp_server/test_mcp_server.py             |   2 +-
 .../mcp_server/test_mcp_server_manager.py     |  38 ++--
 .../mcp_server/test_oauth2_token_cache.py     | 157 ++++++++++++++
 .../mcp_server/test_rest_endpoints.py         |   4 +-
 13 files changed, 603 insertions(+), 45 deletions(-)
 create mode 100644 docs/my-website/docs/mcp_oauth.md
 create mode 100644 litellm/proxy/_experimental/mcp_server/oauth2_token_cache.py
 create mode 100644 tests/test_litellm/proxy/_experimental/mcp_server/test_oauth2_token_cache.py

diff --git a/docs/my-website/docs/mcp.md b/docs/my-website/docs/mcp.md
index d63b55ee29e..84d10c25931 100644
--- a/docs/my-website/docs/mcp.md
+++ b/docs/my-website/docs/mcp.md
@@ -506,7 +506,14 @@ Your OpenAPI specification should follow standard OpenAPI/Swagger conventions:
 - **Operation IDs**: Each operation should have a unique `operationId` (this becomes the tool name)
 - **Parameters**: Request parameters should be properly documented with types and descriptions
 
-## MCP Oauth
+## MCP OAuth
+
+LiteLLM supports OAuth 2.0 for MCP servers -- both interactive (PKCE) flows for user-facing clients and machine-to-machine (M2M) `client_credentials` for backend services.
+
+See the **[MCP OAuth guide](./mcp_oauth.md)** for setup instructions, sequence diagrams, and a test server.
+
+<details>
+<summary>Detailed OAuth reference (click to expand)</summary>
 
 LiteLLM v 1.77.6 added support for OAuth 2.0 Client Credentials for MCP servers.
 
@@ -588,6 +595,8 @@ sequenceDiagram
 
 See the official [MCP Authorization Flow](https://modelcontextprotocol.io/specification/2025-06-18/basic/authorization#authorization-flow-steps) for additional reference.
 
+</details>
+
 
 ## Forwarding Custom Headers to MCP Servers
 
@@ -1486,7 +1495,7 @@ async with stdio_client(server_params) as (read, write):
 
 **Q: How do I use OAuth2 client_credentials (machine-to-machine) with MCP servers behind LiteLLM?**
 
-At the moment LiteLLM only forwards whatever `Authorization` header/value you configure for the MCP server; it does not issue OAuth2 tokens by itself. If your MCP requires the Client Credentials grant, obtain the access token directly from the authorization server and set that bearer token as the MCP server’s Authorization header value. LiteLLM does not yet fetch or refresh those machine-to-machine tokens on your behalf, but we plan to add first-class client_credentials support in a future release so the proxy can manage those tokens automatically.
+LiteLLM supports automatic token management for the `client_credentials` grant. Configure `client_id`, `client_secret`, and `token_url` on your MCP server and LiteLLM will fetch, cache, and refresh tokens automatically. See the [MCP OAuth M2M guide](./mcp_oauth.md#machine-to-machine-m2m-auth) for setup instructions.
 
 **Q: When I fetch an OAuth token from the LiteLLM UI, where is it stored?**
 
diff --git a/docs/my-website/docs/mcp_oauth.md b/docs/my-website/docs/mcp_oauth.md
new file mode 100644
index 00000000000..ed69408196f
--- /dev/null
+++ b/docs/my-website/docs/mcp_oauth.md
@@ -0,0 +1,192 @@
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+# MCP OAuth
+
+LiteLLM supports two OAuth 2.0 flows for MCP servers:
+
+| Flow | Use Case | How It Works |
+|------|----------|--------------|
+| **Interactive (PKCE)** | User-facing apps (Claude Code, Cursor) | Browser-based consent, per-user tokens |
+| **Machine-to-Machine (M2M)** | Backend services, CI/CD, automated agents | `client_credentials` grant, proxy-managed tokens |
+
+## Interactive OAuth (PKCE)
+
+For user-facing MCP clients (Claude Code, Cursor), LiteLLM supports the full OAuth 2.0 authorization code flow with PKCE.
+
+### Setup
+
+```yaml title="config.yaml" showLineNumbers
+mcp_servers:
+  github_mcp:
+    url: "https://api.githubcopilot.com/mcp"
+    auth_type: oauth2
+    client_id: os.environ/GITHUB_OAUTH_CLIENT_ID
+    client_secret: os.environ/GITHUB_OAUTH_CLIENT_SECRET
+```
+
+[**See Claude Code Tutorial**](./tutorials/claude_responses_api#connecting-mcp-servers)
+
+### How It Works
+
+```mermaid
+sequenceDiagram
+    participant Browser as User-Agent (Browser)
+    participant Client as Client
+    participant LiteLLM as LiteLLM Proxy
+    participant MCP as MCP Server (Resource Server)
+    participant Auth as Authorization Server
+
+    Note over Client,LiteLLM: Step 1 – Resource discovery
+    Client->>LiteLLM: GET /.well-known/oauth-protected-resource/{mcp_server_name}/mcp
+    LiteLLM->>Client: Return resource metadata
+
+    Note over Client,LiteLLM: Step 2 – Authorization server discovery
+    Client->>LiteLLM: GET /.well-known/oauth-authorization-server/{mcp_server_name}
+    LiteLLM->>Client: Return authorization server metadata
+
+    Note over Client,Auth: Step 3 – Dynamic client registration
+    Client->>LiteLLM: POST /{mcp_server_name}/register
+    LiteLLM->>Auth: Forward registration request
+    Auth->>LiteLLM: Issue client credentials
+    LiteLLM->>Client: Return client credentials
+
+    Note over Client,Browser: Step 4 – User authorization (PKCE)
+    Client->>Browser: Open authorization URL + code_challenge + resource
+    Browser->>Auth: Authorization request
+    Note over Auth: User authorizes
+    Auth->>Browser: Redirect with authorization code
+    Browser->>LiteLLM: Callback to LiteLLM with code
+    LiteLLM->>Browser: Redirect back with authorization code
+    Browser->>Client: Callback with authorization code
+
+    Note over Client,Auth: Step 5 – Token exchange
+    Client->>LiteLLM: Token request + code_verifier + resource
+    LiteLLM->>Auth: Forward token request
+    Auth->>LiteLLM: Access (and refresh) token
+    LiteLLM->>Client: Return tokens
+
+    Note over Client,MCP: Step 6 – Authenticated MCP call
+    Client->>LiteLLM: MCP request with access token + LiteLLM API key
+    LiteLLM->>MCP: MCP request with Bearer token
+    MCP-->>LiteLLM: MCP response
+    LiteLLM-->>Client: Return MCP response
+```
+
+**Participants**
+
+- **Client** -- The MCP-capable AI agent (e.g., Claude Code, Cursor, or another IDE/agent) that initiates OAuth discovery, authorization, and tool invocations on behalf of the user.
+- **LiteLLM Proxy** -- Mediates all OAuth discovery, registration, token exchange, and MCP traffic while protecting stored credentials.
+- **Authorization Server** -- Issues OAuth 2.0 tokens via dynamic client registration, PKCE authorization, and token endpoints.
+- **MCP Server (Resource Server)** -- The protected MCP endpoint that receives LiteLLM's authenticated JSON-RPC requests.
+- **User-Agent (Browser)** -- Temporarily involved so the end user can grant consent during the authorization step.
+
+**Flow Steps**
+
+1. **Resource Discovery**: The client fetches MCP resource metadata from LiteLLM's `.well-known/oauth-protected-resource` endpoint to understand scopes and capabilities.
+2. **Authorization Server Discovery**: The client retrieves the OAuth server metadata (token endpoint, authorization endpoint, supported PKCE methods) through LiteLLM's `.well-known/oauth-authorization-server` endpoint.
+3. **Dynamic Client Registration**: The client registers through LiteLLM, which forwards the request to the authorization server (RFC 7591). If the provider doesn't support dynamic registration, you can pre-store `client_id`/`client_secret` in LiteLLM (e.g., GitHub MCP) and the flow proceeds the same way.
+4. **User Authorization**: The client launches a browser session (with code challenge and resource hints). The user approves access, the authorization server sends the code through LiteLLM back to the client.
+5. **Token Exchange**: The client calls LiteLLM with the authorization code, code verifier, and resource. LiteLLM exchanges them with the authorization server and returns the issued access/refresh tokens.
+6. **MCP Invocation**: With a valid token, the client sends the MCP JSON-RPC request (plus LiteLLM API key) to LiteLLM, which forwards it to the MCP server and relays the tool response.
+
+See the official [MCP Authorization Flow](https://modelcontextprotocol.io/specification/2025-06-18/basic/authorization#authorization-flow-steps) for additional reference.
+
+## Machine-to-Machine (M2M) Auth
+
+LiteLLM automatically fetches, caches, and refreshes OAuth2 tokens using the `client_credentials` grant. No manual token management required.
+
+### Setup
+
+<Tabs>
+<TabItem value="config" label="config.yaml">
+
+```yaml title="config.yaml" showLineNumbers
+mcp_servers:
+  my_mcp_server:
+    url: "https://my-mcp-server.com/mcp"
+    auth_type: oauth2
+    client_id: os.environ/MCP_CLIENT_ID
+    client_secret: os.environ/MCP_CLIENT_SECRET
+    token_url: "https://auth.example.com/oauth/token"
+    scopes: ["mcp:read", "mcp:write"]  # optional
+```
+
+</TabItem>
+<TabItem value="ui" label="LiteLLM UI">
+
+Navigate to **MCP Servers → Add Server → Authentication → OAuth**, then fill in `client_id`, `client_secret`, and `token_url`.
+
+</TabItem>
+</Tabs>
+
+### How It Works
+
+1. On first MCP request, LiteLLM POSTs to `token_url` with `grant_type=client_credentials`
+2. The access token is cached in-memory with TTL = `expires_in - 60s`
+3. Subsequent requests reuse the cached token
+4. When the token expires, LiteLLM fetches a new one automatically
+
+```mermaid
+sequenceDiagram
+    participant Client as Client
+    participant LiteLLM as LiteLLM Proxy
+    participant Auth as Authorization Server
+    participant MCP as MCP Server
+
+    Client->>LiteLLM: MCP request + LiteLLM API key
+    LiteLLM->>Auth: POST /oauth/token (client_credentials)
+    Auth->>LiteLLM: access_token (expires_in: 3600)
+    LiteLLM->>MCP: MCP request + Bearer token
+    MCP-->>LiteLLM: MCP response
+    LiteLLM-->>Client: MCP response
+
+    Note over LiteLLM: Token cached for subsequent requests
+    Client->>LiteLLM: Next MCP request
+    LiteLLM->>MCP: MCP request + cached Bearer token
+    MCP-->>LiteLLM: MCP response
+    LiteLLM-->>Client: MCP response
+```
+
+### Test with Mock Server
+
+Use [BerriAI/mock-oauth2-mcp-server](https://github.com/BerriAI/mock-oauth2-mcp-server) to test locally:
+
+```bash title="Terminal 1 - Start mock server" showLineNumbers
+pip install fastapi uvicorn
+python mock_oauth2_mcp_server.py  # starts on :8765
+```
+
+```yaml title="config.yaml" showLineNumbers
+mcp_servers:
+  test_oauth2:
+    url: "http://localhost:8765/mcp"
+    auth_type: oauth2
+    client_id: "test-client"
+    client_secret: "test-secret"
+    token_url: "http://localhost:8765/oauth/token"
+```
+
+```bash title="Terminal 2 - Start proxy and test" showLineNumbers
+litellm --config config.yaml --port 4000
+
+# List tools
+curl http://localhost:4000/mcp-rest/tools/list \
+  -H "Authorization: Bearer sk-1234"
+
+# Call a tool
+curl http://localhost:4000/mcp-rest/tools/call \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer sk-1234" \
+  -d '{"name": "echo", "arguments": {"message": "hello"}}'
+```
+
+### Config Reference
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `auth_type` | Yes | Must be `oauth2` |
+| `client_id` | Yes | OAuth2 client ID. Supports `os.environ/VAR_NAME` |
+| `client_secret` | Yes | OAuth2 client secret. Supports `os.environ/VAR_NAME` |
+| `token_url` | Yes | Token endpoint URL |
+| `scopes` | No | List of scopes to request |
diff --git a/docs/my-website/sidebars.js b/docs/my-website/sidebars.js
index 0d95bf7e545..2c3dfb2b863 100644
--- a/docs/my-website/sidebars.js
+++ b/docs/my-website/sidebars.js
@@ -563,6 +563,7 @@ const sidebars = {
           items: [
             "mcp",
             "mcp_usage",
+            "mcp_oauth",
             "mcp_public_internet",
             "mcp_semantic_filter",
             "mcp_control",
diff --git a/litellm/constants.py b/litellm/constants.py
index f5f2c7a49e4..9c25cf77906 100644
--- a/litellm/constants.py
+++ b/litellm/constants.py
@@ -83,6 +83,20 @@ MAX_MCP_SEMANTIC_FILTER_TOOLS_HEADER_LENGTH = int(
     os.getenv("MAX_MCP_SEMANTIC_FILTER_TOOLS_HEADER_LENGTH", 150)
 )
 
+# MCP OAuth2 Client Credentials Defaults
+MCP_OAUTH2_TOKEN_EXPIRY_BUFFER_SECONDS = int(
+    os.getenv("MCP_OAUTH2_TOKEN_EXPIRY_BUFFER_SECONDS", "60")
+)
+MCP_OAUTH2_TOKEN_CACHE_MAX_SIZE = int(
+    os.getenv("MCP_OAUTH2_TOKEN_CACHE_MAX_SIZE", "200")
+)
+MCP_OAUTH2_TOKEN_CACHE_DEFAULT_TTL = int(
+    os.getenv("MCP_OAUTH2_TOKEN_CACHE_DEFAULT_TTL", "3600")
+)
+MCP_OAUTH2_TOKEN_CACHE_MIN_TTL = int(
+    os.getenv("MCP_OAUTH2_TOKEN_CACHE_MIN_TTL", "10")
+)
+
 LITELLM_UI_ALLOW_HEADERS = [
     "x-litellm-semantic-filter",
     "x-litellm-semantic-filter-tools",
diff --git a/litellm/proxy/_experimental/mcp_server/mcp_server_manager.py b/litellm/proxy/_experimental/mcp_server/mcp_server_manager.py
index e7174f943b2..532aea249bf 100644
--- a/litellm/proxy/_experimental/mcp_server/mcp_server_manager.py
+++ b/litellm/proxy/_experimental/mcp_server/mcp_server_manager.py
@@ -36,6 +36,7 @@ from litellm.llms.custom_httpx.http_handler import get_async_httpx_client
 from litellm.proxy._experimental.mcp_server.auth.user_api_key_auth_mcp import (
     MCPRequestHandler,
 )
+from litellm.proxy._experimental.mcp_server.oauth2_token_cache import resolve_mcp_auth
 from litellm.proxy._experimental.mcp_server.utils import (
     MCP_TOOL_PREFIX_SEPARATOR,
     add_server_prefix_to_name,
@@ -833,7 +834,7 @@ class MCPServerManager:
 
         return resolved_env
 
-    def _create_mcp_client(
+    async def _create_mcp_client(
         self,
         server: MCPServer,
         mcp_auth_header: Optional[Union[str, Dict[str, str]]] = None,
@@ -843,13 +844,22 @@ class MCPServerManager:
         """
         Create an MCPClient instance for the given server.
 
+        Auth resolution (single place for all auth logic):
+        1. ``mcp_auth_header`` — per-request/per-user override
+        2. OAuth2 client_credentials token — auto-fetched and cached
+        3. ``server.authentication_token`` — static token from config/DB
+
         Args:
-            server (MCPServer): The server configuration
-            mcp_auth_header: MCP auth header to be passed to the MCP server. This is optional and will be used if provided.
+            server: The server configuration.
+            mcp_auth_header: Optional per-request auth override.
+            extra_headers: Additional headers to forward.
+            stdio_env: Environment variables for stdio transport.
 
         Returns:
-            MCPClient: Configured MCP client instance
+            Configured MCP client instance.
         """
+        auth_value = await resolve_mcp_auth(server, mcp_auth_header)
+
         transport = server.transport or MCPTransport.sse
 
         # Handle stdio transport
@@ -868,7 +878,7 @@ class MCPServerManager:
                 server_url="",  # Not used for stdio
                 transport_type=transport,
                 auth_type=server.auth_type,
-                auth_value=mcp_auth_header or server.authentication_token,
+                auth_value=auth_value,
                 timeout=60.0,
                 stdio_config=stdio_config,
                 extra_headers=extra_headers,
@@ -880,7 +890,7 @@ class MCPServerManager:
                 server_url=server_url,
                 transport_type=transport,
                 auth_type=server.auth_type,
-                auth_value=mcp_auth_header or server.authentication_token,
+                auth_value=auth_value,
                 timeout=60.0,
                 extra_headers=extra_headers,
             )
@@ -920,7 +930,7 @@ class MCPServerManager:
 
             stdio_env = self._build_stdio_env(server, raw_headers)
 
-            client = self._create_mcp_client(
+            client = await self._create_mcp_client(
                 server=server,
                 mcp_auth_header=mcp_auth_header,
                 extra_headers=extra_headers,
@@ -980,7 +990,7 @@ class MCPServerManager:
 
             stdio_env = self._build_stdio_env(server, raw_headers)
 
-            client = self._create_mcp_client(
+            client = await self._create_mcp_client(
                 server=server,
                 mcp_auth_header=mcp_auth_header,
                 extra_headers=extra_headers,
@@ -1024,7 +1034,7 @@ class MCPServerManager:
 
             stdio_env = self._build_stdio_env(server, raw_headers)
 
-            client = self._create_mcp_client(
+            client = await self._create_mcp_client(
                 server=server,
                 mcp_auth_header=mcp_auth_header,
                 extra_headers=extra_headers,
@@ -1068,7 +1078,7 @@ class MCPServerManager:
 
             stdio_env = self._build_stdio_env(server, raw_headers)
 
-            client = self._create_mcp_client(
+            client = await self._create_mcp_client(
                 server=server,
                 mcp_auth_header=mcp_auth_header,
                 extra_headers=extra_headers,
@@ -1109,7 +1119,7 @@ class MCPServerManager:
 
         stdio_env = self._build_stdio_env(server, raw_headers)
 
-        client = self._create_mcp_client(
+        client = await self._create_mcp_client(
             server=server,
             mcp_auth_header=mcp_auth_header,
             extra_headers=extra_headers,
@@ -1139,7 +1149,7 @@ class MCPServerManager:
 
         stdio_env = self._build_stdio_env(server, raw_headers)
 
-        client = self._create_mcp_client(
+        client = await self._create_mcp_client(
             server=server,
             mcp_auth_header=mcp_auth_header,
             extra_headers=extra_headers,
@@ -1943,7 +1953,7 @@ class MCPServerManager:
 
         stdio_env = self._build_stdio_env(mcp_server, raw_headers)
 
-        client = self._create_mcp_client(
+        client = await self._create_mcp_client(
             server=mcp_server,
             mcp_auth_header=server_auth_header,
             extra_headers=extra_headers,
@@ -2119,8 +2129,8 @@ class MCPServerManager:
         Note: This now handles prefixed tool names
         """
         for server in self.get_registry().values():
-            if server.auth_type == MCPAuth.oauth2:
-                # Skip OAuth2 servers for now as they may require user-specific tokens
+            if server.needs_user_oauth_token:
+                # Skip OAuth2 servers that rely on user-provided tokens
                 continue
             tools = await self._get_tools_from_server(server)
             for tool in tools:
@@ -2414,7 +2424,7 @@ class MCPServerManager:
         should_skip_health_check = False
 
         # Skip if auth_type is oauth2
-        if server.auth_type == MCPAuth.oauth2:
+        if server.needs_user_oauth_token:
             should_skip_health_check = True
         # Skip if auth_type is not none and authentication_token is missing
         elif (
@@ -2429,7 +2439,7 @@ class MCPServerManager:
             if server.static_headers:
                 extra_headers.update(server.static_headers)
 
-            client = self._create_mcp_client(
+            client = await self._create_mcp_client(
                 server=server,
                 mcp_auth_header=None,
                 extra_headers=extra_headers,
diff --git a/litellm/proxy/_experimental/mcp_server/oauth2_token_cache.py b/litellm/proxy/_experimental/mcp_server/oauth2_token_cache.py
new file mode 100644
index 00000000000..0de381ee1df
--- /dev/null
+++ b/litellm/proxy/_experimental/mcp_server/oauth2_token_cache.py
@@ -0,0 +1,163 @@
+"""
+OAuth2 client_credentials token cache for MCP servers.
+
+Automatically fetches and refreshes access tokens for MCP servers configured
+with ``client_id``, ``client_secret``, and ``token_url``.
+"""
+
+import asyncio
+from typing import TYPE_CHECKING, Dict, Optional, Tuple, Union
+
+import httpx
+
+from litellm._logging import verbose_logger
+from litellm.caching.in_memory_cache import InMemoryCache
+from litellm.constants import (
+    MCP_OAUTH2_TOKEN_CACHE_DEFAULT_TTL,
+    MCP_OAUTH2_TOKEN_CACHE_MAX_SIZE,
+    MCP_OAUTH2_TOKEN_CACHE_MIN_TTL,
+    MCP_OAUTH2_TOKEN_EXPIRY_BUFFER_SECONDS,
+)
+from litellm.llms.custom_httpx.http_handler import get_async_httpx_client
+from litellm.types.llms.custom_http import httpxSpecialProvider
+
+if TYPE_CHECKING:
+    from litellm.types.mcp_server.mcp_server_manager import MCPServer
+
+
+class MCPOAuth2TokenCache(InMemoryCache):
+    """
+    In-memory cache for OAuth2 client_credentials tokens, keyed by server_id.
+
+    Inherits from ``InMemoryCache`` for TTL-based storage and eviction.
+    Adds per-server ``asyncio.Lock`` to prevent duplicate concurrent fetches.
+    """
+
+    def __init__(self) -> None:
+        super().__init__(
+            max_size_in_memory=MCP_OAUTH2_TOKEN_CACHE_MAX_SIZE,
+            default_ttl=MCP_OAUTH2_TOKEN_CACHE_DEFAULT_TTL,
+        )
+        self._locks: Dict[str, asyncio.Lock] = {}
+
+    def _get_lock(self, server_id: str) -> asyncio.Lock:
+        return self._locks.setdefault(server_id, asyncio.Lock())
+
+    async def async_get_token(self, server: "MCPServer") -> Optional[str]:
+        """Return a valid access token, fetching or refreshing as needed.
+
+        Returns ``None`` when the server lacks client credentials config.
+        """
+        if not server.has_client_credentials:
+            return None
+
+        server_id = server.server_id
+
+        # Fast path — cached token is still valid
+        cached = self.get_cache(server_id)
+        if cached is not None:
+            return cached
+
+        # Slow path — acquire per-server lock then double-check
+        async with self._get_lock(server_id):
+            cached = self.get_cache(server_id)
+            if cached is not None:
+                return cached
+
+            token, ttl = await self._fetch_token(server)
+            self.set_cache(server_id, token, ttl=ttl)
+            return token
+
+    async def _fetch_token(self, server: "MCPServer") -> Tuple[str, int]:
+        """POST to ``token_url`` with ``grant_type=client_credentials``.
+
+        Returns ``(access_token, ttl_seconds)`` where ttl accounts for the
+        expiry buffer so the cache entry expires before the real token does.
+        """
+        client = get_async_httpx_client(llm_provider=httpxSpecialProvider.MCP)
+
+        if not server.client_id or not server.client_secret or not server.token_url:
+            raise ValueError(
+                f"MCP server '{server.server_id}' missing required OAuth2 fields: "
+                f"client_id={bool(server.client_id)}, "
+                f"client_secret={bool(server.client_secret)}, "
+                f"token_url={bool(server.token_url)}"
+            )
+
+        data: Dict[str, str] = {
+            "grant_type": "client_credentials",
+            "client_id": server.client_id,
+            "client_secret": server.client_secret,
+        }
+        if server.scopes:
+            data["scope"] = " ".join(server.scopes)
+
+        verbose_logger.debug(
+            "Fetching OAuth2 client_credentials token for MCP server %s",
+            server.server_id,
+        )
+
+        try:
+            response = await client.post(server.token_url, data=data)
+            response.raise_for_status()
+        except httpx.HTTPStatusError as exc:
+            raise ValueError(
+                f"OAuth2 token request for MCP server '{server.server_id}' "
+                f"failed with status {exc.response.status_code}"
+            ) from exc
+
+        body = response.json()
+
+        if not isinstance(body, dict):
+            raise ValueError(
+                f"OAuth2 token response for MCP server '{server.server_id}' "
+                f"returned non-object JSON (got {type(body).__name__})"
+            )
+
+        access_token = body.get("access_token")
+        if not access_token:
+            raise ValueError(
+                f"OAuth2 token response for MCP server '{server.server_id}' "
+                f"missing 'access_token'"
+            )
+
+        # Safely parse expires_in — providers may return null or non-numeric values
+        raw_expires_in = body.get("expires_in")
+        try:
+            expires_in = int(raw_expires_in) if raw_expires_in is not None else MCP_OAUTH2_TOKEN_CACHE_DEFAULT_TTL
+        except (TypeError, ValueError):
+            expires_in = MCP_OAUTH2_TOKEN_CACHE_DEFAULT_TTL
+
+        ttl = max(expires_in - MCP_OAUTH2_TOKEN_EXPIRY_BUFFER_SECONDS, MCP_OAUTH2_TOKEN_CACHE_MIN_TTL)
+
+        verbose_logger.info(
+            "Fetched OAuth2 token for MCP server %s (expires in %ds)",
+            server.server_id,
+            expires_in,
+        )
+        return access_token, ttl
+
+    def invalidate(self, server_id: str) -> None:
+        """Remove a cached token (e.g. after a 401)."""
+        self.delete_cache(server_id)
+
+
+mcp_oauth2_token_cache = MCPOAuth2TokenCache()
+
+
+async def resolve_mcp_auth(
+    server: "MCPServer",
+    mcp_auth_header: Optional[Union[str, Dict[str, str]]] = None,
+) -> Optional[Union[str, Dict[str, str]]]:
+    """Resolve the auth value for an MCP server.
+
+    Priority:
+    1. ``mcp_auth_header`` — per-request/per-user override
+    2. OAuth2 client_credentials token — auto-fetched and cached
+    3. ``server.authentication_token`` — static token from config/DB
+    """
+    if mcp_auth_header:
+        return mcp_auth_header
+    if server.has_client_credentials:
+        return await mcp_oauth2_token_cache.async_get_token(server)
+    return server.authentication_token
diff --git a/litellm/proxy/_experimental/mcp_server/rest_endpoints.py b/litellm/proxy/_experimental/mcp_server/rest_endpoints.py
index 2fe40bb197e..65d3a2caa16 100644
--- a/litellm/proxy/_experimental/mcp_server/rest_endpoints.py
+++ b/litellm/proxy/_experimental/mcp_server/rest_endpoints.py
@@ -541,7 +541,7 @@ if MCP_AVAILABLE:
                 static_headers=request.static_headers,
             )
 
-            client = global_mcp_server_manager._create_mcp_client(
+            client = await global_mcp_server_manager._create_mcp_client(
                 server=server_model,
                 mcp_auth_header=mcp_auth_header,
                 extra_headers=merged_headers,
diff --git a/litellm/types/mcp_server/mcp_server_manager.py b/litellm/types/mcp_server/mcp_server_manager.py
index 4e6c1810255..2cd385c5bf6 100644
--- a/litellm/types/mcp_server/mcp_server_manager.py
+++ b/litellm/types/mcp_server/mcp_server_manager.py
@@ -4,6 +4,7 @@ from typing import Any, Dict, List, Optional
 from pydantic import BaseModel, ConfigDict
 
 from litellm.proxy._types import MCPAuthType, MCPTransportType
+from litellm.types.mcp import MCPAuth
 
 # MCPInfo now allows arbitrary additional fields for custom metadata
 MCPInfo = Dict[str, Any]
@@ -54,3 +55,13 @@ class MCPServer(BaseModel):
     available_on_public_internet: bool = False
     updated_at: Optional[datetime] = None
     model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    @property
+    def has_client_credentials(self) -> bool:
+        """True if this server has OAuth2 client_credentials config (client_id, client_secret, token_url)."""
+        return bool(self.client_id and self.client_secret and self.token_url)
+
+    @property
+    def needs_user_oauth_token(self) -> bool:
+        """True if this is an OAuth2 server that relies on per-user tokens (no client_credentials)."""
+        return self.auth_type == MCPAuth.oauth2 and not self.has_client_credentials
diff --git a/tests/mcp_tests/test_mcp_auth_priority.py b/tests/mcp_tests/test_mcp_auth_priority.py
index bc217a7903b..ad6e9438edd 100644
--- a/tests/mcp_tests/test_mcp_auth_priority.py
+++ b/tests/mcp_tests/test_mcp_auth_priority.py
@@ -12,7 +12,8 @@ from litellm.types.mcp import MCPAuth, MCPTransport, MCPSpecVersion
 from litellm.types.mcp_server.mcp_server_manager import MCPServer
 
 
-def test_mcp_server_works_without_config_auth_value():
+@pytest.mark.asyncio
+async def test_mcp_server_works_without_config_auth_value():
     """
     Test that MCP servers work without auth_value in config when headers are provided.
     This validates that auth_value is truly optional in config.yaml.
@@ -32,7 +33,7 @@ def test_mcp_server_works_without_config_auth_value():
     manager = MCPServerManager()
 
     # Test that it works with only header auth
-    client = manager._create_mcp_client(
+    client = await manager._create_mcp_client(
         server=server_without_config_auth,
         mcp_auth_header="Bearer token_from_header_only",
     )
@@ -58,7 +59,7 @@ async def test_mcp_server_config_auth_value_header_used(token_key):
     await manager.load_servers_from_config(config)
 
     server = next(iter(manager.config_mcp_servers.values()))
-    client = manager._create_mcp_client(server)
+    client = await manager._create_mcp_client(server)
     headers = client._get_auth_headers()
 
     assert headers["Authorization"] == "Bearer example_token"
diff --git a/tests/test_litellm/proxy/_experimental/mcp_server/test_mcp_server.py b/tests/test_litellm/proxy/_experimental/mcp_server/test_mcp_server.py
index 9aa7de89eff..07c3dfcc763 100644
--- a/tests/test_litellm/proxy/_experimental/mcp_server/test_mcp_server.py
+++ b/tests/test_litellm/proxy/_experimental/mcp_server/test_mcp_server.py
@@ -886,7 +886,7 @@ async def test_oauth2_headers_passed_to_mcp_client():
     # This will capture the arguments passed to _create_mcp_client
     captured_client_args = {}
 
-    def mock_create_mcp_client(
+    async def mock_create_mcp_client(
         server,
         mcp_auth_header=None,
         extra_headers=None,
diff --git a/tests/test_litellm/proxy/_experimental/mcp_server/test_mcp_server_manager.py b/tests/test_litellm/proxy/_experimental/mcp_server/test_mcp_server_manager.py
index f241b2aa0d5..abb8dd49159 100644
--- a/tests/test_litellm/proxy/_experimental/mcp_server/test_mcp_server_manager.py
+++ b/tests/test_litellm/proxy/_experimental/mcp_server/test_mcp_server_manager.py
@@ -1,5 +1,5 @@
-import json
 import importlib
+import json
 import logging
 import os
 import sys
@@ -21,8 +21,8 @@ from mcp.types import (
     Prompt,
     ResourceTemplate,
     TextResourceContents,
-    Tool as MCPTool,
 )
+from mcp.types import Tool as MCPTool
 
 from litellm.proxy._experimental.mcp_server.mcp_server_manager import (
     MCPServerManager,
@@ -92,7 +92,7 @@ class TestMCPServerManager:
         assert added_server.args == ["-m", "server"]
         assert added_server.env == {"DEBUG": "1", "TEST": "1"}
 
-    def test_create_mcp_client_stdio(self):
+    async def test_create_mcp_client_stdio(self):
         """Test creating MCP client for stdio transport"""
         manager = MCPServerManager()
 
@@ -106,7 +106,7 @@ class TestMCPServerManager:
             env={"NODE_ENV": "test"},
         )
 
-        client = manager._create_mcp_client(stdio_server)
+        client = await manager._create_mcp_client(stdio_server)
 
         assert client.transport_type == MCPTransport.stdio
         assert client.stdio_config is not None
@@ -404,14 +404,14 @@ class TestMCPServerManager:
         )
         captured_extra_headers = None
 
-        def capture_create_mcp_client(
+        async def capture_create_mcp_client(
             server, mcp_auth_header, extra_headers, stdio_env
         ):  # pragma: no cover - helper
             nonlocal captured_extra_headers
             captured_extra_headers = extra_headers
             return mock_client
 
-        manager._create_mcp_client = MagicMock(side_effect=capture_create_mcp_client)
+        manager._create_mcp_client = AsyncMock(side_effect=capture_create_mcp_client)
 
         result = await manager._call_regular_mcp_tool(
             mcp_server=server,
@@ -446,7 +446,7 @@ class TestMCPServerManager:
         mock_client = AsyncMock()
         mock_client.list_prompts = AsyncMock(return_value=[mock_prompt])
 
-        with patch.object(manager, "_create_mcp_client", return_value=mock_client):
+        with patch.object(manager, "_create_mcp_client", new_callable=AsyncMock, return_value=mock_client):
             prompts = await manager.get_prompts_from_server(server, add_prefix=True)
 
         mock_client.list_prompts.assert_awaited_once()
@@ -474,7 +474,7 @@ class TestMCPServerManager:
         mock_client = AsyncMock()
         mock_client.get_prompt = AsyncMock(return_value=mock_result)
 
-        with patch.object(manager, "_create_mcp_client", return_value=mock_client):
+        with patch.object(manager, "_create_mcp_client", new_callable=AsyncMock, return_value=mock_client):
             result = await manager.get_prompt_from_server(
                 server=server,
                 prompt_name="hello",
@@ -507,7 +507,7 @@ class TestMCPServerManager:
         mock_client.list_resources = AsyncMock(return_value=mock_resources)
         prefixed_resources = [Resource(name="alias-server-file", uri="https://example.com/file")]
 
-        with patch.object(manager, "_create_mcp_client", return_value=mock_client) as mock_create_client, patch.object(
+        with patch.object(manager, "_create_mcp_client", new_callable=AsyncMock, return_value=mock_client) as mock_create_client, patch.object(
             manager,
             "_create_prefixed_resources",
             return_value=prefixed_resources,
@@ -556,7 +556,7 @@ class TestMCPServerManager:
             )
         ]
 
-        with patch.object(manager, "_create_mcp_client", return_value=mock_client) as mock_create_client, patch.object(
+        with patch.object(manager, "_create_mcp_client", new_callable=AsyncMock, return_value=mock_client) as mock_create_client, patch.object(
             manager,
             "_create_prefixed_resource_templates",
             return_value=prefixed_templates,
@@ -604,7 +604,7 @@ class TestMCPServerManager:
         )
         mock_client.read_resource = AsyncMock(return_value=read_result)
 
-        with patch.object(manager, "_create_mcp_client", return_value=mock_client) as mock_create_client:
+        with patch.object(manager, "_create_mcp_client", new_callable=AsyncMock, return_value=mock_client) as mock_create_client:
             result = await manager.read_resource_from_server(
                 server=server,
                 url="https://example.com/resource",
@@ -816,7 +816,7 @@ class TestMCPServerManager:
         # Mock successful client.run_with_session
         mock_client = AsyncMock()
         mock_client.run_with_session = AsyncMock(return_value="ok")
-        manager._create_mcp_client = MagicMock(return_value=mock_client)
+        manager._create_mcp_client = AsyncMock(return_value=mock_client)
 
         # Perform health check
         result = await manager.health_check_server("test-server")
@@ -850,7 +850,7 @@ class TestMCPServerManager:
         mock_client.run_with_session = AsyncMock(
             side_effect=Exception("Connection timeout")
         )
-        manager._create_mcp_client = MagicMock(return_value=mock_client)
+        manager._create_mcp_client = AsyncMock(return_value=mock_client)
 
         # Perform health check
         result = await manager.health_check_server("test-server")
@@ -898,7 +898,7 @@ class TestMCPServerManager:
         manager.get_mcp_server_by_id = MagicMock(return_value=server)
 
         # _create_mcp_client should not be called for OAuth2 servers
-        manager._create_mcp_client = MagicMock()
+        manager._create_mcp_client = AsyncMock()
 
         # Perform health check
         result = await manager.health_check_server("oauth2-server")
@@ -931,7 +931,7 @@ class TestMCPServerManager:
         manager.get_mcp_server_by_id = MagicMock(return_value=server)
 
         # _create_mcp_client should not be called
-        manager._create_mcp_client = MagicMock()
+        manager._create_mcp_client = AsyncMock()
 
         # Perform health check
         result = await manager.health_check_server("no-token-server")
@@ -971,12 +971,12 @@ class TestMCPServerManager:
         # Capture the extra_headers passed to _create_mcp_client
         captured_extra_headers = None
 
-        def capture_create_mcp_client(server, mcp_auth_header, extra_headers, stdio_env):
+        async def capture_create_mcp_client(server, mcp_auth_header, extra_headers, stdio_env):
             nonlocal captured_extra_headers
             captured_extra_headers = extra_headers
             return mock_client
 
-        manager._create_mcp_client = MagicMock(side_effect=capture_create_mcp_client)
+        manager._create_mcp_client = AsyncMock(side_effect=capture_create_mcp_client)
 
         # Perform health check
         result = await manager.health_check_server("test-server")
@@ -1310,7 +1310,7 @@ class TestMCPServerManager:
         )
 
         # Mock client creation and fetching tools
-        manager._create_mcp_client = MagicMock(return_value=object())
+        manager._create_mcp_client = AsyncMock(return_value=object())
 
         # Tools returned upstream (unprefixed from provider)
         upstream_tool = MCPTool(
@@ -1895,7 +1895,7 @@ class TestMCPServerManager:
         mock_client.call_tool.side_effect = mock_call_tool
 
         # Mock _create_mcp_client to return our mock client
-        manager._create_mcp_client = MagicMock(return_value=mock_client)
+        manager._create_mcp_client = AsyncMock(return_value=mock_client)
 
         # Mock user auth with no restrictions
         user_api_key_auth = MagicMock()
diff --git a/tests/test_litellm/proxy/_experimental/mcp_server/test_oauth2_token_cache.py b/tests/test_litellm/proxy/_experimental/mcp_server/test_oauth2_token_cache.py
new file mode 100644
index 00000000000..55735dca98e
--- /dev/null
+++ b/tests/test_litellm/proxy/_experimental/mcp_server/test_oauth2_token_cache.py
@@ -0,0 +1,157 @@
+"""
+Core tests for MCP OAuth2 machine-to-machine (client_credentials) token management.
+
+Covers the critical path: resolve_mcp_auth(), token caching, auth priority,
+fallback to static token, and the skip-condition property.
+"""
+
+from unittest.mock import AsyncMock, MagicMock, patch
+
+import httpx
+import pytest
+
+from litellm.proxy._experimental.mcp_server.oauth2_token_cache import (
+    MCPOAuth2TokenCache,
+    resolve_mcp_auth,
+)
+from litellm.proxy._types import MCPTransport
+from litellm.types.mcp import MCPAuth
+from litellm.types.mcp_server.mcp_server_manager import MCPServer
+
+
+def _server(**overrides) -> MCPServer:
+    defaults = dict(
+        server_id="srv-1",
+        name="test",
+        url="https://mcp.example.com/mcp",
+        transport=MCPTransport.http,
+        auth_type=MCPAuth.oauth2,
+        client_id="cid",
+        client_secret="csec",
+        token_url="https://auth.example.com/token",
+    )
+    defaults.update(overrides)
+    return MCPServer(**defaults)
+
+
+def _token_response(token="tok-abc", expires_in=3600):
+    resp = MagicMock()
+    resp.json.return_value = {
+        "access_token": token,
+        "token_type": "bearer",
+        "expires_in": expires_in,
+    }
+    resp.raise_for_status = MagicMock()
+    return resp
+
+
+@pytest.mark.asyncio
+async def test_resolve_mcp_auth_fetches_oauth2_token():
+    """resolve_mcp_auth fetches a token via client_credentials when the server has OAuth2 config."""
+    server = _server()
+    mock_client = AsyncMock()
+    mock_client.post.return_value = _token_response("m2m-token-1")
+
+    with patch(
+        "litellm.proxy._experimental.mcp_server.oauth2_token_cache.get_async_httpx_client",
+        return_value=mock_client,
+    ):
+        result = await resolve_mcp_auth(server)
+
+    assert result == "m2m-token-1"
+    mock_client.post.assert_called_once()
+    post_data = mock_client.post.call_args[1]["data"]
+    assert post_data["grant_type"] == "client_credentials"
+    assert post_data["client_id"] == "cid"
+    assert post_data["client_secret"] == "csec"
+
+
+@pytest.mark.asyncio
+async def test_token_cached_across_calls():
+    """Second resolve_mcp_auth call reuses the cached token — only 1 HTTP POST."""
+    cache = MCPOAuth2TokenCache()
+    server = _server()
+    mock_client = AsyncMock()
+    mock_client.post.return_value = _token_response("cached-tok")
+
+    with patch(
+        "litellm.proxy._experimental.mcp_server.oauth2_token_cache.get_async_httpx_client",
+        return_value=mock_client,
+    ), patch(
+        "litellm.proxy._experimental.mcp_server.oauth2_token_cache.mcp_oauth2_token_cache",
+        cache,
+    ):
+        t1 = await resolve_mcp_auth(server)
+        t2 = await resolve_mcp_auth(server)
+
+    assert t1 == t2 == "cached-tok"
+    assert mock_client.post.call_count == 1
+
+
+@pytest.mark.asyncio
+async def test_per_request_header_beats_oauth2():
+    """An explicit mcp_auth_header takes priority over the OAuth2 token."""
+    server = _server()
+    result = await resolve_mcp_auth(server, mcp_auth_header="Bearer user-tok")
+    assert result == "Bearer user-tok"
+
+
+@pytest.mark.asyncio
+async def test_falls_back_to_static_token():
+    """When no client_credentials config, resolve_mcp_auth returns the static authentication_token."""
+    server = _server(
+        client_id=None,
+        client_secret=None,
+        token_url=None,
+        authentication_token="static-tok-xyz",
+    )
+    result = await resolve_mcp_auth(server)
+    assert result == "static-tok-xyz"
+
+
+def test_needs_user_oauth_token_property():
+    """needs_user_oauth_token is True only for OAuth2 servers WITHOUT client_credentials."""
+    # OAuth2 with credentials → M2M, no user token needed
+    assert _server().needs_user_oauth_token is False
+
+    # OAuth2 without credentials → needs per-user token
+    assert _server(client_id=None, client_secret=None, token_url=None).needs_user_oauth_token is True
+
+    # Non-OAuth2 → never needs user OAuth token
+    assert _server(auth_type=MCPAuth.bearer_token).needs_user_oauth_token is False
+
+
+@pytest.mark.asyncio
+async def test_http_error_raises_value_error():
+    """HTTP errors from the token endpoint are wrapped in a clear ValueError."""
+    server = _server()
+    mock_response = MagicMock()
+    mock_response.status_code = 401
+    mock_response.raise_for_status.side_effect = httpx.HTTPStatusError(
+        "Unauthorized", request=MagicMock(), response=mock_response,
+    )
+    mock_client = AsyncMock()
+    mock_client.post.return_value = mock_response
+
+    with patch(
+        "litellm.proxy._experimental.mcp_server.oauth2_token_cache.get_async_httpx_client",
+        return_value=mock_client,
+    ), pytest.raises(ValueError, match="failed with status 401"):
+        await resolve_mcp_auth(server)
+
+
+@pytest.mark.asyncio
+async def test_non_dict_response_raises_value_error():
+    """A non-dict JSON response raises a clear ValueError."""
+    server = _server()
+    resp = MagicMock()
+    resp.json.return_value = ["not", "a", "dict"]
+    resp.raise_for_status = MagicMock()
+    mock_client = AsyncMock()
+    mock_client.post.return_value = resp
+
+    with patch(
+        "litellm.proxy._experimental.mcp_server.oauth2_token_cache.get_async_httpx_client",
+        return_value=mock_client,
+    ), pytest.raises(ValueError, match="non-object JSON"):
+        await resolve_mcp_auth(server)
diff --git a/tests/test_litellm/proxy/_experimental/mcp_server/test_rest_endpoints.py b/tests/test_litellm/proxy/_experimental/mcp_server/test_rest_endpoints.py
index 3091f03a53d..f6c8115f7bc 100644
--- a/tests/test_litellm/proxy/_experimental/mcp_server/test_rest_endpoints.py
+++ b/tests/test_litellm/proxy/_experimental/mcp_server/test_rest_endpoints.py
@@ -76,7 +76,7 @@ def _route_has_dependency(route, dependency) -> bool:
 class TestExecuteWithMcpClient:
     @pytest.mark.asyncio
     async def test_redacts_stack_trace(self, monkeypatch):
-        def fake_create_client(*args, **kwargs):
+        async def fake_create_client(*args, **kwargs):
             return object()
 
         monkeypatch.setattr(
@@ -114,7 +114,7 @@ class TestExecuteWithMcpClient:
         def fake_build_stdio_env(server, raw_headers):
             return None
 
-        def fake_create_client(*args, **kwargs):
+        async def fake_create_client(*args, **kwargs):
             captured["extra_headers"] = kwargs.get("extra_headers")
             return object()