From 391b8a265b7c5285b2640361268ec67b72c143f3 Mon Sep 17 00:00:00 2001
From: Atharva-Kanherkar <142440039+Atharva-Kanherkar@users.noreply.github.com>
Date: Mon, 7 Sep 2026 18:40:43 +0530
Subject: [PATCH 01/55] fix(responses): stream one lifecycle across MCP
 auto-execute rounds

Each auto-executed MCP round is a distinct upstream response, but the
client reads one stream. The follow-up round's response.created,
response.in_progress, and the interim response.completed were forwarded
as-is, so one SSE body carried two lifecycles and output_index restarted
at zero, which aborts accumulating clients such as the OpenAI SDK's
responses.stream() before the final answer arrives.

Fold the rounds into one public lifecycle: drop the openers of follow-up
rounds, hold back the completed event of a round whose tool calls the
gateway executes, shift later output indexes past the items already
emitted, and list every round's items on the single final
response.completed. Each mcp_call item is announced with
output_item.added, keeps one item id across its events, and owns its own
output_index. Sequence numbers stay strictly increasing when a round or a
gateway event restarts numbering. The final round's response id is kept
on response.completed so previous_response_id continuation still works.
---
 .../responses/mcp/mcp_streaming_iterator.py   | 212 ++++++++++++++----
 1 file changed, 166 insertions(+), 46 deletions(-)

diff --git a/litellm/responses/mcp/mcp_streaming_iterator.py b/litellm/responses/mcp/mcp_streaming_iterator.py
index ca12b3e7cc3..ac158a32371 100644
--- a/litellm/responses/mcp/mcp_streaming_iterator.py
+++ b/litellm/responses/mcp/mcp_streaming_iterator.py
@@ -34,6 +34,16 @@ else:
 MAX_MCP_TOOL_CALL_ROUNDS: Final = 5
 
 
+def _output_items(response: ResponsesAPIResponse) -> Sequence[object]:
+    """Read a response's output items as plain objects; the field is a wide union of item models."""
+    return tuple(cast("Sequence[object]", response.output))  # cast-ok: items are only carried, never inspected
+
+
+def _set_event_field(event: ResponsesAPIStreamingResponse, name: str, value: object) -> None:
+    """Events are pydantic models with extra fields allowed, so any event type can carry the field."""
+    setattr(event, name, value)
+
+
 async def create_mcp_list_tools_events(
     mcp_tools_with_litellm_proxy: Sequence[Mapping[str, object]],
     user_api_key_auth: "UserAPIKeyAuth | None",
@@ -170,6 +180,7 @@ def create_mcp_call_events(
     result: str | None = None,
     base_item_id: str | None = None,
     sequence_start: int = 1,
+    output_index: int = 0,
 ) -> list[ResponsesAPIStreamingResponse]:
     """Create MCP call events following OpenAI's specification"""
     events: Final[list[ResponsesAPIStreamingResponse]] = []
@@ -179,7 +190,7 @@ def create_mcp_call_events(
     in_progress_event: Final = MCPCallInProgressEvent(
         type=ResponsesAPIStreamEvents.MCP_CALL_IN_PROGRESS,
         sequence_number=sequence_start,
-        output_index=0,
+        output_index=output_index,
         item_id=item_id,
     )
     events.append(in_progress_event)
@@ -187,7 +198,7 @@ def create_mcp_call_events(
     # MCP call arguments delta event (streaming the arguments)
     arguments_delta_event: Final = MCPCallArgumentsDeltaEvent(
         type=ResponsesAPIStreamEvents.MCP_CALL_ARGUMENTS_DELTA,
-        output_index=0,
+        output_index=output_index,
         item_id=item_id,
         delta=arguments,  # JSON string with arguments
         sequence_number=sequence_start + 1,
@@ -197,7 +208,7 @@ def create_mcp_call_events(
     # MCP call arguments done event
     arguments_done_event: Final = MCPCallArgumentsDoneEvent(
         type=ResponsesAPIStreamEvents.MCP_CALL_ARGUMENTS_DONE,
-        output_index=0,
+        output_index=output_index,
         item_id=item_id,
         arguments=arguments,  # Complete JSON string with finalized arguments
         sequence_number=sequence_start + 2,
@@ -210,7 +221,7 @@ def create_mcp_call_events(
             type=ResponsesAPIStreamEvents.MCP_CALL_COMPLETED,
             sequence_number=sequence_start + 3,
             item_id=item_id,
-            output_index=0,
+            output_index=output_index,
         )
         events.append(completed_event)
 
@@ -219,7 +230,7 @@ def create_mcp_call_events(
 
         output_item_done_event: Final = OutputItemDoneEvent(
             type=ResponsesAPIStreamEvents.OUTPUT_ITEM_DONE,
-            output_index=0,
+            output_index=output_index,
             item=BaseLiteLLMOpenAIResponseObject(
                 **{
                     "id": item_id,
@@ -239,7 +250,7 @@ def create_mcp_call_events(
             type=ResponsesAPIStreamEvents.MCP_CALL_FAILED,
             sequence_number=sequence_start + 3,
             item_id=item_id,
-            output_index=0,
+            output_index=output_index,
         )
         events.append(failed_event)
 
@@ -330,6 +341,17 @@ class MCPEnhancedStreamingIterator(BaseResponsesAPIStreamingIterator):
         self._error_event_emitted = False
         self._last_sequence_number = 0
 
+        # Every auto-execute round is a distinct upstream response, but the
+        # client is reading one stream. Fold the rounds into one public
+        # lifecycle: one response.created, one response.completed whose
+        # output holds every round's items, and output indexes that are
+        # never reused for a different item.
+        self._round_index = 0
+        self._output_index_offset = 0
+        self._round_max_output_index = -1
+        self._composed_output: list[object] = []  # mutable-ok: grows as each round finishes
+        self._pending_mcp_call_items: list[dict[str, object]] = []  # mutable-ok: grows per executed tool
+
     def _extract_mcp_headers_from_params(self) -> None:
         """Extract MCP headers from original request params to pass to tool calls"""
 
@@ -415,8 +437,14 @@ class MCPEnhancedStreamingIterator(BaseResponsesAPIStreamingIterator):
     async def __anext__(self) -> ResponsesAPIStreamingResponse:
         chunk: Final = await self._anext_impl()
         sequence_number: Final = getattr(chunk, "sequence_number", None)
-        if isinstance(sequence_number, int) and sequence_number > self._last_sequence_number:
-            self._last_sequence_number = sequence_number
+        if isinstance(sequence_number, int):
+            # Follow-up rounds and gateway events restart their numbering.
+            # Keep the public stream strictly increasing.
+            if sequence_number <= self._last_sequence_number and self._last_sequence_number > 0:
+                self._last_sequence_number += 1
+                _set_event_field(chunk, "sequence_number", self._last_sequence_number)
+            else:
+                self._last_sequence_number = max(self._last_sequence_number, sequence_number)
         return chunk
 
     async def _anext_impl(self) -> ResponsesAPIStreamingResponse:
@@ -472,7 +500,7 @@ class MCPEnhancedStreamingIterator(BaseResponsesAPIStreamingIterator):
             await self._create_follow_up_iterator()
             if self.base_iterator is not None:
                 self.phase = "continue_initial_response"
-                return await self.__anext__()
+                return await self._anext_impl()
             self.phase = "finished"
             if self._stream_error is not None and not self._error_event_emitted:
                 self._error_event_emitted = True
@@ -530,17 +558,11 @@ class MCPEnhancedStreamingIterator(BaseResponsesAPIStreamingIterator):
                         if chunk_type == ResponsesAPIStreamEvents.OUTPUT_ITEM_ADDED:
                             self.initial_events_emitted = True
                             self.phase = "mcp_discovery"
-                            return chunk
+                            return await self._compose_round_chunk(chunk)
 
-                    # If auto-execution is enabled, check for completed responses
-                    if self.should_auto_execute and self._is_response_completed(chunk):
-                        response_obj = getattr(chunk, "response", None)
-                        if isinstance(response_obj, ResponsesAPIResponse):
-                            self.collected_response = response_obj
-                        self.phase = "tool_execution"
-                        await self._generate_tool_execution_events()
-
-                    return chunk
+                    # None means the chunk was folded into the single public
+                    # lifecycle; fall through so phase 4 runs the follow-up.
+                    return await self._compose_round_chunk(chunk)
                 except StopAsyncIteration:
                     if self.should_auto_execute and self.collected_response:
                         self.phase = "tool_execution"
@@ -566,6 +588,69 @@ class MCPEnhancedStreamingIterator(BaseResponsesAPIStreamingIterator):
         chunk_type: Final[object] = getattr(chunk, "type", None)
         return chunk_type == ResponsesAPIStreamEvents.RESPONSE_COMPLETED
 
+    def _follow_up_pending(self) -> bool:
+        """True when the current round's tool calls were executed and a follow-up round will run."""
+        return self.collected_response is not None and self.collected_response is self._tool_results_for_response
+
+    def _round_output_width(self, response: ResponsesAPIResponse) -> int:
+        """How many output indexes this round used, counting items it streamed but never listed."""
+        return max(len(_output_items(response)), self._round_max_output_index + 1)
+
+    def _absorb_round(self, response: ResponsesAPIResponse) -> None:
+        """Bank a finished round's items so the final response.completed can list them."""
+        width: Final = self._round_output_width(response)
+        self._composed_output.extend(_output_items(response))
+        self._composed_output.extend(self._pending_mcp_call_items)
+        self._output_index_offset += width + len(self._pending_mcp_call_items)
+        self._pending_mcp_call_items = []
+        self._round_max_output_index = -1
+
+    async def _compose_round_chunk(self, chunk: ResponsesAPIStreamingResponse) -> ResponsesAPIStreamingResponse | None:
+        """
+        Fold one round's event into the single public lifecycle.
+
+        Returns None when the event must not reach the client: the lifecycle
+        openers of a follow-up round, and the response.completed of a round
+        whose tool calls the gateway executes itself. Shifts output_index on
+        follow-up rounds past the items already emitted, and lists every
+        round's items on the final response.completed.
+        """
+        chunk_type: Final[object] = getattr(chunk, "type", None)
+        if self._round_index > 0 and chunk_type in (
+            ResponsesAPIStreamEvents.RESPONSE_CREATED,
+            ResponsesAPIStreamEvents.RESPONSE_IN_PROGRESS,
+        ):
+            return None
+
+        output_index: Final[object] = getattr(chunk, "output_index", None)
+        if isinstance(output_index, int):
+            self._round_max_output_index = max(self._round_max_output_index, output_index)
+            if self._output_index_offset:
+                _set_event_field(chunk, "output_index", output_index + self._output_index_offset)
+
+        if not (self.should_auto_execute and self._is_response_completed(chunk)):
+            return chunk
+
+        response_obj: Final[object] = getattr(chunk, "response", None)
+        if isinstance(response_obj, ResponsesAPIResponse):
+            self.collected_response = response_obj
+        # Move to tool execution phase after this chunk
+        self.phase = "tool_execution"
+        await self._generate_tool_execution_events()
+
+        if not isinstance(response_obj, ResponsesAPIResponse):
+            return chunk
+        if self._follow_up_pending():
+            self._absorb_round(response_obj)
+            return None
+        if self._composed_output:
+            merged_output: Final[list[object]] = [  # mutable-ok: the response model declares output as a list
+                *self._composed_output,
+                *_output_items(response_obj),
+            ]
+            _set_event_field(chunk, "response", response_obj.model_copy(update={"output": merged_output}))
+        return chunk
+
     async def _process_base_iterator_chunk(self) -> ResponsesAPIStreamingResponse:
         """
         Process a chunk from the base iterator with response ID consistency enforcement.
@@ -593,17 +678,11 @@ class MCPEnhancedStreamingIterator(BaseResponsesAPIStreamingIterator):
                     )
                     response_obj.id = self._cached_response_id
 
-        # If auto-execution is enabled, check for completed responses
-        if self.should_auto_execute and self._is_response_completed(chunk):
-            # Collect the response for tool execution
-            response_obj = getattr(chunk, "response", None)
-            if isinstance(response_obj, ResponsesAPIResponse):
-                self.collected_response = response_obj
-            # Move to tool execution phase after emitting this chunk
-            self.phase = "tool_execution"
-            await self._generate_tool_execution_events()
-
-        return chunk
+        composed: Final = await self._compose_round_chunk(chunk)
+        if composed is None:
+            # The chunk stays internal; hand the next public event back instead.
+            return await self._anext_impl()
+        return composed
 
     async def _create_initial_response_iterator(self) -> None:
         """Create the initial response iterator by making the first LLM call"""
@@ -667,6 +746,16 @@ class MCPEnhancedStreamingIterator(BaseResponsesAPIStreamingIterator):
                 return
             self.tool_call_round += 1
 
+            # Each executed tool is one mcp_call output item of the single
+            # public response. Announce it at an output_index past the items
+            # this round already streamed, and keep that item id for the
+            # completion events below.
+            from litellm.types.llms.openai import OutputItemAddedEvent
+
+            next_output_index = self._output_index_offset + self._round_output_width(  # rebind-ok: advances per item
+                self.collected_response
+            )
+            call_items: Final[dict[str, tuple[str, int]]] = {}  # mutable-ok: filled per tool call as events queue
             for tool_call in tool_calls:
                 (
                     tool_name,
@@ -674,14 +763,36 @@ class MCPEnhancedStreamingIterator(BaseResponsesAPIStreamingIterator):
                     tool_call_id,
                 ) = LiteLLM_Proxy_MCP_Handler._extract_tool_call_details(tool_call)
                 if tool_name and tool_call_id:
+                    item_id = f"mcp_{uuid.uuid4().hex[:8]}"
+                    output_index = next_output_index
+                    next_output_index += 1
+                    call_items[tool_call_id] = (item_id, output_index)
+                    self.tool_execution_events.append(
+                        OutputItemAddedEvent.model_validate(
+                            {
+                                "type": ResponsesAPIStreamEvents.OUTPUT_ITEM_ADDED,
+                                "sequence_number": len(self.tool_execution_events) + 1,
+                                "output_index": output_index,
+                                "item": {
+                                    "id": item_id,
+                                    "type": "mcp_call",
+                                    "status": "in_progress",
+                                    "arguments": tool_arguments or "{}",
+                                    "name": tool_name,
+                                    "server_label": "litellm",
+                                },
+                            }
+                        )
+                    )
                     # Create MCP call events for this tool execution
                     call_events = create_mcp_call_events(
                         tool_name=tool_name,
                         tool_call_id=tool_call_id,
                         arguments=tool_arguments or "{}",  # JSON string with arguments
                         result=None,  # Will be set after execution
-                        base_item_id=f"mcp_{uuid.uuid4().hex[:8]}",
+                        base_item_id=item_id,
                         sequence_start=len(self.tool_execution_events) + 1,
+                        output_index=output_index,
                     )
                     # Add the in_progress and arguments events (not the completed event yet)
                     self.tool_execution_events.extend(call_events[:-1])
@@ -719,37 +830,45 @@ class MCPEnhancedStreamingIterator(BaseResponsesAPIStreamingIterator):
                         tool_arguments = args or "{}"
                         break
 
-                item_id = f"mcp_{uuid.uuid4().hex[:8]}"
+                if tool_call_id in call_items:
+                    item_id, output_index = call_items[tool_call_id]
+                else:
+                    item_id = f"mcp_{uuid.uuid4().hex[:8]}"
+                    output_index = next_output_index
+                    next_output_index += 1
 
                 # Create the completion event
                 completed_event = MCPCallCompletedEvent(
                     type=ResponsesAPIStreamEvents.MCP_CALL_COMPLETED,
                     sequence_number=len(self.tool_execution_events) + 1,
                     item_id=item_id,
-                    output_index=0,
+                    output_index=output_index,
                 )
                 self.tool_execution_events.append(completed_event)
 
                 # Create output_item.done event with the tool call result
                 from litellm.types.llms.openai import OutputItemDoneEvent
 
+                mcp_call_item = BaseLiteLLMOpenAIResponseObject(
+                    **{
+                        "id": item_id,
+                        "type": "mcp_call",
+                        "approval_request_id": f"mcpr_{uuid.uuid4().hex[:8]}",
+                        "arguments": tool_arguments,
+                        "error": None,
+                        "name": tool_name,
+                        "output": result_text,
+                        "server_label": "litellm",  # or extract from tool config
+                    }
+                )
                 output_item_done_event = OutputItemDoneEvent(
                     type=ResponsesAPIStreamEvents.OUTPUT_ITEM_DONE,
-                    output_index=0,
-                    item=BaseLiteLLMOpenAIResponseObject(
-                        **{
-                            "id": item_id,
-                            "type": "mcp_call",
-                            "approval_request_id": f"mcpr_{uuid.uuid4().hex[:8]}",
-                            "arguments": tool_arguments,
-                            "error": None,
-                            "name": tool_name,
-                            "output": result_text,
-                            "server_label": "litellm",  # or extract from tool config
-                        }
-                    ),
+                    output_index=output_index,
+                    item=mcp_call_item,
                 )
                 self.tool_execution_events.append(output_item_done_event)
+                # The response model accepts output items as dicts, not as the generic event object.
+                self._pending_mcp_call_items.append(mcp_call_item.model_dump())
 
             # Store tool results for follow-up call
             self.tool_results = tool_results
@@ -824,6 +943,7 @@ class MCPEnhancedStreamingIterator(BaseResponsesAPIStreamingIterator):
                 self.base_iterator = follow_up_response
                 self.collected_response = None
                 self._cached_response_id = None
+                self._round_index += 1
 
         except Exception as e:
             verbose_logger.error("Error creating follow-up iterator: %s", e)

From 13ce30488ff6eed68c213a80a41a38979a279e59 Mon Sep 17 00:00:00 2001
From: Atharva-Kanherkar <142440039+Atharva-Kanherkar@users.noreply.github.com>
Date: Mon, 7 Sep 2026 18:40:43 +0530
Subject: [PATCH 02/55] test(responses): cover the single public lifecycle for
 MCP rounds

Assert one response.created and one response.completed across rounds,
dense output indexes for the function call, the mcp_call item, and the
final message, stable mcp_call item ids, strictly increasing sequence
numbers, a serializable merged output, and that a stream without
auto-execution is forwarded unchanged. Update the two existing tests that
counted one completed event per internal round.
---
 .../mcp/test_mcp_streaming_iterator.py        | 128 +++++++++++++++++-
 1 file changed, 122 insertions(+), 6 deletions(-)

diff --git a/tests/test_litellm/responses/mcp/test_mcp_streaming_iterator.py b/tests/test_litellm/responses/mcp/test_mcp_streaming_iterator.py
index 5001589ce54..57ccbbfa493 100644
--- a/tests/test_litellm/responses/mcp/test_mcp_streaming_iterator.py
+++ b/tests/test_litellm/responses/mcp/test_mcp_streaming_iterator.py
@@ -57,6 +57,10 @@ def _text_message(text: str):
     return {"type": "message", "role": "assistant", "content": [{"type": "output_text", "text": text}]}
 
 
+def _item_type(item) -> str:
+    return item["type"] if isinstance(item, dict) else item.type
+
+
 def _tool_call_stream(call_id: str, tool_name: str, response_id: str = "resp-1") -> _FakeAsyncStream:
     return _FakeAsyncStream([_completed_chunk([_function_call(call_id, tool_name)], response_id=response_id)])
 
@@ -134,11 +138,19 @@ async def test_second_round_tool_call_is_executed_and_reaches_final_text(monkeyp
     assert iterator.tool_call_round == 2
 
     # The stream reached round 3 and produced the final text response instead
-    # of stopping after round 1 or round 2.
+    # of stopping after round 1 or round 2. The client sees one lifecycle whose
+    # final output lists every round's items in order.
     completed_chunks = [c for c in chunks if getattr(c, "type", None) == ResponsesAPIStreamEvents.RESPONSE_COMPLETED]
-    assert len(completed_chunks) == 3
+    assert len(completed_chunks) == 1
     final_output = completed_chunks[-1].response.output
-    assert final_output[0]["content"][0]["text"] == "Here's what I found after retrying."
+    assert [_item_type(item) for item in final_output] == [
+        "function_call",
+        "mcp_call",
+        "function_call",
+        "mcp_call",
+        "message",
+    ]
+    assert final_output[-1]["content"][0]["text"] == "Here's what I found after retrying."
 
 
 @pytest.mark.asyncio
@@ -207,7 +219,7 @@ async def test_continuation_id_is_final_round_not_interim_tool_call(monkeypatch)
     chunks = [chunk async for chunk in iterator]
     completed = [c for c in chunks if getattr(c, "type", None) == ResponsesAPIStreamEvents.RESPONSE_COMPLETED]
 
-    assert completed[-1].response.output[0]["content"][0]["text"] == "The first item is Alpha."
+    assert completed[-1].response.output[-1]["content"][0]["text"] == "The first item is Alpha."
     assert completed[-1].response.id == "resp-final"
     assert completed[-1].response.id != "resp-interim"
 
@@ -280,7 +292,9 @@ async def test_streaming_follow_up_replays_reasoning_when_store_is_false(monkeyp
         base_iterator=_FakeAsyncStream(
             [
                 _output_item_added_chunk(),
-                _completed_chunk([_reasoning_item("gAAAAA-opaque-blob"), _function_call("call_1", "read_wiki_contents")]),
+                _completed_chunk(
+                    [_reasoning_item("gAAAAA-opaque-blob"), _function_call("call_1", "read_wiki_contents")]
+                ),
             ]
         ),
         mcp_events=[],
@@ -316,7 +330,9 @@ async def test_streaming_follow_up_keeps_previous_response_id_when_stored(monkey
         base_iterator=_FakeAsyncStream(
             [
                 _output_item_added_chunk(),
-                _completed_chunk([_reasoning_item("gAAAAA-opaque-blob"), _function_call("call_1", "read_wiki_contents")]),
+                _completed_chunk(
+                    [_reasoning_item("gAAAAA-opaque-blob"), _function_call("call_1", "read_wiki_contents")]
+                ),
             ]
         ),
         mcp_events=[],
@@ -336,3 +352,103 @@ async def test_streaming_follow_up_keeps_previous_response_id_when_stored(monkey
     follow_up_kwargs = aresponses_mock.call_args_list[0].kwargs
     assert follow_up_kwargs["previous_response_id"] == "resp_prev"
     assert not [item for item in follow_up_kwargs["input"] if item.get("type") == "reasoning"]
+
+
+def _event(event_type, **fields):
+    return SimpleNamespace(type=event_type, **fields)
+
+
+def _lifecycle_round(response_id: str, item: dict, sequence_start: int = 0):
+    """One upstream Responses round as a provider streams it: its own id, indexes from 0, numbering from 0."""
+    return [
+        _event(
+            ResponsesAPIStreamEvents.RESPONSE_CREATED,
+            response=ResponsesAPIResponse(id=response_id, created_at=0, output=[]),
+            sequence_number=sequence_start,
+        ),
+        _event(
+            ResponsesAPIStreamEvents.OUTPUT_ITEM_ADDED, output_index=0, item=item, sequence_number=sequence_start + 1
+        ),
+        _event(
+            ResponsesAPIStreamEvents.OUTPUT_ITEM_DONE, output_index=0, item=item, sequence_number=sequence_start + 2
+        ),
+        _completed_chunk([item], response_id=response_id),
+    ]
+
+
+@pytest.mark.asyncio
+async def test_auto_execute_rounds_share_one_public_lifecycle(monkeypatch):
+    """
+    Every auto-execute round is a distinct upstream response, but the client
+    reads one stream. It must see one response.created, one response.completed,
+    and no output_index reused for a different item, otherwise accumulating
+    clients such as the OpenAI SDK's responses.stream() abort mid-stream.
+    """
+    _mock_mcp_environment(monkeypatch)
+
+    follow_up = _FakeAsyncStream(_lifecycle_round("resp-final", _text_message("Alpha.")))
+    monkeypatch.setattr(responses_main_module, "aresponses", AsyncMock(side_effect=[follow_up]))
+
+    iterator = _make_iterator(_lifecycle_round("resp-interim", _function_call("call_1", "read_wiki_contents")))
+    chunks = [chunk async for chunk in iterator]
+    types = [chunk.type for chunk in chunks]
+
+    assert types.count(ResponsesAPIStreamEvents.RESPONSE_CREATED) == 1
+    assert types.count(ResponsesAPIStreamEvents.RESPONSE_COMPLETED) == 1
+    assert types[-1] == ResponsesAPIStreamEvents.RESPONSE_COMPLETED
+
+    # The function call, the gateway's mcp_call, and the final message each own an index.
+    added = [c for c in chunks if c.type == ResponsesAPIStreamEvents.OUTPUT_ITEM_ADDED]
+    assert [(c.output_index, _item_type(c.item)) for c in added] == [
+        (0, "function_call"),
+        (1, "mcp_call"),
+        (2, "message"),
+    ]
+    mcp_item_ids = {c.item_id for c in chunks if c.type == ResponsesAPIStreamEvents.MCP_CALL_IN_PROGRESS}
+    mcp_done = [
+        c for c in chunks if c.type == ResponsesAPIStreamEvents.OUTPUT_ITEM_DONE and _item_type(c.item) == "mcp_call"
+    ]
+    assert [c.output_index for c in mcp_done] == [1]
+    assert {c.item.id for c in mcp_done} == mcp_item_ids
+    round_two = [
+        c for c in chunks if getattr(c, "item_id", None) is None and getattr(c, "output_index", None) is not None
+    ]
+    assert max(c.output_index for c in round_two) == 2
+
+    # The single completed event lists every round's items and keeps the final round's id for continuation.
+    completed = chunks[-1]
+    assert completed.response.id == "resp-final"
+    assert [_item_type(item) for item in completed.response.output] == ["function_call", "mcp_call", "message"]
+    assert completed.response.output[-1]["content"][0]["text"] == "Alpha."
+    # The proxy serializes every chunk; the merged output must still be a valid response.
+    assert '"type":"mcp_call"' in completed.response.model_dump_json(exclude_none=True, exclude_unset=True)
+
+    # Numbering stays strictly increasing across rounds and gateway events.
+    sequence_numbers = [c.sequence_number for c in chunks if getattr(c, "sequence_number", None) is not None]
+    assert sequence_numbers == sorted(sequence_numbers)
+    assert len(set(sequence_numbers)) == len(sequence_numbers)
+
+
+@pytest.mark.asyncio
+async def test_stream_without_auto_execute_is_forwarded_unchanged(monkeypatch):
+    """With approval required there is one round, and it passes through untouched."""
+    _mock_mcp_environment(monkeypatch)
+    aresponses_mock = AsyncMock()
+    monkeypatch.setattr(responses_main_module, "aresponses", aresponses_mock)
+
+    upstream = _lifecycle_round("resp-1", _function_call("call_1", "read_wiki_contents"))
+    iterator = MCPEnhancedStreamingIterator(
+        base_iterator=_FakeAsyncStream(list(upstream)),
+        mcp_events=[],
+        tool_server_map={"read_wiki_contents": "deepwiki"},
+        mcp_tools_with_litellm_proxy=[{"require_approval": "always"}],
+        user_api_key_auth=None,
+        original_request_params={"model": "gpt-4", "input": "hi", "tools": [{"type": "mcp"}]},
+    )
+
+    chunks = [chunk async for chunk in iterator]
+
+    assert chunks == upstream
+    assert [c.output_index for c in chunks if hasattr(c, "output_index")] == [0, 0]
+    assert [c.sequence_number for c in chunks if hasattr(c, "sequence_number")] == [0, 1, 2]
+    aresponses_mock.assert_not_called()

From 146e5c492b1bee31a57c77a8fafff74122a13df9 Mon Sep 17 00:00:00 2001
From: Atharva-Kanherkar <142440039+Atharva-Kanherkar@users.noreply.github.com>
Date: Mon, 7 Sep 2026 18:49:04 +0530
Subject: [PATCH 03/55] fix(responses): keep the MCP lifecycle change within
 the type-discipline budget

Mark the dict literals handed straight to model constructors, clear the pending mcp_call list in place, and bind the merged response before setting it on the event, so LIT002 stays at or below its base count.
---
 litellm/responses/mcp/mcp_streaming_iterator.py | 13 ++++++++-----
 1 file changed, 8 insertions(+), 5 deletions(-)

diff --git a/litellm/responses/mcp/mcp_streaming_iterator.py b/litellm/responses/mcp/mcp_streaming_iterator.py
index ac158a32371..1c892eec803 100644
--- a/litellm/responses/mcp/mcp_streaming_iterator.py
+++ b/litellm/responses/mcp/mcp_streaming_iterator.py
@@ -602,7 +602,7 @@ class MCPEnhancedStreamingIterator(BaseResponsesAPIStreamingIterator):
         self._composed_output.extend(_output_items(response))
         self._composed_output.extend(self._pending_mcp_call_items)
         self._output_index_offset += width + len(self._pending_mcp_call_items)
-        self._pending_mcp_call_items = []
+        self._pending_mcp_call_items.clear()
         self._round_max_output_index = -1
 
     async def _compose_round_chunk(self, chunk: ResponsesAPIStreamingResponse) -> ResponsesAPIStreamingResponse | None:
@@ -648,7 +648,10 @@ class MCPEnhancedStreamingIterator(BaseResponsesAPIStreamingIterator):
                 *self._composed_output,
                 *_output_items(response_obj),
             ]
-            _set_event_field(chunk, "response", response_obj.model_copy(update={"output": merged_output}))
+            merged_response: Final = response_obj.model_copy(
+                update={"output": merged_output}  # mutable-ok: pydantic's update argument must be a dict
+            )
+            _set_event_field(chunk, "response", merged_response)
         return chunk
 
     async def _process_base_iterator_chunk(self) -> ResponsesAPIStreamingResponse:
@@ -769,11 +772,11 @@ class MCPEnhancedStreamingIterator(BaseResponsesAPIStreamingIterator):
                     call_items[tool_call_id] = (item_id, output_index)
                     self.tool_execution_events.append(
                         OutputItemAddedEvent.model_validate(
-                            {
+                            {  # mutable-ok: consumed once by model_validate
                                 "type": ResponsesAPIStreamEvents.OUTPUT_ITEM_ADDED,
                                 "sequence_number": len(self.tool_execution_events) + 1,
                                 "output_index": output_index,
-                                "item": {
+                                "item": {  # mutable-ok: consumed once by model_validate
                                     "id": item_id,
                                     "type": "mcp_call",
                                     "status": "in_progress",
@@ -850,7 +853,7 @@ class MCPEnhancedStreamingIterator(BaseResponsesAPIStreamingIterator):
                 from litellm.types.llms.openai import OutputItemDoneEvent
 
                 mcp_call_item = BaseLiteLLMOpenAIResponseObject(
-                    **{
+                    **{  # mutable-ok: consumed once by the model constructor
                         "id": item_id,
                         "type": "mcp_call",
                         "approval_request_id": f"mcpr_{uuid.uuid4().hex[:8]}",

From fa966ca2d0bc9bca963112c8befbda5997f306ef Mon Sep 17 00:00:00 2001
From: mateo-berri <277851410+mateo-berri@users.noreply.github.com>
Date: Tue, 8 Sep 2026 08:10:30 +0000
Subject: [PATCH 04/55] refactor(types): replace Any with real types across 20
 backend files

Fifth round of basedpyright Any reduction. Every change is typing-only and
leaves runtime behavior identical.

Prisma table access now goes through the PrismaTableRepository and TableActions
protocols the repo already has, instead of reading untyped attributes off
prisma_client.db. Payload and parameter annotations move from dict[str, Any] to
dict[str, object] or Mapping[str, object]. Guardrail constructors that took
**kwargs: Any now take Unpack of a PEP 728 TypedDict, the same
_CustomGuardrailOptions shape three other guardrails already use. Calls into the
OpenAI and Azure assistants SDKs pass explicit keywords rather than splatting a
dict, so the arguments are checked against the real SDK signatures.
---
 litellm/llms/azure/assistants.py              |  9 +--
 litellm/llms/ollama/chat/transformation.py    |  2 +-
 .../llms/ollama/completion/transformation.py  |  2 +-
 litellm/llms/openai/openai.py                 | 61 ++++++++++++++-----
 litellm/llms/vertex_ai/fine_tuning/handler.py |  5 +-
 .../vertex_imagen_transformation.py           | 25 ++++----
 .../vertex_gemini_transformation.py           |  6 +-
 litellm/proxy/_experimental/mcp_server/db.py  |  8 ++-
 .../proxy/common_utils/reset_budget_job.py    | 15 +++--
 .../cisco_ai_defense/cisco_ai_defense.py      |  7 ++-
 .../guardrail_hooks/deepkeep/deepkeep.py      | 14 +++--
 .../guardrail_hooks/headroom/headroom.py      | 13 ++--
 .../model_armor/model_armor.py                |  6 +-
 .../auto_router_endpoints.py                  | 10 +--
 .../spend_tracking/ptu_flat_cost_rollup.py    | 30 +++++++--
 litellm/proxy/utils.py                        | 11 ++--
 litellm/realtime_api/main.py                  |  2 +-
 litellm/repositories/model_repository.py      | 20 ++----
 litellm/repositories/team_repository.py       | 42 ++++++++++++-
 .../router_utils/fallback_event_handlers.py   | 11 ++--
 20 files changed, 199 insertions(+), 100 deletions(-)

diff --git a/litellm/llms/azure/assistants.py b/litellm/llms/azure/assistants.py
index f7b419405ac..a4742a25a87 100644
--- a/litellm/llms/azure/assistants.py
+++ b/litellm/llms/azure/assistants.py
@@ -1,5 +1,5 @@
 from collections.abc import Coroutine, Iterable
-from typing import Any, Final, Literal, TypedDict
+from typing import Final, Literal, TypedDict
 
 import httpx
 from openai import AsyncAzureOpenAI, AzureOpenAI
@@ -715,7 +715,8 @@ class AzureAssistantsAPI(BaseAzureLLM):
         event_handler: AssistantEventHandler | None,
         litellm_params: dict | None = None,
     ) -> AsyncAssistantStreamManager[AsyncAssistantEventHandler]:
-        data: Final[dict[str, Any]] = {
+        stream_fn: Final = client.beta.threads.runs.stream
+        base_data: Final[_RunThreadStreamData] = {
             "thread_id": thread_id,
             "assistant_id": assistant_id,
             "additional_instructions": additional_instructions,
@@ -725,8 +726,8 @@ class AzureAssistantsAPI(BaseAzureLLM):
             "tools": tools,
         }
         if event_handler is not None:
-            data["event_handler"] = event_handler
-        return client.beta.threads.runs.stream(**data)
+            return stream_fn(**base_data, event_handler=event_handler)
+        return stream_fn(**base_data)
 
     def run_thread_stream(
         self,
diff --git a/litellm/llms/ollama/chat/transformation.py b/litellm/llms/ollama/chat/transformation.py
index 181894646e3..257ebf921d9 100644
--- a/litellm/llms/ollama/chat/transformation.py
+++ b/litellm/llms/ollama/chat/transformation.py
@@ -124,7 +124,7 @@ class OllamaChatConfig(BaseConfig):
                 setattr(self.__class__, key, value)
 
     @classmethod
-    def get_config(cls):
+    def get_config(cls) -> dict[str, object]:
         return super().get_config()
 
     def get_supported_openai_params(self, model: str):
diff --git a/litellm/llms/ollama/completion/transformation.py b/litellm/llms/ollama/completion/transformation.py
index dccc83efed4..a9bbfedafd6 100644
--- a/litellm/llms/ollama/completion/transformation.py
+++ b/litellm/llms/ollama/completion/transformation.py
@@ -227,7 +227,7 @@ class OllamaConfig(BaseConfig):
         model: str,
         api_base: str | None = None,
         api_key: str | None = None,
-    ) -> Any:
+    ) -> dict[str, object] | None:
         """
         curl http://localhost:11434/api/show -d '{
           "name": "mistral"
diff --git a/litellm/llms/openai/openai.py b/litellm/llms/openai/openai.py
index edc8d64d9c2..15c543b94f0 100644
--- a/litellm/llms/openai/openai.py
+++ b/litellm/llms/openai/openai.py
@@ -1,7 +1,7 @@
 import time
 import types
 from collections.abc import AsyncIterator, Callable, Coroutine, Iterable, Iterator, Mapping
-from typing import TYPE_CHECKING, Any, Final, Literal, Optional, cast
+from typing import TYPE_CHECKING, Final, Literal, Optional, cast
 
 import httpx
 
@@ -2754,7 +2754,12 @@ class OpenAIAssistantsAPI(BaseLLM):
 
         message_thread: Final = await openai_client.beta.threads.create(**data)
 
-        return Thread(**message_thread.dict())
+        return Thread(
+            id=message_thread.id,
+            created_at=message_thread.created_at,
+            metadata=message_thread.metadata,
+            object=message_thread.object,
+        )
 
     # fmt: off
 
@@ -2840,7 +2845,12 @@ class OpenAIAssistantsAPI(BaseLLM):
 
         message_thread: Final = openai_client.beta.threads.create(**data)
 
-        return Thread(**message_thread.dict())
+        return Thread(
+            id=message_thread.id,
+            created_at=message_thread.created_at,
+            metadata=message_thread.metadata,
+            object=message_thread.object,
+        )
 
     async def async_get_thread(
         self,
@@ -2863,7 +2873,12 @@ class OpenAIAssistantsAPI(BaseLLM):
 
         response: Final = await openai_client.beta.threads.retrieve(thread_id=thread_id)
 
-        return Thread(**response.dict())
+        return Thread(
+            id=response.id,
+            created_at=response.created_at,
+            metadata=response.metadata,
+            object=response.object,
+        )
 
     # fmt: off
 
@@ -2929,7 +2944,12 @@ class OpenAIAssistantsAPI(BaseLLM):
 
         response: Final = openai_client.beta.threads.retrieve(thread_id=thread_id)
 
-        return Thread(**response.dict())
+        return Thread(
+            id=response.id,
+            created_at=response.created_at,
+            metadata=response.metadata,
+            object=response.object,
+        )
 
     def delete_thread(self):
         pass
@@ -2986,18 +3006,27 @@ class OpenAIAssistantsAPI(BaseLLM):
         tools: Iterable[AssistantToolParam] | None,
         event_handler: AssistantEventHandler | None,
     ) -> AsyncAssistantStreamManager[AsyncAssistantEventHandler]:
-        data: Final[dict[str, Any]] = {
-            "thread_id": thread_id,
-            "assistant_id": assistant_id,
-            "additional_instructions": additional_instructions,
-            "instructions": instructions,
-            "metadata": metadata,
-            "model": model,
-            "tools": tools,
-        }
+        runs_stream: Final = client.beta.threads.runs.stream
         if event_handler is not None:
-            data["event_handler"] = event_handler
-        return client.beta.threads.runs.stream(**data)
+            return runs_stream(
+                thread_id=thread_id,
+                assistant_id=assistant_id,
+                additional_instructions=additional_instructions,
+                instructions=instructions,
+                metadata=metadata,
+                model=model,
+                tools=tools,
+                event_handler=event_handler,
+            )
+        return runs_stream(
+            thread_id=thread_id,
+            assistant_id=assistant_id,
+            additional_instructions=additional_instructions,
+            instructions=instructions,
+            metadata=metadata,
+            model=model,
+            tools=tools,
+        )
 
     def run_thread_stream(
         self,
diff --git a/litellm/llms/vertex_ai/fine_tuning/handler.py b/litellm/llms/vertex_ai/fine_tuning/handler.py
index 7ecc5e8ff3d..c79b6ffce43 100644
--- a/litellm/llms/vertex_ai/fine_tuning/handler.py
+++ b/litellm/llms/vertex_ai/fine_tuning/handler.py
@@ -280,7 +280,7 @@ class VertexFineTuningAPI(VertexLLM):
         vertex_location: str,
         vertex_credentials: str,
         request_route: str,
-    ):
+    ) -> object:
         _auth_header, vertex_project = await self._ensure_access_token_async(
             credentials=vertex_credentials,
             project_id=vertex_project,
@@ -341,5 +341,4 @@ class VertexFineTuningAPI(VertexLLM):
                 f"Error creating fine tuning job. Status code: {response.status_code}. Response: {response.text}"
             )
 
-        response_json: Final = response.json()
-        return response_json
+        return response.json()
diff --git a/litellm/llms/vertex_ai/image_edit/vertex_imagen_transformation.py b/litellm/llms/vertex_ai/image_edit/vertex_imagen_transformation.py
index c6ad5928b74..fddc075bfc6 100644
--- a/litellm/llms/vertex_ai/image_edit/vertex_imagen_transformation.py
+++ b/litellm/llms/vertex_ai/image_edit/vertex_imagen_transformation.py
@@ -1,6 +1,7 @@
 import base64
 import json
 import os
+from collections.abc import Mapping
 from io import BufferedRandom, BufferedReader, BytesIO
 from pathlib import Path
 from typing import TYPE_CHECKING, Any, Final, cast
@@ -47,11 +48,11 @@ class VertexAIImagenImageEditConfig(BaseImageEditConfig, VertexLLM):
         image_edit_optional_params: ImageEditOptionalRequestParams,
         model: str,
         drop_params: bool,
-    ) -> dict[str, Any]:
+    ) -> dict[str, object]:
         supported_params: Final = self.get_supported_openai_params(model)
         filtered_params = {key: value for key, value in image_edit_optional_params.items() if key in supported_params}
 
-        mapped_params: Final[dict[str, Any]] = {}
+        mapped_params: Final[dict[str, object]] = {}
 
         # Map OpenAI parameters to Imagen format
         if "n" in filtered_params:
@@ -148,10 +149,10 @@ class VertexAIImagenImageEditConfig(BaseImageEditConfig, VertexLLM):
         model: str,
         prompt: str | None,
         image: FileTypes | None,
-        image_edit_optional_request_params: dict[str, Any],
+        image_edit_optional_request_params: Mapping[str, object],
         litellm_params: GenericLiteLLMParams,
         headers: dict,
-    ) -> tuple[dict[str, Any], RequestFiles | None]:
+    ) -> tuple[dict[str, object], RequestFiles | None]:
         # Prepare reference images in the correct Imagen format
         if image is None:
             raise ValueError("Vertex AI Imagen image edit requires at least one reference image.")
@@ -182,14 +183,14 @@ class VertexAIImagenImageEditConfig(BaseImageEditConfig, VertexLLM):
         parameters["guidanceScale"] = 7.5  # Default guidance scale
         parameters["seed"] = None  # Let Vertex AI choose random seed
 
-        request_body: Final[dict[str, Any]] = {
+        request_body: Final[dict[str, object]] = {
             "instances": instances,
             "parameters": parameters,
         }
 
-        payload: Final[Any] = json.dumps(request_body)
+        payload: Final = json.dumps(request_body)
         empty_files: Final = cast(RequestFiles, [])
-        return cast(tuple[dict[str, Any], RequestFiles | None], (payload, empty_files))
+        return cast(tuple[dict[str, object], RequestFiles | None], (payload, empty_files))
 
     def transform_image_edit_response(
         self,
@@ -237,8 +238,8 @@ class VertexAIImagenImageEditConfig(BaseImageEditConfig, VertexLLM):
     def _prepare_reference_images(
         self,
         image: FileTypes | list[FileTypes],
-        image_edit_optional_request_params: dict[str, Any],
-    ) -> list[dict[str, Any]]:
+        image_edit_optional_request_params: Mapping[str, object],
+    ) -> list[dict[str, object]]:
         """
         Prepare reference images in the correct Imagen API format
         """
@@ -248,7 +249,7 @@ class VertexAIImagenImageEditConfig(BaseImageEditConfig, VertexLLM):
         else:
             images = [image]
 
-        reference_images: Final[list[dict[str, Any]]] = []
+        reference_images: Final[list[dict[str, object]]] = []
 
         for idx, img in enumerate(images):
             if img is None:
@@ -258,7 +259,7 @@ class VertexAIImagenImageEditConfig(BaseImageEditConfig, VertexLLM):
             base64_data = base64.b64encode(image_bytes).decode("utf-8")
 
             # Create reference image structure
-            reference_image = {
+            reference_image: dict[str, object] = {
                 "referenceType": "REFERENCE_TYPE_RAW",
                 "referenceId": idx + 1,
                 "referenceImage": {"bytesBase64Encoded": base64_data},
@@ -272,7 +273,7 @@ class VertexAIImagenImageEditConfig(BaseImageEditConfig, VertexLLM):
             mask_bytes: Final = self._read_all_bytes(mask_image)
             mask_base64: Final = base64.b64encode(mask_bytes).decode("utf-8")
 
-            mask_reference: Final = {
+            mask_reference: Final[dict[str, object]] = {
                 "referenceType": "REFERENCE_TYPE_MASK",
                 "referenceId": len(reference_images) + 1,
                 "referenceImage": {"bytesBase64Encoded": mask_base64},
diff --git a/litellm/llms/vertex_ai/image_generation/vertex_gemini_transformation.py b/litellm/llms/vertex_ai/image_generation/vertex_gemini_transformation.py
index d7a2491c04a..b2c52c53580 100644
--- a/litellm/llms/vertex_ai/image_generation/vertex_gemini_transformation.py
+++ b/litellm/llms/vertex_ai/image_generation/vertex_gemini_transformation.py
@@ -218,10 +218,10 @@ class VertexAIGeminiImageGenerationConfig(BaseImageGenerationConfig, VertexLLM):
         contents: Final = [{"role": "user", "parts": [{"text": prompt}]}]
 
         # Prepare generation config
-        generation_config: Final[dict[str, Any]] = {"responseModalities": ["IMAGE"]}
+        generation_config: Final[dict[str, object]] = {"responseModalities": ["IMAGE"]}
 
         # Seed from user-supplied imageConfig dict; flat params are overlaid for backward compat.
-        image_config: Final[dict[str, Any]] = dict(optional_params.get("imageConfig") or {})
+        image_config: Final[dict[str, object]] = dict(optional_params.get("imageConfig") or {})
 
         if "aspectRatio" in optional_params:
             image_config["aspectRatio"] = optional_params["aspectRatio"]
@@ -242,7 +242,7 @@ class VertexAIGeminiImageGenerationConfig(BaseImageGenerationConfig, VertexLLM):
         elif "n" in optional_params:
             generation_config["candidateCount"] = optional_params["n"]
 
-        request_body: Final[dict[str, Any]] = {
+        request_body: Final[dict[str, object]] = {
             "contents": contents,
             "generationConfig": generation_config,
         }
diff --git a/litellm/proxy/_experimental/mcp_server/db.py b/litellm/proxy/_experimental/mcp_server/db.py
index 082a90fdcfb..980a67b30d6 100644
--- a/litellm/proxy/_experimental/mcp_server/db.py
+++ b/litellm/proxy/_experimental/mcp_server/db.py
@@ -37,6 +37,7 @@ from litellm.repositories.table_repositories import (
     MCPServerOAuthClientRepository,
     MCPServerRepository,
     MCPUserCredentialsRepository,
+    PrismaTableRepository,
 )
 from litellm.repositories.team_repository import TeamRepository
 from litellm.repositories.verification_token_repository import (
@@ -522,11 +523,14 @@ def _user_credential_actions(
     return table
 
 
+class _MCPUserEnvVarsRepository(PrismaTableRepository["prisma_db_models.LiteLLM_MCPUserEnvVars"]):
+    table_name = "litellm_mcpuserenvvars"
+
+
 def _user_env_var_actions(
     prisma_client: PrismaClient,
 ) -> "TableActions[prisma_db_models.LiteLLM_MCPUserEnvVars]":
-    table: Final[TableActions[prisma_db_models.LiteLLM_MCPUserEnvVars]] = prisma_client.db.litellm_mcpuserenvvars
-    return table
+    return _MCPUserEnvVarsRepository(prisma_client).table
 
 
 async def _db_find_user_credential_row(
diff --git a/litellm/proxy/common_utils/reset_budget_job.py b/litellm/proxy/common_utils/reset_budget_job.py
index f2648c8466e..dc29a8377c9 100644
--- a/litellm/proxy/common_utils/reset_budget_job.py
+++ b/litellm/proxy/common_utils/reset_budget_job.py
@@ -48,7 +48,7 @@ from litellm.proxy.db.db_transaction_queue.pod_lock_manager import PodLockManage
 from litellm.proxy.db.exception_handler import call_with_db_reconnect_retry
 from litellm.proxy.utils import PrismaClient, ProxyLogging
 from litellm.repositories.organization_repository import OrganizationRepository
-from litellm.repositories.prisma_protocols import SpendLinkedTable
+from litellm.repositories.prisma_protocols import PrismaBatch, SpendLinkedTable
 from litellm.repositories.table_repositories import (
     EndUserRepository,
     ModelAccessGroupBudgetRepository,
@@ -435,6 +435,11 @@ class ResetBudgetJob:
         self.reset_settings: BudgetResetSettings = reset_settings or get_budget_reset_settings()
         self.pod_lock_manager: PodLockManager | None = pod_lock_manager
 
+    @property
+    def _new_batch(self) -> Callable[[], PrismaBatch]:
+        new_batch: Final[Callable[[], PrismaBatch]] = self.prisma_client.db.batch_
+        return new_batch
+
     async def _lease_is_held(self, lock_manager: PodLockManager) -> bool:
         """True only when the lease is readable and someone holds it.
 
@@ -721,7 +726,7 @@ class ResetBudgetJob:
         )
 
     async def _commit_budget_cascade_once(self, cascade: _BudgetCascade) -> None:
-        async with budget_cascade_unit_of_work(self.prisma_client.db.batch_) as uow:
+        async with budget_cascade_unit_of_work(self._new_batch) as uow:
             _queue_budget_linked_resets(uow.team_memberships, cascade)
             _queue_budget_linked_resets(uow.keys, cascade, extra=_LINKED_KEYS_WHERE)
             _queue_budget_linked_resets(uow.organizations, cascade, extra=_SPENT_ROWS_WHERE)
@@ -861,7 +866,7 @@ class ResetBudgetJob:
         )
 
     async def _write_key_reset_updates_once(self, updated_keys: list[LiteLLM_VerificationToken]) -> None:
-        async with spend_reset_unit_of_work(self.prisma_client.db.batch_) as uow:
+        async with spend_reset_unit_of_work(self._new_batch) as uow:
             for k in updated_keys:
                 if k.token is None:
                     continue
@@ -885,7 +890,7 @@ class ResetBudgetJob:
         )
 
     async def _write_user_reset_updates_once(self, updated_users: list[LiteLLM_UserTable]) -> None:
-        async with spend_reset_unit_of_work(self.prisma_client.db.batch_) as uow:
+        async with spend_reset_unit_of_work(self._new_batch) as uow:
             for u in updated_users:
                 uow.users.queue_spend_reset(
                     user_id=u.user_id,
@@ -907,7 +912,7 @@ class ResetBudgetJob:
         )
 
     async def _write_team_reset_updates_once(self, updated_teams: list[LiteLLM_TeamTable]) -> None:
-        async with spend_reset_unit_of_work(self.prisma_client.db.batch_) as uow:
+        async with spend_reset_unit_of_work(self._new_batch) as uow:
             for t in updated_teams:
                 uow.teams.queue_spend_reset(
                     team_id=t.team_id,
diff --git a/litellm/proxy/guardrails/guardrail_hooks/cisco_ai_defense/cisco_ai_defense.py b/litellm/proxy/guardrails/guardrail_hooks/cisco_ai_defense/cisco_ai_defense.py
index facb822d00d..017ef6e09f6 100644
--- a/litellm/proxy/guardrails/guardrail_hooks/cisco_ai_defense/cisco_ai_defense.py
+++ b/litellm/proxy/guardrails/guardrail_hooks/cisco_ai_defense/cisco_ai_defense.py
@@ -26,6 +26,7 @@ from typing import TYPE_CHECKING, Any, Final, Literal
 
 import httpx
 from fastapi import HTTPException
+from typing_extensions import TypedDict, Unpack
 
 from litellm import DualCache
 from litellm._logging import verbose_proxy_logger
@@ -111,6 +112,10 @@ class CiscoAIDefenseGuardrailAPIError(Exception):
     """Raised when there is an error talking to the Cisco AI Defense API."""
 
 
+class _CustomGuardrailOptions(TypedDict, total=False, extra_items=object):
+    """Base-class constructor options this guardrail forwards untouched to CustomGuardrail."""
+
+
 class CiscoAIDefenseGuardrail(_CiscoAIDefenseMcpMixin, CustomGuardrail):
     """
     Cisco AI Defense guardrail integration.
@@ -144,7 +149,7 @@ class CiscoAIDefenseGuardrail(_CiscoAIDefenseMcpMixin, CustomGuardrail):
         on_flagged_action: str | None = None,
         fallback_on_error: str | None = None,
         timeout: float | None = None,
-        **kwargs: Any,
+        **kwargs: Unpack[_CustomGuardrailOptions],
     ) -> None:
         resolved_api_key: Final = api_key or os.environ.get("CISCO_AI_DEFENSE_API_KEY")
         if not resolved_api_key:
diff --git a/litellm/proxy/guardrails/guardrail_hooks/deepkeep/deepkeep.py b/litellm/proxy/guardrails/guardrail_hooks/deepkeep/deepkeep.py
index 214d4b486d4..539dc1ea1e9 100644
--- a/litellm/proxy/guardrails/guardrail_hooks/deepkeep/deepkeep.py
+++ b/litellm/proxy/guardrails/guardrail_hooks/deepkeep/deepkeep.py
@@ -7,10 +7,10 @@
 
 import os
 from collections.abc import Mapping
-from typing import TYPE_CHECKING, Any, Final, Literal, Optional, Protocol
+from typing import TYPE_CHECKING, Final, Literal, Optional, Protocol
 
 import httpx
-from typing_extensions import NotRequired, ReadOnly, TypedDict
+from typing_extensions import NotRequired, ReadOnly, TypedDict, Unpack
 
 from litellm._logging import verbose_proxy_logger
 from litellm._version import version as litellm_version
@@ -56,7 +56,13 @@ class DeepKeepFirewallResponse(TypedDict):
 class _DeepKeepInitKwargsView(TypedDict):
     """Typed read of the guardrail name carried in the untyped base-guardrail kwargs."""
 
-    guardrail_name: ReadOnly[str]
+    guardrail_name: ReadOnly[str | None]
+
+
+class _CustomGuardrailOptions(TypedDict, total=False, extra_items=object):
+    """Base-class constructor options this guardrail forwards untouched to CustomGuardrail."""
+
+    guardrail_name: ReadOnly[str | None]
 
 
 class _DeepKeepMetadataSource(TypedDict, total=False):
@@ -110,7 +116,7 @@ class DeepKeepGuardrail(CustomGuardrail):
         firewall_id: str | None = None,
         unreachable_fallback: Literal["fail_closed", "fail_open"] = "fail_closed",
         extra_headers: Mapping[str, str] | list[str] | None = None,
-        **kwargs: Any,
+        **kwargs: Unpack[_CustomGuardrailOptions],
     ):
         self.async_handler = get_async_httpx_client(llm_provider=httpxSpecialProvider.GuardrailCallback)
 
diff --git a/litellm/proxy/guardrails/guardrail_hooks/headroom/headroom.py b/litellm/proxy/guardrails/guardrail_hooks/headroom/headroom.py
index fa113aa4d33..eb62b896784 100644
--- a/litellm/proxy/guardrails/guardrail_hooks/headroom/headroom.py
+++ b/litellm/proxy/guardrails/guardrail_hooks/headroom/headroom.py
@@ -7,7 +7,7 @@ import time
 import uuid
 from collections.abc import Mapping, Sequence
 from dataclasses import dataclass
-from typing import TYPE_CHECKING, Any, ClassVar, Final, Literal, TypeGuard
+from typing import TYPE_CHECKING, ClassVar, Final, Literal, TypeGuard
 
 import httpx
 from fastapi import HTTPException
@@ -50,6 +50,7 @@ from litellm.types.utils import CallTypes, GenericGuardrailAPIInputs
 
 if TYPE_CHECKING:
     from litellm.litellm_core_utils.litellm_logging import Logging as LiteLLMLoggingObj
+    from litellm.llms.base_llm.anthropic_messages.transformation import BaseAnthropicMessagesConfig
     from litellm.types.guardrails import LitellmParams
     from litellm.types.proxy.guardrails.guardrail_hooks.base import GuardrailConfigModel
 
@@ -878,9 +879,9 @@ class HeadroomGuardrail(CustomGuardrail):
 
     async def async_pre_call_deployment_hook(
         self,
-        kwargs: dict[str, Any],
+        kwargs: dict[str, object],
         call_type: CallTypes | None,
-    ) -> dict[str, Any] | None:  # mutable-ok: overrides CustomLogger hook whose contract is a plain dict
+    ) -> dict[str, object] | None:  # mutable-ok: overrides CustomLogger hook whose contract is a plain dict
         base_result: Final = await super().async_pre_call_deployment_hook(kwargs, call_type)
         effective: Final = base_result if base_result is not None else kwargs
         if call_type not in _STREAM_CONVERTIBLE_CALL_TYPES:
@@ -897,7 +898,7 @@ class HeadroomGuardrail(CustomGuardrail):
 
     async def async_should_run_agentic_loop(
         self,
-        response: Any,
+        response: object,
         model: str,
         messages: list[dict],
         tools: list[dict] | None,
@@ -919,8 +920,8 @@ class HeadroomGuardrail(CustomGuardrail):
         tools: dict,
         model: str,
         messages: list[dict],
-        response: Any,
-        anthropic_messages_provider_config: Any,
+        response: object,
+        anthropic_messages_provider_config: BaseAnthropicMessagesConfig | None,
         anthropic_messages_optional_request_params: dict,
         logging_obj: LiteLLMLoggingObj | None,
         stream: bool,
diff --git a/litellm/proxy/guardrails/guardrail_hooks/model_armor/model_armor.py b/litellm/proxy/guardrails/guardrail_hooks/model_armor/model_armor.py
index fde40111d49..88c7f21ad72 100644
--- a/litellm/proxy/guardrails/guardrail_hooks/model_armor/model_armor.py
+++ b/litellm/proxy/guardrails/guardrail_hooks/model_armor/model_armor.py
@@ -360,7 +360,7 @@ class ModelArmorGuardrail(CustomGuardrail, VertexBase):
         else:
             return {"modelResponseData": {"byteItem": {"byteDataType": file_type, "byteData": base64_data}}}
 
-    def _should_block_content(self, armor_response: Mapping[str, Any], allow_sanitization: bool = False) -> bool:
+    def _should_block_content(self, armor_response: Mapping[str, object], allow_sanitization: bool = False) -> bool:
         """Check if Model Armor response indicates content should be blocked, including both inspectResult and deidentifyResult."""
         for filt in self._filter_result_items(armor_response):
             # Check RAI, PI/Jailbreak, Malicious URI, CSAM, Virus scan as before
@@ -429,7 +429,7 @@ class ModelArmorGuardrail(CustomGuardrail, VertexBase):
             return filter_results
         return []
 
-    def _has_deidentify_match(self, armor_response: Mapping[str, Any]) -> bool:
+    def _has_deidentify_match(self, armor_response: Mapping[str, object]) -> bool:
         """Whether an SDP de-identify filter matched, i.e. Model Armor owes this response a redaction."""
         for filter_entry in self._filter_result_items(armor_response):
             sdp = filter_entry.get("sdpFilterResult")
@@ -439,7 +439,7 @@ class ModelArmorGuardrail(CustomGuardrail, VertexBase):
 
     def _resolve_streaming_outcome(
         self,
-        armor_response: Mapping[str, Any],
+        armor_response: Mapping[str, object],
         assembled_response: object,
         content: str,
     ) -> tuple[bool, str | None]:
diff --git a/litellm/proxy/management_endpoints/auto_router_endpoints.py b/litellm/proxy/management_endpoints/auto_router_endpoints.py
index bbc914a772a..12d23550cb9 100644
--- a/litellm/proxy/management_endpoints/auto_router_endpoints.py
+++ b/litellm/proxy/management_endpoints/auto_router_endpoints.py
@@ -8,7 +8,6 @@ POST /auto_router/validate_complexity_router_config - Dry-run the complexity-rou
 from collections.abc import Mapping, Sequence
 from datetime import datetime, timedelta, timezone
 from itertools import chain, groupby
-from operator import attrgetter
 from types import MappingProxyType
 from typing import TYPE_CHECKING, Annotated, Final, Protocol
 from uuid import uuid4
@@ -1094,6 +1093,10 @@ def _slices(rows: Sequence[_AttemptAggRow]) -> tuple[ShadowEvalSlice, ...]:
     )
 
 
+def _leg_group_id(leg: "_LegRow") -> str:
+    return leg.group_id
+
+
 class _LegRow(BaseModel):
     """One LiteLLM_ShadowEvalJob row, validated off the untyped prisma record. A row is
     one target's leg of a job; the legs of a job share group_id and identical config,
@@ -1598,10 +1601,7 @@ async def list_shadow_eval_jobs(
         or ()
     )
     by_group: Final[Mapping[str, tuple[_LegRow, ...]]] = MappingProxyType(
-        {
-            group_id: tuple(group)
-            for group_id, group in groupby(sorted(legs, key=attrgetter("group_id")), key=attrgetter("group_id"))
-        }
+        {group_id: tuple(group) for group_id, group in groupby(sorted(legs, key=_leg_group_id), key=_leg_group_id)}
     )
     newest_first: Final = sorted(
         by_group, key=lambda group_id: max(leg.created_at for leg in by_group[group_id]), reverse=True
diff --git a/litellm/proxy/spend_tracking/ptu_flat_cost_rollup.py b/litellm/proxy/spend_tracking/ptu_flat_cost_rollup.py
index 0e6412a2c64..b8af432029f 100644
--- a/litellm/proxy/spend_tracking/ptu_flat_cost_rollup.py
+++ b/litellm/proxy/spend_tracking/ptu_flat_cost_rollup.py
@@ -31,11 +31,31 @@ from litellm.constants import (
 )
 from litellm.litellm_core_utils.ptu_pricing import ptu_terms
 from litellm.proxy.spend_tracking.ptu_feature_flag import is_ptu_cost_attribution_enabled
+from litellm.repositories.model_repository import ModelRepository
+from litellm.repositories.prisma_protocols import TableActions
+from litellm.repositories.table_repositories import PrismaTableRepository
 
 if TYPE_CHECKING:
+    from prisma import models as prisma_models
+
     from litellm.proxy.db.db_transaction_queue.pod_lock_manager import PodLockManager
     from litellm.proxy.utils import PrismaClient
 
+
+class _DailyTeamSpendRepository(PrismaTableRepository["prisma_models.LiteLLM_DailyTeamSpend"]):
+    table_name = "litellm_dailyteamspend"
+
+
+def _daily_team_spend_table(prisma_client: "PrismaClient") -> "TableActions[prisma_models.LiteLLM_DailyTeamSpend]":
+    """The sentinel rows this rollup writes, reads back and prunes."""
+    return _DailyTeamSpendRepository(prisma_client).table
+
+
+def _proxy_model_table(prisma_client: "PrismaClient") -> "TableActions[prisma_models.LiteLLM_ProxyModelTable]":
+    """The stored deployments the rollup scans for PTU config."""
+    return ModelRepository(prisma_client).table
+
+
 _HOURS_PER_DAY: Final = 24
 _PRUNE_ID_CHUNK_SIZE: Final = 5_000
 _UPSERT_ATTEMPTS: Final = 3
@@ -97,7 +117,7 @@ def _decode_model_info(raw: object) -> "Mapping[str, object] | None":
     """
     if isinstance(raw, str):
         try:
-            decoded: Final = json.loads(raw)
+            decoded: Final[object] = json.loads(raw)
         except (TypeError, ValueError):
             return None
         return decoded if isinstance(decoded, dict) else None
@@ -240,7 +260,7 @@ async def _upsert_ptu_daily_row(
         }
     }
     now: Final = datetime.now(timezone.utc)
-    await prisma_client.db.litellm_dailyteamspend.upsert(
+    await _daily_team_spend_table(prisma_client).upsert(
         where=where,
         data={  # mutable-ok: prisma upsert data payload
             "create": {  # mutable-ok: prisma create payload
@@ -353,7 +373,7 @@ async def _load_ptu_models(prisma_client: "PrismaClient", *, router: object | No
     The router is handed in rather than read off the proxy module, so a run prices exactly
     the deployments its caller declares and nothing a co-resident process left behind.
     """
-    rows: Final = await prisma_client.db.litellm_proxymodeltable.find_many()
+    rows: Final = await _proxy_model_table(prisma_client).find_many()
     db_ids: Final = frozenset(model_id for row in rows if (model_id := str(getattr(row, "model_id", "") or "")))
     config_records: Final = _config_deployments(router, owned_by_db=db_ids)
     models: Final = tuple(
@@ -503,7 +523,7 @@ async def _existing_sentinel_keys(
     survives a rename. Nothing here reads the display name.
     """
     date_range: Final = {"gte": start.isoformat(), "lte": end.isoformat()}  # mutable-ok: prisma range filter
-    rows: Final = await prisma_client.db.litellm_dailyteamspend.find_many(
+    rows: Final = await _daily_team_spend_table(prisma_client).find_many(
         where={"api_key": PTU_SENTINEL_API_KEY, "date": date_range}  # mutable-ok: prisma find filter
     )
     return frozenset(
@@ -771,7 +791,7 @@ async def _prune_unrefreshed_sentinel_rows(
     )
     filters: Final = tuple(_prune_filter(date_str=date_str, cutoff=cutoff, chunk=chunk) for chunk in chunks)
     deletions: Final = tuple(
-        [await prisma_client.db.litellm_dailyteamspend.delete_many(where=where) for where in filters]
+        [await _daily_team_spend_table(prisma_client).delete_many(where=where) for where in filters]
     )
     deleted: Final = sum(deletions)
     if deleted:
diff --git a/litellm/proxy/utils.py b/litellm/proxy/utils.py
index ddf31cb1d8a..21328a4962a 100644
--- a/litellm/proxy/utils.py
+++ b/litellm/proxy/utils.py
@@ -3401,7 +3401,7 @@ class _ConfigRow:
 
     __slots__ = ("param_name", "param_value")
 
-    def __init__(self, param_name: str, param_value: Any) -> None:
+    def __init__(self, param_name: str, param_value: object) -> None:
         self.param_name = param_name
         self.param_value = param_value
 
@@ -3414,7 +3414,7 @@ def _pack_config_row(row: Any) -> dict[str, object]:
     return {"param_name": row.param_name, "param_value": row.param_value}
 
 
-def _unpack_config_row(cached: Any) -> _ConfigRow | None:
+def _unpack_config_row(cached: object) -> _ConfigRow | None:
     if cached is None or cached == _CONFIG_CACHE_MISS:
         return None
     if isinstance(cached, dict):
@@ -3557,6 +3557,7 @@ class PrismaClient:
         verbose_proxy_logger.debug("Creating Prisma Client..")
         try:
             from prisma import Prisma
+            from prisma.types import DatasourceOverride
         except Exception as e:
             verbose_proxy_logger.error("Failed to import Prisma client: %s", e)
             verbose_proxy_logger.error("This usually means 'prisma generate' hasn't been run yet.")
@@ -3607,11 +3608,11 @@ class PrismaClient:
                     reader_token: Final = mint_database_token(token_auth, reader_iam_endpoint)
                     read_replica_url = reader_iam_endpoint.build_url(reader_token)
                     os.environ["DATABASE_URL_READ_REPLICA"] = read_replica_url
-                reader_kwargs: Final[dict[str, Any]] = {"datasource": {"url": read_replica_url}}
+                reader_datasource: Final = DatasourceOverride(url=read_replica_url)
                 if http_client is not None:
-                    reader_prisma = Prisma(http=http_client, **reader_kwargs)
+                    reader_prisma = Prisma(http=http_client, datasource=reader_datasource)
                 else:
-                    reader_prisma = Prisma(**reader_kwargs)
+                    reader_prisma = Prisma(datasource=reader_datasource)
                 reader_wrapper: Final = PrismaWrapper(
                     original_prisma=reader_prisma,
                     token_auth=token_auth,
diff --git a/litellm/realtime_api/main.py b/litellm/realtime_api/main.py
index b824a5928c6..9d81c725c70 100644
--- a/litellm/realtime_api/main.py
+++ b/litellm/realtime_api/main.py
@@ -53,7 +53,7 @@ bedrock_realtime: Final = BedrockRealtime()
 xai_realtime: Final = XAIRealtime()
 vertex_llm_base: Final = VertexBase()
 base_llm_http_handler = BaseLLMHTTPHandler()
-_EMPTY_MODEL_PARAMS: Final[Mapping[str, Any]] = MappingProxyType({})
+_EMPTY_MODEL_PARAMS: Final[Mapping[str, object]] = MappingProxyType({})
 
 
 def _with_resolved_session_model(session: dict[str, object], model_name: str) -> dict[str, object]:
diff --git a/litellm/repositories/model_repository.py b/litellm/repositories/model_repository.py
index d24eb8ffc62..8ee76b93923 100644
--- a/litellm/repositories/model_repository.py
+++ b/litellm/repositories/model_repository.py
@@ -4,29 +4,23 @@ Model repository for database operations on LiteLLM_ProxyModelTable.
 
 import json
 from collections.abc import Mapping, Sequence
-from typing import TYPE_CHECKING, Any, Final, Protocol
+from typing import TYPE_CHECKING, Any, Final
 
 from litellm.models.model import LiteLLM_ProxyModelTable
-from litellm.proxy.common_utils.config_sync_pubsub import wrap_table_actions_for_config_sync
 from litellm.proxy.common_utils.encrypt_decrypt_utils import (
     decrypt_value_helper,
     encrypt_value_helper,
 )
 from litellm.repositories.base_repository import BaseRepository
 from litellm.repositories.prisma_protocols import TableActions
+from litellm.repositories.table_repositories import PrismaTableRepository
 
 if TYPE_CHECKING:
     from prisma import models as prisma_models
 
 
-class _PrismaModelDb(Protocol):
-    @property
-    def litellm_proxymodeltable(self) -> TableActions["prisma_models.LiteLLM_ProxyModelTable"]: ...
-
-
-class _PrismaClientView(Protocol):
-    @property
-    def db(self) -> _PrismaModelDb: ...
+class _ProxyModelTableRepository(PrismaTableRepository["prisma_models.LiteLLM_ProxyModelTable"]):
+    table_name = "litellm_proxymodeltable"
 
 
 class ModelRepository(BaseRepository[LiteLLM_ProxyModelTable]):
@@ -38,11 +32,7 @@ class ModelRepository(BaseRepository[LiteLLM_ProxyModelTable]):
 
     @property
     def table(self) -> TableActions["prisma_models.LiteLLM_ProxyModelTable"]:
-        client: Final[_PrismaClientView] = self.prisma_client
-        return wrap_table_actions_for_config_sync(
-            actions=client.db.litellm_proxymodeltable,
-            table_name="litellm_proxymodeltable",
-        )
+        return _ProxyModelTableRepository(self._prisma_client).table
 
     @property
     def model_class(self) -> type[LiteLLM_ProxyModelTable]:
diff --git a/litellm/repositories/team_repository.py b/litellm/repositories/team_repository.py
index 5ff07d76b5d..cbe263699c9 100644
--- a/litellm/repositories/team_repository.py
+++ b/litellm/repositories/team_repository.py
@@ -5,6 +5,7 @@ Team repository for database operations on LiteLLM_TeamTable.
 import json
 from collections.abc import Mapping, Sequence
 from datetime import datetime
+from types import TracebackType
 from typing import TYPE_CHECKING, Final, Protocol
 
 from pydantic import TypeAdapter
@@ -40,6 +41,36 @@ def _team_arrays(team: LiteLLM_TeamTable) -> _TeamArrays:
     return team
 
 
+class _TeamTables(Protocol):
+    """The two team tables this repository reads and writes."""
+
+    @property
+    def litellm_teamtable(self) -> TableActions["prisma_models.LiteLLM_TeamTable"]: ...
+
+    @property
+    def litellm_deletedteamtable(self) -> TableActions["prisma_models.LiteLLM_DeletedTeamTable"]: ...
+
+
+class _TeamTransactionManager(Protocol):
+    async def __aenter__(self) -> _TeamTables: ...
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_value: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> bool | None: ...
+
+
+class _PrismaTeamDb(_TeamTables, Protocol):
+    def tx(self) -> _TeamTransactionManager: ...
+
+
+class _PrismaClientView(Protocol):
+    @property
+    def db(self) -> _PrismaTeamDb: ...
+
+
 _MEMBERS_WITH_ROLES_ADAPTER: Final = TypeAdapter(list[Member])
 _JSON_ENCODED_TEAM_FIELDS: Final = (
     "metadata",
@@ -54,13 +85,18 @@ _JSON_ENCODED_TEAM_FIELDS: Final = (
 class TeamRepository(BaseRepository[LiteLLM_TeamTable]):
     """Repository for team database operations."""
 
+    @property
+    def _db(self) -> _PrismaTeamDb:
+        client: Final[_PrismaClientView] = self.prisma_client
+        return client.db
+
     @property
     def table(self) -> TableActions["prisma_models.LiteLLM_TeamTable"]:
-        return self.prisma_client.db.litellm_teamtable
+        return self._db.litellm_teamtable
 
     @property
     def deleted_table(self) -> TableActions["prisma_models.LiteLLM_DeletedTeamTable"]:
-        return self.prisma_client.db.litellm_deletedteamtable
+        return self._db.litellm_deletedteamtable
 
     @property
     def model_class(self) -> type[LiteLLM_TeamTable]:
@@ -256,7 +292,7 @@ class TeamRepository(BaseRepository[LiteLLM_TeamTable]):
         archive_data["litellm_changed_by"] = litellm_changed_by
         archive_data["deleted_at"] = datetime.utcnow()
 
-        async with self.prisma_client.db.tx() as tx:
+        async with self._db.tx() as tx:
             await tx.litellm_deletedteamtable.create(data=archive_data)
             await tx.litellm_teamtable.delete(where={"team_id": team_id})
 
diff --git a/litellm/router_utils/fallback_event_handlers.py b/litellm/router_utils/fallback_event_handlers.py
index 7fda5d96fb0..bf1838e50f7 100644
--- a/litellm/router_utils/fallback_event_handlers.py
+++ b/litellm/router_utils/fallback_event_handlers.py
@@ -266,7 +266,7 @@ def get_pre_routing_selection(kwargs: Mapping[str, object]) -> str | None:
 DISABLE_FALLBACKS_METADATA_KEY: Final = "_disable_fallbacks"
 
 
-def record_disable_fallbacks(request_kwargs: Mapping[str, Any] | None, disabled: bool) -> None:
+def record_disable_fallbacks(request_kwargs: Mapping[str, object] | None, disabled: bool) -> None:
     """
     Write-or-clear the request's disable_fallbacks verdict into the router-internal metadata
     bucket. The wrapper pops the raw kwarg before any downstream frame runs, so the refusal
@@ -286,7 +286,7 @@ def record_disable_fallbacks(request_kwargs: Mapping[str, Any] | None, disabled:
         bucket.pop(DISABLE_FALLBACKS_METADATA_KEY, None)
 
 
-def fallbacks_disabled_for_request(kwargs: Mapping[str, Any]) -> bool:
+def fallbacks_disabled_for_request(kwargs: Mapping[str, object]) -> bool:
     """True when this request opted out of fallbacks, read from the raw kwarg (pre-pop
     snapshots keep it) or the router-internal bucket the wrapper stamps after popping it."""
     if kwargs.get("disable_fallbacks") is True:
@@ -639,7 +639,7 @@ async def log_failure_fallback_event(original_model_group: str, kwargs: dict, or
             verbose_router_logger.error("Error in log_failure_fallback_event: %s", e)
 
 
-def _check_non_standard_fallback_format(fallbacks: list[Any] | None) -> bool:
+def _check_non_standard_fallback_format(fallbacks: Sequence[object] | None) -> bool:
     """
     Checks if the fallbacks list is a list of strings or a list of dictionaries.
 
@@ -653,8 +653,9 @@ def _check_non_standard_fallback_format(fallbacks: list[Any] | None) -> bool:
         return False
     if all(isinstance(item, str) for item in fallbacks):
         return True
-    elif all(isinstance(item, dict) for item in fallbacks):
-        for item in fallbacks:
+    dict_entries: Final = tuple(item for item in fallbacks if isinstance(item, dict))
+    if len(dict_entries) == len(fallbacks):
+        for item in dict_entries:
             for key in LiteLLMParamsTypedDict.__annotations__:
                 if key in item:
                     # If the value is a list, it's likely a standard fallback model group mapping

From f747bc67048f2b38e6e99bd57ca284fe6f77bdb5 Mon Sep 17 00:00:00 2001
From: mateo-berri <277851410+mateo-berri@users.noreply.github.com>
Date: Tue, 8 Sep 2026 10:14:07 +0000
Subject: [PATCH 05/55] refactor(types): replace Any with real types across 29
 more backend files

Second batch of the fifth basedpyright Any reduction round. Every change is
typing-only and leaves runtime behavior identical.

Guardrail hooks and file, vector store and usage endpoints move their payload,
header and response annotations from Any to object, Mapping[str, object] or the
concrete response model the call site already produces. Two private aggregation
helpers in the guardrail usage endpoints take a key accessor function instead of
an attribute name string, so the key they read is checked against the row type.
The verification token repository reaches its two tables through Protocols that
name the handles it calls, rather than reading them off an untyped prisma
client, and the Azure AD credential wrapper describes the azure-identity
credential it wraps the same way.
---
 .../litellm_core_utils/llm_cost_calc/utils.py | 15 +++--
 .../azure/text_to_speech/transformation.py    |  9 +--
 .../image_edit/stability_transformation.py    |  4 +-
 .../responses/transformation.py               | 14 ++---
 .../llms/cohere/embed/v1_transformation.py    | 15 +++--
 litellm/llms/gdc/chat/transformation.py       | 22 ++++++-
 .../llama3/transformation.py                  |  4 +-
 litellm/llms/voyage/rerank/transformation.py  |  6 +-
 litellm/proxy/client/users.py                 |  3 +-
 .../proxy/common_utils/http_parsing_utils.py  | 14 +++--
 litellm/proxy/db/prisma_client.py             |  9 ++-
 .../block_code_execution.py                   |  9 ++-
 .../cato_networks/cato_networks.py            | 10 ++--
 .../guardrail_hooks/compresr/compresr.py      | 11 ++--
 .../llm_as_a_judge/__init__.py                | 23 +++++++-
 .../guardrails/guardrail_hooks/noma/noma.py   | 15 +++--
 .../panw_prisma_airs/panw_prisma_airs.py      |  4 +-
 litellm/proxy/guardrails/usage_endpoints.py   | 25 ++++----
 .../proxy/hooks/proxy_track_cost_callback.py  | 28 +++++++--
 ...model_access_group_management_endpoints.py | 25 ++++----
 .../usage_endpoints/ai_usage_chat.py          | 11 ++--
 .../openai_files_endpoints/files_endpoints.py |  4 +-
 .../storage_backend_service.py                |  9 ++-
 .../proxy/vector_store_endpoints/endpoints.py |  2 +-
 .../vector_store_files_endpoints/endpoints.py | 10 ++--
 litellm/proxy_auth/credentials.py             | 58 ++++++++++++++-----
 litellm/rag/rag_query.py                      |  4 +-
 .../verification_token_repository.py          | 46 ++++++++++++---
 litellm/router_utils/search_api_router.py     |  4 +-
 29 files changed, 274 insertions(+), 139 deletions(-)

diff --git a/litellm/litellm_core_utils/llm_cost_calc/utils.py b/litellm/litellm_core_utils/llm_cost_calc/utils.py
index 68dc27ec25e..52dac92ee22 100644
--- a/litellm/litellm_core_utils/llm_cost_calc/utils.py
+++ b/litellm/litellm_core_utils/llm_cost_calc/utils.py
@@ -6,7 +6,7 @@ from collections.abc import Mapping, Sequence
 from dataclasses import dataclass
 from datetime import datetime, timezone, tzinfo
 from types import MappingProxyType
-from typing import Any, Final, Literal, TypedDict, cast
+from typing import Final, Literal, TypedDict, cast
 from zoneinfo import ZoneInfo, ZoneInfoNotFoundError
 
 import litellm
@@ -89,7 +89,7 @@ def _requested_image_size(optional_params: Mapping[str, object] | None) -> str |
     return value if value is not None and _IMAGE_SIZE_PATTERN.fullmatch(value) else None
 
 
-def get_web_search_requests(server_tool_use: Any) -> int | None:
+def get_web_search_requests(server_tool_use: object) -> int | None:
     """
     Tolerantly read ``web_search_requests`` from a ``server_tool_use`` value
     that may be ``None``, a ``dict``, a ``ServerToolUse`` pydantic instance,
@@ -1494,7 +1494,7 @@ def calculate_image_response_cost_from_usage(
     if prompt_tokens == 0 and completion_tokens == 0 and total_tokens == 0:
         return None
 
-    input_tokens_details: Final = getattr(usage, "input_tokens_details", None)
+    input_tokens_details: Final[object] = getattr(usage, "input_tokens_details", None)
     prompt_tokens_details: PromptTokensDetailsWrapper | None = None
     if input_tokens_details is not None:
         # input_tokens_details may be a dict (e.g. OpenAI image edit responses)
@@ -1507,9 +1507,12 @@ def calculate_image_response_cost_from_usage(
             cached_tokens=0,
         )
 
-    output_tokens_details = getattr(usage, "completion_tokens_details", None)
-    if output_tokens_details is None:
-        output_tokens_details = getattr(usage, "output_tokens_details", None)
+    completion_tokens_details_attr: Final[object] = getattr(usage, "completion_tokens_details", None)
+    output_tokens_details: Final[object] = (
+        getattr(usage, "output_tokens_details", None)
+        if completion_tokens_details_attr is None
+        else completion_tokens_details_attr
+    )
 
     if output_tokens_details is None:
         completion_tokens_details = CompletionTokensDetailsWrapper(
diff --git a/litellm/llms/azure/text_to_speech/transformation.py b/litellm/llms/azure/text_to_speech/transformation.py
index d8ccf26ce60..eed7a3178ca 100644
--- a/litellm/llms/azure/text_to_speech/transformation.py
+++ b/litellm/llms/azure/text_to_speech/transformation.py
@@ -19,6 +19,7 @@ from litellm.secret_managers.main import get_secret_str
 
 if TYPE_CHECKING:
     from litellm.litellm_core_utils.litellm_logging import Logging as LiteLLMLoggingObj
+    from litellm.llms.custom_httpx.llm_http_handler import BaseLLMHTTPHandler
     from litellm.types.llms.openai import HttpxBinaryResponseContent
 else:
     LiteLLMLoggingObj = Any
@@ -67,15 +68,15 @@ class AzureAVATextToSpeechConfig(BaseTextToSpeechConfig):
         litellm_params_dict: dict,
         logging_obj: "LiteLLMLoggingObj",
         timeout: float | httpx.Timeout,
-        extra_headers: dict[str, Any] | None,
-        base_llm_http_handler: Any,
+        extra_headers: dict[str, object] | None,
+        base_llm_http_handler: "BaseLLMHTTPHandler",
         aspeech: bool,
         api_base: str | None,
         api_key: str | None,
-        **kwargs: Any,
+        **kwargs: object,
     ) -> Union[
         "HttpxBinaryResponseContent",
-        Coroutine[Any, Any, "HttpxBinaryResponseContent"],
+        Coroutine[object, object, "HttpxBinaryResponseContent"],
     ]:
         """
         Dispatch method to handle Azure AVA TTS requests
diff --git a/litellm/llms/bedrock/image_edit/stability_transformation.py b/litellm/llms/bedrock/image_edit/stability_transformation.py
index bc9a64f587a..01e25f4671e 100644
--- a/litellm/llms/bedrock/image_edit/stability_transformation.py
+++ b/litellm/llms/bedrock/image_edit/stability_transformation.py
@@ -125,7 +125,7 @@ class BedrockStabilityImageEditConfig(BaseImageEditConfig):
         }
 
         # Create a copy to not mutate original - convert TypedDict to regular dict
-        mapped_params: Final[dict[str, Any]] = dict(image_edit_optional_params)
+        mapped_params: Final[dict[str, object]] = dict(image_edit_optional_params)
 
         for k, v in image_edit_optional_params.items():
             if k in param_mapping:
@@ -172,7 +172,7 @@ class BedrockStabilityImageEditConfig(BaseImageEditConfig):
         Returns the request body dict that will be JSON-encoded by the handler.
         """
         # Build Bedrock Stability request
-        data: Final[dict[str, Any]] = {
+        data: Final[dict[str, object]] = {
             "output_format": "png",  # Default to PNG
         }
 
diff --git a/litellm/llms/bedrock_mantle/responses/transformation.py b/litellm/llms/bedrock_mantle/responses/transformation.py
index bbbda4d14b6..3d2eab8fcee 100644
--- a/litellm/llms/bedrock_mantle/responses/transformation.py
+++ b/litellm/llms/bedrock_mantle/responses/transformation.py
@@ -16,8 +16,8 @@ BaseAWSLLM._sign_request after the request body is finalized.
 """
 
 import json
-from collections.abc import Mapping
-from typing import Any, Final
+from collections.abc import Mapping, Sequence
+from typing import Final
 
 import httpx
 from typing_extensions import ReadOnly, TypedDict
@@ -142,9 +142,9 @@ class BedrockMantleResponsesAPIConfig(BedrockMantleAuthMixin, OpenAIResponsesAPI
         return False
 
     @staticmethod
-    def _filter_unsupported_tools(tools: list[Any]) -> list[Any]:
+    def _filter_unsupported_tools(tools: "Sequence[object]") -> "list[object]":
         """Keep only tool types Mantle's Responses API accepts."""
-        kept: Final[list[Any]] = []
+        kept: Final[list[object]] = []
         dropped_types: Final[list[str]] = []
         for tool in tools:
             if not isinstance(tool, dict):
@@ -217,11 +217,11 @@ class BedrockMantleResponsesAPIConfig(BedrockMantleAuthMixin, OpenAIResponsesAPI
         )
 
     @staticmethod
-    def _is_codex_additional_tools_item(item: Any) -> bool:
+    def _is_codex_additional_tools_item(item: object) -> bool:
         return isinstance(item, dict) and item.get("type") == _CODEX_ADDITIONAL_TOOLS_INPUT_ITEM_TYPE
 
     @staticmethod
-    def _tools_of_additional_tools_item(item: "dict[str, Any]") -> "list[Any]":
+    def _tools_of_additional_tools_item(item: "Mapping[str, object]") -> "list[object]":
         tools: Final = item.get("tools")
         return tools if isinstance(tools, list) else []
 
@@ -229,7 +229,7 @@ class BedrockMantleResponsesAPIConfig(BedrockMantleAuthMixin, OpenAIResponsesAPI
     def _hoist_codex_additional_tools(
         cls,
         input: "str | ResponseInputParam",
-    ) -> "tuple[str | ResponseInputParam, list[Any]]":
+    ) -> "tuple[str | ResponseInputParam, list[object]]":
         """Codex's "responses lite" wire mode ships tool definitions inside
         `input` as {"type": "additional_tools", "role": "developer",
         "tools": [...]} items. api.openai.com accepts that item type; Mantle
diff --git a/litellm/llms/cohere/embed/v1_transformation.py b/litellm/llms/cohere/embed/v1_transformation.py
index ee40464362d..b35fae5a1ac 100644
--- a/litellm/llms/cohere/embed/v1_transformation.py
+++ b/litellm/llms/cohere/embed/v1_transformation.py
@@ -2,7 +2,8 @@
 Legacy /v1/embedding transformation logic for Bedrock Cohere.
 """
 
-from typing import Any, Final
+from collections.abc import Sized
+from typing import Final, Protocol
 
 import httpx
 
@@ -16,6 +17,12 @@ from litellm.types.utils import EmbeddingResponse, PromptTokensDetailsWrapper, U
 from litellm.utils import is_base64_encoded
 
 
+class _SupportsEncode(Protocol):
+    """Tokenizer handle: the embedding usage path only encodes text to measure its token length."""
+
+    def encode(self, text: str, /) -> Sized: ...
+
+
 class CohereEmbeddingConfig:
     """
     Reference: https://docs.cohere.com/v2/reference/embed
@@ -61,7 +68,7 @@ class CohereEmbeddingConfig:
 
         return transformed_request
 
-    def _calculate_usage(self, input: list[str], encoding: Any, meta: dict) -> Usage:
+    def _calculate_usage(self, input: list[str], encoding: _SupportsEncode, meta: dict) -> Usage:
         input_tokens = 0
 
         text_tokens: Final[int | None] = meta.get("billed_units", {}).get("input_tokens")
@@ -97,7 +104,7 @@ class CohereEmbeddingConfig:
         data: dict | CohereEmbeddingRequest,
         model_response: EmbeddingResponse,
         model: str,
-        encoding: Any,
+        encoding: _SupportsEncode,
         input: list,
     ) -> EmbeddingResponse:
         response_json: Final = response.json()
@@ -121,7 +128,7 @@ class CohereEmbeddingConfig:
         response_json: dict,
         model_response: EmbeddingResponse,
         model: str,
-        encoding: Any,
+        encoding: _SupportsEncode,
         input: list,
     ) -> EmbeddingResponse:
         """
diff --git a/litellm/llms/gdc/chat/transformation.py b/litellm/llms/gdc/chat/transformation.py
index 03037512551..6eac3ac79cd 100644
--- a/litellm/llms/gdc/chat/transformation.py
+++ b/litellm/llms/gdc/chat/transformation.py
@@ -7,14 +7,32 @@ import os
 import re
 import threading
 from collections.abc import Callable
-from typing import Any, Final, Protocol
+from typing import Final, Protocol
 from urllib.parse import urlsplit
 
+from typing_extensions import ReadOnly, TypedDict, Unpack
+
 import litellm
 from litellm.llms.openai_like.chat.transformation import OpenAILikeChatConfig
 from litellm.types.llms.openai import AllMessageValues
 
 
+class _OpenAIGPTConfigOptions(TypedDict, total=False):
+    """The sampling defaults ``OpenAIGPTConfig.__init__`` accepts and stashes on the class."""
+
+    frequency_penalty: ReadOnly[int | None]
+    function_call: ReadOnly[str | dict[str, object] | None]
+    functions: ReadOnly[list[object] | None]
+    logit_bias: ReadOnly[dict[str, object] | None]
+    max_tokens: ReadOnly[int | None]
+    n: ReadOnly[int | None]
+    presence_penalty: ReadOnly[int | None]
+    stop: ReadOnly[str | list[object] | None]
+    temperature: ReadOnly[int | None]
+    top_p: ReadOnly[int | None]
+    response_format: ReadOnly[dict[str, object] | None]
+
+
 class _GDCHAudienceCredentials(Protocol):
     """A GDCH service account credential already bound to an audience, ready to mint a bearer token."""
 
@@ -32,7 +50,7 @@ class GDCGeminiConfig(OpenAILikeChatConfig):
     _GDCH_CREDENTIAL_TYPE: Final[str] = "gdch_service_account"
     _PATH_ID_PATTERN: Final[re.Pattern[str]] = re.compile(r"^[a-zA-Z0-9_-]+$")
 
-    def __init__(self, **kwargs: Any) -> None:
+    def __init__(self, **kwargs: Unpack[_OpenAIGPTConfigOptions]) -> None:
         super().__init__(**kwargs)
         self._creds_lock = threading.Lock()
         self._gdch_creds_cache: dict[tuple[str, str], _GDCHAudienceCredentials] = {}
diff --git a/litellm/llms/vertex_ai/vertex_ai_partner_models/llama3/transformation.py b/litellm/llms/vertex_ai/vertex_ai_partner_models/llama3/transformation.py
index 279035c455d..89a5b8a570e 100644
--- a/litellm/llms/vertex_ai/vertex_ai_partner_models/llama3/transformation.py
+++ b/litellm/llms/vertex_ai/vertex_ai_partner_models/llama3/transformation.py
@@ -1,6 +1,6 @@
 import types
 from collections.abc import AsyncIterator, Iterator
-from typing import TYPE_CHECKING, Any, Final
+from typing import TYPE_CHECKING, Final
 
 import httpx
 
@@ -95,7 +95,7 @@ class VertexAILlama3Config(OpenAIGPTConfig):
         streaming_response: Iterator[str] | AsyncIterator[str] | ModelResponse,
         sync_stream: bool,
         json_mode: bool | None = False,
-    ) -> Any:
+    ) -> "VertexAILlama3StreamingHandler":
         return VertexAILlama3StreamingHandler(
             streaming_response=streaming_response,
             sync_stream=sync_stream,
diff --git a/litellm/llms/voyage/rerank/transformation.py b/litellm/llms/voyage/rerank/transformation.py
index fea8452d934..6f8d024f0b1 100644
--- a/litellm/llms/voyage/rerank/transformation.py
+++ b/litellm/llms/voyage/rerank/transformation.py
@@ -4,8 +4,8 @@ Transformation logic for Voyage AI's /v1/rerank endpoint.
 Docs - https://docs.voyageai.com/docs/reranker
 """
 
-from collections.abc import Mapping
-from typing import Any, Final
+from collections.abc import Mapping, Sequence
+from typing import Final
 
 import httpx
 
@@ -33,7 +33,7 @@ class VoyageRerankConfig(BaseRerankConfig):
         model: str,
         drop_params: bool,
         query: str,
-        documents: list[str | dict[str, Any]],
+        documents: Sequence[str | Mapping[str, object]],
         custom_llm_provider: str | None = None,
         top_n: int | None = None,
         rank_fields: list[str] | None = None,
diff --git a/litellm/proxy/client/users.py b/litellm/proxy/client/users.py
index 3f11fe94043..503c92228a8 100644
--- a/litellm/proxy/client/users.py
+++ b/litellm/proxy/client/users.py
@@ -1,3 +1,4 @@
+from collections.abc import Mapping
 from typing import Any, Final
 
 import requests
@@ -50,7 +51,7 @@ class UsersManagementClient:
         response.raise_for_status()
         return response.json()
 
-    def create_user(self, user_data: dict[str, Any]) -> dict[str, Any]:
+    def create_user(self, user_data: Mapping[str, object]) -> dict[str, Any]:
         """Create a new user (POST /user/new)"""
         url: Final = f"{self.base_url}/user/new"
         response: Final = requests.post(url, headers=self._get_headers(), json=user_data, timeout=self.timeout)
diff --git a/litellm/proxy/common_utils/http_parsing_utils.py b/litellm/proxy/common_utils/http_parsing_utils.py
index 54a0f18fd63..2bae3e946f7 100644
--- a/litellm/proxy/common_utils/http_parsing_utils.py
+++ b/litellm/proxy/common_utils/http_parsing_utils.py
@@ -52,14 +52,18 @@ def _unqualified(annotation: object) -> object:
     return _unqualified(qualified[0])
 
 
+def _union_members(annotation: object) -> tuple[object, ...]:
+    """The non-``None`` members of a union annotation, or the annotation itself when it is not a union."""
+    if get_origin(annotation) not in (Union, UnionType):
+        return (annotation,)
+    members: Final[tuple[object, ...]] = get_args(annotation)
+    return tuple(arg for arg in members if arg is not type(None))
+
+
 def _numeric_form_type(annotation: object) -> type[int] | type[float] | None:
     """The scalar to parse an ``int``/``float``-typed field as, else ``None``."""
     unwrapped: Final = _unqualified(annotation)
-    candidates: Final = (
-        tuple(arg for arg in get_args(unwrapped) if arg is not type(None))
-        if get_origin(unwrapped) in (Union, UnionType)
-        else (unwrapped,)
-    )
+    candidates: Final = _union_members(unwrapped)
     if len(candidates) != 1:
         return None
     if candidates[0] is int:
diff --git a/litellm/proxy/db/prisma_client.py b/litellm/proxy/db/prisma_client.py
index 2190ae55fd2..2f2ebfdf2bb 100644
--- a/litellm/proxy/db/prisma_client.py
+++ b/litellm/proxy/db/prisma_client.py
@@ -13,7 +13,7 @@ import urllib
 import urllib.parse
 from collections.abc import Callable
 from datetime import datetime, timedelta
-from typing import Any, Final, Protocol
+from typing import TYPE_CHECKING, Any, Final, Protocol
 
 from litellm._logging import verbose_proxy_logger
 from litellm.proxy.db.token_auth import (
@@ -27,6 +27,9 @@ from litellm.proxy.db.token_auth import (
 )
 from litellm.secret_managers.main import str_to_bool
 
+if TYPE_CHECKING:
+    from prisma import Prisma
+
 __all__ = (
     "IAMEndpoint",
     "PrismaManager",
@@ -242,7 +245,7 @@ class PrismaWrapper:
     def _write_engine(prisma_client: _PrismaClient, engine: _PrismaEngine) -> None:
         prisma_client._Prisma__engine = engine
 
-    def _instrument_prisma_client(self, prisma_client: _PrismaClient) -> _PrismaDrainTracker | None:
+    def _instrument_prisma_client(self, prisma_client: "Prisma | _PrismaClient") -> _PrismaDrainTracker | None:
         from prisma.errors import ClientNotConnectedError
 
         try:
@@ -255,7 +258,7 @@ class PrismaWrapper:
         self._write_engine(prisma_client, _TrackedPrismaEngine(engine, tracker))
         return tracker
 
-    def _get_engine_pid(self, prisma_client: _PrismaClient | None = None) -> int:
+    def _get_engine_pid(self, prisma_client: "Prisma | _PrismaClient | None" = None) -> int:
         """Get the PID of the current Prisma engine subprocess, or 0 if unavailable.
 
         Must never raise: it runs inside the reconnect path, where the client
diff --git a/litellm/proxy/guardrails/guardrail_hooks/block_code_execution/block_code_execution.py b/litellm/proxy/guardrails/guardrail_hooks/block_code_execution/block_code_execution.py
index bf2aa1f76e0..2b697671eda 100644
--- a/litellm/proxy/guardrails/guardrail_hooks/block_code_execution/block_code_execution.py
+++ b/litellm/proxy/guardrails/guardrail_hooks/block_code_execution/block_code_execution.py
@@ -8,9 +8,10 @@ confidence scoring and a tunable threshold (only block when confidence >= thresh
 
 import re
 from datetime import datetime
-from typing import TYPE_CHECKING, Any, Final, Literal, Optional, cast
+from typing import TYPE_CHECKING, Final, Literal, Optional, cast
 
 from fastapi import HTTPException
+from typing_extensions import TypedDict, Unpack
 
 from litellm.integrations.custom_guardrail import (
     CustomGuardrail,
@@ -314,6 +315,10 @@ def _confidence_for_block(
     return 0.0
 
 
+class _CustomGuardrailOptions(TypedDict, total=False, extra_items=object):
+    """Base-class constructor options this guardrail forwards untouched to CustomGuardrail."""
+
+
 class BlockCodeExecutionGuardrail(CustomGuardrail):
     """
     Guardrail that detects fenced code blocks (markdown ```) and blocks or masks them
@@ -332,7 +337,7 @@ class BlockCodeExecutionGuardrail(CustomGuardrail):
         detect_execution_intent: bool = True,
         event_hook: Literal["pre_call", "post_call", "during_call"] | list[str] | None = None,
         default_on: bool = False,
-        **kwargs: Any,
+        **kwargs: Unpack[_CustomGuardrailOptions],
     ) -> None:
         # Normalize to type expected by CustomGuardrail
         _event_hook: GuardrailEventHooks | list[GuardrailEventHooks] | None = None
diff --git a/litellm/proxy/guardrails/guardrail_hooks/cato_networks/cato_networks.py b/litellm/proxy/guardrails/guardrail_hooks/cato_networks/cato_networks.py
index 176c308eda6..2d203c31974 100644
--- a/litellm/proxy/guardrails/guardrail_hooks/cato_networks/cato_networks.py
+++ b/litellm/proxy/guardrails/guardrail_hooks/cato_networks/cato_networks.py
@@ -264,7 +264,7 @@ class CatoNetworksGuardrail(CustomGuardrail):
                 stack.extend(reversed(node))
 
     @classmethod
-    def _extra_inspection_sources(cls, data: Mapping[str, Any]) -> Sequence[tuple[str, Sequence[Mapping[str, str]]]]:
+    def _extra_inspection_sources(cls, data: Mapping[str, object]) -> Sequence[tuple[str, Sequence[Mapping[str, str]]]]:
         """Text the proxy forwards to the model outside chat ``messages``:
         Responses-API ``input`` and ``instructions``, legacy completion
         ``prompt`` and tool/function/``response_format`` schema strings. Returned
@@ -336,7 +336,7 @@ class CatoNetworksGuardrail(CustomGuardrail):
         )
         raise HTTPException(status_code=400, detail=detection_message)
 
-    def _anonymize_request(self, res: Any, data: dict) -> dict:
+    def _anonymize_request(self, res: _CatoAnalyzeResponse, data: dict) -> dict:
         verbose_proxy_logger.info("Cato: anonymize action")
         redacted_chat: Final = res.get("redacted_chat")
         if not redacted_chat:
@@ -379,7 +379,7 @@ class CatoNetworksGuardrail(CustomGuardrail):
         return data
 
     @classmethod
-    def _apply_extra_redaction(cls, data: dict, field: str, redacted: list) -> bool:
+    def _apply_extra_redaction(cls, data: dict, field: str, redacted: Sequence[Mapping[str, object]]) -> bool:
         if field == "input":
             input_only: Final = {"input": data["input"]}
             if not redacted:
@@ -400,7 +400,7 @@ class CatoNetworksGuardrail(CustomGuardrail):
         return True
 
     @classmethod
-    def _apply_schema_string_redaction(cls, data: dict, redacted: list) -> None:
+    def _apply_schema_string_redaction(cls, data: dict, redacted: Sequence[Mapping[str, object]]) -> None:
         redactions: Final = iter(redacted)
         for container, key in cls._iter_schema_string_refs(data):
             replacement = next(redactions, None)
@@ -408,7 +408,7 @@ class CatoNetworksGuardrail(CustomGuardrail):
                 container[key] = replacement["content"]
 
     @staticmethod
-    def _apply_prompt_redaction(data: dict, redacted: list) -> None:
+    def _apply_prompt_redaction(data: dict, redacted: Sequence[Mapping[str, object]]) -> None:
         contents: Final = [m.get("content") for m in redacted if isinstance(m, dict)]
         prompt: Final = data.get("prompt")
         if isinstance(prompt, str):
diff --git a/litellm/proxy/guardrails/guardrail_hooks/compresr/compresr.py b/litellm/proxy/guardrails/guardrail_hooks/compresr/compresr.py
index 93d859066b0..1ecdb1b0f63 100644
--- a/litellm/proxy/guardrails/guardrail_hooks/compresr/compresr.py
+++ b/litellm/proxy/guardrails/guardrail_hooks/compresr/compresr.py
@@ -22,7 +22,7 @@ import json
 import time
 from collections import Counter, OrderedDict
 from dataclasses import dataclass, field
-from typing import TYPE_CHECKING, Any, Final, Literal, TypeGuard
+from typing import TYPE_CHECKING, Final, Literal, TypeGuard
 from urllib.parse import urlparse
 
 import httpx
@@ -64,6 +64,9 @@ if TYPE_CHECKING:
     from litellm.litellm_core_utils.litellm_logging import (
         Logging as LiteLLMLoggingObj,
     )
+    from litellm.llms.base_llm.anthropic_messages.transformation import (
+        BaseAnthropicMessagesConfig,
+    )
     from litellm.types.proxy.guardrails.guardrail_hooks.base import (
         GuardrailConfigModel,
     )
@@ -1049,7 +1052,7 @@ class CompresrGuardrail(CustomGuardrail):
 
     async def async_should_run_agentic_loop(
         self,
-        response: Any,
+        response: object,
         model: str,
         messages: list[dict],
         tools: list[dict] | None,
@@ -1069,8 +1072,8 @@ class CompresrGuardrail(CustomGuardrail):
         tools: dict,
         model: str,
         messages: list[dict],
-        response: Any,
-        anthropic_messages_provider_config: Any,
+        response: object,
+        anthropic_messages_provider_config: BaseAnthropicMessagesConfig | None,
         anthropic_messages_optional_request_params: dict,
         logging_obj: LiteLLMLoggingObj | None,
         stream: bool,
diff --git a/litellm/proxy/guardrails/guardrail_hooks/llm_as_a_judge/__init__.py b/litellm/proxy/guardrails/guardrail_hooks/llm_as_a_judge/__init__.py
index 172b1440ca3..806ab5161e8 100644
--- a/litellm/proxy/guardrails/guardrail_hooks/llm_as_a_judge/__init__.py
+++ b/litellm/proxy/guardrails/guardrail_hooks/llm_as_a_judge/__init__.py
@@ -2,10 +2,10 @@
 
 from collections.abc import Callable, Sequence
 from datetime import datetime
-from typing import TYPE_CHECKING, Any, Final, Generic, Literal, Optional, TypeVar
+from typing import TYPE_CHECKING, Final, Generic, Literal, Optional, TypeVar
 
 from fastapi import HTTPException
-from typing_extensions import NotRequired, ReadOnly, TypedDict
+from typing_extensions import NotRequired, ReadOnly, TypedDict, Unpack
 
 import litellm
 from litellm._logging import verbose_logger
@@ -106,6 +106,23 @@ def _build_judge_prompt(
     )
 
 
+class _CustomGuardrailOptions(TypedDict, total=False):
+    """The ``CustomGuardrail`` options this guardrail accepts and forwards untouched."""
+
+    mask_request_content: ReadOnly[bool]
+    mask_response_content: ReadOnly[bool]
+    violation_message_template: ReadOnly[str | None]
+    end_session_after_n_fails: ReadOnly[int | None]
+    on_violation: ReadOnly[str | None]
+    realtime_violation_message: ReadOnly[str | None]
+    on_sensitive_data: ReadOnly[str | None]
+    sensitive_data_route_to_model: ReadOnly[str | None]
+    sticky_session_routing: ReadOnly[bool]
+    run_in_parallel: ReadOnly[bool]
+    scan_raw_request: ReadOnly[bool]
+    only_scan_new_messages: ReadOnly[bool]
+
+
 class LLMAsAJudgeGuardrail(CustomGuardrail):
     """Post-call guardrail that judges response quality via an LLM."""
 
@@ -119,7 +136,7 @@ class LLMAsAJudgeGuardrail(CustomGuardrail):
         event_hook: GuardrailEventHooks | list[GuardrailEventHooks] | None = None,
         default_on: bool = False,
         router_provider: "Callable[[], Router | None] | None" = None,
-        **kwargs: Any,
+        **kwargs: Unpack[_CustomGuardrailOptions],
     ) -> None:
         _event_hook: GuardrailEventHooks | list[GuardrailEventHooks] | None = None
         if event_hook is not None:
diff --git a/litellm/proxy/guardrails/guardrail_hooks/noma/noma.py b/litellm/proxy/guardrails/guardrail_hooks/noma/noma.py
index 7ef0a9f73f3..edd78e0bbc6 100644
--- a/litellm/proxy/guardrails/guardrail_hooks/noma/noma.py
+++ b/litellm/proxy/guardrails/guardrail_hooks/noma/noma.py
@@ -9,13 +9,13 @@ import asyncio
 import json
 import os
 import warnings
-from collections.abc import AsyncGenerator
+from collections.abc import AsyncGenerator, AsyncIterable
 from datetime import datetime
 from typing import (
     TYPE_CHECKING,
-    Any,
     Final,
     Literal,
+    TypeVar,
 )
 from urllib.parse import urljoin
 
@@ -39,9 +39,7 @@ from litellm.types.guardrails import GuardrailEventHooks
 from litellm.types.utils import (
     CallTypes,
     CallTypesLiteral,
-    EmbeddingResponse,
     GuardrailStatus,
-    ImageResponse,
     ModelResponseStream,
     TextCompletionResponse,
 )
@@ -53,7 +51,8 @@ SENSITIVE_DATA_DETECTOR_KEYS: Final[list[str]] = ["sensitiveData", "dataDetector
 
 # Type aliases
 MessageRole = Literal["user", "assistant"]
-LLMResponse = Any | ModelResponse | EmbeddingResponse | ImageResponse
+LLMResponse = object
+_LLMResponseT: Final = TypeVar("_LLMResponseT")
 _LEGACY_NOMA_DEPRECATION_WARNED = False
 
 if TYPE_CHECKING:
@@ -709,10 +708,10 @@ class NomaGuardrail(CustomGuardrail):
     async def _check_llm_response(
         self,
         request_data: dict,
-        response: LLMResponse,
+        response: _LLMResponseT,
         user_auth: UserAPIKeyAuth,
         event_type: GuardrailEventHooks | None = None,
-    ) -> Any:
+    ) -> _LLMResponseT:
         """Check LLM response for policy violations"""
         content: Final = await self._process_llm_response_check(request_data, response, user_auth, event_type)
         if not content:
@@ -798,7 +797,7 @@ class NomaGuardrail(CustomGuardrail):
     async def async_post_call_streaming_iterator_hook(
         self,
         user_api_key_dict: UserAPIKeyAuth,
-        response: Any,
+        response: AsyncIterable[ModelResponseStream],
         request_data: dict,
     ) -> AsyncGenerator[ModelResponseStream, None]:
         """Process streaming response chunks with Noma guardrail."""
diff --git a/litellm/proxy/guardrails/guardrail_hooks/panw_prisma_airs/panw_prisma_airs.py b/litellm/proxy/guardrails/guardrail_hooks/panw_prisma_airs/panw_prisma_airs.py
index b73d3adb99e..86ad2f9db5f 100644
--- a/litellm/proxy/guardrails/guardrail_hooks/panw_prisma_airs/panw_prisma_airs.py
+++ b/litellm/proxy/guardrails/guardrail_hooks/panw_prisma_airs/panw_prisma_airs.py
@@ -793,7 +793,7 @@ class PanwPrismaAirsHandler(CustomGuardrail):
             },
         )
 
-    def _prepare_metadata_from_request(self, data: dict[str, Any]) -> dict[str, Any]:
+    def _prepare_metadata_from_request(self, data: dict[str, Any]) -> dict[str, object]:
         """
         Extract and prepare metadata from request data for PANW API call.
 
@@ -809,7 +809,7 @@ class PanwPrismaAirsHandler(CustomGuardrail):
         """
         user_metadata: Final = data.get("metadata", {}) or {}
         requester_meta: Final = user_metadata.get("requester_metadata", {}) or {}
-        metadata: Final = {
+        metadata: Final[dict[str, object]] = {
             "user": data.get("user") or "litellm_user",
             "model": data.get("model") or "unknown",
         }
diff --git a/litellm/proxy/guardrails/usage_endpoints.py b/litellm/proxy/guardrails/usage_endpoints.py
index 6259efb6654..3f7c36bbbf2 100644
--- a/litellm/proxy/guardrails/usage_endpoints.py
+++ b/litellm/proxy/guardrails/usage_endpoints.py
@@ -45,6 +45,7 @@ _EMPTY_UNITS: Final[Mapping[str, int]] = MappingProxyType({})
 _ACTION_SEVERITY: Final[Mapping[str, int]] = MappingProxyType({"passed": 0, "flagged": 1, "blocked": 2})
 
 _T = TypeVar("_T")
+_MetricsRowT = TypeVar("_MetricsRowT", bound="_DailyMetricsRow")
 
 _USAGE_MAX_RANGE_DAYS: Final = 366
 
@@ -360,10 +361,12 @@ def _trend_from_comparison(current_fail: float, previous_fail: float) -> str:
     return "stable"
 
 
-def _aggregate_daily_metrics(metrics: "Sequence[_DailyMetricsRow]", id_attr: str) -> Mapping[str, _MetricTotals]:
+def _aggregate_daily_metrics(
+    metrics: "Sequence[_MetricsRowT]", id_of: "Callable[[_MetricsRowT], str]"
+) -> Mapping[str, _MetricTotals]:
     agg: Final[dict[str, _MetricTotals]] = {}
     for m in metrics:
-        gid: str = getattr(m, id_attr)
+        gid: str = id_of(m)
         if gid not in agg:
             agg[gid] = {"requests": 0, "passed": 0, "blocked": 0, "flagged": 0}
         agg[gid]["requests"] += int(m.requests_evaluated or 0)
@@ -373,10 +376,12 @@ def _aggregate_daily_metrics(metrics: "Sequence[_DailyMetricsRow]", id_attr: str
     return agg
 
 
-def _prev_fail_rates(metrics_prev: "Sequence[_DailyMetricsRow]", id_attr: str) -> Mapping[str, float]:
+def _prev_fail_rates(
+    metrics_prev: "Sequence[_MetricsRowT]", id_of: "Callable[[_MetricsRowT], str]"
+) -> Mapping[str, float]:
     prev_agg_raw: Final[dict[str, _PrevPeriodCounts]] = {}
     for m in metrics_prev:
-        gid: str = getattr(m, id_attr)
+        gid: str = id_of(m)
         r, b = int(m.requests_evaluated or 0), int(m.blocked_count or 0)
         if gid not in prev_agg_raw:
             prev_agg_raw[gid] = {"req": 0, "blocked": 0}
@@ -429,7 +434,7 @@ def _field_str(mapping: Mapping[str, object], key: str, default: str) -> str:
     return str(mapping.get(key, default))
 
 
-def _get_guardrail_attrs(g: "_DbOrConfigGuardrail") -> tuple[Any, str]:
+def _get_guardrail_attrs(g: "_DbOrConfigGuardrail") -> tuple[str | None, str]:
     """Get (guardrail_id, display_name) from guardrail - handles Prisma model or dict."""
     gid: Final = _get_guardrail_field(g, "guardrail_id")
     name: Final = _get_guardrail_field(g, "guardrail_name")
@@ -592,8 +597,8 @@ async def guardrails_usage_overview(
             Sequence[prisma_models.LiteLLM_DailyGuardrailUsageUnits]
         ] = await _find_daily_guardrail_usage_units(prisma_client, where=units_where)
 
-        agg: Final = _aggregate_daily_metrics(metrics, "guardrail_id")
-        prev_agg: Final = _prev_fail_rates(metrics_prev, "guardrail_id")
+        agg: Final = _aggregate_daily_metrics(metrics, lambda m: m.guardrail_id)
+        prev_agg: Final = _prev_fail_rates(metrics_prev, lambda m: m.guardrail_id)
         units_agg: Final = _by(units_rows, lambda r: r.guardrail_id, _sum_counter_units)
         cost_agg: Final = _by(units_rows, lambda r: r.guardrail_id, _sum_tracked_cost)
         untracked_agg: Final = _by(units_rows, lambda r: r.guardrail_id, _sum_untracked_units)
@@ -811,7 +816,7 @@ def _usage_log_entry_from_row(
     )
 
 
-def _snippet(text: Any, max_len: int = 200) -> str | None:
+def _snippet(text: object, max_len: int = 200) -> str | None:
     if text is None:
         return None
     if isinstance(text, str):
@@ -964,8 +969,8 @@ async def policies_usage_overview(
                 }
             },
         )
-        agg: Final = _aggregate_daily_metrics(metrics, "policy_id")
-        prev_agg: Final = _prev_fail_rates(metrics_prev, "policy_id")
+        agg: Final = _aggregate_daily_metrics(metrics, lambda m: m.policy_id)
+        prev_agg: Final = _prev_fail_rates(metrics_prev, lambda m: m.policy_id)
         chart: Final = _chart_from_metrics(metrics)
         total_requests: Final = sum(a["requests"] for a in agg.values())
         total_blocked: Final = sum(a["blocked"] for a in agg.values())
diff --git a/litellm/proxy/hooks/proxy_track_cost_callback.py b/litellm/proxy/hooks/proxy_track_cost_callback.py
index c4fba8ecf9e..e6ada41f062 100644
--- a/litellm/proxy/hooks/proxy_track_cost_callback.py
+++ b/litellm/proxy/hooks/proxy_track_cost_callback.py
@@ -2,7 +2,7 @@ import asyncio
 import traceback
 from collections.abc import Sequence
 from datetime import datetime
-from typing import TYPE_CHECKING, Any, Final, cast
+from typing import TYPE_CHECKING, Any, Final, Protocol, cast
 
 import litellm
 from litellm._logging import verbose_proxy_logger
@@ -578,18 +578,36 @@ def _get_request_tags_for_cost_tracking(
     return None
 
 
+class _IncrementSpendCounters(Protocol):
+    """The ``increment_spend_counters`` coroutine :func:`_update_database_and_spend_counters` awaits."""
+
+    async def __call__(
+        self,
+        token: str | None,
+        team_id: str | None,
+        user_id: str | None,
+        response_cost: float | None,
+        org_id: str | None = None,
+        budget_reservation: dict[str, object] | None = None,
+        end_user_id: str | None = None,
+        tags: list[str] | None = None,
+        request_started_at: datetime | None = None,
+        model_access_groups: Sequence[str] | None = None,
+    ) -> None: ...
+
+
 async def _update_database_and_spend_counters(
     proxy_logging_obj: "ProxyLogging",
-    increment_spend_counters: Any,
+    increment_spend_counters: _IncrementSpendCounters,
     user_api_key: str | None,
     user_id: str | None,
     end_user_id: str | None,
     team_id: str | None,
     org_id: str | None,
     kwargs: dict,
-    completion_response: litellm.ModelResponse | Any | None,
-    start_time: Any,
-    end_time: Any,
+    completion_response: object,
+    start_time: datetime | None,
+    end_time: datetime | None,
     response_cost: float,
     budget_reservation: dict | None,
     request_tags: list[str] | None = None,
diff --git a/litellm/proxy/management_endpoints/model_access_group_management_endpoints.py b/litellm/proxy/management_endpoints/model_access_group_management_endpoints.py
index a48130a4f22..e960bdfe337 100644
--- a/litellm/proxy/management_endpoints/model_access_group_management_endpoints.py
+++ b/litellm/proxy/management_endpoints/model_access_group_management_endpoints.py
@@ -540,7 +540,7 @@ async def get_all_access_groups_from_db(
     deployments: Final = await ModelRepository(prisma_client).table.find_many()
 
     # Build access group map
-    access_group_map: Final[dict[str, dict[str, Any]]] = {}
+    model_names_by_group: Final[dict[str, list[str]]] = {}
 
     for deployment in deployments:
         model_info = deployment.model_info or {}
@@ -550,25 +550,20 @@ async def get_all_access_groups_from_db(
         model_name = deployment.model_name
 
         for access_group in access_groups:
-            if access_group not in access_group_map:
-                access_group_map[access_group] = {
-                    "model_names": set(),
-                    "deployment_count": 0,
-                }
+            if access_group not in model_names_by_group:
+                model_names_by_group[access_group] = []
 
-            access_group_map[access_group]["model_names"].add(model_name)
-            access_group_map[access_group]["deployment_count"] += 1
+            model_names_by_group[access_group].append(model_name)
 
     # Convert to AccessGroupInfo objects
-    result: Final = {}
-    for access_group, data in access_group_map.items():
-        result[access_group] = AccessGroupInfo(
+    return {
+        access_group: AccessGroupInfo(
             access_group=access_group,
-            model_names=sorted(list(data["model_names"])),
-            deployment_count=data["deployment_count"],
+            model_names=sorted(frozenset(model_names)),
+            deployment_count=len(model_names),
         )
-
-    return result
+        for access_group, model_names in model_names_by_group.items()
+    }
 
 
 @router.post(
diff --git a/litellm/proxy/management_endpoints/usage_endpoints/ai_usage_chat.py b/litellm/proxy/management_endpoints/usage_endpoints/ai_usage_chat.py
index da4ddbd0aac..1265da99d89 100644
--- a/litellm/proxy/management_endpoints/usage_endpoints/ai_usage_chat.py
+++ b/litellm/proxy/management_endpoints/usage_endpoints/ai_usage_chat.py
@@ -6,7 +6,7 @@ usage/spend data by querying the aggregated daily activity endpoints.
 import json
 from collections.abc import AsyncGenerator, AsyncIterator, Awaitable, Callable, Mapping, Sequence
 from datetime import date
-from typing import Any, Final, Literal, NamedTuple, Protocol, cast, overload
+from typing import Final, Literal, NamedTuple, Protocol, cast, overload
 
 from typing_extensions import ReadOnly, TypedDict
 
@@ -16,6 +16,7 @@ from litellm.constants import DEFAULT_COMPETITOR_DISCOVERY_MODEL
 from litellm.types.proxy.management_endpoints.common_daily_activity import (
     SpendAnalyticsPaginatedResponse,
 )
+from litellm.types.utils import ChatCompletionMessageToolCall
 
 # ---------------------------------------------------------------------------
 # Constants
@@ -489,19 +490,19 @@ async def _execute_tool_call(
 
 
 async def _process_tool_call(
-    tc: Any,
+    tc: ChatCompletionMessageToolCall,
     chat_messages: list[Mapping[str, object]],
     user_id: str | None,
     is_admin: bool,
 ) -> AsyncIterator[str]:
     """Execute a single tool call, yielding SSE events for status."""
-    fn_name: Final[str] = tc.function.name
+    fn_name: Final = tc.function.name
     fn_args: Final[Mapping[str, str]] = json.loads(tc.function.arguments)
 
     allowed_names: Final = {t["function"]["name"] for t in get_tools_for_role(is_admin)}
-    handler: Final = TOOL_HANDLERS.get(fn_name)
+    handler: Final = TOOL_HANDLERS.get(fn_name) if fn_name is not None else None
 
-    if fn_name not in allowed_names or not handler:
+    if fn_name is None or fn_name not in allowed_names or not handler:
         chat_messages.append(
             {
                 "role": "tool",
diff --git a/litellm/proxy/openai_files_endpoints/files_endpoints.py b/litellm/proxy/openai_files_endpoints/files_endpoints.py
index bf07f4748ef..4d3a397e519 100644
--- a/litellm/proxy/openai_files_endpoints/files_endpoints.py
+++ b/litellm/proxy/openai_files_endpoints/files_endpoints.py
@@ -485,8 +485,8 @@ async def create_file(
         # Parse expires_after if provided
         expires_after: FileExpiresAfter | None = None
         form_data_raw: Final = await request.form()
-        form_data_dict: Final[dict[str, Any]] = dict(form_data_raw)
-        extracted_litellm_metadata: Final[dict[str, Any] | None] = extract_nested_form_metadata(
+        form_data_dict: Final[Mapping[str, object]] = dict(form_data_raw)
+        extracted_litellm_metadata: Final[Mapping[str, object] | None] = extract_nested_form_metadata(
             form_data=form_data_dict, prefix="litellm_metadata["
         )
         expires_after_anchor: Final = form_data_raw.get("expires_after[anchor]")
diff --git a/litellm/proxy/openai_files_endpoints/storage_backend_service.py b/litellm/proxy/openai_files_endpoints/storage_backend_service.py
index e766f335071..0407499cbcc 100644
--- a/litellm/proxy/openai_files_endpoints/storage_backend_service.py
+++ b/litellm/proxy/openai_files_endpoints/storage_backend_service.py
@@ -7,7 +7,6 @@ storage backends (e.g., Azure Blob Storage) and managing associated metadata.
 
 import base64
 import time
-from collections.abc import Mapping
 from typing import Any, Final, cast
 
 from litellm._logging import verbose_proxy_logger
@@ -17,7 +16,7 @@ from litellm.llms.base_llm.files.transformation import BaseFileEndpoints
 from litellm.proxy._types import ProxyException, UserAPIKeyAuth
 from litellm.proxy.utils import ProxyLogging
 from litellm.types.llms.openai import OpenAIFileObject, OpenAIFilesPurpose
-from litellm.types.utils import SpecialEnums
+from litellm.types.utils import ExtractedFileData, SpecialEnums
 
 
 class StorageBackendFileService:
@@ -33,7 +32,7 @@ class StorageBackendFileService:
 
     @staticmethod
     async def upload_file_to_storage_backend(
-        file_data: Mapping[str, Any],
+        file_data: ExtractedFileData,
         target_storage: str,
         target_model_names: list[str],
         purpose: OpenAIFilesPurpose,
@@ -163,7 +162,7 @@ class StorageBackendFileService:
 
     @staticmethod
     def _create_unified_file_id(
-        file_type: str,
+        file_type: str | None,
         target_model_names: list[str],
         file_id: str,
     ) -> str:
@@ -193,7 +192,7 @@ class StorageBackendFileService:
     @staticmethod
     async def _store_in_managed_files(
         file_object: OpenAIFileObject,
-        file_data: Mapping[str, Any],
+        file_data: ExtractedFileData,
         target_model_names: list[str],
         target_storage: str,
         storage_url: str,
diff --git a/litellm/proxy/vector_store_endpoints/endpoints.py b/litellm/proxy/vector_store_endpoints/endpoints.py
index 1feda0b0bb5..f21c294e5a2 100644
--- a/litellm/proxy/vector_store_endpoints/endpoints.py
+++ b/litellm/proxy/vector_store_endpoints/endpoints.py
@@ -244,7 +244,7 @@ async def vector_store_create(
             )
 
         # Create vector store across multiple models
-        response: Final = await managed_vector_stores.acreate_vector_store(
+        response: Final[object] = await managed_vector_stores.acreate_vector_store(
             create_request=data,
             llm_router=llm_router,
             target_model_names_list=target_model_names_list,
diff --git a/litellm/proxy/vector_store_files_endpoints/endpoints.py b/litellm/proxy/vector_store_files_endpoints/endpoints.py
index 957ed9fd0b9..3ddea288ab8 100644
--- a/litellm/proxy/vector_store_files_endpoints/endpoints.py
+++ b/litellm/proxy/vector_store_files_endpoints/endpoints.py
@@ -553,7 +553,7 @@ async def vector_store_file_create(
 
     processor: Final = ProxyBaseLLMRequestProcessing(data=data)
     try:
-        response = await processor.base_process_llm_request(
+        response: object = await processor.base_process_llm_request(
             request=request,
             fastapi_response=fastapi_response,
             user_api_key_dict=user_api_key_dict,
@@ -756,7 +756,7 @@ async def vector_store_file_retrieve(
 
     processor: Final = ProxyBaseLLMRequestProcessing(data=data)
     try:
-        response = await processor.base_process_llm_request(
+        response: object = await processor.base_process_llm_request(
             request=request,
             fastapi_response=fastapi_response,
             user_api_key_dict=user_api_key_dict,
@@ -863,7 +863,7 @@ async def vector_store_file_content(
 
     processor: Final = ProxyBaseLLMRequestProcessing(data=data)
     try:
-        response = await processor.base_process_llm_request(
+        response: object = await processor.base_process_llm_request(
             request=request,
             fastapi_response=fastapi_response,
             user_api_key_dict=user_api_key_dict,
@@ -973,7 +973,7 @@ async def vector_store_file_update(
 
     processor: Final = ProxyBaseLLMRequestProcessing(data=data)
     try:
-        response = await processor.base_process_llm_request(
+        response: object = await processor.base_process_llm_request(
             request=request,
             fastapi_response=fastapi_response,
             user_api_key_dict=user_api_key_dict,
@@ -1080,7 +1080,7 @@ async def vector_store_file_delete(
 
     processor: Final = ProxyBaseLLMRequestProcessing(data=data)
     try:
-        response = await processor.base_process_llm_request(
+        response: object = await processor.base_process_llm_request(
             request=request,
             fastapi_response=fastapi_response,
             user_api_key_dict=user_api_key_dict,
diff --git a/litellm/proxy_auth/credentials.py b/litellm/proxy_auth/credentials.py
index a4e29241959..f8814954a7a 100644
--- a/litellm/proxy_auth/credentials.py
+++ b/litellm/proxy_auth/credentials.py
@@ -7,7 +7,7 @@ It follows the same TokenCredential protocol used by Azure SDK.
 
 import time
 from dataclasses import dataclass
-from typing import Any, Final, Protocol, runtime_checkable
+from typing import Final, Protocol, runtime_checkable
 
 
 @dataclass
@@ -50,6 +50,22 @@ class TokenCredential(Protocol):
         ...
 
 
+class _AzureAccessToken(Protocol):
+    """The two attributes :class:`AzureADCredential` reads off an azure-identity token."""
+
+    @property
+    def token(self) -> str: ...
+
+    @property
+    def expires_on(self) -> int: ...
+
+
+class _AzureTokenCredential(Protocol):
+    """The single method :class:`AzureADCredential` calls on the credential it wraps."""
+
+    def get_token(self, *scopes: str) -> _AzureAccessToken: ...
+
+
 class AzureADCredential:
     """
     Wrapper for Azure Identity credentials.
@@ -71,7 +87,7 @@ class AzureADCredential:
         cred = AzureADCredential(credential=azure_cred)
     """
 
-    def __init__(self, credential: Any | None = None):
+    def __init__(self, credential: _AzureTokenCredential | None = None):
         """
         Initialize with an optional Azure credential.
 
@@ -79,7 +95,7 @@ class AzureADCredential:
             credential: An azure-identity credential object. If None,
                        DefaultAzureCredential will be used on first token request.
         """
-        self._credential: Any = credential
+        self._credential: _AzureTokenCredential | None = credential
         self._initialized = credential is not None
 
     def get_token(self, scope: str) -> AccessToken:
@@ -95,20 +111,30 @@ class AzureADCredential:
         Raises:
             ImportError: If azure-identity is not installed.
         """
-        if not self._initialized:
-            try:
-                from azure.identity import DefaultAzureCredential
-
-                self._credential = DefaultAzureCredential()
-                self._initialized = True
-            except ImportError:
-                raise ImportError(
-                    "azure-identity is required for AzureADCredential. Install it with: pip install azure-identity"
-                )
-
-        result: Final = self._credential.get_token(scope)
+        result: Final = self._resolve_credential().get_token(scope)
         return AccessToken(token=result.token, expires_on=result.expires_on)
 
+    def _resolve_credential(self) -> _AzureTokenCredential:
+        """Return the wrapped credential, building the Azure default chain on first use.
+
+        Raises:
+            ImportError: If azure-identity is not installed.
+        """
+        existing: Final = self._credential
+        if existing is not None:
+            return existing
+        try:
+            from azure.identity import DefaultAzureCredential
+
+            created: Final = DefaultAzureCredential()
+        except ImportError:
+            raise ImportError(
+                "azure-identity is required for AzureADCredential. Install it with: pip install azure-identity"
+            )
+        self._credential = created
+        self._initialized = True
+        return created
+
 
 class GenericOAuth2Credential:
     """
@@ -228,7 +254,7 @@ class ProxyAuthHandler:
             self._cached_token = self.credential.get_token(self.scope)
         return self._cached_token
 
-    def get_auth_headers(self) -> dict:
+    def get_auth_headers(self) -> dict[str, str]:
         """
         Get HTTP headers for authentication.
 
diff --git a/litellm/rag/rag_query.py b/litellm/rag/rag_query.py
index 255faf94402..9325547c17d 100644
--- a/litellm/rag/rag_query.py
+++ b/litellm/rag/rag_query.py
@@ -124,9 +124,9 @@ class RAGQuery:
     @staticmethod
     def extract_documents_from_search(
         search_response: Any,
-    ) -> list[str | dict[str, Any]]:
+    ) -> list[str | dict[str, object]]:
         """Extract text documents from vector store search response."""
-        documents: Final[list[str | dict[str, Any]]] = []
+        documents: Final[list[str | dict[str, object]]] = []
         search_data: Final[_SearchDataView] = {"results": search_response.get("data", [])}
         for result in search_data["results"]:
             content_list = result.get("content", [])
diff --git a/litellm/repositories/verification_token_repository.py b/litellm/repositories/verification_token_repository.py
index c0e59f9b975..d02c2114136 100644
--- a/litellm/repositories/verification_token_repository.py
+++ b/litellm/repositories/verification_token_repository.py
@@ -5,7 +5,8 @@ VerificationToken repository for database operations on LiteLLM_VerificationToke
 import json
 from collections.abc import Mapping, Sequence
 from datetime import datetime
-from typing import TYPE_CHECKING, Final
+from types import TracebackType
+from typing import TYPE_CHECKING, Final, Protocol
 
 from litellm.models.verification_token import (
     LiteLLM_VerificationToken,
@@ -25,7 +26,36 @@ if TYPE_CHECKING:
         LiteLLM_VerificationToken as PrismaVerificationToken,
     )
 
-    from litellm.proxy.utils import PrismaClient
+
+class _VerificationTokenTables(Protocol):
+    """The two verification token tables this repository reads and writes."""
+
+    @property
+    def litellm_verificationtoken(self) -> TableActions["PrismaVerificationToken"]: ...
+
+    @property
+    def litellm_deletedverificationtoken(self) -> TableActions["PrismaDeletedVerificationToken"]: ...
+
+
+class _VerificationTokenTransactionManager(Protocol):
+    async def __aenter__(self) -> _VerificationTokenTables: ...
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_value: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> bool | None: ...
+
+
+class _PrismaVerificationTokenDb(_VerificationTokenTables, Protocol):
+    def tx(self) -> _VerificationTokenTransactionManager: ...
+
+
+class _PrismaClientView(Protocol):
+    @property
+    def db(self) -> _PrismaVerificationTokenDb: ...
+
 
 _JSON_ENCODED_TOKEN_FIELDS: Final = (
     "aliases",
@@ -44,17 +74,17 @@ class VerificationTokenRepository(BaseRepository[LiteLLM_VerificationToken]):
     """Repository for verification token (API key) database operations."""
 
     @property
-    def prisma_client(self) -> "PrismaClient":
-        prisma_client: Final[PrismaClient] = super().prisma_client
-        return prisma_client
+    def _db(self) -> _PrismaVerificationTokenDb:
+        client: Final[_PrismaClientView] = self.prisma_client
+        return client.db
 
     @property
     def table(self) -> TableActions["PrismaVerificationToken"]:
-        return self.prisma_client.db.litellm_verificationtoken
+        return self._db.litellm_verificationtoken
 
     @property
     def deleted_table(self) -> TableActions["PrismaDeletedVerificationToken"]:
-        return self.prisma_client.db.litellm_deletedverificationtoken
+        return self._db.litellm_deletedverificationtoken
 
     @property
     def model_class(self) -> type[LiteLLM_VerificationToken]:
@@ -325,7 +355,7 @@ class VerificationTokenRepository(BaseRepository[LiteLLM_VerificationToken]):
         archive_data["litellm_changed_by"] = litellm_changed_by
         archive_data["deleted_at"] = datetime.utcnow()
 
-        async with self.prisma_client.db.tx() as tx:
+        async with self._db.tx() as tx:
             await tx.litellm_deletedverificationtoken.create(data=archive_data)
             await tx.litellm_verificationtoken.delete(where={"token": token})
 
diff --git a/litellm/router_utils/search_api_router.py b/litellm/router_utils/search_api_router.py
index 309894957ea..76e833563ba 100644
--- a/litellm/router_utils/search_api_router.py
+++ b/litellm/router_utils/search_api_router.py
@@ -15,7 +15,7 @@ from typing import TYPE_CHECKING, Any, Final, Protocol
 from litellm._logging import verbose_router_logger
 
 if TYPE_CHECKING:
-    from litellm.types.router import SearchToolTypedDict
+    from litellm.types.router import SearchToolLiteLLMParams, SearchToolTypedDict
 
 
 class _SearchToolsRouter(Protocol):
@@ -34,7 +34,7 @@ class SearchAPIRouter:
     @staticmethod
     def _resolve_search_provider_credentials(
         *,
-        tool_litellm_params: dict[str, Any],
+        tool_litellm_params: "SearchToolLiteLLMParams",
     ) -> tuple[str | None, str | None]:
         """
         Resolve search provider credentials from tool configuration ONLY.

From 1ec5083ab4d94c758227c22be052f69e2ae2cf49 Mon Sep 17 00:00:00 2001
From: mateo-berri <277851410+mateo-berri@users.noreply.github.com>
Date: Tue, 8 Sep 2026 12:41:07 +0000
Subject: [PATCH 06/55] refactor(types): replace Any with real types across 54
 more backend files

Third batch of the fifth basedpyright Any reduction round. Every change is
typing-only and leaves runtime behavior identical.

Provider transformation configs, video and rerank base classes, OTel metadata
and the guardrail and realtime type modules move their payload, header and
optional-parameter annotations from Any to object, Mapping[str, object] or the
concrete model the call site already produces. Repositories and endpoints that
reached Prisma through an untyped handle now name the actions they call with the
repo's own TableActions protocol. The pydantic field retypes were checked
against pydantic to confirm object and Any validate, serialize and generate JSON
schema identically.
---
 .../providers/pydantic_ai_agents/config.py    |  4 +--
 litellm/integrations/argilla.py               |  7 +++--
 litellm/integrations/dynamodb.py              | 19 +++++++++++--
 litellm/integrations/focus/database.py        |  6 ++--
 .../focus/destinations/vantage_destination.py |  5 ++--
 .../langfuse/langfuse_otel_attributes.py      |  3 +-
 litellm/integrations/langsmith.py             |  8 +++---
 litellm/integrations/otel/model/metadata.py   | 14 +++++-----
 litellm/integrations/otel/mount.py            | 19 +++++++++++--
 .../litellm_core_utils/coroutine_checker.py   |  6 ++--
 .../exception_mapping_utils.py                |  6 ++--
 .../huggingface_template_handler.py           | 26 +++++++++++++----
 .../anthropic/count_tokens/handler.py         |  2 +-
 .../llms/base_llm/videos/transformation.py    | 10 +++----
 .../count_tokens/bedrock_token_counter.py     | 11 ++++----
 litellm/llms/bedrock/files/transformation.py  |  6 ++--
 .../guardrail_translation/handler.py          |  5 +++-
 litellm/llms/chatgpt/common_utils.py          |  4 +--
 .../responses/transformation.py               |  7 +++--
 .../llms/hosted_vllm/chat/transformation.py   | 21 ++++++--------
 litellm/llms/openai/common_utils.py           |  6 ++--
 litellm/llms/snowflake/chat/transformation.py |  4 +--
 .../stability/image_edit/transformations.py   |  4 +--
 .../llms/triton/completion/transformation.py  |  8 +++---
 .../llms/vertex_ai/rerank/transformation.py   |  4 +--
 .../volcengine/embedding/transformation.py    |  9 +++---
 litellm/llms/watsonx/rerank/transformation.py |  8 +++---
 litellm/llms/xai/realtime/transformation.py   | 18 ++++++------
 .../analytics_endpoints/cache_activity.py     | 20 +++++++++----
 .../proxy/client/cli/commands/model_groups.py | 18 ++++++++----
 litellm/proxy/client/cli/commands/up.py       |  3 +-
 .../common_utils/cache_pydantic_utils.py      |  2 +-
 .../common_utils/proxy_rate_limit_error.py    |  4 +--
 .../proxy/container_endpoints/endpoints.py    | 10 ++++---
 litellm/proxy/db/exception_handler.py         | 16 +++++++++--
 litellm/proxy/db/spend_log_tool_index.py      |  2 +-
 .../crowdstrike_aidr/crowdstrike_aidr.py      | 16 +++++------
 .../guardrail_hooks/enkryptai/enkryptai.py    |  4 +--
 .../guardrail_hooks/qualifire/qualifire.py    |  2 +-
 .../semantic_guard/route_loader.py            |  3 +-
 .../proxy/hooks/parallel_request_limiter.py   |  6 ++--
 .../common_daily_activity.py                  |  7 +++--
 litellm/proxy/ocr_endpoints/endpoints.py      | 14 +++++-----
 litellm/repositories/budget_repository.py     | 28 +++++++++++++++----
 .../repositories/organization_repository.py   | 28 +++++++++++++++----
 litellm/repositories/project_repository.py    | 11 ++++----
 .../adaptive_router/adaptive_router.py        |  9 +++---
 .../adaptive_router/signals.py                |  8 +++---
 .../adaptive_router/update_queue.py           | 11 ++++----
 litellm/types/containers/main.py              |  2 +-
 litellm/types/guardrails.py                   | 16 +++++------
 litellm/types/integrations/prometheus.py      |  8 +++---
 litellm/types/realtime.py                     | 16 +++++------
 litellm/vector_store_files/utils.py           | 11 ++++----
 54 files changed, 323 insertions(+), 202 deletions(-)

diff --git a/litellm/a2a_protocol/providers/pydantic_ai_agents/config.py b/litellm/a2a_protocol/providers/pydantic_ai_agents/config.py
index b7546e1a2a1..20404e3702b 100644
--- a/litellm/a2a_protocol/providers/pydantic_ai_agents/config.py
+++ b/litellm/a2a_protocol/providers/pydantic_ai_agents/config.py
@@ -23,7 +23,7 @@ class PydanticAIProviderConfig(BaseA2AProviderConfig):
         params: dict[str, Any],
         api_base: str | None = None,
         **kwargs: Any,
-    ) -> dict[str, Any]:
+    ) -> dict[str, object]:
         """Handle non-streaming request to Pydantic AI agent."""
         if api_base is None:
             raise ValueError("api_base is required for PydanticAIProviderConfig")
@@ -41,7 +41,7 @@ class PydanticAIProviderConfig(BaseA2AProviderConfig):
         params: dict[str, Any],
         api_base: str | None = None,
         **kwargs,
-    ) -> AsyncIterator[dict[str, Any]]:
+    ) -> AsyncIterator[dict[str, object]]:
         """Handle streaming request with fake streaming."""
         if not api_base:
             raise ValueError("api_base is required for Pydantic AI agents")
diff --git a/litellm/integrations/argilla.py b/litellm/integrations/argilla.py
index 9a87a94cf0b..664ef8efda1 100644
--- a/litellm/integrations/argilla.py
+++ b/litellm/integrations/argilla.py
@@ -7,7 +7,8 @@ import json
 import os
 import random
 import types
-from typing import Any, Final
+from collections.abc import Mapping
+from typing import Final
 
 import httpx
 from pydantic import BaseModel
@@ -69,7 +70,7 @@ class ArgillaLogger(CustomBatchLogger):
         self.flush_lock = asyncio.Lock()
         super().__init__(**kwargs, flush_lock=self.flush_lock)
 
-    def validate_argilla_transformation_object(self, argilla_transformation_object: dict[str, Any]):
+    def validate_argilla_transformation_object(self, argilla_transformation_object: Mapping[str, object]):
         if not isinstance(argilla_transformation_object, dict):
             raise Exception("'argilla_transformation_object' must be a dictionary, to log your payload to Argilla.")
 
@@ -115,7 +116,7 @@ class ArgillaLogger(CustomBatchLogger):
             ARGILLA_DATASET_NAME=_credentials_dataset_name,
         )
 
-    def get_chat_messages(self, payload: StandardLoggingPayload) -> list[dict[str, Any]]:
+    def get_chat_messages(self, payload: StandardLoggingPayload) -> list[dict[str, object]]:
         payload_messages: Final = payload.get("messages", None)
 
         if payload_messages is None:
diff --git a/litellm/integrations/dynamodb.py b/litellm/integrations/dynamodb.py
index 38f5924a233..3401ced4efb 100644
--- a/litellm/integrations/dynamodb.py
+++ b/litellm/integrations/dynamodb.py
@@ -3,12 +3,25 @@
 
 import os
 import traceback
-from typing import Any, Final
+from collections.abc import Mapping
+from typing import Final, Protocol
 
 import litellm
 from litellm._uuid import uuid
 
 
+class _DynamoTable(Protocol):
+    """The one boto3 DynamoDB table call this logger makes."""
+
+    def put_item(self, *, Item: Mapping[str, object]) -> object: ...
+
+
+class _DynamoResource(Protocol):
+    """The one boto3 DynamoDB resource call this logger makes."""
+
+    def Table(self, name: str) -> _DynamoTable: ...
+
+
 class DyanmoDBLogger:
     # Class variables or attributes
 
@@ -16,7 +29,7 @@ class DyanmoDBLogger:
         # Instance variables
         import boto3
 
-        self.dynamodb: Any = boto3.resource("dynamodb", region_name=os.environ["AWS_REGION_NAME"])
+        self.dynamodb: Final[_DynamoResource] = boto3.resource("dynamodb", region_name=os.environ["AWS_REGION_NAME"])
         if litellm.dynamodb_table_name is None:
             raise ValueError(
                 "LiteLLM Error, trying to use DynamoDB but not table name passed. Create a table and set `litellm.dynamodb_table_name=<your-table>`"
@@ -41,7 +54,7 @@ class DyanmoDBLogger:
             id: Final = response_obj.get("id", str(uuid.uuid4()))
 
             # Build the initial payload
-            payload: Final = {
+            payload: Final[dict[str, object]] = {
                 "id": id,
                 "call_type": call_type,
                 "startTime": start_time,
diff --git a/litellm/integrations/focus/database.py b/litellm/integrations/focus/database.py
index 657c7e0d264..891318f1c54 100644
--- a/litellm/integrations/focus/database.py
+++ b/litellm/integrations/focus/database.py
@@ -3,7 +3,7 @@
 from __future__ import annotations
 
 from datetime import datetime
-from typing import Any, Final
+from typing import Final
 
 import polars as pl
 
@@ -32,7 +32,7 @@ class FocusLiteLLMDatabase:
         client: Final = self._ensure_prisma_client()
 
         where_clauses: Final[list[str]] = []
-        query_params: Final[list[Any]] = []
+        query_params: Final[list[datetime | int]] = []
         placeholder_index = 1
         if start_time_utc:
             where_clauses.append(f"dus.updated_at >= ${placeholder_index}::timestamptz")
@@ -112,7 +112,7 @@ class FocusLiteLLMDatabase:
         except Exception as exc:
             raise RuntimeError(f"Error retrieving usage data: {exc}") from exc
 
-    async def get_table_info(self) -> dict[str, Any]:
+    async def get_table_info(self) -> dict[str, object]:
         """Return metadata about the spend table for diagnostics."""
         client: Final = self._ensure_prisma_client()
 
diff --git a/litellm/integrations/focus/destinations/vantage_destination.py b/litellm/integrations/focus/destinations/vantage_destination.py
index 132f27779c2..68b0d399975 100644
--- a/litellm/integrations/focus/destinations/vantage_destination.py
+++ b/litellm/integrations/focus/destinations/vantage_destination.py
@@ -4,7 +4,8 @@ from __future__ import annotations
 
 import csv
 import io
-from typing import Any, Final
+from collections.abc import Mapping
+from typing import Final
 
 import httpx  # noqa: F401 - used at runtime (AsyncClient, HTTPStatusError)
 
@@ -94,7 +95,7 @@ class FocusVantageDestination(FocusDestination):
         self,
         *,
         prefix: str,
-        config: dict[str, Any] | None = None,
+        config: Mapping[str, object] | None = None,
     ) -> None:
         config = config or {}
         api_key: Final = config.get("api_key")
diff --git a/litellm/integrations/langfuse/langfuse_otel_attributes.py b/litellm/integrations/langfuse/langfuse_otel_attributes.py
index 70fea1abb3b..1eb3ce1a9c2 100644
--- a/litellm/integrations/langfuse/langfuse_otel_attributes.py
+++ b/litellm/integrations/langfuse/langfuse_otel_attributes.py
@@ -5,6 +5,7 @@ Relevant Issue: https://github.com/BerriAI/litellm/issues/13764
 """
 
 import json
+from collections.abc import Mapping
 from typing import TYPE_CHECKING, Any, Final
 
 from pydantic import BaseModel
@@ -40,7 +41,7 @@ def get_output_content_by_type(
     | HttpxBinaryResponseContent
     | ResponsesAPIResponse
     | list,
-    kwargs: dict[str, Any] | None = None,
+    kwargs: Mapping[str, object] | None = None,
 ) -> str:
     """
     Extract output content from response objects based on their type.
diff --git a/litellm/integrations/langsmith.py b/litellm/integrations/langsmith.py
index 9607eccef52..2c3837b12ec 100644
--- a/litellm/integrations/langsmith.py
+++ b/litellm/integrations/langsmith.py
@@ -75,9 +75,9 @@ class LangsmithLogger(CustomBatchLogger):
         if _batch_size:
             self.batch_size = int(_batch_size)
         self.log_queue: list[LangsmithQueueObject] = []
-        self._flush_task: asyncio.Task[Any] | None = self._start_periodic_flush_task()
+        self._flush_task: asyncio.Task[None] | None = self._start_periodic_flush_task()
 
-    def _start_periodic_flush_task(self) -> asyncio.Task[Any] | None:
+    def _start_periodic_flush_task(self) -> asyncio.Task[None] | None:
         """Start the periodic flush task only when an event loop is already running."""
         try:
             loop: Final = asyncio.get_running_loop()
@@ -152,9 +152,9 @@ class LangsmithLogger(CustomBatchLogger):
 
         return self._redact_metadata(extra_metadata)
 
-    def _build_outputs_with_usage(self, payload: StandardLoggingPayload) -> dict[str, Any]:
+    def _build_outputs_with_usage(self, payload: StandardLoggingPayload) -> dict[str, object]:
         response: Final = payload["response"]
-        outputs: dict[str, Any]
+        outputs: dict[str, object]
         if isinstance(response, dict):
             outputs = {**response}
         else:
diff --git a/litellm/integrations/otel/model/metadata.py b/litellm/integrations/otel/model/metadata.py
index ee116aca46b..9eab3021d58 100644
--- a/litellm/integrations/otel/model/metadata.py
+++ b/litellm/integrations/otel/model/metadata.py
@@ -36,7 +36,7 @@ model. They coincide on the SDK path, which is correct.
 
 from __future__ import annotations
 
-from collections.abc import Iterator, Mapping
+from collections.abc import Callable, Iterator, Mapping
 from dataclasses import dataclass, field
 from types import MappingProxyType
 from typing import TYPE_CHECKING, Any, Final, cast
@@ -57,7 +57,7 @@ class RequestIdentity:
     # The team's free-form metadata, carried raw (empty/missing -> None) and
     # filtered to an operator allowlist only at Baggage-promotion time, so an
     # unconfigured deployment never promotes any of it.
-    team_metadata: Mapping[str, Any] | None = None
+    team_metadata: Mapping[str, object] | None = None
     key_hash: str | None = None
     end_user: str | None = None
     # The model litellm dispatched to the provider. Only known once the call
@@ -103,7 +103,7 @@ class RequestIdentity:
         ``user_api_key_*`` names that ``baggage.DEFAULT_BAGGAGE_METADATA_KEYS``
         promotes.
         """
-        get: Final = lambda name: getattr(auth, name, None)  # noqa: E731
+        get: Final[Callable[[str], object]] = lambda name: getattr(auth, name, None)  # noqa: E731
         metadata: Final = {
             meta_key: str(value)
             for meta_key, attr in (
@@ -217,7 +217,7 @@ class LLMCallEvent:
     time_to_first_chunk_seconds: float | None
 
     @classmethod
-    def from_dict(cls, kwargs: Mapping[str, Any]) -> LLMCallEvent:
+    def from_dict(cls, kwargs: Mapping[str, object]) -> LLMCallEvent:
         raw_payload: Final = kwargs.get("standard_logging_object")
         payload: Final = cast("StandardLoggingPayload", raw_payload) if raw_payload else None
         operation: Final = resolve_operation(as_str(kwargs.get("call_type")))
@@ -239,7 +239,7 @@ def time_to_first_chunk_seconds(kwargs: Mapping[str, Any]) -> float | None:
     to the first streamed chunk (``completion_start_time``); ``None`` for
     non-streaming calls, where ``completion_start_time`` is backfilled with the
     end time and would not measure first-chunk latency."""
-    optional_params: Final = cast(Mapping[str, Any], kwargs.get("optional_params") or {})
+    optional_params: Final = cast(Mapping[str, object], kwargs.get("optional_params") or {})
     if not optional_params.get("stream"):
         return None
     api_call_start: Final = to_seconds(kwargs.get("api_call_start_time"))
@@ -307,7 +307,7 @@ def _metadata_dicts(
     )
 
 
-def _call_id(payload: StandardLoggingPayload | None, kwargs: Mapping[str, Any]) -> str | None:
+def _call_id(payload: StandardLoggingPayload | None, kwargs: Mapping[str, object]) -> str | None:
     """The call id from the payload (when closed) or the bare kwargs (at pre_call)."""
     if payload is not None:
         call_id: Final = as_str(payload.get("litellm_call_id")) or as_str(payload.get("id"))
@@ -351,7 +351,7 @@ def _model_info_id(model_info: object) -> str | None:
     return None
 
 
-def _team_metadata_dict(value: object) -> Mapping[str, Any] | None:
+def _team_metadata_dict(value: object) -> Mapping[str, object] | None:
     """The team's free-form metadata as a raw mapping, or ``None`` when missing
     or empty.
 
diff --git a/litellm/integrations/otel/mount.py b/litellm/integrations/otel/mount.py
index ac647c2c4f6..776d8722d14 100644
--- a/litellm/integrations/otel/mount.py
+++ b/litellm/integrations/otel/mount.py
@@ -12,11 +12,14 @@ when the feature gate is off.
 """
 
 import os
-from typing import Any, Final
+from typing import TYPE_CHECKING, Final, Protocol
 
 from litellm._logging import verbose_logger
 from litellm.integrations.otel.model.config import is_otel_v2_enabled
 
+if TYPE_CHECKING:
+    from fastapi import FastAPI
+
 # Routes excluded from server-span tracing by default: high-frequency pollers and
 # static UI/docs assets, none of which are LLM traffic. Entries are substring-matched
 # against the request path (unanchored, so they survive a ``server_root_path`` prefix
@@ -65,7 +68,17 @@ PASSTHROUGH_PREFIXES: Final = frozenset(
 )
 
 
-def _passthrough_span_name_hook(span: Any, scope: dict) -> None:
+class _RenameableSpan(Protocol):
+    """The span surface the passthrough naming hook drives."""
+
+    def is_recording(self) -> bool: ...
+
+    def update_name(self, name: str) -> None: ...
+
+    def set_attribute(self, key: str, value: str) -> None: ...
+
+
+def _passthrough_span_name_hook(span: "_RenameableSpan | None", scope: dict) -> None:
     """FastAPI ``server_request_hook``: give passthrough server spans a useful name.
 
     The instrumentation matches the route at span creation, so both the span name
@@ -88,7 +101,7 @@ def _passthrough_span_name_hook(span: Any, scope: dict) -> None:
         pass
 
 
-def instrument_fastapi_app(app: Any) -> None:
+def instrument_fastapi_app(app: "FastAPI") -> None:
     """Attach OTel server-span instrumentation to the proxy FastAPI app.
 
     Safe no-op when the V2 gate is off or ``opentelemetry-instrumentation-fastapi``
diff --git a/litellm/litellm_core_utils/coroutine_checker.py b/litellm/litellm_core_utils/coroutine_checker.py
index 52fc44ba8dc..a5d4f8b968f 100644
--- a/litellm/litellm_core_utils/coroutine_checker.py
+++ b/litellm/litellm_core_utils/coroutine_checker.py
@@ -16,7 +16,7 @@ class CoroutineChecker:
     """
 
     def __init__(self):
-        self._cache = WeakKeyDictionary()
+        self._cache: WeakKeyDictionary[object, bool] = WeakKeyDictionary()
         self._max_size = COROUTINE_CHECKER_MAX_SIZE_IN_MEMORY
 
     def is_async_callable(self, callback: Any) -> bool:
@@ -33,10 +33,10 @@ class CoroutineChecker:
             pass
 
         # Determine target - optimized path for common cases
-        target = callback
+        target: object = callback
         if not inspect.isfunction(target) and not inspect.ismethod(target):
             try:
-                call_attr: Final = getattr(target, "__call__", None)
+                call_attr: Final[object] = getattr(target, "__call__", None)
                 if call_attr is not None:
                     target = call_attr
             except Exception:
diff --git a/litellm/litellm_core_utils/exception_mapping_utils.py b/litellm/litellm_core_utils/exception_mapping_utils.py
index 82708d412c9..92f07057da5 100644
--- a/litellm/litellm_core_utils/exception_mapping_utils.py
+++ b/litellm/litellm_core_utils/exception_mapping_utils.py
@@ -1,7 +1,7 @@
 import json
 import re
 import traceback
-from typing import Any, Final, Protocol, cast
+from typing import Final, Protocol, cast
 
 import httpx
 
@@ -191,7 +191,7 @@ def _get_response_headers(original_exception: Exception) -> httpx.Headers | None
     _response_headers: httpx.Headers | None = None
     try:
         _response_headers = getattr(original_exception, "headers", None)
-        error_response: Final = getattr(original_exception, "response", None)
+        error_response: Final[object] = getattr(original_exception, "response", None)
         if not _response_headers and error_response:
             _response_headers = getattr(error_response, "headers", None)
         if not _response_headers:
@@ -203,7 +203,7 @@ def _get_response_headers(original_exception: Exception) -> httpx.Headers | None
 
 
 def extract_and_raise_litellm_exception(
-    response: Any | None,
+    response: object | None,
     error_str: str,
     model: str,
     custom_llm_provider: str,
diff --git a/litellm/litellm_core_utils/prompt_templates/huggingface_template_handler.py b/litellm/litellm_core_utils/prompt_templates/huggingface_template_handler.py
index 3878b36cd91..8f8228d6dfd 100644
--- a/litellm/litellm_core_utils/prompt_templates/huggingface_template_handler.py
+++ b/litellm/litellm_core_utils/prompt_templates/huggingface_template_handler.py
@@ -1,6 +1,8 @@
 import json
 from datetime import datetime
-from typing import Any, Final
+from typing import Any, Final, Literal
+
+from typing_extensions import NotRequired, ReadOnly, TypedDict
 
 from litellm.llms.custom_httpx.http_handler import (
     _get_httpx_client,
@@ -9,6 +11,20 @@ from litellm.llms.custom_httpx.http_handler import (
 from litellm.types.llms.custom_http import httpxSpecialProvider
 
 
+class _TokenizerConfigResult(TypedDict):
+    """Outcome of a tokenizer_config.json fetch, carrying the parsed document when the fetch succeeded."""
+
+    status: ReadOnly[Literal["success", "failure"]]
+    tokenizer: NotRequired[ReadOnly[object]]
+
+
+class _ChatTemplateFileResult(TypedDict):
+    """Outcome of a chat template file fetch, carrying the template body when the fetch succeeded."""
+
+    status: ReadOnly[Literal["success", "failure"]]
+    chat_template: NotRequired[ReadOnly[str]]
+
+
 def strftime_now(fmt: str) -> str:
     """
     Custom function for templates that need current date/time formatting (e.g., gpt-oss)
@@ -22,7 +38,7 @@ def strftime_now(fmt: str) -> str:
     return datetime.now().strftime(fmt)
 
 
-def _get_tokenizer_config(hf_model_name: str) -> dict[str, Any]:
+def _get_tokenizer_config(hf_model_name: str) -> _TokenizerConfigResult:
     """
     Fetch tokenizer_config.json from HuggingFace (sync)
 
@@ -45,7 +61,7 @@ def _get_tokenizer_config(hf_model_name: str) -> dict[str, Any]:
         return {"status": "failure"}
 
 
-async def _aget_tokenizer_config(hf_model_name: str) -> dict[str, Any]:
+async def _aget_tokenizer_config(hf_model_name: str) -> _TokenizerConfigResult:
     """
     Fetch tokenizer_config.json from HuggingFace (async)
 
@@ -70,7 +86,7 @@ async def _aget_tokenizer_config(hf_model_name: str) -> dict[str, Any]:
         return {"status": "failure"}
 
 
-def _get_chat_template_file(hf_model_name: str) -> dict[str, Any]:
+def _get_chat_template_file(hf_model_name: str) -> _ChatTemplateFileResult:
     """
     Fetch chat template from separate .jinja file (sync)
 
@@ -98,7 +114,7 @@ def _get_chat_template_file(hf_model_name: str) -> dict[str, Any]:
     return {"status": "failure"}
 
 
-async def _aget_chat_template_file(hf_model_name: str) -> dict[str, Any]:
+async def _aget_chat_template_file(hf_model_name: str) -> _ChatTemplateFileResult:
     """
     Fetch chat template from separate .jinja file (async)
 
diff --git a/litellm/llms/azure_ai/anthropic/count_tokens/handler.py b/litellm/llms/azure_ai/anthropic/count_tokens/handler.py
index 3cc90823af9..36d5a56db0d 100644
--- a/litellm/llms/azure_ai/anthropic/count_tokens/handler.py
+++ b/litellm/llms/azure_ai/anthropic/count_tokens/handler.py
@@ -33,7 +33,7 @@ class AzureAIAnthropicCountTokensHandler(AzureAIAnthropicCountTokensConfig):
         litellm_params: dict[str, Any] | None = None,
         timeout: float | httpx.Timeout | None = None,
         tools: list[dict[str, Any]] | None = None,
-        system: Any | None = None,
+        system: object = None,
     ) -> dict[str, Any]:
         """
         Handle a CountTokens request using httpx with Azure authentication.
diff --git a/litellm/llms/base_llm/videos/transformation.py b/litellm/llms/base_llm/videos/transformation.py
index f725b295d0f..88cdcd61dd6 100644
--- a/litellm/llms/base_llm/videos/transformation.py
+++ b/litellm/llms/base_llm/videos/transformation.py
@@ -180,7 +180,7 @@ class BaseVideoConfig(ABC):
         api_base: str,
         litellm_params: GenericLiteLLMParams,
         headers: dict,
-        extra_body: dict[str, Any] | None = None,
+        extra_body: dict[str, object] | None = None,
     ) -> tuple[str, dict]:
         """
         Transform the video remix request into a URL and data
@@ -207,7 +207,7 @@ class BaseVideoConfig(ABC):
         after: str | None = None,
         limit: int | None = None,
         order: str | None = None,
-        extra_query: dict[str, Any] | None = None,
+        extra_query: dict[str, object] | None = None,
     ) -> tuple[str, dict]:
         """
         Transform the video list request into a URL and params
@@ -342,8 +342,8 @@ class BaseVideoConfig(ABC):
         litellm_params: GenericLiteLLMParams,
         headers: dict,
         video_file: FileContent | None = None,
-        extra_body: dict[str, Any] | None = None,
-        prefetched_source_data: dict[str, Any] | None = None,
+        extra_body: dict[str, object] | None = None,
+        prefetched_source_data: dict[str, object] | None = None,
     ) -> tuple[str, Mapping[str, object], RequestFiles | None]:
         """
         Transform the video edit request into a URL plus either JSON data or
@@ -373,7 +373,7 @@ class BaseVideoConfig(ABC):
         api_base: str,
         litellm_params: GenericLiteLLMParams,
         headers: dict,
-        extra_body: dict[str, Any] | None = None,
+        extra_body: dict[str, object] | None = None,
     ) -> tuple[str, dict]:
         """
         Transform the video extension request into a URL and JSON data.
diff --git a/litellm/llms/bedrock/count_tokens/bedrock_token_counter.py b/litellm/llms/bedrock/count_tokens/bedrock_token_counter.py
index 9c5211ed072..2d02b152c61 100644
--- a/litellm/llms/bedrock/count_tokens/bedrock_token_counter.py
+++ b/litellm/llms/bedrock/count_tokens/bedrock_token_counter.py
@@ -2,6 +2,7 @@
 Bedrock Token Counter implementation using the CountTokens API.
 """
 
+from collections.abc import Mapping, Sequence
 from typing import Any, Final
 
 from litellm._logging import verbose_logger
@@ -26,12 +27,12 @@ class BedrockTokenCounter(BaseTokenCounter):
     async def count_tokens(
         self,
         model_to_use: str,
-        messages: list[dict[str, Any]] | None,
-        contents: list[dict[str, Any]] | None,
+        messages: Sequence[Mapping[str, object]] | None,
+        contents: Sequence[Mapping[str, object]] | None,
         deployment: dict[str, Any] | None = None,
         request_model: str = "",
-        tools: list[dict[str, Any]] | None = None,
-        system: Any | None = None,
+        tools: Sequence[Mapping[str, object]] | None = None,
+        system: object | None = None,
     ) -> TokenCountResponse | None:
         """
         Count tokens using AWS Bedrock's CountTokens API.
@@ -56,7 +57,7 @@ class BedrockTokenCounter(BaseTokenCounter):
         litellm_params: Final = deployment.get("litellm_params", {})
 
         # Build request data in the format expected by BedrockCountTokensHandler
-        request_data: Final[dict[str, Any]] = {
+        request_data: Final[dict[str, object]] = {
             "model": model_to_use,
             "messages": messages,
         }
diff --git a/litellm/llms/bedrock/files/transformation.py b/litellm/llms/bedrock/files/transformation.py
index 33b27943ad8..f50d63c9f6f 100644
--- a/litellm/llms/bedrock/files/transformation.py
+++ b/litellm/llms/bedrock/files/transformation.py
@@ -247,7 +247,7 @@ def _validate_file_id_against_configured_buckets(
     return validate_against(configured_bucket_names[-1])
 
 
-def _uploaded_object_size(litellm_params: Mapping[str, object], raw_response: Response) -> int:
+def _uploaded_object_size(litellm_params: Mapping[str, object], response_headers: Mapping[str, str]) -> int:
     """
     S3 answers PutObject with an empty body, so the stored object size comes from the
     signed request recorded by `transform_create_file_request`, not the response headers.
@@ -255,7 +255,7 @@ def _uploaded_object_size(litellm_params: Mapping[str, object], raw_response: Re
     uploaded_size: Final = litellm_params.get(UPLOAD_CONTENT_LENGTH_PARAM)
     if isinstance(uploaded_size, int):
         return uploaded_size
-    response_content_length: Final = raw_response.headers.get("Content-Length", "0")
+    response_content_length: Final = response_headers.get("Content-Length", "0")
     return int(response_content_length) if response_content_length.isdigit() else 0
 
 
@@ -1161,7 +1161,7 @@ class BedrockFilesConfig(BaseAWSLLM, BaseFilesConfig):
             filename=filename,
             created_at=int(time.time()),  # Current timestamp
             status="uploaded",
-            bytes=_uploaded_object_size(litellm_params=litellm_params, raw_response=raw_response),
+            bytes=_uploaded_object_size(litellm_params=litellm_params, response_headers=raw_response.headers),
             object="file",
         )
 
diff --git a/litellm/llms/bedrock/passthrough/guardrail_translation/handler.py b/litellm/llms/bedrock/passthrough/guardrail_translation/handler.py
index b87f6196e51..eac8afd767c 100644
--- a/litellm/llms/bedrock/passthrough/guardrail_translation/handler.py
+++ b/litellm/llms/bedrock/passthrough/guardrail_translation/handler.py
@@ -14,6 +14,9 @@ from litellm.types.utils import GenericGuardrailAPIInputs
 if TYPE_CHECKING:
     from litellm.integrations.custom_guardrail import CustomGuardrail
     from litellm.litellm_core_utils.litellm_logging import Logging as LiteLLMLoggingObj
+    from litellm.llms.pass_through.guardrail_translation.handler import (
+        PassThroughEndpointHandler,
+    )
     from litellm.proxy._types import UserAPIKeyAuth
     from litellm.proxy.utils import ProxyLogging
 
@@ -27,7 +30,7 @@ def _is_converse_endpoint(endpoint: str) -> bool:
     return bool(parts) and parts[-1] in _CONVERSE_ACTIONS
 
 
-def _generic_passthrough_handler() -> BaseTranslation:
+def _generic_passthrough_handler() -> "PassThroughEndpointHandler":
     """
     Fallback for non-Converse Bedrock routes (e.g. invoke). The generic
     handler scans the full request/response payload so blocking guardrails
diff --git a/litellm/llms/chatgpt/common_utils.py b/litellm/llms/chatgpt/common_utils.py
index 35e32e4172f..fe33219f110 100644
--- a/litellm/llms/chatgpt/common_utils.py
+++ b/litellm/llms/chatgpt/common_utils.py
@@ -268,7 +268,7 @@ def _normalize_litellm_params(litellm_params: Any | None) -> dict:
     return {}
 
 
-def get_chatgpt_session_id(litellm_params: Any | None) -> str | None:
+def get_chatgpt_session_id(litellm_params: object) -> str | None:
     params: Final = _normalize_litellm_params(litellm_params)
     for key in ("litellm_session_id", "session_id"):
         value = params.get(key)
@@ -286,5 +286,5 @@ def get_chatgpt_session_id(litellm_params: Any | None) -> str | None:
     return None
 
 
-def ensure_chatgpt_session_id(litellm_params: Any | None) -> str:
+def ensure_chatgpt_session_id(litellm_params: object) -> str:
     return get_chatgpt_session_id(litellm_params) or str(uuid4())
diff --git a/litellm/llms/github_copilot/responses/transformation.py b/litellm/llms/github_copilot/responses/transformation.py
index 5a4bb798851..8b85b668cba 100644
--- a/litellm/llms/github_copilot/responses/transformation.py
+++ b/litellm/llms/github_copilot/responses/transformation.py
@@ -19,6 +19,7 @@ from litellm.llms.openai.responses.transformation import OpenAIResponsesAPIConfi
 from litellm.types.llms.openai import (
     ResponseInputParam,
     ResponsesAPIOptionalRequestParams,
+    ResponsesAPIStreamingResponse,
 )
 from litellm.types.router import GenericLiteLLMParams
 from litellm.types.utils import LlmProviders
@@ -129,7 +130,7 @@ class GithubCopilotResponsesAPIConfig(OpenAIResponsesAPIConfig):
         model: str,
         parsed_chunk: dict,
         logging_obj: LiteLLMLoggingObj,
-    ) -> Any:
+    ) -> ResponsesAPIStreamingResponse:
         parsed_chunk = self._normalize_stream_item_id(parsed_chunk)
         return super().transform_streaming_response(
             model=model,
@@ -262,7 +263,7 @@ class GithubCopilotResponsesAPIConfig(OpenAIResponsesAPIConfig):
         # Return the responses endpoint
         return f"{effective_api_base}/responses"
 
-    def _handle_reasoning_item(self, item: dict[str, Any]) -> dict[str, Any]:
+    def _handle_reasoning_item(self, item: dict[str, object]) -> dict[str, object]:
         """
         Handle reasoning items for GitHub Copilot, preserving encrypted_content.
 
@@ -280,7 +281,7 @@ class GithubCopilotResponsesAPIConfig(OpenAIResponsesAPIConfig):
 
             # Filter out None values for known problematic fields,
             # but preserve encrypted_content even if it exists
-            filtered_item: Final[dict[str, Any]] = {}
+            filtered_item: Final[dict[str, object]] = {}
             for k, v in item.items():
                 # Always include encrypted_content if present (even if None)
                 if k == "encrypted_content":
diff --git a/litellm/llms/hosted_vllm/chat/transformation.py b/litellm/llms/hosted_vllm/chat/transformation.py
index 29dc485732f..92bc857e385 100644
--- a/litellm/llms/hosted_vllm/chat/transformation.py
+++ b/litellm/llms/hosted_vllm/chat/transformation.py
@@ -28,12 +28,12 @@ from ...openai.chat.gpt_transformation import OpenAIGPTConfig
 
 
 class HostedVLLMChatConfig(OpenAIGPTConfig):
-    def _convert_custom_tools_to_function_tools(self, tools: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    def _convert_custom_tools_to_function_tools(self, tools: list[dict[str, Any]]) -> list[dict[str, object]]:
         """
         vLLM chat completions currently accepts only OpenAI function tools.
         Convert custom tools into function tools so request validation does not fail.
         """
-        converted_tools: Final[list[dict[str, Any]]] = []
+        converted_tools: Final[list[dict[str, object]]] = []
         for idx, tool in enumerate(tools):
             if not isinstance(tool, dict):
                 converted_tools.append(tool)
@@ -63,17 +63,14 @@ class HostedVLLMChatConfig(OpenAIGPTConfig):
                     "required": ["input"],
                 }
 
-            function_tool: dict[str, Any] = {
-                "type": "function",
-                "function": {
-                    "name": str(tool_name),
-                    "parameters": tool_parameters,
-                },
+            function_definition: dict[str, object] = {
+                "name": str(tool_name),
+                "parameters": tool_parameters,
             }
             if isinstance(tool_description, str):
-                function_tool["function"]["description"] = tool_description
+                function_definition["description"] = tool_description
 
-            converted_tools.append(function_tool)
+            converted_tools.append({"type": "function", "function": function_definition})
 
         return converted_tools
 
@@ -148,7 +145,7 @@ class HostedVLLMChatConfig(OpenAIGPTConfig):
     @overload
     def _transform_messages(
         self, messages: list[AllMessageValues], model: str, is_async: Literal[True]
-    ) -> Coroutine[Any, Any, list[AllMessageValues]]: ...
+    ) -> Coroutine[object, object, list[AllMessageValues]]: ...
 
     @overload
     def _transform_messages(
@@ -160,7 +157,7 @@ class HostedVLLMChatConfig(OpenAIGPTConfig):
 
     def _transform_messages(
         self, messages: list[AllMessageValues], model: str, is_async: bool = False
-    ) -> list[AllMessageValues] | Coroutine[Any, Any, list[AllMessageValues]]:
+    ) -> list[AllMessageValues] | Coroutine[object, object, list[AllMessageValues]]:
         """
         Support translating:
         - video files from file_id or file_data to video_url
diff --git a/litellm/llms/openai/common_utils.py b/litellm/llms/openai/common_utils.py
index 2db6d78a218..e60b6145b44 100644
--- a/litellm/llms/openai/common_utils.py
+++ b/litellm/llms/openai/common_utils.py
@@ -10,7 +10,7 @@ import ssl
 import time
 import uuid
 from collections.abc import AsyncIterator, Iterator, Mapping
-from typing import TYPE_CHECKING, Any, Final, Literal, NamedTuple, Optional
+from typing import TYPE_CHECKING, Final, Literal, NamedTuple, Optional
 from urllib.parse import urlsplit
 
 import httpx
@@ -87,8 +87,8 @@ class OpenAIError(BaseLLMException):
 ###################################################################
 def drop_params_from_unprocessable_entity_error(
     e: openai.UnprocessableEntityError | httpx.HTTPStatusError,
-    data: dict[str, Any],
-) -> dict[str, Any]:
+    data: Mapping[str, object],
+) -> dict[str, object]:
     """
     Helper function to read OpenAI UnprocessableEntityError and drop the params that raised an error from the error message.
 
diff --git a/litellm/llms/snowflake/chat/transformation.py b/litellm/llms/snowflake/chat/transformation.py
index f65b0876202..aeff902f655 100644
--- a/litellm/llms/snowflake/chat/transformation.py
+++ b/litellm/llms/snowflake/chat/transformation.py
@@ -315,7 +315,7 @@ class SnowflakeConfig(SnowflakeBaseConfig, OpenAIGPTConfig):
         for msg in messages:
             if isinstance(msg, dict):
                 role = msg.get("role", "")
-                content: Any = msg.get("content", "")
+                content: object = msg.get("content", "")
                 msg_cache_control: object = msg.get("cache_control")
             else:
                 role = getattr(msg, "role", "")
@@ -463,7 +463,7 @@ class SnowflakeConfig(SnowflakeBaseConfig, OpenAIGPTConfig):
 
         return body
 
-    def _transform_tool_choice_to_anthropic(self, tool_choice: Any) -> dict[str, Any]:
+    def _transform_tool_choice_to_anthropic(self, tool_choice: object) -> Mapping[str, object]:
         """
         Convert tool_choice from OpenAI format to Anthropic format.
 
diff --git a/litellm/llms/stability/image_edit/transformations.py b/litellm/llms/stability/image_edit/transformations.py
index 0b6052ad593..94711d21b50 100644
--- a/litellm/llms/stability/image_edit/transformations.py
+++ b/litellm/llms/stability/image_edit/transformations.py
@@ -74,7 +74,7 @@ class StabilityImageEditConfig(BaseImageEditConfig):
         }
 
         # Create a copy to not mutate original - convert TypedDict to regular dict
-        mapped_params: Final[dict[str, Any]] = dict(image_edit_optional_params)
+        mapped_params: Final[dict[str, object]] = dict(image_edit_optional_params)
 
         for k, v in image_edit_optional_params.items():
             if k in param_mapping:
@@ -182,7 +182,7 @@ class StabilityImageEditConfig(BaseImageEditConfig):
         # Build Stability request
         # Populate multipart form-data as separate text fields (data) and files.
         # Stability expects prompt/output_format/etc. as normal form fields, not file parts.
-        data: Final[dict[str, Any]] = {
+        data: Final[dict[str, object]] = {
             "output_format": "png",  # Default to PNG
         }
 
diff --git a/litellm/llms/triton/completion/transformation.py b/litellm/llms/triton/completion/transformation.py
index 98a68ba2c36..3c868b3a96f 100644
--- a/litellm/llms/triton/completion/transformation.py
+++ b/litellm/llms/triton/completion/transformation.py
@@ -4,7 +4,7 @@ Translates from OpenAI's `/v1/chat/completions` endpoint to Triton's `/generate`
 
 import json
 from collections.abc import AsyncIterator, Iterator
-from typing import TYPE_CHECKING, Any, Final, Literal
+from typing import TYPE_CHECKING, Final, Literal
 
 from httpx import Headers, Response
 
@@ -172,7 +172,7 @@ class TritonConfig(BaseConfig):
         streaming_response: Iterator[str] | AsyncIterator[str] | ModelResponse,
         sync_stream: bool,
         json_mode: bool | None = False,
-    ) -> Any:
+    ) -> "TritonResponseIterator":
         return TritonResponseIterator(
             streaming_response=streaming_response,
             sync_stream=sync_stream,
@@ -195,14 +195,14 @@ class TritonGenerateConfig(TritonConfig):
     ) -> dict:
         inference_params: Final = optional_params.copy()
         stream: Final = inference_params.pop("stream", False)
-        data_for_triton: Final[dict[str, Any]] = {
+        data_for_triton: Final[dict[str, object]] = {
             "text_input": prompt_factory(model=model, messages=messages),
             "parameters": {
                 "max_tokens": int(optional_params.get("max_tokens", DEFAULT_MAX_TOKENS_FOR_TRITON)),
+                **inference_params,
             },
             "stream": bool(stream),
         }
-        data_for_triton["parameters"].update(inference_params)
         return data_for_triton
 
     def transform_response(
diff --git a/litellm/llms/vertex_ai/rerank/transformation.py b/litellm/llms/vertex_ai/rerank/transformation.py
index 2ec4f2da79b..2b1ed3a29a8 100644
--- a/litellm/llms/vertex_ai/rerank/transformation.py
+++ b/litellm/llms/vertex_ai/rerank/transformation.py
@@ -5,7 +5,7 @@ Why separate file? Make it easy to see how transformation works
 """
 
 from collections.abc import Mapping
-from typing import Any, Final
+from typing import Final
 
 import httpx
 
@@ -227,7 +227,7 @@ class VertexAIRerankConfig(BaseRerankConfig, VertexBase):
         model: str,
         drop_params: bool,
         query: str,
-        documents: list[str | dict[str, Any]],
+        documents: list[str | dict[str, object]],
         custom_llm_provider: str | None = None,
         top_n: int | None = None,
         rank_fields: list[str] | None = None,
diff --git a/litellm/llms/volcengine/embedding/transformation.py b/litellm/llms/volcengine/embedding/transformation.py
index 091b9dfd334..7c626c66e9d 100644
--- a/litellm/llms/volcengine/embedding/transformation.py
+++ b/litellm/llms/volcengine/embedding/transformation.py
@@ -3,7 +3,8 @@ Volcengine Embedding Transformation
 Transforms OpenAI embedding requests to Volcengine format
 """
 
-from typing import Any, Final
+from collections.abc import Mapping
+from typing import Final
 
 import httpx
 
@@ -83,11 +84,11 @@ class VolcEngineEmbeddingConfig(BaseEmbeddingConfig):
 
     def map_openai_params(
         self,
-        non_default_params: dict[str, Any],
-        optional_params: dict[str, Any],
+        non_default_params: Mapping[str, object],
+        optional_params: dict[str, object],
         model: str,
         drop_params: bool,
-    ) -> dict[str, Any]:
+    ) -> dict[str, object]:
         """
         Map OpenAI embedding parameters to Volcengine format.
 
diff --git a/litellm/llms/watsonx/rerank/transformation.py b/litellm/llms/watsonx/rerank/transformation.py
index 293880b188d..0c81d50a5fe 100644
--- a/litellm/llms/watsonx/rerank/transformation.py
+++ b/litellm/llms/watsonx/rerank/transformation.py
@@ -5,8 +5,8 @@ Docs - https://cloud.ibm.com/apidocs/watsonx-ai#text-rerank
 """
 
 import uuid
-from collections.abc import Mapping
-from typing import Any, Final, cast
+from collections.abc import Mapping, Sequence
+from typing import Final, cast
 
 import httpx
 
@@ -96,7 +96,7 @@ class IBMWatsonXRerankConfig(IBMWatsonXMixin, BaseRerankConfig):
         model: str,
         drop_params: bool,
         query: str,
-        documents: list[str | dict[str, Any]],
+        documents: Sequence[str | Mapping[str, object]],
         custom_llm_provider: str | None = None,
         top_n: int | None = None,
         rank_fields: list[str] | None = None,
@@ -178,7 +178,7 @@ class IBMWatsonXRerankConfig(IBMWatsonXMixin, BaseRerankConfig):
         transformed_results: Final = []
 
         for result in _results:
-            transformed_result: dict[str, Any] = {
+            transformed_result: dict[str, object] = {
                 "index": result["index"],
                 "relevance_score": result["score"],
             }
diff --git a/litellm/llms/xai/realtime/transformation.py b/litellm/llms/xai/realtime/transformation.py
index e9d16daad7c..5efe125ee60 100644
--- a/litellm/llms/xai/realtime/transformation.py
+++ b/litellm/llms/xai/realtime/transformation.py
@@ -16,7 +16,7 @@ construction time (see ``handler.py``) so all normalization is isolated here
 and ``RealTimeStreaming`` stays provider-agnostic.
 """
 
-from typing import Any, Final
+from typing import Final
 
 
 class XAIRealtimeNormalizer:
@@ -58,7 +58,7 @@ class XAIRealtimeNormalizer:
         # Cache content-part objects keyed by (response_id, item_id, content_index)
         # so that ``response.content_part.done`` events missing ``part`` can be
         # back-filled from earlier ``content_part.added`` / delta-done events.
-        self._content_part_by_key: dict[tuple, dict[str, Any]] = {}
+        self._content_part_by_key: dict[tuple, dict[str, object]] = {}
 
     # ---------------------------------------------------------------------------
     # Public interface consumed by RealTimeStreaming
@@ -140,7 +140,7 @@ class XAIRealtimeNormalizer:
             }
         self._content_part_by_key[key] = updated
 
-    def _resolve_content_part(self, event: dict) -> dict[str, Any]:
+    def _resolve_content_part(self, event: dict) -> dict[str, object]:
         part: Final = event.get("part")
         if isinstance(part, dict):
             return part
@@ -214,7 +214,7 @@ class XAIRealtimeNormalizer:
         needs_content: Final = event_type in self._EVENTS_NEEDING_CONTENT_INDEX
         if not needs_output and not needs_content:
             return event
-        patch: Final[dict[str, Any]] = {}
+        patch: Final[dict[str, object]] = {}
         if needs_output and "output_index" not in event:
             patch["output_index"] = 0
         if needs_content and "content_index" not in event:
@@ -228,8 +228,8 @@ class XAIRealtimeNormalizer:
     # ---------------------------------------------------------------------------
 
     @staticmethod
-    def _default_ga_usage() -> dict[str, Any]:
-        default_details: Final[dict[str, Any]] = {
+    def _default_ga_usage() -> dict[str, object]:
+        default_details: Final[dict[str, int]] = {
             "cached_tokens": 0,
             "text_tokens": 0,
             "audio_tokens": 0,
@@ -243,7 +243,7 @@ class XAIRealtimeNormalizer:
         }
 
     @staticmethod
-    def _normalize_usage(usage: object, *, empty_as_null: bool) -> dict[str, Any] | None:
+    def _normalize_usage(usage: object, *, empty_as_null: bool) -> dict[str, object] | None:
         """Coerce a usage object into the full OpenAI GA shape.
 
         ``empty_as_null=True`` for ``response.created`` (usage optional).
@@ -253,12 +253,12 @@ class XAIRealtimeNormalizer:
             return None
         if not usage:
             return None if empty_as_null else XAIRealtimeNormalizer._default_ga_usage()
-        default_details: Final[dict[str, Any]] = {
+        default_details: Final[dict[str, int]] = {
             "cached_tokens": 0,
             "text_tokens": 0,
             "audio_tokens": 0,
         }
-        normalized: Final[dict[str, Any]] = {
+        normalized: Final[dict[str, object]] = {
             "total_tokens": usage.get("total_tokens", 0),
             "input_tokens": usage.get("input_tokens", 0),
             "output_tokens": usage.get("output_tokens", 0),
diff --git a/litellm/proxy/analytics_endpoints/cache_activity.py b/litellm/proxy/analytics_endpoints/cache_activity.py
index b87b8eac3ef..952ef5bdcfc 100644
--- a/litellm/proxy/analytics_endpoints/cache_activity.py
+++ b/litellm/proxy/analytics_endpoints/cache_activity.py
@@ -2,16 +2,26 @@ import asyncio
 import json
 from collections.abc import Sequence
 from datetime import datetime
-from typing import TYPE_CHECKING, Final
+from typing import Final, Protocol
 
 from pydantic import BaseModel, TypeAdapter
 
-if TYPE_CHECKING:
-    from litellm.proxy.utils import PrismaClient
-
 UNKNOWN_CALL_TYPE: Final = "Unknown"
 
 
+class _SupportsQueryRaw(Protocol):
+    """The single database operation the cache-activity queries issue."""
+
+    async def query_raw(self, query: str, *args: object) -> Sequence[object]: ...
+
+
+class _SupportsRawQueryDb(Protocol):
+    """A prisma client handle, narrowed to the raw-query surface used here."""
+
+    @property
+    def db(self) -> _SupportsQueryRaw: ...
+
+
 class CacheActivityGroup(BaseModel):
     call_type: str
     api_requests: int
@@ -143,7 +153,7 @@ def compute_totals(groups: Sequence[CacheActivityGroup]) -> CacheActivityTotals:
 
 
 async def get_cache_activity(
-    prisma_client: "PrismaClient",
+    prisma_client: _SupportsRawQueryDb,
     start_date: datetime,
     end_date: datetime,
     key_aliases: Sequence[str],
diff --git a/litellm/proxy/client/cli/commands/model_groups.py b/litellm/proxy/client/cli/commands/model_groups.py
index c904e5bed49..367c2063b6b 100644
--- a/litellm/proxy/client/cli/commands/model_groups.py
+++ b/litellm/proxy/client/cli/commands/model_groups.py
@@ -1,3 +1,4 @@
+from collections.abc import Mapping
 from typing import Final, Literal
 
 import click
@@ -5,10 +6,17 @@ import rich
 import rich.table
 
 from ... import Client
+from ._cli_context import cli_context_values
 
 
 def create_client(ctx: click.Context) -> Client:
-    return Client(base_url=ctx.obj["base_url"], api_key=ctx.obj["api_key"])
+    context: Final = cli_context_values(ctx)
+    return Client(base_url=context["base_url"], api_key=context["api_key"])
+
+
+def _rendered_field(group: Mapping[str, object], key: str, default: str) -> str:
+    """The rendered value of one model group field, or ``default`` when the group omits it."""
+    return str(group.get(key, default))
 
 
 @click.group(name="model-groups")
@@ -46,10 +54,10 @@ def list_model_groups(ctx: click.Context, output_format: Literal["table", "json"
 
     for group in groups:
         table.add_row(
-            str(group.get("model_group", "")),
-            str(group.get("mode", "chat")),
-            str(group.get("input_cost_per_token", "")),
-            str(group.get("output_cost_per_token", "")),
+            _rendered_field(group, "model_group", ""),
+            _rendered_field(group, "mode", "chat"),
+            _rendered_field(group, "input_cost_per_token", ""),
+            _rendered_field(group, "output_cost_per_token", ""),
         )
     rich.print(table)
 
diff --git a/litellm/proxy/client/cli/commands/up.py b/litellm/proxy/client/cli/commands/up.py
index b7c02866d6f..45d21b0c0b5 100644
--- a/litellm/proxy/client/cli/commands/up.py
+++ b/litellm/proxy/client/cli/commands/up.py
@@ -166,7 +166,8 @@ def up(ctx: click.Context) -> None:
     is already running (this does not start one for you). Cursor is not
     supported: it has no equivalent file-based config to patch.
     """
-    base_url: Final = ctx.obj["base_url"]
+    ctx_obj: Final[CliContextObj] = ctx.obj
+    base_url: Final = ctx_obj["base_url"]
 
     try:
         _ensure_fresh_login(ctx)
diff --git a/litellm/proxy/common_utils/cache_pydantic_utils.py b/litellm/proxy/common_utils/cache_pydantic_utils.py
index 725c2b61145..3703cf7c916 100644
--- a/litellm/proxy/common_utils/cache_pydantic_utils.py
+++ b/litellm/proxy/common_utils/cache_pydantic_utils.py
@@ -37,7 +37,7 @@ class CacheCodec:
     """
 
     @staticmethod
-    def serialize(value: Any, model_type: type[T] | None = None) -> Any:
+    def serialize(value: object, model_type: type[T] | None = None) -> object:
         """
         Encode a value for DualCache / Redis (``json.dumps``-safe).
 
diff --git a/litellm/proxy/common_utils/proxy_rate_limit_error.py b/litellm/proxy/common_utils/proxy_rate_limit_error.py
index c109da6f571..8d3a587a4cd 100644
--- a/litellm/proxy/common_utils/proxy_rate_limit_error.py
+++ b/litellm/proxy/common_utils/proxy_rate_limit_error.py
@@ -66,7 +66,7 @@ def map_v3_rate_limit_type(
     return None
 
 
-def _coerce_message(detail: Any) -> str:
+def _coerce_message(detail: object) -> str:
     """Best-effort, JSON-friendly stringification of an HTTPException-style detail."""
     if detail is None:
         return ""
@@ -144,7 +144,7 @@ class ProxyRateLimitError(HTTPException, RateLimitError):
     def __init__(
         self,
         detail: Any,
-        headers: Mapping[str, Any] | None = None,
+        headers: Mapping[str, object] | None = None,
         category: str | RateLimitErrorCategory = RateLimitErrorCategory.LITELLM_RATE_LIMIT,
         rate_limit_type: str | RateLimitType | None = None,
         model: str | None = None,
diff --git a/litellm/proxy/container_endpoints/endpoints.py b/litellm/proxy/container_endpoints/endpoints.py
index e852eb5d6f9..c1407979f29 100644
--- a/litellm/proxy/container_endpoints/endpoints.py
+++ b/litellm/proxy/container_endpoints/endpoints.py
@@ -106,7 +106,7 @@ async def create_container(
     # Process request using ProxyBaseLLMRequestProcessing
     processor: Final = ProxyBaseLLMRequestProcessing(data=data)
     try:
-        response: Final = await processor.base_process_llm_request(
+        response: Final[object] = await processor.base_process_llm_request(
             request=request,
             fastapi_response=fastapi_response,
             user_api_key_dict=user_api_key_dict,
@@ -216,7 +216,7 @@ async def list_containers(
         or get_custom_llm_provider_from_request_query(request=request)
         or "openai"
     )
-    data: Final[dict[str, Any]] = {
+    data: Final[dict[str, object]] = {
         "query_params": query_params,
         "model": query_params.get("model"),
         "order": order,
@@ -341,7 +341,7 @@ async def retrieve_container(
     # Process request using ProxyBaseLLMRequestProcessing
     processor: Final = ProxyBaseLLMRequestProcessing(data=data)
     try:
-        return await processor.base_process_llm_request(
+        container: Final[object] = await processor.base_process_llm_request(
             request=request,
             fastapi_response=fastapi_response,
             user_api_key_dict=user_api_key_dict,
@@ -366,6 +366,7 @@ async def retrieve_container(
             proxy_logging_obj=proxy_logging_obj,
             version=version,
         )
+    return container
 
 
 @router.delete(
@@ -446,7 +447,7 @@ async def delete_container(
     # Process request using ProxyBaseLLMRequestProcessing
     processor: Final = ProxyBaseLLMRequestProcessing(data=data)
     try:
-        return await processor.base_process_llm_request(
+        deleted_container: Final[object] = await processor.base_process_llm_request(
             request=request,
             fastapi_response=fastapi_response,
             user_api_key_dict=user_api_key_dict,
@@ -471,6 +472,7 @@ async def delete_container(
             proxy_logging_obj=proxy_logging_obj,
             version=version,
         )
+    return deleted_container
 
 
 # Register JSON-configured container file endpoints
diff --git a/litellm/proxy/db/exception_handler.py b/litellm/proxy/db/exception_handler.py
index f469587ab8e..de20416ad9c 100644
--- a/litellm/proxy/db/exception_handler.py
+++ b/litellm/proxy/db/exception_handler.py
@@ -1,5 +1,5 @@
 from collections.abc import Awaitable, Callable, Iterator
-from typing import Any, Final, TypeVar
+from typing import Final, Protocol, TypeVar
 
 from litellm._logging import verbose_proxy_logger
 from litellm.proxy._types import (
@@ -407,8 +407,20 @@ def _coerce_timeout(value: object, fallback: float) -> float:
 _ReadResultT: Final = TypeVar("_ReadResultT")
 
 
+class _DBReconnectClient(Protocol):
+    """The one method `call_with_db_reconnect_retry` needs from a Prisma client."""
+
+    async def attempt_db_reconnect(
+        self,
+        *,
+        reason: str,
+        timeout_seconds: float | None = None,
+        lock_timeout_seconds: float | None = None,
+    ) -> bool: ...
+
+
 async def call_with_db_reconnect_retry(
-    prisma_client: Any,
+    prisma_client: _DBReconnectClient,
     coro_factory: Callable[[], Awaitable[_ReadResultT]],
     *,
     reason: str,
diff --git a/litellm/proxy/db/spend_log_tool_index.py b/litellm/proxy/db/spend_log_tool_index.py
index 93bbc567430..7a7982481fb 100644
--- a/litellm/proxy/db/spend_log_tool_index.py
+++ b/litellm/proxy/db/spend_log_tool_index.py
@@ -148,4 +148,4 @@ async def flush_tool_usage_transactions(
         except DB_RETRY_SAFE_ERROR_TYPES:
             if attempt >= n_retry_times:
                 raise
-            await asyncio.sleep(2**attempt + random.uniform(0, 1))
+            await asyncio.sleep(2.0**attempt + random.uniform(0, 1))
diff --git a/litellm/proxy/guardrails/guardrail_hooks/crowdstrike_aidr/crowdstrike_aidr.py b/litellm/proxy/guardrails/guardrail_hooks/crowdstrike_aidr/crowdstrike_aidr.py
index f7f500b1adc..db6fc238b9b 100644
--- a/litellm/proxy/guardrails/guardrail_hooks/crowdstrike_aidr/crowdstrike_aidr.py
+++ b/litellm/proxy/guardrails/guardrail_hooks/crowdstrike_aidr/crowdstrike_aidr.py
@@ -6,7 +6,7 @@ from typing import TYPE_CHECKING, Annotated, Final, Literal, NamedTuple, Optiona
 
 from fastapi import HTTPException
 from pydantic import BaseModel, ConfigDict, Field, ValidationError
-from typing_extensions import Any, override
+from typing_extensions import override
 
 from litellm._logging import verbose_proxy_logger
 from litellm.integrations.custom_guardrail import (
@@ -78,7 +78,7 @@ class _GuardChatCompletionsResult(BaseModel):
     """Whether or not the prompt triggered a block detection."""
     transformed: bool | None = None
     """Whether or not the original input was transformed."""
-    detectors: dict[str, Any] | None = None
+    detectors: dict[str, object] | None = None
     """Result of the policy analyzing and input prompt."""
 
 
@@ -146,8 +146,8 @@ def _extract_text_from_message(message: _Message) -> str:
     return "\n".join(part.text for part in content if isinstance(part, _TextContentPart))
 
 
-def _merge_metadata_bags(request_data: Mapping[str, Any]) -> Mapping[str, Any] | None:
-    merged: Final[dict[str, Any]] = {}
+def _merge_metadata_bags(request_data: Mapping[str, object]) -> Mapping[str, object] | None:
+    merged: Final[dict[str, object]] = {}
     present = False
     for bag in (request_data.get("metadata"), request_data.get("litellm_metadata")):
         if isinstance(bag, Mapping):
@@ -313,7 +313,7 @@ class CrowdStrikeAIDRHandler(CustomGuardrail):
         self._set_streaming_params(streaming_params_from_litellm_params(litellm_params))
 
     async def _call_crowdstrike_aidr_guard(
-        self, payload: dict[str, Any], hook_name: str
+        self, payload: dict[str, object], hook_name: str
     ) -> _GuardChatCompletionsResult:
         """
         Makes the API call to the CrowdStrike AIDR AI Guard endpoint.
@@ -423,7 +423,7 @@ class CrowdStrikeAIDRHandler(CustomGuardrail):
         return [_extract_text_from_message(msg) for msg in tail]
 
     async def _call_or_fail_open(
-        self, payload: dict[str, Any], hook_name: str, request_data: dict[str, object]
+        self, payload: dict[str, object], hook_name: str, request_data: dict[str, object]
     ) -> _GuardChatCompletionsResult:
         start_time: Final = time.time()
         try:
@@ -506,7 +506,7 @@ class CrowdStrikeAIDRHandler(CustomGuardrail):
             event_type = "output"
             hook_name = "apply_guardrail (response)"
 
-        ai_guard_payload: Final[dict[str, Any]] = {
+        ai_guard_payload: Final[dict[str, object]] = {
             "guard_input": guard_input.model_dump(mode="json"),
             "event_type": event_type,
         }
@@ -521,7 +521,7 @@ class CrowdStrikeAIDRHandler(CustomGuardrail):
             if user_id:
                 ai_guard_payload["user_id"] = user_id
 
-            extra_info: Final[dict[str, str]] = {}
+            extra_info: Final[dict[str, object]] = {}
             user_email: Final = metadata.get("user_api_key_user_email")
             if user_email:
                 extra_info["user_name"] = user_email
diff --git a/litellm/proxy/guardrails/guardrail_hooks/enkryptai/enkryptai.py b/litellm/proxy/guardrails/guardrail_hooks/enkryptai/enkryptai.py
index 89afecafb0f..efe959bd186 100644
--- a/litellm/proxy/guardrails/guardrail_hooks/enkryptai/enkryptai.py
+++ b/litellm/proxy/guardrails/guardrail_hooks/enkryptai/enkryptai.py
@@ -6,7 +6,7 @@
 # +-------------------------------------------------------------+
 
 import os
-from collections.abc import AsyncGenerator
+from collections.abc import AsyncGenerator, AsyncIterable
 from datetime import datetime
 from typing import TYPE_CHECKING, Any, Final, Literal, Optional
 
@@ -465,7 +465,7 @@ class EnkryptAIGuardrails(CustomGuardrail):
     async def async_post_call_streaming_iterator_hook(
         self,
         user_api_key_dict: UserAPIKeyAuth,
-        response: Any,
+        response: AsyncIterable[ModelResponseStream],
         request_data: dict,
     ) -> AsyncGenerator[ModelResponseStream, None]:
         """
diff --git a/litellm/proxy/guardrails/guardrail_hooks/qualifire/qualifire.py b/litellm/proxy/guardrails/guardrail_hooks/qualifire/qualifire.py
index d82944c44ed..eceb54681f6 100644
--- a/litellm/proxy/guardrails/guardrail_hooks/qualifire/qualifire.py
+++ b/litellm/proxy/guardrails/guardrail_hooks/qualifire/qualifire.py
@@ -383,7 +383,7 @@ class QualifireGuardrail(CustomGuardrail):
             result: Final = response.json()
 
             # Extract response info for logging
-            qualifire_response: Final = {
+            qualifire_response: Final[dict[str, object]] = {
                 "score": result.get("score"),
                 "status": result.get("status"),
             }
diff --git a/litellm/proxy/guardrails/guardrail_hooks/semantic_guard/route_loader.py b/litellm/proxy/guardrails/guardrail_hooks/semantic_guard/route_loader.py
index 8d5923d1302..b2139779925 100644
--- a/litellm/proxy/guardrails/guardrail_hooks/semantic_guard/route_loader.py
+++ b/litellm/proxy/guardrails/guardrail_hooks/semantic_guard/route_loader.py
@@ -6,6 +6,7 @@ then builds a SemanticRouter for prompt matching.
 """
 
 import os
+from collections.abc import Mapping, Sequence
 from typing import TYPE_CHECKING, Any, Final
 
 import yaml
@@ -66,7 +67,7 @@ class SemanticGuardRouteLoader:
         cls,
         route_templates: list[str] | None,
         custom_routes_file: str | None,
-        custom_routes: list[dict[str, Any]] | None,
+        custom_routes: Sequence[Mapping[str, object]] | None,
         global_threshold: float = DEFAULT_SEMANTIC_GUARD_SIMILARITY_THRESHOLD,
     ) -> list["Route"]:
         """Build semantic-router Route objects from templates + custom config."""
diff --git a/litellm/proxy/hooks/parallel_request_limiter.py b/litellm/proxy/hooks/parallel_request_limiter.py
index b313cb64c3f..d41acadc4dd 100644
--- a/litellm/proxy/hooks/parallel_request_limiter.py
+++ b/litellm/proxy/hooks/parallel_request_limiter.py
@@ -27,7 +27,7 @@ if TYPE_CHECKING:
 
     from litellm.proxy.utils import InternalUsageCache as _InternalUsageCache
 
-    Span = _Span | Any
+    Span = _Span
     InternalUsageCache = _InternalUsageCache
 else:
     Span = Any
@@ -75,7 +75,7 @@ class _PROXY_MaxParallelRequestsHandler(CustomLogger):
         current: dict | None,
         request_count_api_key: str,
         rate_limit_type: Literal["key", "model_per_key", "user", "customer", "team"],
-        values_to_update_in_cache: list[tuple[Any, Any]],
+        values_to_update_in_cache: list[tuple[str, object]],
     ) -> dict:
         verbose_proxy_logger.info("Current Usage of %s in this minute: %s", rate_limit_type, current)
         if current is None:
@@ -266,7 +266,7 @@ class _PROXY_MaxParallelRequestsHandler(CustomLogger):
             rpm_limit = sys.maxsize
 
         values_to_update_in_cache: list[
-            tuple[Any, Any]
+            tuple[str, object]
         ] = []  # values that need to get updated in cache, will run a batch_set_cache after this function
 
         # ------------
diff --git a/litellm/proxy/management_endpoints/common_daily_activity.py b/litellm/proxy/management_endpoints/common_daily_activity.py
index ce6a97708ab..6841cadf972 100644
--- a/litellm/proxy/management_endpoints/common_daily_activity.py
+++ b/litellm/proxy/management_endpoints/common_daily_activity.py
@@ -17,6 +17,7 @@ from litellm.proxy.spend_tracking.key_metadata_recovery import (
 )
 from litellm.proxy.spend_tracking.ptu_feature_flag import is_ptu_cost_attribution_enabled
 from litellm.proxy.utils import PrismaClient
+from litellm.repositories.prisma_protocols import TableActions
 from litellm.repositories.table_repositories import DeletedVerificationTokenRepository
 from litellm.repositories.verification_token_repository import (
     VerificationTokenRepository,
@@ -1155,8 +1156,10 @@ async def get_daily_activity(
             include_current_utc_day=include_current_utc_day,
         )
 
+        spend_table: Final[TableActions[DailySpendRecord]] = getattr(prisma_client.db, table_name)
+
         # Get total count for pagination
-        total_count: Final[int] = await getattr(prisma_client.db, table_name).count(where=where_conditions)
+        total_count: Final[int] = await spend_table.count(where=where_conditions)
 
         # Fetch paginated results.
         # ``date`` alone is not a unique sort key -- a busy tenant has many
@@ -1168,7 +1171,7 @@ async def get_daily_activity(
         # total. Adding ``id`` (the row's UUID primary key, present on both
         # LiteLLM_DailyUserSpend and LiteLLM_DailyTeamSpend) as a tiebreaker
         # gives every page a stable cursor (#30164).
-        daily_spend_data: Final[Sequence[DailySpendRecord]] = await getattr(prisma_client.db, table_name).find_many(
+        daily_spend_data: Final[Sequence[DailySpendRecord]] = await spend_table.find_many(
             where=where_conditions,
             order=[
                 {"date": "desc"},
diff --git a/litellm/proxy/ocr_endpoints/endpoints.py b/litellm/proxy/ocr_endpoints/endpoints.py
index ebf4d988fdd..1d0108cc2ba 100644
--- a/litellm/proxy/ocr_endpoints/endpoints.py
+++ b/litellm/proxy/ocr_endpoints/endpoints.py
@@ -2,7 +2,7 @@
 
 import json
 from collections.abc import Mapping
-from typing import Any, Final, cast
+from typing import Final, cast
 
 import orjson
 from fastapi import APIRouter, Depends, HTTPException, Request, Response, UploadFile
@@ -48,7 +48,7 @@ def _build_document_from_upload(
     )
 
 
-def _with_request_format(data: Mapping[str, Any], request: Request) -> Mapping[str, Any]:
+def _with_request_format(data: Mapping[str, object], request: Request) -> Mapping[str, object]:
     """
     Resolve the requested response format from the body or the `x-req-format` header.
 
@@ -90,7 +90,7 @@ def _native_response(response: object, fastapi_response: Response) -> Response |
     )
 
 
-async def _parse_multipart_form(request: Request) -> dict[str, Any]:
+async def _parse_multipart_form(request: Request) -> dict[str, object]:
     """
     Extract OCR data from a multipart form request.
 
@@ -130,7 +130,7 @@ async def _parse_multipart_form(request: Request) -> dict[str, Any]:
         content_type=uploaded_file.content_type,
     )
 
-    data: Final[dict[str, Any]] = {"document": document}
+    data: Final[dict[str, object]] = {"document": document}
 
     for field_name, field_value in form.items():
         if field_name in ("file", "document"):
@@ -154,12 +154,12 @@ async def _parse_multipart_form(request: Request) -> dict[str, Any]:
     return data
 
 
-async def _parse_ocr_request(request: Request) -> Mapping[str, Any]:
+async def _parse_ocr_request(request: Request) -> Mapping[str, object]:
     """Parse an OCR request and apply the `x-req-format` header, if any."""
     return _with_request_format(await _parse_ocr_request_body(request), request)
 
 
-async def _parse_ocr_request_body(request: Request) -> dict[str, Any]:
+async def _parse_ocr_request_body(request: Request) -> dict[str, object]:
     """
     Parse an OCR request, supporting both JSON and multipart form data.
 
@@ -320,7 +320,7 @@ async def ocr(
         # Process request using ProxyBaseLLMRequestProcessing
         processor = ProxyBaseLLMRequestProcessing(data=data)
 
-        response: Final = await processor.base_process_llm_request(
+        response: Final[object] = await processor.base_process_llm_request(
             request=request,
             fastapi_response=fastapi_response,
             user_api_key_dict=user_api_key_dict,
diff --git a/litellm/repositories/budget_repository.py b/litellm/repositories/budget_repository.py
index 62632ffb5f6..205646c8393 100644
--- a/litellm/repositories/budget_repository.py
+++ b/litellm/repositories/budget_repository.py
@@ -2,7 +2,8 @@
 Budget repository for database operations on LiteLLM_BudgetTable.
 """
 
-from typing import TYPE_CHECKING, Any, Final
+from collections.abc import Mapping
+from typing import TYPE_CHECKING, Final, Protocol
 
 from litellm.models.budget import LiteLLM_BudgetTable
 from litellm.repositories.base_repository import BaseRepository
@@ -12,12 +13,27 @@ if TYPE_CHECKING:
     from prisma import models as prisma_models
 
 
+class _BudgetDb(Protocol):
+    """The single Prisma table this repository reaches for on ``prisma_client.db``."""
+
+    @property
+    def litellm_budgettable(self) -> TableActions["prisma_models.LiteLLM_BudgetTable"]: ...
+
+
+class _PrismaClientView(Protocol):
+    """The one attribute this repository reads off the untyped Prisma client wrapper."""
+
+    @property
+    def db(self) -> _BudgetDb: ...
+
+
 class BudgetRepository(BaseRepository[LiteLLM_BudgetTable]):
     """Repository for budget database operations."""
 
     @property
     def table(self) -> TableActions["prisma_models.LiteLLM_BudgetTable"]:
-        return self.prisma_client.db.litellm_budgettable
+        client: Final[_PrismaClientView] = self.prisma_client
+        return client.db.litellm_budgettable
 
     @property
     def model_class(self) -> type[LiteLLM_BudgetTable]:
@@ -34,12 +50,12 @@ class BudgetRepository(BaseRepository[LiteLLM_BudgetTable]):
         max_parallel_requests: int | None = None,
         tpm_limit: int | None = None,
         rpm_limit: int | None = None,
-        model_max_budget: dict[str, Any] | None = None,
+        model_max_budget: Mapping[str, object] | None = None,
         budget_duration: str | None = None,
         allowed_models: list[str] | None = None,
     ) -> LiteLLM_BudgetTable:
         """Create a new budget record."""
-        data: Final[dict[str, Any]] = {
+        data: Final[dict[str, object]] = {
             "created_by": created_by,
             "updated_by": created_by,
         }
@@ -71,12 +87,12 @@ class BudgetRepository(BaseRepository[LiteLLM_BudgetTable]):
         max_parallel_requests: int | None = None,
         tpm_limit: int | None = None,
         rpm_limit: int | None = None,
-        model_max_budget: dict[str, Any] | None = None,
+        model_max_budget: Mapping[str, object] | None = None,
         budget_duration: str | None = None,
         allowed_models: list[str] | None = None,
     ) -> LiteLLM_BudgetTable | None:
         """Update an existing budget record."""
-        data: Final[dict[str, Any]] = {"updated_by": updated_by}
+        data: Final[dict[str, object]] = {"updated_by": updated_by}
         if max_budget is not None:
             data["max_budget"] = max_budget
         if soft_budget is not None:
diff --git a/litellm/repositories/organization_repository.py b/litellm/repositories/organization_repository.py
index 5a9bd3724e0..47eb8f4a609 100644
--- a/litellm/repositories/organization_repository.py
+++ b/litellm/repositories/organization_repository.py
@@ -2,7 +2,8 @@
 Organization repository for database operations on LiteLLM_OrganizationTable.
 """
 
-from typing import TYPE_CHECKING, Any, Final
+from collections.abc import Mapping
+from typing import TYPE_CHECKING, Final, Protocol
 
 from litellm.models.organization import LiteLLM_OrganizationTable
 from litellm.repositories.base_repository import BaseRepository
@@ -12,12 +13,27 @@ if TYPE_CHECKING:
     from prisma import models as prisma_models
 
 
+class _OrganizationDb(Protocol):
+    """The single Prisma table this repository reaches for on ``prisma_client.db``."""
+
+    @property
+    def litellm_organizationtable(self) -> TableActions["prisma_models.LiteLLM_OrganizationTable"]: ...
+
+
+class _PrismaClientView(Protocol):
+    """The one attribute this repository reads off the untyped Prisma client wrapper."""
+
+    @property
+    def db(self) -> _OrganizationDb: ...
+
+
 class OrganizationRepository(BaseRepository[LiteLLM_OrganizationTable]):
     """Repository for organization database operations."""
 
     @property
     def table(self) -> TableActions["prisma_models.LiteLLM_OrganizationTable"]:
-        return self.prisma_client.db.litellm_organizationtable
+        client: Final[_PrismaClientView] = self.prisma_client
+        return client.db.litellm_organizationtable
 
     @property
     def model_class(self) -> type[LiteLLM_OrganizationTable]:
@@ -39,12 +55,12 @@ class OrganizationRepository(BaseRepository[LiteLLM_OrganizationTable]):
         budget_id: str,
         created_by: str,
         organization_id: str | None = None,
-        metadata: dict[str, Any] | None = None,
+        metadata: Mapping[str, object] | None = None,
         models: list[str] | None = None,
         object_permission_id: str | None = None,
     ) -> LiteLLM_OrganizationTable:
         """Create a new organization."""
-        data: Final[dict[str, Any]] = {
+        data: Final[dict[str, object]] = {
             "organization_alias": organization_alias,
             "budget_id": budget_id,
             "created_by": created_by,
@@ -67,12 +83,12 @@ class OrganizationRepository(BaseRepository[LiteLLM_OrganizationTable]):
         updated_by: str,
         organization_alias: str | None = None,
         budget_id: str | None = None,
-        metadata: dict[str, Any] | None = None,
+        metadata: Mapping[str, object] | None = None,
         models: list[str] | None = None,
         object_permission_id: str | None = None,
     ) -> LiteLLM_OrganizationTable | None:
         """Update an organization."""
-        data: Final[dict[str, Any]] = {"updated_by": updated_by}
+        data: Final[dict[str, object]] = {"updated_by": updated_by}
         if organization_alias is not None:
             data["organization_alias"] = organization_alias
         if budget_id is not None:
diff --git a/litellm/repositories/project_repository.py b/litellm/repositories/project_repository.py
index 48e55efd258..905e813f35e 100644
--- a/litellm/repositories/project_repository.py
+++ b/litellm/repositories/project_repository.py
@@ -2,7 +2,8 @@
 Project repository for database operations on LiteLLM_ProjectTable.
 """
 
-from typing import TYPE_CHECKING, Any, Final
+from collections.abc import Mapping
+from typing import TYPE_CHECKING, Final
 
 from litellm.models.project import LiteLLM_ProjectTable
 from litellm.repositories.base_repository import BaseRepository
@@ -43,14 +44,14 @@ class ProjectRepository(BaseRepository[LiteLLM_ProjectTable]):
         description: str | None = None,
         team_id: str | None = None,
         budget_id: str | None = None,
-        metadata: dict[str, Any] | None = None,
+        metadata: Mapping[str, object] | None = None,
         models: list[str] | None = None,
         model_rpm_limit: dict[str, int] | None = None,
         model_tpm_limit: dict[str, int] | None = None,
         object_permission_id: str | None = None,
     ) -> LiteLLM_ProjectTable:
         """Create a new project."""
-        data: Final[dict[str, Any]] = {
+        data: Final[dict[str, object]] = {
             "created_by": created_by,
             "updated_by": created_by,
         }
@@ -85,7 +86,7 @@ class ProjectRepository(BaseRepository[LiteLLM_ProjectTable]):
         description: str | None = None,
         team_id: str | None = None,
         budget_id: str | None = None,
-        metadata: dict[str, Any] | None = None,
+        metadata: Mapping[str, object] | None = None,
         models: list[str] | None = None,
         model_rpm_limit: dict[str, int] | None = None,
         model_tpm_limit: dict[str, int] | None = None,
@@ -93,7 +94,7 @@ class ProjectRepository(BaseRepository[LiteLLM_ProjectTable]):
         object_permission_id: str | None = None,
     ) -> LiteLLM_ProjectTable | None:
         """Update a project."""
-        data: Final[dict[str, Any]] = {"updated_by": updated_by}
+        data: Final[dict[str, object]] = {"updated_by": updated_by}
         if project_alias is not None:
             data["project_alias"] = project_alias
         if description is not None:
diff --git a/litellm/router_strategy/adaptive_router/adaptive_router.py b/litellm/router_strategy/adaptive_router/adaptive_router.py
index 12ccacbbc1d..8727c3a69f0 100644
--- a/litellm/router_strategy/adaptive_router/adaptive_router.py
+++ b/litellm/router_strategy/adaptive_router/adaptive_router.py
@@ -16,6 +16,7 @@ from __future__ import annotations
 import asyncio
 import time
 from collections import OrderedDict
+from collections.abc import Mapping
 from dataclasses import asdict, dataclass
 from typing import Any, Final, cast
 
@@ -122,7 +123,7 @@ class AdaptiveRouter:
                 prefs = self.model_to_prefs.get(model) or _default_prefs()
                 self._cells[(rt, model)] = initial_cell(prefs, rt)
 
-    async def load_state_from_db(self, prisma_client: Any) -> None:
+    async def load_state_from_db(self, prisma_client: object) -> None:
         """Add each row's persisted delta to a freshly computed cold-start prior.
 
         A row holds an accumulated delta, not a full posterior, and can be one-sided
@@ -237,7 +238,7 @@ class AdaptiveRouter:
             cost_weight=self.config.weights.cost,
         )
 
-    async def get_state_snapshot(self) -> dict[str, Any]:
+    async def get_state_snapshot(self) -> dict[str, object]:
         """In-memory snapshot for the introspection endpoint. Cheap; no DB hit."""
         cells: Final = []
         for (rt, model), cell in sorted(self._cells.items(), key=lambda kv: (kv[0][0].value, kv[0][1])):
@@ -278,7 +279,7 @@ class AdaptiveRouter:
 
     @staticmethod
     def _extract_min_quality_tier(
-        request_kwargs: dict[str, Any],
+        request_kwargs: Mapping[str, object],
     ) -> int | None:
         """Pull `min_quality_tier` from request headers or metadata.
 
@@ -484,7 +485,7 @@ class AdaptiveRouter:
             return combined_delta
 
     @staticmethod
-    def _persistable_session_snapshot(state: SessionState) -> dict[str, Any]:
+    def _persistable_session_snapshot(state: SessionState) -> dict[str, object]:
         snapshot: Final = asdict(state)
         for sensitive in (
             "last_user_content",
diff --git a/litellm/router_strategy/adaptive_router/signals.py b/litellm/router_strategy/adaptive_router/signals.py
index c28613b54eb..72e8d27d2bf 100644
--- a/litellm/router_strategy/adaptive_router/signals.py
+++ b/litellm/router_strategy/adaptive_router/signals.py
@@ -92,7 +92,7 @@ class Turn:
 
     user_content: str | None = None
     assistant_content: str | None = None
-    tool_calls: list[dict[str, Any]] = field(default_factory=list)
+    tool_calls: Sequence[Mapping[str, object]] = field(default_factory=list[Mapping[str, object]])
     tool_results: Sequence[Mapping[str, object]] = field(default_factory=list)
     response_status: int | None = None
 
@@ -174,7 +174,7 @@ def _detect_failure(tool_results: Sequence[Mapping[str, object]]) -> bool:
     return False
 
 
-def _signature(call: dict[str, Any]) -> str:
+def _signature(call: Mapping[str, Any]) -> str:
     """Stable signature for loop detection: name + sorted JSON-ish args."""
     name: Final = call.get("name") or call.get("function", {}).get("name", "")
     call_args = call.get("arguments")
@@ -185,7 +185,7 @@ def _signature(call: dict[str, Any]) -> str:
     return f"{name}({call_args})"
 
 
-def _detect_loop(history: list[str], new_calls: list[dict[str, Any]]) -> bool:
+def _detect_loop(history: list[str], new_calls: Sequence[Mapping[str, object]]) -> bool:
     """Fires if any new call's signature appears >= LOOP_REPEAT_THRESHOLD-1 times
     in recent history (so this call would be the Nth)."""
     if not new_calls:
@@ -238,7 +238,7 @@ def detect_response_signals(
     previous_assistant_content: str | None,
     current_assistant_content: str | None,
     tool_call_history: list[str],
-    tool_calls: list[dict[str, Any]],
+    tool_calls: Sequence[Mapping[str, object]],
     tool_results: Sequence[Mapping[str, object]],
     response_status: int | None,
 ) -> SignalDelta:
diff --git a/litellm/router_strategy/adaptive_router/update_queue.py b/litellm/router_strategy/adaptive_router/update_queue.py
index 1b9fce284ac..e28f2379f9c 100644
--- a/litellm/router_strategy/adaptive_router/update_queue.py
+++ b/litellm/router_strategy/adaptive_router/update_queue.py
@@ -19,7 +19,8 @@ to the in-memory aggregator). Flush is async and batched.
 from __future__ import annotations
 
 import asyncio
-from typing import Any, Final
+from collections.abc import Mapping
+from typing import Final
 
 from litellm._logging import verbose_router_logger
 from litellm.repositories.table_repositories import (
@@ -39,7 +40,7 @@ class AdaptiveRouterUpdateQueue:
 
     def __init__(self) -> None:
         self._state_agg: dict[StateKey, dict[str, float]] = {}
-        self._session_agg: dict[SessionKey, dict[str, Any]] = {}
+        self._session_agg: dict[SessionKey, Mapping[str, object]] = {}
         self._lock = asyncio.Lock()
         self._max_state_size_seen = 0
         self._max_session_size_seen = 0
@@ -77,7 +78,7 @@ class AdaptiveRouterUpdateQueue:
         session_id: str,
         router_name: str,
         model_name: str,
-        state_dict: dict[str, Any],
+        state_dict: Mapping[str, object],
     ) -> None:
         """
         Last-write-wins per session row. The state_dict is a snapshot of the
@@ -91,7 +92,7 @@ class AdaptiveRouterUpdateQueue:
 
     # ---- Flushers (called by background task) ----------------------------
 
-    async def flush_state_to_db(self, prisma_client: Any) -> int:
+    async def flush_state_to_db(self, prisma_client: object) -> int:
         """
         Drain state aggregator and apply to LiteLLM_AdaptiveRouterState.
         Returns number of cells flushed.
@@ -147,7 +148,7 @@ class AdaptiveRouterUpdateQueue:
 
         return len(batch)
 
-    async def flush_session_to_db(self, prisma_client: Any) -> int:
+    async def flush_session_to_db(self, prisma_client: object) -> int:
         """
         Drain session aggregator and upsert into LiteLLM_AdaptiveRouterSession.
         Returns number of session rows flushed.
diff --git a/litellm/types/containers/main.py b/litellm/types/containers/main.py
index 6a339fd2eac..62ef524a435 100644
--- a/litellm/types/containers/main.py
+++ b/litellm/types/containers/main.py
@@ -140,7 +140,7 @@ class ContainerFileObject(BaseModel):
     created_at: int
     path: str
     source: str
-    _hidden_params: dict[str, Any] = {}
+    _hidden_params: dict[str, builtins.object] = {}
 
     def __contains__(self, key: str) -> bool:
         return hasattr(self, key)
diff --git a/litellm/types/guardrails.py b/litellm/types/guardrails.py
index 02dee40f2a3..175226f8d4b 100644
--- a/litellm/types/guardrails.py
+++ b/litellm/types/guardrails.py
@@ -2,10 +2,10 @@ from collections.abc import Mapping
 from datetime import datetime
 from enum import Enum
 from types import MappingProxyType
-from typing import Any, Final, Literal
+from typing import Final, Literal
 
 from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator
-from typing_extensions import Required, TypedDict
+from typing_extensions import ReadOnly, Required, TypedDict
 
 from litellm.constants import BEDROCK_APPLY_GUARDRAIL_CHUNK_BUDGET_CHARS
 from litellm.types.proxy.guardrails.guardrail_hooks.akto import (
@@ -935,7 +935,7 @@ class BaseLitellmParams(ContentFilterConfigModel):  # works for new and patch up
         ),
     )
 
-    additional_provider_specific_params: dict[str, Any] | None = Field(
+    additional_provider_specific_params: dict[str, object] | None = Field(
         default=None,
         description="Additional provider-specific parameters for generic guardrail APIs",
     )
@@ -1157,7 +1157,7 @@ class GuardrailEventHooks(str, Enum):
 
 
 class DynamicGuardrailParams(TypedDict):
-    extra_body: dict[str, Any]
+    extra_body: ReadOnly[dict[str, object]]
 
 
 class GUARDRAIL_DEFINITION_LOCATION(str, Enum):
@@ -1188,7 +1188,7 @@ class GuardrailUIAddGuardrailSettings(BaseModel):
     supported_modes: list[str]
     supported_modes_by_provider: dict[str, list[str]]
     pii_entity_categories: list[PiiEntityCategoryMap]
-    content_filter_settings: dict[str, Any] | None = None
+    content_filter_settings: dict[str, object] | None = None
 
 
 class PresidioPerRequestConfig(BaseModel):
@@ -1206,8 +1206,8 @@ class ApplyGuardrailRequest(BaseModel):
     language: str | None = None
     entities: list[PiiEntityType] | None = None
     input_type: str = "request"
-    messages: list[dict[str, Any]] | None = None
-    metadata: dict[str, Any] | None = None
+    messages: list[dict[str, object]] | None = None
+    metadata: dict[str, object] | None = None
 
 
 class ApplyGuardrailResponse(BaseModel):
@@ -1217,4 +1217,4 @@ class ApplyGuardrailResponse(BaseModel):
 class PatchGuardrailRequest(BaseModel):
     guardrail_name: str | None = None
     litellm_params: BaseLitellmParams | None = None
-    guardrail_info: dict[str, Any] | None = None
+    guardrail_info: dict[str, object] | None = None
diff --git a/litellm/types/integrations/prometheus.py b/litellm/types/integrations/prometheus.py
index 8498b6f6d00..323f43f4b01 100644
--- a/litellm/types/integrations/prometheus.py
+++ b/litellm/types/integrations/prometheus.py
@@ -44,7 +44,7 @@ def _sanitize_prometheus_label_name(label: str) -> str:
 _PROMETHEUS_LABEL_VALUE_TRANSLATE_V1: Final = str.maketrans("\n", " ", "\r\u2028\u2029")
 
 
-def _sanitize_prometheus_label_value(value: Any | None) -> str | None:
+def _sanitize_prometheus_label_value(value: object | None) -> str | None:
     """
     Same semantics as :func:`_sanitize_prometheus_label_value`, implemented with
     ``str.translate`` plus a single escape pass instead of chained ``replace``.
@@ -1023,7 +1023,7 @@ class UserAPIKeyLabelValues:
         ``hashed_api_key``. This supports ``**standard_logging_payload`` in tests.
         """
         field_names: Final = {f.name for f in fields(self)}
-        merged: Final[dict[str, Any]] = {}
+        merged: Final[dict[str, object]] = {}
         for f in fields(self):
             if f.default_factory is not MISSING:
                 merged[f.name] = f.default_factory()
@@ -1060,9 +1060,9 @@ class UserAPIKeyLabelValues:
         # stays cheap. (Dataclass default `str()` delegates to `__repr__`.)
         return ""
 
-    def model_dump(self) -> dict[str, Any]:
+    def model_dump(self) -> dict[str, object]:
         """Same shape as the former Pydantic ``model_dump()`` (plain dict, list tags)."""
-        d: Final[dict[str, Any]] = {f.name: getattr(self, f.name) for f in fields(self)}
+        d: Final[dict[str, object]] = {f.name: getattr(self, f.name) for f in fields(self)}
         d["tags"] = list(self.tags)
         d["custom_metadata_labels"] = dict(self.custom_metadata_labels)
         return d
diff --git a/litellm/types/realtime.py b/litellm/types/realtime.py
index 17dc70126f3..bda3865c46a 100644
--- a/litellm/types/realtime.py
+++ b/litellm/types/realtime.py
@@ -78,15 +78,15 @@ class RealtimeSessionConfig(BaseModel):
     type: str | None = None
     model: str | None = None
     instructions: str | None = None
-    audio: dict[str, Any] | None = None
+    audio: dict[str, object] | None = None
     include: list[str] | None = None
     max_output_tokens: int | str | None = None
     output_modalities: list[str] | None = None
-    tool_choice: Any | None = None
-    tools: list[dict[str, Any]] | None = None
-    tracing: Any | None = None
-    truncation: Any | None = None
-    prompt: dict[str, Any] | None = None
+    tool_choice: object | None = None
+    tools: list[dict[str, object]] | None = None
+    tracing: object | None = None
+    truncation: object | None = None
+    prompt: dict[str, object] | None = None
 
 
 class RealtimeClientSecretRequest(BaseModel):
@@ -114,7 +114,7 @@ class RealtimeClientSecretResponse(BaseModel):
 
     expires_at: int | None = None
     value: str
-    session: dict[str, Any] | None = None
+    session: dict[str, object] | None = None
 
 
 class RealtimeTranscriptionSessionRequest(BaseModel):
@@ -151,7 +151,7 @@ class RealtimeTranscriptionSessionResponse(BaseModel):
 
     model_config = {"extra": "allow"}
 
-    client_secret: dict[str, Any] | None = None
+    client_secret: dict[str, object] | None = None
 
 
 class RealtimeErrorDetail(TypedDict):
diff --git a/litellm/vector_store_files/utils.py b/litellm/vector_store_files/utils.py
index 94ad5c0ecdf..8b4bff921f8 100644
--- a/litellm/vector_store_files/utils.py
+++ b/litellm/vector_store_files/utils.py
@@ -1,4 +1,5 @@
-from typing import Any, Final, cast, get_type_hints
+from collections.abc import Mapping
+from typing import Final, cast, get_type_hints
 
 from litellm.types.vector_store_files import (
     VectorStoreFileCreateRequest,
@@ -11,25 +12,25 @@ class VectorStoreFileRequestUtils:
     """Helper utilities for constructing vector store file requests."""
 
     @staticmethod
-    def _filter_params(params: dict[str, Any], model: Any) -> dict[str, Any]:
+    def _filter_params(params: Mapping[str, object], model: type[object]) -> dict[str, object]:
         valid_keys: Final = get_type_hints(model).keys()
         return {key: value for key, value in params.items() if key in valid_keys and value is not None}
 
     @staticmethod
     def get_create_request_params(
-        params: dict[str, Any],
+        params: Mapping[str, object],
     ) -> VectorStoreFileCreateRequest:
         filtered: Final = VectorStoreFileRequestUtils._filter_params(params=params, model=VectorStoreFileCreateRequest)
         return cast(VectorStoreFileCreateRequest, filtered)
 
     @staticmethod
-    def get_list_query_params(params: dict[str, Any]) -> VectorStoreFileListQueryParams:
+    def get_list_query_params(params: Mapping[str, object]) -> VectorStoreFileListQueryParams:
         filtered = VectorStoreFileRequestUtils._filter_params(params=params, model=VectorStoreFileListQueryParams)
         return cast(VectorStoreFileListQueryParams, filtered)
 
     @staticmethod
     def get_update_request_params(
-        params: dict[str, Any],
+        params: Mapping[str, object],
     ) -> VectorStoreFileUpdateRequest:
         filtered: Final = VectorStoreFileRequestUtils._filter_params(params=params, model=VectorStoreFileUpdateRequest)
         return cast(VectorStoreFileUpdateRequest, filtered)

From bf9437780b7fd0aa74827239cfe9ea2e19bbacc7 Mon Sep 17 00:00:00 2001
From: mateo-berri <277851410+mateo-berri@users.noreply.github.com>
Date: Tue, 8 Sep 2026 14:09:22 +0000
Subject: [PATCH 07/55] refactor(types): replace Any with real types across 11
 more backend files

Final batch of the fifth basedpyright Any reduction round. Every change is
typing-only and leaves runtime behavior identical.

These are the densest remaining files, so the yield per file is small and most
of the batch was left alone deliberately. The Riva transcription handler
describes the SDK module attributes it reads with Protocols instead of a bare
ModuleType, the AWS secret manager stops hiding a botocore header object behind
Any, and the sensitive data masker, MCP SSO assertion store and Ovalix guardrail
move payload and option annotations to object and Mapping[str, object].
---
 .../sensitive_data_masker.py                  | 10 ++---
 .../audio_transcription/handler.py            | 37 +++++++++++++---
 .../vertex_gemma_models/transformation.py     |  7 +--
 .../mcp_server/openapi_to_mcp_generator.py    |  2 +-
 .../sso_assertion_store.py                    | 43 ++++++++++++++++---
 litellm/proxy/_lazy_features.py               |  4 +-
 .../guardrail_hooks/ovalix/ovalix.py          | 17 +++++---
 .../team_callback_endpoints.py                |  8 ++--
 .../management_endpoints.py                   |  5 ++-
 litellm/rag/ingestion/gemini_ingestion.py     |  2 +-
 .../secret_managers/aws_secret_manager_v2.py  |  7 ++-
 11 files changed, 104 insertions(+), 38 deletions(-)

diff --git a/litellm/litellm_core_utils/sensitive_data_masker.py b/litellm/litellm_core_utils/sensitive_data_masker.py
index 22dd4170963..e78c4bd24c3 100644
--- a/litellm/litellm_core_utils/sensitive_data_masker.py
+++ b/litellm/litellm_core_utils/sensitive_data_masker.py
@@ -91,13 +91,13 @@ class SensitiveDataMasker:
 
     def _mask_sequence(
         self,
-        values: list[Any],
+        values: Sequence[object],
         depth: int,
         max_depth: int,
         excluded_keys: set[str] | None,
         key_is_sensitive: bool,
-    ) -> list[Any]:
-        masked_items: Final[list[Any]] = []
+    ) -> Sequence[object]:
+        masked_items: Final[list[object]] = []
         if depth >= max_depth:
             return values
 
@@ -197,7 +197,7 @@ def _walk_payload(node: object, key_is_sensitive: bool, depth: int) -> object:
     return node
 
 
-def mask_sensitive_keys(data: dict[str, Any], sensitive_fields: set[str]) -> dict[str, Any]:
+def mask_sensitive_keys(data: Mapping[str, object], sensitive_fields: set[str]) -> dict[str, object]:
     """Return a new dict with values masked for keys listed in ``sensitive_fields``.
 
     Unlike :meth:`SensitiveDataMasker.mask_dict`, this does exact key-name
@@ -209,7 +209,7 @@ def mask_sensitive_keys(data: dict[str, Any], sensitive_fields: set[str]) -> dic
     range and are replaced with a fixed-length all-mask string, so a short
     credential is never returned verbatim.
     """
-    masked: Final[dict[str, Any]] = {}
+    masked: Final[dict[str, object]] = {}
     mask_char: Final = _default_masker.mask_char
     min_visible: Final = _default_masker.visible_prefix + _default_masker.visible_suffix
     for key, value in data.items():
diff --git a/litellm/llms/nvidia_riva/audio_transcription/handler.py b/litellm/llms/nvidia_riva/audio_transcription/handler.py
index d188fac8704..bea77a6761c 100644
--- a/litellm/llms/nvidia_riva/audio_transcription/handler.py
+++ b/litellm/llms/nvidia_riva/audio_transcription/handler.py
@@ -27,7 +27,6 @@ without the optional STT extras installed.
 import asyncio
 import inspect
 from collections.abc import Callable, Iterable
-from types import ModuleType
 from typing import TYPE_CHECKING, Any, Final, Protocol
 
 from litellm.litellm_core_utils.audio_utils.utils import (
@@ -95,11 +94,37 @@ class _AudioEncoding(Protocol):
     def LINEAR_PCM(self) -> object: ...
 
 
-def _auth_factory(riva_module: ModuleType) -> Callable[..., _RivaAuth]:
+class _RivaClientModule(Protocol):
+    """The ``riva.client`` entry points this handler calls."""
+
+    @property
+    def Auth(self) -> Callable[..., _RivaAuth]: ...
+
+    @property
+    def ASRService(self) -> Callable[[_RivaAuth], _AsrService]: ...
+
+
+class _RivaAsrModule(Protocol):
+    """The protobuf constructors this handler calls, from whichever module exposes them."""
+
+    @property
+    def AudioEncoding(self) -> _AudioEncoding: ...
+
+    @property
+    def RecognitionConfig(self) -> Callable[..., _RecognitionConfig]: ...
+
+    @property
+    def StreamingRecognitionConfig(self) -> Callable[..., _StreamingRecognitionConfig]: ...
+
+    @property
+    def EndpointingConfig(self) -> Callable[..., _EndpointingConfig]: ...
+
+
+def _auth_factory(riva_module: _RivaClientModule) -> Callable[..., _RivaAuth]:
     return riva_module.Auth
 
 
-def _audio_encoding(riva_asr_module: ModuleType) -> _AudioEncoding:
+def _audio_encoding(riva_asr_module: _RivaAsrModule) -> _AudioEncoding:
     return riva_asr_module.AudioEncoding
 
 
@@ -317,7 +342,7 @@ class NvidiaRivaAudioTranscription:
 
     def _construct_auth(
         self,
-        riva_module: ModuleType,
+        riva_module: _RivaClientModule,
         api_base: str,
         api_key: str | None,
         optional_params: dict,
@@ -349,7 +374,7 @@ class NvidiaRivaAudioTranscription:
             return _auth_factory(riva_module)(None, use_ssl, api_base, metadata)
 
     def _build_recognition_config_proto(
-        self, riva_asr_module: ModuleType, recognition_config_dict: dict[str, Any]
+        self, riva_asr_module: _RivaAsrModule, recognition_config_dict: dict[str, Any]
     ) -> _RecognitionConfig:
         encoding_name: Final = (recognition_config_dict.get("encoding") or "LINEAR_PCM").upper()
         encoding_enum: Final[object] = getattr(
@@ -436,7 +461,7 @@ class NvidiaRivaAudioTranscription:
         return final_results
 
 
-def _import_riva() -> tuple[ModuleType, ModuleType]:
+def _import_riva() -> tuple[_RivaClientModule, _RivaAsrModule]:
     """
     Lazy import of ``riva.client`` and ``riva.client.proto.riva_asr_pb2``.
 
diff --git a/litellm/llms/vertex_ai/vertex_gemma_models/transformation.py b/litellm/llms/vertex_ai/vertex_gemma_models/transformation.py
index 58cf7c7e702..67b01c2dc43 100644
--- a/litellm/llms/vertex_ai/vertex_gemma_models/transformation.py
+++ b/litellm/llms/vertex_ai/vertex_gemma_models/transformation.py
@@ -27,6 +27,7 @@ if TYPE_CHECKING:
     import tiktoken
 
     from litellm.litellm_core_utils.litellm_logging import Logging as LiteLLMLoggingObj
+    from litellm.llms.base_llm.base_model_iterator import MockResponseIterator
 
 
 class VertexGemmaConfig(OpenAIGPTConfig):
@@ -56,7 +57,7 @@ class VertexGemmaConfig(OpenAIGPTConfig):
         self,
         model_response: ModelResponse,
         stream: bool,
-    ) -> ModelResponse | Any:
+    ) -> "ModelResponse | MockResponseIterator":
         """
         Helper method to return fake stream iterator if streaming is requested.
 
@@ -138,7 +139,7 @@ class VertexGemmaConfig(OpenAIGPTConfig):
         client: HTTPHandler | httpx.Client | None,
         api_base: str,
         headers: dict[str, str],  # mutable-ok: forwarded to post(headers: dict | None)
-        request_data: dict[str, Any],  # mutable-ok: forwarded to post(json: dict | ...)
+        request_data: dict[str, object],  # mutable-ok: forwarded to post(json: dict | ...)
         timeout: float | httpx.Timeout | None,
     ) -> httpx.Response:
         if isinstance(client, HTTPHandler):
@@ -173,7 +174,7 @@ class VertexGemmaConfig(OpenAIGPTConfig):
         client: AsyncHTTPHandler | httpx.AsyncClient | None,
         api_base: str,
         headers: dict[str, str],  # mutable-ok: forwarded to post(headers: dict | None)
-        request_data: dict[str, Any],  # mutable-ok: forwarded to post(json: dict | ...)
+        request_data: dict[str, object],  # mutable-ok: forwarded to post(json: dict | ...)
         timeout: float | httpx.Timeout | None,
     ) -> httpx.Response:
         from litellm.llms.custom_httpx.http_handler import get_async_httpx_client
diff --git a/litellm/proxy/_experimental/mcp_server/openapi_to_mcp_generator.py b/litellm/proxy/_experimental/mcp_server/openapi_to_mcp_generator.py
index 16f58ef5b76..4cf63b1fceb 100644
--- a/litellm/proxy/_experimental/mcp_server/openapi_to_mcp_generator.py
+++ b/litellm/proxy/_experimental/mcp_server/openapi_to_mcp_generator.py
@@ -453,7 +453,7 @@ def _raise_for_upstream_failure(
     if response.status_code == 401 and relays_upstream_auth:
         raise MCPUpstreamAuthError(
             status_code=response.status_code,
-            www_authenticate=response.headers.get("www-authenticate"),
+            www_authenticate=dict(response.headers).get("www-authenticate"),
             server_name=upstream,
         )
     raise MCPOpenApiUpstreamError(response.status_code, upstream)
diff --git a/litellm/proxy/_experimental/mcp_server/outbound_credentials/sso_assertion_store.py b/litellm/proxy/_experimental/mcp_server/outbound_credentials/sso_assertion_store.py
index f7b92df5ba3..5503d19211b 100644
--- a/litellm/proxy/_experimental/mcp_server/outbound_credentials/sso_assertion_store.py
+++ b/litellm/proxy/_experimental/mcp_server/outbound_credentials/sso_assertion_store.py
@@ -18,6 +18,7 @@ TTL ``MCP_SSO_ASSERTION_CACHE_TTL_SECONDS``; invalidation also guards against st
 from __future__ import annotations
 
 import json
+from collections.abc import Mapping, Sequence
 from datetime import datetime, timezone
 from typing import TYPE_CHECKING, Final, Protocol
 
@@ -29,6 +30,8 @@ from litellm.caching.in_memory_cache import InMemoryCache
 from litellm.constants import MCP_OAUTH2_TOKEN_CACHE_MAX_SIZE, MCP_SSO_ASSERTION_CACHE_TTL_SECONDS
 
 if TYPE_CHECKING:
+    from prisma.models import LiteLLM_SSOIdentityAssertion
+
     from litellm.proxy.utils import PrismaClient
 
 _ASSERTION_DECRYPT_LOG_KEY: Final = "sso_identity_assertion"
@@ -36,6 +39,34 @@ _STR_ADAPTER: Final[TypeAdapter[str]] = TypeAdapter(str)
 _MAYBE_STR_ADAPTER: Final[TypeAdapter[str | None]] = TypeAdapter(str | None)
 
 
+class _SSOAssertionTable(Protocol):
+    """The ``LiteLLM_SSOIdentityAssertion`` table operations this store calls."""
+
+    async def find_unique(self, *, where: Mapping[str, str]) -> LiteLLM_SSOIdentityAssertion | None: ...
+
+    async def find_many(self) -> Sequence[LiteLLM_SSOIdentityAssertion]: ...
+
+    async def upsert(self, *, where: Mapping[str, str], data: Mapping[str, Mapping[str, str]]) -> object: ...
+
+    async def update(self, *, where: Mapping[str, str], data: Mapping[str, str]) -> object: ...
+
+
+class _MCPServerTable(Protocol):
+    """The ``LiteLLM_MCPServerTable`` lookup the retention gate calls."""
+
+    async def find_first(self, *, where: Mapping[str, str]) -> object | None: ...
+
+
+def _assertion_table(prisma_client: PrismaClient) -> _SSOAssertionTable:
+    """The SSO assertion table, typed so the untyped prisma client surface stops here."""
+    return prisma_client.db.litellm_ssoidentityassertion
+
+
+def _mcp_server_table(prisma_client: PrismaClient) -> _MCPServerTable:
+    """The MCP server table, typed so the untyped prisma client surface stops here."""
+    return prisma_client.db.litellm_mcpservertable
+
+
 class SSOIdentityAssertion(BaseModel):
     """The IdP material an EMA exchange needs: ``id_token`` is the RFC 8693 subject token,
     ``expires_at`` bounds its usefulness, and the refresh token renews it without re-login."""
@@ -163,9 +194,7 @@ async def ema_assertion_retention_enabled() -> bool:
         return True
     if prisma_client is None:
         return False
-    row: Final = await prisma_client.db.litellm_mcpservertable.find_first(
-        where={"auth_type": MCPAuth.oauth2_id_jag.value}
-    )
+    row: Final = await _mcp_server_table(prisma_client).find_first(where={"auth_type": MCPAuth.oauth2_id_jag.value})
     return row is not None
 
 
@@ -184,7 +213,7 @@ async def persist_sso_identity_assertion(
         **({"expires_at": assertion.expires_at.isoformat()} if assertion.expires_at else {}),
     }
     encoded: Final = _STR_ADAPTER.validate_python(encrypt_value_helper(json.dumps(payload)))
-    await prisma_client.db.litellm_ssoidentityassertion.upsert(
+    await _assertion_table(prisma_client).upsert(
         where={"user_id": user_id},
         data={
             "create": {"user_id": user_id, "assertion_b64": encoded},
@@ -200,7 +229,7 @@ async def _read_assertion_from_db(user_id: str) -> SSOIdentityAssertion | None:
 
     if prisma_client is None:
         return None
-    row: Final = await prisma_client.db.litellm_ssoidentityassertion.find_unique(where={"user_id": user_id})
+    row: Final = await _assertion_table(prisma_client).find_unique(where={"user_id": user_id})
     if row is None:
         return None
     raw: Final = _MAYBE_STR_ADAPTER.validate_python(
@@ -310,13 +339,13 @@ async def rotate_sso_identity_assertions_master_key(prisma_client: PrismaClient,
         re_encrypted: Final = _STR_ADAPTER.validate_python(
             encrypt_value_helper(plaintext, new_encryption_key=new_master_key)
         )
-        await prisma_client.db.litellm_ssoidentityassertion.update(
+        await _assertion_table(prisma_client).update(
             where={"user_id": row.user_id},
             data={"assertion_b64": re_encrypted},
         )
         return True
 
-    rows: Final = await prisma_client.db.litellm_ssoidentityassertion.find_many()
+    rows: Final = await _assertion_table(prisma_client).find_many()
     outcomes: Final = [await _rotate_row(row) for row in rows]
     verbose_proxy_logger.info(
         "rotate_sso_identity_assertions_master_key: rotated %d row(s), skipped %d",
diff --git a/litellm/proxy/_lazy_features.py b/litellm/proxy/_lazy_features.py
index 50e0a961a49..17743e153f2 100644
--- a/litellm/proxy/_lazy_features.py
+++ b/litellm/proxy/_lazy_features.py
@@ -13,7 +13,7 @@ from collections.abc import Set as AbstractSet
 from dataclasses import dataclass, field
 from typing import TYPE_CHECKING, Final
 
-from starlette.types import Receive, Scope, Send
+from starlette.types import ASGIApp, Receive, Scope, Send
 
 from litellm._logging import verbose_proxy_logger
 
@@ -266,7 +266,7 @@ class LazyFeatureMiddleware:
 
     def __init__(
         self,
-        app,
+        app: ASGIApp,
         fastapi_app: "FastAPI",
         features: tuple[LazyFeature, ...] = LAZY_FEATURES,
     ):
diff --git a/litellm/proxy/guardrails/guardrail_hooks/ovalix/ovalix.py b/litellm/proxy/guardrails/guardrail_hooks/ovalix/ovalix.py
index b31ed4b0f4a..c69b24c0553 100644
--- a/litellm/proxy/guardrails/guardrail_hooks/ovalix/ovalix.py
+++ b/litellm/proxy/guardrails/guardrail_hooks/ovalix/ovalix.py
@@ -10,6 +10,7 @@ import os
 from typing import TYPE_CHECKING, Any, Final, Literal
 
 import httpx
+from typing_extensions import ReadOnly, TypedDict, Unpack
 
 from litellm._logging import verbose_proxy_logger
 from litellm.exceptions import GuardrailRaisedException
@@ -33,6 +34,12 @@ BLOCKED_BY_OVALIX_FALLBACK_MESSAGE: Final = "This message was blocked by Ovalix"
 BLOCKED_ACTION_TYPE: Final = "block"
 
 
+class _CustomGuardrailOptions(TypedDict, total=False, extra_items=object):
+    """Base-class constructor options this guardrail forwards untouched to CustomGuardrail."""
+
+    supported_event_hooks: ReadOnly[list[GuardrailEventHooks]]
+
+
 class OvalixGuardrailMissingSecrets(Exception):
     """Raised when required Ovalix config (API base, key, application/checkpoint IDs) is missing."""
 
@@ -80,7 +87,7 @@ class OvalixGuardrail(CustomGuardrail):
         application_id: str | None = None,
         pre_checkpoint_id: str | None = None,
         post_checkpoint_id: str | None = None,
-        **kwargs: Any,
+        **kwargs: Unpack[_CustomGuardrailOptions],
     ):
         self._tracker_api_base = tracker_api_base or os.environ.get("OVALIX_TRACKER_API_BASE")
         self._tracker_api_key = tracker_api_key or os.environ.get("OVALIX_TRACKER_API_KEY")
@@ -88,10 +95,9 @@ class OvalixGuardrail(CustomGuardrail):
         self._pre_checkpoint_id = pre_checkpoint_id or os.environ.get("OVALIX_PRE_CHECKPOINT_ID")
         self._post_checkpoint_id = post_checkpoint_id or os.environ.get("OVALIX_POST_CHECKPOINT_ID")
 
-        if "supported_event_hooks" not in kwargs:
-            kwargs["supported_event_hooks"] = []
+        supported_event_hooks: Final = kwargs.get("supported_event_hooks", [])
 
-        self._validate_config(kwargs["supported_event_hooks"])
+        self._validate_config(supported_event_hooks)
 
         self._tracker_headers = httpx.Headers(
             {
@@ -103,7 +109,8 @@ class OvalixGuardrail(CustomGuardrail):
 
         self._async_handler = get_async_httpx_client(llm_provider=httpxSpecialProvider.GuardrailCallback)
 
-        super().__init__(**kwargs)
+        forwarded: Final[_CustomGuardrailOptions] = {**kwargs, "supported_event_hooks": supported_event_hooks}
+        super().__init__(**forwarded)
         verbose_proxy_logger.debug(
             "Ovalix Guardrail initialized: tracker=%s, application_id=%s, pre_checkpoint_id=%s, post_checkpoint_id=%s",
             self._tracker_api_base,
diff --git a/litellm/proxy/management_endpoints/team_callback_endpoints.py b/litellm/proxy/management_endpoints/team_callback_endpoints.py
index fe658a13c24..b7fcd4ac7a9 100644
--- a/litellm/proxy/management_endpoints/team_callback_endpoints.py
+++ b/litellm/proxy/management_endpoints/team_callback_endpoints.py
@@ -473,7 +473,7 @@ async def delete_team_callback(
             raise _callback_error(404, f"callback_name = {callback_name} is not registered for team_id = {team_id}.")
 
         updated_metadata: Final = {**team_metadata, "logging": remaining_callbacks}  # mutable-ok: persisted as JSON
-        encrypted_metadata: Final = encrypt_callback_vars(updated_metadata)
+        encrypted_metadata: Final[object] = encrypt_callback_vars(updated_metadata)
         team_metadata_json: Final = json.dumps(encrypted_metadata)
 
         updated_team: Final = await TeamRepository(prisma_client).table.update(
@@ -610,8 +610,8 @@ async def disable_team_logging(
         # _get_dynamic_logging_metadata stops at metadata["logging"], where the API
         # and Admin UI register callbacks, without ever reading callback_settings.
         team_metadata["logging"] = []  # mutable-ok: the disabled state is persisted as an empty JSON array
-        team_metadata = encrypt_callback_vars(team_metadata)
-        team_metadata_json: Final = json.dumps(team_metadata)
+        encrypted_metadata: Final[object] = encrypt_callback_vars(team_metadata)
+        team_metadata_json: Final = json.dumps(encrypted_metadata)
 
         # Update team in database
         updated_team: Final = await TeamRepository(prisma_client).table.update(
@@ -643,7 +643,7 @@ async def disable_team_logging(
         await _emit_team_callback_audit_log(
             team_id=team_id,
             before_metadata=before_metadata,
-            after_metadata=team_metadata,
+            after_metadata=encrypted_metadata,
             user_api_key_dict=user_api_key_dict,
             litellm_changed_by=litellm_changed_by,
         )
diff --git a/litellm/proxy/vector_store_endpoints/management_endpoints.py b/litellm/proxy/vector_store_endpoints/management_endpoints.py
index 0ca2c4c8865..2fb6813a471 100644
--- a/litellm/proxy/vector_store_endpoints/management_endpoints.py
+++ b/litellm/proxy/vector_store_endpoints/management_endpoints.py
@@ -88,7 +88,7 @@ def _redact_sensitive_litellm_params(litellm_params: object, _depth: int = 0) ->
         return None
     if isinstance(litellm_params, str):
         try:
-            parsed: Final = json.loads(litellm_params)
+            parsed: Final[object] = json.loads(litellm_params)
         except (TypeError, ValueError):
             return REDACTED_BY_LITELM_STRING
         return json.dumps(_redact_sensitive_litellm_params(parsed, _depth + 1))
@@ -589,7 +589,8 @@ async def update_vector_store(
 
     try:
         update_data: Final = data.model_dump(exclude_unset=True)
-        vector_store_id: Final[str] = update_data.pop("vector_store_id")
+        vector_store_id: Final[str] = data.vector_store_id
+        update_data.pop("vector_store_id")
 
         # Per-store access control: anyone authenticated who passes the
         # premium-feature gate could otherwise update *any* vector store —
diff --git a/litellm/rag/ingestion/gemini_ingestion.py b/litellm/rag/ingestion/gemini_ingestion.py
index 73a0159fc9f..b81c2cc0ebe 100644
--- a/litellm/rag/ingestion/gemini_ingestion.py
+++ b/litellm/rag/ingestion/gemini_ingestion.py
@@ -277,7 +277,7 @@ class GeminiRAGIngestion(BaseRAGIngestion):
             raise Exception(error_msg)
         verbose_logger.debug("Initiate resumable upload response: %s", response.headers)
         # Extract upload URL from response headers
-        upload_url: Final = response.headers.get("x-goog-upload-url")
+        upload_url: Final = dict(response.headers).get("x-goog-upload-url")
         if not upload_url:
             raise Exception("No upload URL returned in response headers")
 
diff --git a/litellm/secret_managers/aws_secret_manager_v2.py b/litellm/secret_managers/aws_secret_manager_v2.py
index e86c8e7c919..9f5bf783958 100644
--- a/litellm/secret_managers/aws_secret_manager_v2.py
+++ b/litellm/secret_managers/aws_secret_manager_v2.py
@@ -16,7 +16,7 @@ Requires:
 
 import json
 import os
-from typing import Any, Final
+from typing import TYPE_CHECKING, Final
 
 import httpx
 
@@ -35,6 +35,9 @@ from litellm.types.secret_managers.main import KeyManagementSettings
 
 from .base_secret_manager import BaseSecretManager
 
+if TYPE_CHECKING:
+    from botocore.awsrequest import HTTPHeaders
+
 
 class AWSSecretsManagerV2(BaseAWSLLM, BaseSecretManager):
     def __init__(
@@ -530,7 +533,7 @@ class AWSSecretsManagerV2(BaseAWSLLM, BaseSecretManager):
         secret_value: str | None = None,
         optional_params: dict | None = None,
         request_data: dict | None = None,
-    ) -> tuple[str, Any, bytes]:
+    ) -> tuple[str, "HTTPHeaders", bytes]:
         """Prepare the AWS Secrets Manager request"""
         try:
             from botocore.auth import SigV4Auth

From e46c816ec7b42bdab4ac6cdbb7df10022629e693 Mon Sep 17 00:00:00 2001
From: mateo-berri <277851410+mateo-berri@users.noreply.github.com>
Date: Mon, 14 Sep 2026 07:31:41 +0000
Subject: [PATCH 08/55] fix: address review feedback on Any reduction

- drop redundant Protocol docstrings in dynamodb and otel mount
- widen hosted_vllm custom-tool conversion signature from Any to object
---
 litellm/integrations/dynamodb.py                | 4 ----
 litellm/integrations/otel/mount.py              | 2 --
 litellm/llms/hosted_vllm/chat/transformation.py | 4 ++--
 3 files changed, 2 insertions(+), 8 deletions(-)

diff --git a/litellm/integrations/dynamodb.py b/litellm/integrations/dynamodb.py
index 3401ced4efb..3fbbfe91ddf 100644
--- a/litellm/integrations/dynamodb.py
+++ b/litellm/integrations/dynamodb.py
@@ -11,14 +11,10 @@ from litellm._uuid import uuid
 
 
 class _DynamoTable(Protocol):
-    """The one boto3 DynamoDB table call this logger makes."""
-
     def put_item(self, *, Item: Mapping[str, object]) -> object: ...
 
 
 class _DynamoResource(Protocol):
-    """The one boto3 DynamoDB resource call this logger makes."""
-
     def Table(self, name: str) -> _DynamoTable: ...
 
 
diff --git a/litellm/integrations/otel/mount.py b/litellm/integrations/otel/mount.py
index 776d8722d14..9340f6e9e15 100644
--- a/litellm/integrations/otel/mount.py
+++ b/litellm/integrations/otel/mount.py
@@ -69,8 +69,6 @@ PASSTHROUGH_PREFIXES: Final = frozenset(
 
 
 class _RenameableSpan(Protocol):
-    """The span surface the passthrough naming hook drives."""
-
     def is_recording(self) -> bool: ...
 
     def update_name(self, name: str) -> None: ...
diff --git a/litellm/llms/hosted_vllm/chat/transformation.py b/litellm/llms/hosted_vllm/chat/transformation.py
index 92bc857e385..32c60bd01b5 100644
--- a/litellm/llms/hosted_vllm/chat/transformation.py
+++ b/litellm/llms/hosted_vllm/chat/transformation.py
@@ -4,7 +4,7 @@ Translate from OpenAI's `/v1/chat/completions` to VLLM's `/v1/chat/completions`
 
 import json
 from collections.abc import Coroutine
-from typing import Any, Final, Literal, cast, overload
+from typing import Final, Literal, cast, overload
 
 from litellm.litellm_core_utils.prompt_templates.common_utils import (
     _get_image_mime_type_from_url,
@@ -28,7 +28,7 @@ from ...openai.chat.gpt_transformation import OpenAIGPTConfig
 
 
 class HostedVLLMChatConfig(OpenAIGPTConfig):
-    def _convert_custom_tools_to_function_tools(self, tools: list[dict[str, Any]]) -> list[dict[str, object]]:
+    def _convert_custom_tools_to_function_tools(self, tools: list[dict[str, object]]) -> list[dict[str, object]]:
         """
         vLLM chat completions currently accepts only OpenAI function tools.
         Convert custom tools into function tools so request validation does not fail.

From da7d5fe1284da59502cb6738d853acc8c431af40 Mon Sep 17 00:00:00 2001
From: mateo-berri <277851410+mateo-berri@users.noreply.github.com>
Date: Mon, 14 Sep 2026 11:13:39 +0000
Subject: [PATCH 09/55] refactor: replace Any with precise types across 54
 modules

Narrow or remove reportAny / reportExplicitAny sites in provider
transformations, caching, guardrails, proxy endpoints and enterprise
batch-cost polling. Public parameters widen to Mapping/Sequence rather
than dict/list so no caller signature breaks, and runtime behavior is
unchanged.
---
 .../proxy/common_utils/check_batch_cost.py    | 127 +++++++++++-------
 .../common_utils/check_responses_cost.py      |  31 ++++-
 .../proxy/hooks/managed_files.py              |  22 ++-
 litellm/caching/caching.py                    |   2 +-
 litellm/caching/caching_handler.py            |  10 +-
 litellm/caching/redis_cache.py                |   4 +-
 .../handler.py                                |   6 +-
 .../transformation.py                         |  30 +++--
 litellm/cost_calculator.py                    |   6 +-
 litellm/integrations/braintrust_logging.py    |   8 +-
 litellm/integrations/custom_guardrail.py      |   2 +-
 .../integrations/datadog/datadog_llm_obs.py   |  22 +--
 litellm/integrations/galileo.py               |  11 +-
 litellm/integrations/langfuse/langfuse.py     |   8 +-
 .../llm_response_utils/response_metadata.py   |   4 +-
 .../prompt_templates/common_utils.py          |  39 ++----
 .../a2a/chat/guardrail_translation/handler.py |   2 +-
 litellm/llms/anthropic/chat/transformation.py |  24 ++--
 litellm/llms/anthropic/common_utils.py        |  10 +-
 .../messages/agentic_streaming_iterator.py    |  16 ++-
 litellm/llms/anthropic/files/handler.py       |   6 +-
 .../bedrock/chat/converse_transformation.py   |   2 +-
 .../llms/chatgpt/responses/transformation.py  |  22 +--
 litellm/llms/cohere/chat/transformation.py    |   2 +-
 .../llms/databricks/chat/transformation.py    |  10 +-
 .../llms/fireworks_ai/chat/transformation.py  |   4 +-
 litellm/llms/gemini/count_tokens/handler.py   |   2 +-
 .../llms/gemini/image_edit/transformation.py  |  13 +-
 litellm/llms/gigachat/chat/transformation.py  |  14 +-
 .../huggingface/embedding/transformation.py   |  10 +-
 .../chat/guardrail_translation/handler.py     |  20 +--
 litellm/llms/openai/videos/transformation.py  |   6 +-
 .../openrouter/image_edit/transformation.py   |  11 +-
 .../perplexity/embedding/transformation.py    |   2 +-
 .../llms/vertex_ai/gemini/transformation.py   |   4 +-
 .../mcp_server/mcp_server_manager.py          |   2 +-
 litellm/proxy/auth/auth_utils.py              |  26 ++--
 .../proxy/client/cli/commands/configure.py    |  60 +++++----
 litellm/proxy/common_utils/callback_utils.py  |   6 +-
 litellm/proxy/db/db_spend_update_writer.py    |  20 ++-
 .../guardrails/guardrail_hooks/akto/akto.py   |  36 ++++-
 .../custom_code/custom_code_guardrail.py      |   9 +-
 .../guardrails/guardrail_hooks/lasso/lasso.py |  12 +-
 .../vigil_guard/vigil_guard.py                |  23 +++-
 .../guardrail_hooks/xecguard/xecguard.py      |  12 +-
 .../model_management_endpoints.py             |   5 +-
 .../vertex_passthrough_logging_handler.py     |   3 +-
 .../proxy/response_api_endpoints/endpoints.py |   2 +-
 litellm/proxy/video_endpoints/endpoints.py    |  28 ++--
 .../mcp/litellm_proxy_mcp_handler.py          |  10 +-
 litellm/responses/streaming_iterator.py       |   2 +-
 .../complexity_router/complexity_router.py    |  32 ++---
 litellm/types/router.py                       |  16 +--
 .../vector_stores/vector_store_registry.py    |   5 +-
 54 files changed, 485 insertions(+), 336 deletions(-)

diff --git a/enterprise/litellm_enterprise/proxy/common_utils/check_batch_cost.py b/enterprise/litellm_enterprise/proxy/common_utils/check_batch_cost.py
index 13e9e5093a8..3ea9b7d9bfd 100644
--- a/enterprise/litellm_enterprise/proxy/common_utils/check_batch_cost.py
+++ b/enterprise/litellm_enterprise/proxy/common_utils/check_batch_cost.py
@@ -2,10 +2,11 @@
 Polls LiteLLM_ManagedObjectTable to check if the batch job is complete, and if the cost has been tracked.
 """
 
+from collections.abc import Sequence
 from dataclasses import replace as dataclasses_replace
 from datetime import datetime, timedelta, timezone
 from types import MappingProxyType
-from typing import TYPE_CHECKING, Final, List, Literal, Optional, Tuple, cast
+from typing import TYPE_CHECKING, Final, List, Literal, Optional, Protocol, Tuple, cast
 
 from litellm._logging import verbose_proxy_logger
 from litellm._uuid import uuid
@@ -18,8 +19,8 @@ if TYPE_CHECKING:
     from prisma import models as prisma_models
 
     from litellm.integrations.prometheus import PrometheusLogger
-    from litellm.proxy._types import LiteLLM_ManagedObjectTable
     from litellm.proxy.utils import PrismaClient, ProxyLogging
+    from litellm.repositories.prisma_protocols import TableActions
     from litellm.router import Router
     from litellm.types.router import Deployment
     from litellm.types.utils import LiteLLMBatch
@@ -41,6 +42,48 @@ TERMINAL_MANAGED_OBJECT_STATUSES: Final[Tuple[str, ...]] = (
 )
 
 
+class _ManagedObjectRow(Protocol):
+    """The managed-object row fields this poller reads off whatever the DB hands back."""
+
+    @property
+    def id(self) -> str: ...
+
+    @property
+    def unified_object_id(self) -> str: ...
+
+    @property
+    def created_by(self) -> str | None: ...
+
+    @property
+    def file_object(self) -> object: ...
+
+
+def _managed_object_table(prisma_client: "PrismaClient") -> "TableActions[_ManagedObjectRow]":
+    """The managed-object table's prisma actions, typed to the row fields this module reads."""
+    table: Final[TableActions[_ManagedObjectRow]] = prisma_client.db.litellm_managedobjecttable
+    return table
+
+
+def _user_table(prisma_client: "PrismaClient") -> "TableActions[prisma_models.LiteLLM_UserTable]":
+    """The user table's prisma actions."""
+    table: Final[TableActions[prisma_models.LiteLLM_UserTable]] = prisma_client.db.litellm_usertable
+    return table
+
+
+def _token_table(prisma_client: "PrismaClient") -> "TableActions[prisma_models.LiteLLM_VerificationToken]":
+    """The virtual-key table's prisma actions."""
+    table: Final[TableActions[prisma_models.LiteLLM_VerificationToken]] = (
+        prisma_client.db.litellm_verificationtoken
+    )
+    return table
+
+
+def _team_table(prisma_client: "PrismaClient") -> "TableActions[prisma_models.LiteLLM_TeamTable]":
+    """The team table's prisma actions."""
+    table: Final[TableActions[prisma_models.LiteLLM_TeamTable]] = prisma_client.db.litellm_teamtable
+    return table
+
+
 class CheckBatchCost:
     def __init__(
         self,
@@ -73,7 +116,7 @@ class CheckBatchCost:
         inline for a batch the first poll cycle then accounts again.
         """
         try:
-            await self.prisma_client.db.litellm_managedobjecttable.find_first(
+            await _managed_object_table(self.prisma_client).find_first(
                 where={"file_purpose": "batch", "batch_processed": False}
             )
         except Exception as probe_err:
@@ -97,10 +140,8 @@ class CheckBatchCost:
         if not user_id:
             return {}
         try:
-            user_row: prisma_models.LiteLLM_UserTable | None = (
-                await self.prisma_client.db.litellm_usertable.find_unique(
-                    where={"user_id": user_id}
-                )
+            user_row: prisma_models.LiteLLM_UserTable | None = await _user_table(self.prisma_client).find_unique(
+                where={"user_id": user_id}
             )
             if user_row is None:
                 return {}
@@ -117,11 +158,9 @@ class CheckBatchCost:
         if not api_key:
             return None
         try:
-            key_row: prisma_models.LiteLLM_VerificationToken | None = (
-                await self.prisma_client.db.litellm_verificationtoken.find_unique(
-                    where={"token": api_key}
-                )
-            )
+            key_row: prisma_models.LiteLLM_VerificationToken | None = await _token_table(
+                self.prisma_client
+            ).find_unique(where={"token": api_key})
             return getattr(key_row, "key_alias", None) if key_row is not None else None
         except Exception as e:
             verbose_proxy_logger.error(f"CheckBatchCost: could not look up key alias for batch {batch_id}: {e}")
@@ -132,17 +171,15 @@ class CheckBatchCost:
         if not team_id:
             return None
         try:
-            team_row: prisma_models.LiteLLM_TeamTable | None = (
-                await self.prisma_client.db.litellm_teamtable.find_unique(
-                    where={"team_id": team_id}
-                )
+            team_row: prisma_models.LiteLLM_TeamTable | None = await _team_table(self.prisma_client).find_unique(
+                where={"team_id": team_id}
             )
             return getattr(team_row, "team_alias", None) if team_row is not None else None
         except Exception as e:
             verbose_proxy_logger.error(f"CheckBatchCost: could not look up team alias for team {team_id}: {e}")
             return None
 
-    async def _get_org_id(self, job: "LiteLLM_ManagedObjectTable", batch_id: str) -> str | None:
+    async def _get_org_id(self, job: "_ManagedObjectRow", batch_id: str) -> str | None:
         org_id = getattr(job, "org_id", None)
         if org_id:
             return org_id
@@ -150,11 +187,9 @@ class CheckBatchCost:
         team_id = getattr(job, "team_id", None)
         if api_key:
             try:
-                key_row: prisma_models.LiteLLM_VerificationToken | None = (
-                    await self.prisma_client.db.litellm_verificationtoken.find_unique(
-                        where={"token": api_key}
-                    )
-                )
+                key_row: prisma_models.LiteLLM_VerificationToken | None = await _token_table(
+                    self.prisma_client
+                ).find_unique(where={"token": api_key})
                 key_org_id = getattr(key_row, "organization_id", None) if key_row is not None else None
                 if key_org_id:
                     return key_org_id
@@ -166,10 +201,8 @@ class CheckBatchCost:
         if not team_id:
             return None
         try:
-            team_row: prisma_models.LiteLLM_TeamTable | None = (
-                await self.prisma_client.db.litellm_teamtable.find_unique(
-                    where={"team_id": team_id}
-                )
+            team_row: prisma_models.LiteLLM_TeamTable | None = await _team_table(self.prisma_client).find_unique(
+                where={"team_id": team_id}
             )
             return getattr(team_row, "organization_id", None) if team_row is not None else None
         except Exception as e:
@@ -177,7 +210,7 @@ class CheckBatchCost:
             return None
 
     async def _build_creator_attribution_metadata(
-        self, job: "LiteLLM_ManagedObjectTable", batch_id: str
+        self, job: "_ManagedObjectRow", batch_id: str
     ) -> dict[str, object]:
         """
         Rebuild the spend-tracking metadata for the key, team, and tags that created the
@@ -225,7 +258,7 @@ class CheckBatchCost:
         should not be polled.
         """
         cutoff: Final = datetime.now(timezone.utc) - timedelta(days=MANAGED_OBJECT_STALENESS_CUTOFF_DAYS)
-        result: Final = await self.prisma_client.db.litellm_managedobjecttable.update_many(
+        result: Final = await _managed_object_table(self.prisma_client).update_many(
             where={
                 "file_purpose": "batch",
                 "status": {"not_in": list(TERMINAL_MANAGED_OBJECT_STATUSES)},
@@ -244,7 +277,7 @@ class CheckBatchCost:
 
         # A row already in a terminal status is never rewritten by the sweep above, so
         # without this it keeps a poll-page slot forever and starves newer batches.
-        retired: Final = await self.prisma_client.db.litellm_managedobjecttable.update_many(
+        retired: Final = await _managed_object_table(self.prisma_client).update_many(
             where={
                 "file_purpose": "batch",
                 "batch_processed": False,
@@ -259,9 +292,9 @@ class CheckBatchCost:
                 f"{MANAGED_OBJECT_STALENESS_CUTOFF_DAYS} days that were never costed"
             )
 
-    async def _fallback_find_jobs(self) -> list:
+    async def _fallback_find_jobs(self) -> "Sequence[_ManagedObjectRow]":
         """Query batch jobs without the batch_processed filter (for older schemas)."""
-        return await self.prisma_client.db.litellm_managedobjecttable.find_many(
+        return await _managed_object_table(self.prisma_client).find_many(
             where={
                 "file_purpose": "batch",
                 "status": {
@@ -279,7 +312,7 @@ class CheckBatchCost:
             order={"created_at": "asc"},
         )
 
-    async def _retire_job(self, job: "LiteLLM_ManagedObjectTable", reason: str) -> None:
+    async def _retire_job(self, job: "_ManagedObjectRow", reason: str) -> None:
         """
         Take a row that can never be costed out of the poll page. Leaving it selectable
         would burn one of the MAX_OBJECTS_PER_POLL_CYCLE slots on every future cycle, and
@@ -292,7 +325,7 @@ class CheckBatchCost:
             else {"status": "stale_expired"}
         )
         try:
-            await self.prisma_client.db.litellm_managedobjecttable.update(
+            await _managed_object_table(self.prisma_client).update(
                 where={"id": job.id},
                 data=data,
             )
@@ -306,7 +339,7 @@ class CheckBatchCost:
             "so it will no longer be polled"
         )
 
-    async def _claim_job_for_costing(self, job: "LiteLLM_ManagedObjectTable") -> bool:
+    async def _claim_job_for_costing(self, job: "_ManagedObjectRow") -> bool:
         """
         Atomically flip batch_processed from false to true, returning whether this pod won
         the row. Every pod and uvicorn worker schedules its own poller against the shared
@@ -321,7 +354,7 @@ class CheckBatchCost:
         if not self._has_batch_processed_column:
             return True
         try:
-            claimed: Final = await self.prisma_client.db.litellm_managedobjecttable.update_many(
+            claimed: Final = await _managed_object_table(self.prisma_client).update_many(
                 where={"id": job.id, "batch_processed": False},
                 data={"batch_processed": True},
             )
@@ -332,7 +365,7 @@ class CheckBatchCost:
             return False
         return claimed > 0
 
-    async def _release_job_claim(self, job: "LiteLLM_ManagedObjectTable") -> None:
+    async def _release_job_claim(self, job: "_ManagedObjectRow") -> None:
         """Give a claimed row back once billing it failed, so a later poll cycle retries it.
 
         Safe to match on batch_processed=True: while this poller is active the retrieve
@@ -342,7 +375,7 @@ class CheckBatchCost:
         if not self._has_batch_processed_column:
             return
         try:
-            await self.prisma_client.db.litellm_managedobjecttable.update_many(
+            await _managed_object_table(self.prisma_client).update_many(
                 where={"id": job.id, "batch_processed": True},
                 data={"batch_processed": False},
             )
@@ -353,7 +386,7 @@ class CheckBatchCost:
             )
 
     @staticmethod
-    def _has_unified_id_without_model(job: "LiteLLM_ManagedObjectTable") -> bool:
+    def _has_unified_id_without_model(job: "_ManagedObjectRow") -> bool:
         """A unified id that decodes but carries no model_id can never be routed."""
         from litellm.proxy.openai_files_endpoints.common_utils import (
             convert_b64_uid_to_unified_uid,
@@ -402,7 +435,7 @@ class CheckBatchCost:
         return isinstance(error, (NotFoundError, openai.NotFoundError)) and output_file_id in str(error)
 
     async def _finalize_unbilled_terminal_job(
-        self, job: "prisma_models.LiteLLM_ManagedObjectTable", response: "LiteLLMBatch"
+        self, job: "_ManagedObjectRow", response: "LiteLLMBatch"
     ) -> None:
         """Persist a terminal batch that has nothing billable, converting any raw
         provider file ids to managed ids, and take it out of the poll page."""
@@ -426,7 +459,7 @@ class CheckBatchCost:
                 "file_object": response.model_dump_json(),
                 **({"batch_processed": True} if self._has_batch_processed_column else {}),
             }
-            await self.prisma_client.db.litellm_managedobjecttable.update(
+            await _managed_object_table(self.prisma_client).update(
                 where={"id": job.id},
                 data=update_data,
             )
@@ -447,7 +480,7 @@ class CheckBatchCost:
 
     def _resolve_job_routing(
         self,
-        job: "LiteLLM_ManagedObjectTable",
+        job: "_ManagedObjectRow",
         prom_logger: Optional["PrometheusLogger"],
     ) -> Optional[Tuple[str, str]]:
         """
@@ -524,7 +557,7 @@ class CheckBatchCost:
 
     def _resolve_unmanaged_provider_routing(
         self,
-        job: "LiteLLM_ManagedObjectTable",
+        job: "_ManagedObjectRow",
         prom_logger: Optional["PrometheusLogger"],
         llm_provider: str,
         bare_model_name: str,
@@ -620,7 +653,7 @@ class CheckBatchCost:
     @classmethod
     def _get_managed_file_model_name(
         cls,
-        job: "LiteLLM_ManagedObjectTable",
+        job: "_ManagedObjectRow",
         deployment_info: "Deployment",
     ) -> Optional[str]:
         """
@@ -640,7 +673,7 @@ class CheckBatchCost:
         )
 
     @staticmethod
-    def _get_input_file_id(job: "LiteLLM_ManagedObjectTable") -> Optional[str]:
+    def _get_input_file_id(job: "_ManagedObjectRow") -> Optional[str]:
         import json
 
         from litellm.types.utils import LiteLLMBatch
@@ -660,7 +693,7 @@ class CheckBatchCost:
 
     async def _track_completed_batch_cost(
         self,
-        job: "LiteLLM_ManagedObjectTable",
+        job: "_ManagedObjectRow",
         response: "LiteLLMBatch",
         model_id: str,
         batch_id: str,
@@ -936,7 +969,7 @@ class CheckBatchCost:
                 # endpoint may transition a batch to "complete" before
                 # CheckBatchCost runs.  The batch_processed=False filter
                 # already prevents reprocessing finished batches.
-                jobs = await self.prisma_client.db.litellm_managedobjecttable.find_many(
+                jobs = await _managed_object_table(self.prisma_client).find_many(
                     where={
                         "file_purpose": "batch",
                         "batch_processed": False,
@@ -1038,7 +1071,7 @@ class CheckBatchCost:
                     }
                     if self._has_batch_processed_column:
                         update_data["batch_processed"] = True
-                    await self.prisma_client.db.litellm_managedobjecttable.update(
+                    await _managed_object_table(self.prisma_client).update(
                         where={"id": job.id},
                         data=update_data,
                     )
diff --git a/enterprise/litellm_enterprise/proxy/common_utils/check_responses_cost.py b/enterprise/litellm_enterprise/proxy/common_utils/check_responses_cost.py
index 06cf5fcf82f..1bc41f2aa5b 100644
--- a/enterprise/litellm_enterprise/proxy/common_utils/check_responses_cost.py
+++ b/enterprise/litellm_enterprise/proxy/common_utils/check_responses_cost.py
@@ -6,7 +6,7 @@ same route are non-inference and free.
 """
 
 from datetime import datetime, timedelta, timezone
-from typing import TYPE_CHECKING, Dict, Optional, cast
+from typing import TYPE_CHECKING, Dict, Final, Optional, Protocol, cast
 
 import litellm
 from litellm._logging import verbose_proxy_logger
@@ -22,11 +22,34 @@ from litellm.types.utils import BACKGROUND_RESPONSE_COST_POLL_CALL_ORIGIN
 
 if TYPE_CHECKING:
     from litellm.proxy.utils import PrismaClient, ProxyLogging
+    from litellm.repositories.prisma_protocols import TableActions
     from litellm.router import Router
 
 TERMINAL_RESPONSE_STATUSES = frozenset({"completed", "failed", "cancelled", "incomplete"})
 
 
+class _ManagedObjectRow(Protocol):
+    """The managed-object row fields this poller reads off whatever the DB hands back."""
+
+    @property
+    def id(self) -> str: ...
+
+    @property
+    def unified_object_id(self) -> str: ...
+
+    @property
+    def created_by(self) -> str | None: ...
+
+    @property
+    def file_object(self) -> object: ...
+
+
+def _managed_object_table(prisma_client: "PrismaClient") -> "TableActions[_ManagedObjectRow]":
+    """The managed-object table's prisma actions, typed to the row fields this poller reads."""
+    table: Final[TableActions[_ManagedObjectRow]] = prisma_client.db.litellm_managedobjecttable
+    return table
+
+
 class CheckResponsesCost:
     def __init__(
         self,
@@ -128,7 +151,7 @@ class CheckResponsesCost:
                 f"CheckResponsesCost: stale cleanup failed (poll will continue): {cleanup_err}"
             )
 
-        jobs = await self.prisma_client.db.litellm_managedobjecttable.find_many(
+        jobs = await _managed_object_table(self.prisma_client).find_many(
             where={
                 "status": {"in": ["queued", "in_progress"]},
                 "file_purpose": "response",
@@ -138,7 +161,7 @@ class CheckResponsesCost:
         )
         
         verbose_proxy_logger.debug(f"Found {len(jobs)} response jobs to check")
-        completed_jobs = []
+        completed_jobs: Final[list[_ManagedObjectRow]] = []
 
         for job in jobs:
             unified_object_id = job.unified_object_id
@@ -189,7 +212,7 @@ class CheckResponsesCost:
 
         # Mark completed jobs in the database
         if len(completed_jobs) > 0:
-            await self.prisma_client.db.litellm_managedobjecttable.update_many(
+            await _managed_object_table(self.prisma_client).update_many(
                 where={"id": {"in": [job.id for job in completed_jobs]}},
                 data={"status": "completed"},
             )
diff --git a/enterprise/litellm_enterprise/proxy/hooks/managed_files.py b/enterprise/litellm_enterprise/proxy/hooks/managed_files.py
index 4899b87da7a..5204894bee6 100644
--- a/enterprise/litellm_enterprise/proxy/hooks/managed_files.py
+++ b/enterprise/litellm_enterprise/proxy/hooks/managed_files.py
@@ -465,10 +465,8 @@ class _PROXY_LiteLLMManagedFiles(CustomLogger, BaseFileEndpoints):
         """
         if self.prisma_client is None:
             return
-        managed_object = (
-            await self.prisma_client.db.litellm_managedobjecttable.find_first(
-                where={"OR": [{"unified_object_id": object_id}, {"model_object_id": object_id}]}
-            )
+        managed_object = await _managed_object_table(self.prisma_client).find_first(
+            where={"OR": [{"unified_object_id": object_id}, {"model_object_id": object_id}]}
         )
         if managed_object is None:
             return
@@ -493,10 +491,8 @@ class _PROXY_LiteLLMManagedFiles(CustomLogger, BaseFileEndpoints):
         """
         if self.prisma_client is None:
             return
-        managed_file = (
-            await self.prisma_client.db.litellm_managedfiletable.find_first(
-                where={"OR": [{"unified_file_id": file_id}, {"flat_model_file_ids": {"has": file_id}}]}
-            )
+        managed_file = await _managed_file_table(self.prisma_client).find_first(
+            where={"OR": [{"unified_file_id": file_id}, {"flat_model_file_ids": {"has": file_id}}]}
         )
         if managed_file is None:
             return
@@ -519,8 +515,8 @@ class _PROXY_LiteLLMManagedFiles(CustomLogger, BaseFileEndpoints):
         provider_file_ids = tuple(
             file_id
             for file_id in (
-                getattr(response, "output_file_id", None),
-                getattr(response, "error_file_id", None),
+                response.output_file_id,
+                response.error_file_id,
             )
             if file_id and not _is_base64_encoded_unified_file_id(file_id)
         )
@@ -528,10 +524,8 @@ class _PROXY_LiteLLMManagedFiles(CustomLogger, BaseFileEndpoints):
             return
         if self.prisma_client is None:
             return
-        batch_row = (
-            await self.prisma_client.db.litellm_managedobjecttable.find_first(
-                where={"unified_object_id": response.id}
-            )
+        batch_row = await _managed_object_table(self.prisma_client).find_first(
+            where={"unified_object_id": response.id}
         )
         if batch_row is None or (
             batch_row.created_by is None and batch_row.team_id is None
diff --git a/litellm/caching/caching.py b/litellm/caching/caching.py
index d6dd2a073af..813ee655a1d 100644
--- a/litellm/caching/caching.py
+++ b/litellm/caching/caching.py
@@ -81,7 +81,7 @@ class Cache:
         s3_aws_access_key_id: str | None = None,
         s3_aws_secret_access_key: str | None = None,
         s3_aws_session_token: str | None = None,
-        s3_config: Any | None = None,
+        s3_config: object | None = None,
         s3_path: str | None = None,
         gcs_bucket_name: str | None = None,
         gcs_path_service_account: str | None = None,
diff --git a/litellm/caching/caching_handler.py b/litellm/caching/caching_handler.py
index 139dcf058d2..2c4f80b8708 100644
--- a/litellm/caching/caching_handler.py
+++ b/litellm/caching/caching_handler.py
@@ -73,7 +73,7 @@ class CachingHandlerResponse(BaseModel):
     For embeddings there can be a cache hit for some of the inputs in the list and a cache miss for others
     """
 
-    cached_result: Any | None = None
+    cached_result: object | None = None
     final_embedding_cached_response: EmbeddingResponse | None = None
     embedding_all_elements_cache_hit: bool = False  # this is set to True when all elements in the list have a cache hit in the embedding cache, if true return the final_embedding_cached_response no need to make an API call
 
@@ -707,7 +707,7 @@ class LLMCachingHandler:
 
     async def _retrieve_from_cache(
         self, call_type: str, kwargs: dict[str, object], args: tuple[object, ...]
-    ) -> Any | None:
+    ) -> object | None:
         """
         Internal method to
         - get cache key
@@ -953,7 +953,7 @@ class LLMCachingHandler:
 
     def _convert_cached_stream_response(
         self,
-        cached_result: Any,
+        cached_result: dict[str, object],
         call_type: str,
         logging_obj: LiteLLMLoggingObj,
         model: str,
@@ -982,7 +982,7 @@ class LLMCachingHandler:
 
     async def async_set_cache(
         self,
-        result: Any,
+        result: object,
         original_function: Callable,
         kwargs: dict[str, Any],
         args: tuple[object, ...] | None = None,
@@ -1050,7 +1050,7 @@ class LLMCachingHandler:
 
     def sync_set_cache(
         self,
-        result: Any,
+        result: object,
         kwargs: dict[str, object],
         args: tuple[object, ...] | None = None,
     ):
diff --git a/litellm/caching/redis_cache.py b/litellm/caching/redis_cache.py
index d0cefcb6086..e2b48159e01 100644
--- a/litellm/caching/redis_cache.py
+++ b/litellm/caching/redis_cache.py
@@ -934,7 +934,7 @@ class RedisCache(BaseCache):
             client: object = None,
         ) -> object:
             async def execute() -> object:
-                executor: Callable[..., Awaitable[Any]] | None = litellm.in_memory_llm_clients_cache.get_cache(
+                executor: Callable[..., Awaitable[object]] | None = litellm.in_memory_llm_clients_cache.get_cache(
                     key=script_cache_key
                 )
                 if executor is None:
@@ -946,7 +946,7 @@ class RedisCache(BaseCache):
 
         return run_script
 
-    def _register_script_for_current_loop(self, script: str) -> Callable[..., Awaitable[Any]]:
+    def _register_script_for_current_loop(self, script: str) -> Callable[..., Awaitable[object]]:
         """
         Register the script against the current event loop's Redis client.
 
diff --git a/litellm/completion_extras/litellm_responses_transformation/handler.py b/litellm/completion_extras/litellm_responses_transformation/handler.py
index f494d6610a1..642a78789b2 100644
--- a/litellm/completion_extras/litellm_responses_transformation/handler.py
+++ b/litellm/completion_extras/litellm_responses_transformation/handler.py
@@ -2,7 +2,7 @@
 Handler for transforming /chat/completions api requests to litellm.responses requests
 """
 
-from collections.abc import Coroutine
+from collections.abc import AsyncIterable, Coroutine, Iterable
 from typing import TYPE_CHECKING, Any, Final, Union
 
 from typing_extensions import TypedDict
@@ -74,7 +74,7 @@ class ResponsesToCompletionBridgeHandler:
                     existing.setdefault(key, value)
         return response
 
-    def _collect_response_from_stream(self, stream_iter: Any) -> "ResponsesAPIResponse":
+    def _collect_response_from_stream(self, stream_iter: Iterable[object]) -> "ResponsesAPIResponse":
         for _ in stream_iter:
             pass
 
@@ -89,7 +89,7 @@ class ResponsesToCompletionBridgeHandler:
             raise ValueError("Stream completed response is invalid")
         return response
 
-    async def _collect_response_from_stream_async(self, stream_iter: Any) -> "ResponsesAPIResponse":
+    async def _collect_response_from_stream_async(self, stream_iter: AsyncIterable[object]) -> "ResponsesAPIResponse":
         async for _ in stream_iter:
             pass
 
diff --git a/litellm/completion_extras/litellm_responses_transformation/transformation.py b/litellm/completion_extras/litellm_responses_transformation/transformation.py
index 5a6debc4af5..a5d67273768 100644
--- a/litellm/completion_extras/litellm_responses_transformation/transformation.py
+++ b/litellm/completion_extras/litellm_responses_transformation/transformation.py
@@ -6,7 +6,7 @@ import json
 import os
 from collections.abc import AsyncIterator, Callable, Iterable, Iterator, Mapping, Sequence
 from types import MappingProxyType
-from typing import TYPE_CHECKING, Any, Final, Literal, TypedDict, Union, cast, get_args
+from typing import TYPE_CHECKING, Any, Final, Literal, TypedDict, TypeVar, Union, cast, get_args
 
 from openai.types.chat import ChatCompletion
 from openai.types.responses import Response
@@ -52,7 +52,7 @@ from litellm.types.llms.openai import (
 from litellm.types.utils import GenericStreamingChunk, ModelResponseStream
 
 if TYPE_CHECKING:
-    from openai.types.responses import ResponseInputImageParam
+    from openai.types.responses import ResponseInputImageParam, ResponseOutputItem
     from openai.types.responses.response_text_config_param import (
         ResponseTextConfigParam as ResponseText,
     )
@@ -197,6 +197,9 @@ def _as_chat_reasoning_items(
     return cast(list[ChatCompletionReasoningItem], list(reasoning_items))
 
 
+_ToolChoiceT = TypeVar("_ToolChoiceT")
+
+
 def _map_incomplete_reason_to_finish_reason(incomplete_reason: str | None) -> Literal["length", "content_filter"]:
     if incomplete_reason == "content_filter":
         return "content_filter"
@@ -291,7 +294,9 @@ class LiteLLMResponsesTransformationHandler(CompletionTransformationBridge):
     def __init__(self):
         pass
 
-    def _normalize_tool_choice_for_responses_api(self, tool_choice: Any) -> Any:
+    def _normalize_tool_choice_for_responses_api(
+        self, tool_choice: _ToolChoiceT
+    ) -> _ToolChoiceT | ToolChoiceFunctionParam | ToolChoiceCustomParam | Literal["auto", "none", "required"]:
         """Chat tool_choice nests the name under function/custom; Responses API expects top-level name."""
         if not isinstance(tool_choice, dict):
             return tool_choice
@@ -497,7 +502,7 @@ class LiteLLMResponsesTransformationHandler(CompletionTransformationBridge):
                 responses_api_request["max_output_tokens"] = value
             elif key == "tools" and value is not None:
                 responses_api_request["tools"] = self._convert_tools_to_responses_format(
-                    cast(list[dict[str, Any]], value)
+                    cast(list[dict[str, object]], value)
                 )
             elif key == "response_format":
                 text_format = self._transform_response_format_to_text_format(value)
@@ -810,7 +815,7 @@ class LiteLLMResponsesTransformationHandler(CompletionTransformationBridge):
         response_output: Final = response_payload.get("output")
         if not isinstance(response_output, list) or len(response_output) == 0:
             return None
-        return cast(list[dict[str, Any]], response_output)
+        return cast(list[dict[str, object]], response_output)
 
     @classmethod
     def _recover_output_items_from_raw_sse(cls, raw_sse: str | None) -> list[dict[str, object]]:
@@ -893,10 +898,12 @@ class LiteLLMResponsesTransformationHandler(CompletionTransformationBridge):
 
         output_items = raw_response.output
         if len(output_items) == 0:
-            recovered_output_items: Final = self._recover_output_items_from_logging(logging_obj)
+            recovered_output_items: Final[list[ResponseOutputItem | dict[str, object]]] = [
+                *self._recover_output_items_from_logging(logging_obj)
+            ]
             if recovered_output_items:
-                output_items = cast(Any, recovered_output_items)
-                raw_response.output = cast(Any, recovered_output_items)
+                output_items = recovered_output_items
+                raw_response.output = recovered_output_items
                 verbose_logger.warning(
                     "Recovered empty Responses API output from raw SSE for model=%s",
                     model,
@@ -1092,7 +1099,9 @@ class LiteLLMResponsesTransformationHandler(CompletionTransformationBridge):
             verbose_logger.debug("Chat provider: Other content type -> %s", result)
             return result
 
-    def _convert_tools_to_responses_format(self, tools: list[dict[str, Any]]) -> list["ALL_RESPONSES_API_TOOL_PARAMS"]:
+    def _convert_tools_to_responses_format(
+        self, tools: list[dict[str, object]]
+    ) -> list["ALL_RESPONSES_API_TOOL_PARAMS"]:
         """Convert chat completion tools to responses API tools format"""
         responses_tools: Final[list[ALL_RESPONSES_API_TOOL_PARAMS]] = []
         for tool in tools:
@@ -1108,12 +1117,11 @@ class LiteLLMResponsesTransformationHandler(CompletionTransformationBridge):
                         description=function_tool.get("description"),
                     )
                 )
-            elif tool.get("type") == "custom" and isinstance(tool.get("custom"), dict):
+            elif tool.get("type") == "custom" and isinstance(custom_payload := tool.get("custom"), dict):
                 from litellm.litellm_core_utils.prompt_templates.common_utils import (
                     convert_custom_tool_format_to_responses_shape,
                 )
 
-                custom_payload = tool["custom"]
                 flat_custom = CustomToolParam(type="custom", name=custom_payload.get("name", ""))
                 if custom_payload.get("description") is not None:
                     flat_custom["description"] = custom_payload["description"]
diff --git a/litellm/cost_calculator.py b/litellm/cost_calculator.py
index 440d97d13be..d93bf1e8769 100644
--- a/litellm/cost_calculator.py
+++ b/litellm/cost_calculator.py
@@ -351,7 +351,7 @@ def cost_per_token(
     data_residency: str | None = None,  # for OpenAI regional-processing uplift (e.g. "eu", "us")
     ### VERTEX LOCATION ###
     vertex_location: str | None = None,  # for Vertex AI regional-endpoint uplift (e.g. "us-east5", "global")
-    response: Any | None = None,
+    response: object | None = None,
     ### REQUEST MODEL ###
     request_model: str | None = None,  # original request model for router detection
     custom_model_info: OCRPricing | None = None,
@@ -607,7 +607,7 @@ def cost_per_token(
             model=model,
             custom_llm_provider=custom_llm_provider,
             number_of_queries=number_of_queries or 1,
-            optional_params=(response._hidden_params if response and hasattr(response, "_hidden_params") else None),
+            optional_params=(getattr(response, "_hidden_params", None) if response else None),
         )
     elif custom_llm_provider == "vertex_ai":
         cost_router: Final = google_cost_router(
@@ -996,7 +996,7 @@ def _is_known_usage_objects(usage_obj):
     )
 
 
-def _infer_call_type(call_type: CallTypesLiteral | None, completion_response: Any) -> CallTypesLiteral | None:
+def _infer_call_type(call_type: CallTypesLiteral | None, completion_response: object) -> CallTypesLiteral | None:
     if call_type is not None:
         return call_type
 
diff --git a/litellm/integrations/braintrust_logging.py b/litellm/integrations/braintrust_logging.py
index aaf72a0bc4e..501f5749ea4 100644
--- a/litellm/integrations/braintrust_logging.py
+++ b/litellm/integrations/braintrust_logging.py
@@ -139,13 +139,13 @@ class BraintrustLogger(CustomLogger):
             ):
                 output = None
             elif response_obj is not None and isinstance(response_obj, litellm.ModelResponse):
-                output = response_obj["choices"][0]["message"].json()
+                output = response_obj.choices[0].message.json()
                 choices = response_obj["choices"]
             elif response_obj is not None and isinstance(response_obj, litellm.TextCompletionResponse):
                 output = response_obj.choices[0].text
                 choices = response_obj.choices
             elif response_obj is not None and isinstance(response_obj, litellm.ImageResponse):
-                output = response_obj["data"]
+                output = response_obj.data
 
             litellm_params: Final = kwargs.get("litellm_params", {}) or {}
             dynamic_metadata: Final = litellm_params.get("metadata", {}) or {}
@@ -264,13 +264,13 @@ class BraintrustLogger(CustomLogger):
             ):
                 output = None
             elif response_obj is not None and isinstance(response_obj, litellm.ModelResponse):
-                output = response_obj["choices"][0]["message"].json()
+                output = response_obj.choices[0].message.json()
                 choices = response_obj["choices"]
             elif response_obj is not None and isinstance(response_obj, litellm.TextCompletionResponse):
                 output = response_obj.choices[0].text
                 choices = response_obj.choices
             elif response_obj is not None and isinstance(response_obj, litellm.ImageResponse):
-                output = response_obj["data"]
+                output = response_obj.data
 
             litellm_params: Final = kwargs.get("litellm_params", {})
             dynamic_metadata: Final = litellm_params.get("metadata", {}) or {}
diff --git a/litellm/integrations/custom_guardrail.py b/litellm/integrations/custom_guardrail.py
index 39adea30828..eaee84fae93 100644
--- a/litellm/integrations/custom_guardrail.py
+++ b/litellm/integrations/custom_guardrail.py
@@ -155,7 +155,7 @@ class CustomGuardrail(CustomLogger):
 
     def __init_subclass__(cls, **kwargs: object) -> None:  # kwargs-ok: forwarded to cooperative __init_subclass__ hooks
         super().__init_subclass__(**kwargs)
-        own_apply_guardrail: Final = cls.__dict__.get("apply_guardrail")
+        own_apply_guardrail: Final[object] = cls.__dict__.get("apply_guardrail")
         if own_apply_guardrail is None or LOGS_GUARDRAIL_INFORMATION_MARKER in vars(own_apply_guardrail):
             return
         cls.apply_guardrail = log_guardrail_information(own_apply_guardrail)
diff --git a/litellm/integrations/datadog/datadog_llm_obs.py b/litellm/integrations/datadog/datadog_llm_obs.py
index c64a12c6d75..3afe38ea075 100644
--- a/litellm/integrations/datadog/datadog_llm_obs.py
+++ b/litellm/integrations/datadog/datadog_llm_obs.py
@@ -54,7 +54,7 @@ from litellm.types.utils import (
     StandardLoggingPayloadErrorInformation,
 )
 
-_EMPTY_MAPPING: Final[Mapping[str, Any]] = MappingProxyType({})
+_EMPTY_MAPPING: Final[Mapping[str, object]] = MappingProxyType({})
 _EMPTY_MESSAGE: Final[Message] = {"role": "", "content": ""}
 _MAX_PARSED_TOOL_ARGUMENT_CHARS: Final = 256 * 1024
 _SAFE_REDACTED_MESSAGE_ROLES: Final = frozenset(
@@ -154,7 +154,7 @@ def _guardrail_information_without_prompt_carriers(
     return tuple(_guardrail_entry_without_prompt_carriers(entry) for entry in _guardrail_entries(guardrail_information))
 
 
-def _metadata_without_prompt_carriers(standard_logging_metadata: Mapping[str, Any]) -> Mapping[str, Any]:
+def _metadata_without_prompt_carriers(standard_logging_metadata: Mapping[str, object]) -> Mapping[str, object]:
     """The metadata minus the records that quote prompts, tool arguments, tool results, or retrieved text."""
     return MappingProxyType(
         {
@@ -237,7 +237,7 @@ def _declared_cost_tags(span_tags: Sequence[str]) -> tuple[str, ...]:
     return tuple(dimension for dimension in _COST_DIMENSIONS if dimension in present)
 
 
-def _reasoning_output_tokens(usage_object: Mapping[str, Any] | None) -> float:
+def _reasoning_output_tokens(usage_object: Mapping[str, object] | None) -> float:
     """The provider's reasoning-token count, from either the chat or the responses spelling."""
     if usage_object is None:
         return 0.0
@@ -254,20 +254,20 @@ def _reasoning_output_tokens(usage_object: Mapping[str, Any] | None) -> float:
     )
 
 
-def _mapping_field(source: Mapping[str, Any], key: str) -> Mapping[str, Any]:
+def _mapping_field(source: Mapping[str, object], key: str) -> Mapping[str, Any]:
     """The value at `key` when it is a mapping, else an empty one."""
     value: Final = source.get(key)
     return value if isinstance(value, dict) else _EMPTY_MAPPING
 
 
-def _content_blocks(message: Mapping[str, Any]) -> tuple[Mapping[str, Any], ...]:
+def _content_blocks(message: Mapping[str, object]) -> tuple[Mapping[str, Any], ...]:
     content: Final = message.get("content")
     if not isinstance(content, list):
         return ()
     return tuple(block for block in content if isinstance(block, dict))
 
 
-def _to_dd_arguments(raw_arguments: object) -> dict[str, Any] | str:
+def _to_dd_arguments(raw_arguments: object) -> dict[str, object] | str:
     """
     Arguments as the object LLM Obs types them as, or the raw string when they are not one.
 
@@ -282,7 +282,7 @@ def _to_dd_arguments(raw_arguments: object) -> dict[str, Any] | str:
     return parsed if isinstance(parsed, dict) else raw_arguments
 
 
-def _to_dd_tool_calls(message: Mapping[str, Any]) -> tuple[ToolCall, ...]:
+def _to_dd_tool_calls(message: Mapping[str, object]) -> tuple[ToolCall, ...]:
     """
     The tool calls a message carries, in LLM Obs' ToolCall schema, from either dialect.
 
@@ -315,7 +315,7 @@ def _to_dd_tool_calls(message: Mapping[str, Any]) -> tuple[ToolCall, ...]:
     return openai_calls + anthropic_calls
 
 
-def _to_dd_tool_results(message: Mapping[str, Any], tool_call_names: Mapping[str, str]) -> tuple[ToolResult, ...]:
+def _to_dd_tool_results(message: Mapping[str, object], tool_call_names: Mapping[str, str]) -> tuple[ToolResult, ...]:
     """
     The tool results a message carries, linked back to the call each answers.
 
@@ -400,7 +400,7 @@ def _to_dd_messages(messages: object) -> tuple[Message, ...]:
     return tuple(_to_dd_message(message, tool_call_names) for message in messages)
 
 
-def _to_dd_tool_definition(entry: Mapping[str, Any]) -> ToolDefinition | None:
+def _to_dd_tool_definition(entry: Mapping[str, object]) -> ToolDefinition | None:
     function: Final = entry.get("function")
     declared: Final[Mapping[str, Any]] = function if isinstance(function, dict) else entry
     name: Final = declared.get("name")
@@ -683,7 +683,7 @@ class DataDogLLMObsLogger(CustomBatchLogger):
             if callable(current_span_fn):
                 current_span: Final = current_span_fn()
                 if current_span is not None:
-                    trace_id: Final = getattr(current_span, "trace_id", None)
+                    trace_id: Final[object] = getattr(current_span, "trace_id", None)
                     if trace_id is not None:
                         return str(trace_id)
         except Exception:
@@ -716,7 +716,7 @@ class DataDogLLMObsLogger(CustomBatchLogger):
     def redacts_messages_itself(self) -> bool:
         return True
 
-    def _payload_logging_is_off(self, kwargs: Mapping[str, Any]) -> bool:
+    def _payload_logging_is_off(self, kwargs: Mapping[str, object]) -> bool:
         return (
             bool(self.turn_off_message_logging)
             or self.message_logging is not True
diff --git a/litellm/integrations/galileo.py b/litellm/integrations/galileo.py
index b27618993a3..010f8ad8ef2 100644
--- a/litellm/integrations/galileo.py
+++ b/litellm/integrations/galileo.py
@@ -396,12 +396,13 @@ class GalileoObserve(CustomLogger):
         )
 
     @staticmethod
-    def _log_v2_payload_validation(payload: dict[str, Any]) -> None:
+    def _log_v2_payload_validation(payload: dict[str, object]) -> None:
         missing_fields: Final[list[str]] = []
-        traces: Final[Sequence[object]] = payload.get("traces", [])
-        if not traces:
+        traces_value: Final = payload.get("traces", [])
+        if not traces_value:
             missing_fields.append("traces")
 
+        traces: Final[Sequence[object]] = traces_value if isinstance(traces_value, list) else []
         for trace_index, trace in enumerate(traces):
             if not isinstance(trace, dict):
                 continue
@@ -425,8 +426,8 @@ class GalileoObserve(CustomLogger):
                 missing_fields,
             )
 
-    def _log_flush_payload(self, url: str, payload: dict[str, Any]) -> None:
-        traces: Final[Sequence[object]] = payload.get("traces", [])
+    def _log_flush_payload(self, url: str, payload: dict[str, object]) -> None:
+        traces: Final = payload.get("traces")
         verbose_logger.debug(
             "Galileo Logger flush URL: %s trace_count=%s",
             url,
diff --git a/litellm/integrations/langfuse/langfuse.py b/litellm/integrations/langfuse/langfuse.py
index b75369965de..c89506facbd 100644
--- a/litellm/integrations/langfuse/langfuse.py
+++ b/litellm/integrations/langfuse/langfuse.py
@@ -4,7 +4,7 @@ import inspect
 import os
 import re
 import traceback
-from collections.abc import Callable, Iterable, Mapping
+from collections.abc import Callable, Iterable, Mapping, Sequence
 from datetime import datetime
 from functools import lru_cache
 from types import MappingProxyType
@@ -447,7 +447,7 @@ class LangFuseLogger:
         prompt: dict,
         level: str,
         status_message: str | None,
-    ) -> tuple[dict | None, str | dict | list | None]:
+    ) -> tuple[dict | None, str | dict | Sequence[object] | None]:
         """
         Get the input and output content for Langfuse logging
 
@@ -463,7 +463,7 @@ class LangFuseLogger:
             output: The output content for Langfuse logging
         """
         input = None
-        output: str | dict | list[Any] | None = None
+        output: str | dict | Sequence[object] | None = None
         if level == "ERROR" and status_message is not None and isinstance(status_message, str):
             input = prompt
             output = status_message
@@ -575,7 +575,7 @@ class LangFuseLogger:
         user_id: str | None,
         metadata: dict[str, object],
         litellm_params: dict,
-        output: str | dict | list | None,
+        output: str | dict | Sequence[object] | None,
         start_time: datetime | None,
         end_time: datetime | None,
         kwargs: dict,
diff --git a/litellm/litellm_core_utils/llm_response_utils/response_metadata.py b/litellm/litellm_core_utils/llm_response_utils/response_metadata.py
index c83c266a17e..d279fb9e259 100644
--- a/litellm/litellm_core_utils/llm_response_utils/response_metadata.py
+++ b/litellm/litellm_core_utils/llm_response_utils/response_metadata.py
@@ -1,6 +1,6 @@
 import datetime
 from collections.abc import Mapping
-from typing import Any, Final
+from typing import Final
 
 import httpx
 
@@ -54,7 +54,7 @@ class ResponseMetadata:
     Handles setting and managing `_hidden_params`, `response_time_ms`, and `litellm_overhead_time_ms` for LiteLLM responses
     """
 
-    def __init__(self, result: Any):
+    def __init__(self, result: object):
         self.result = result
         self._hidden_params: HiddenParams | dict = getattr(result, "_hidden_params", {}) or {}
 
diff --git a/litellm/litellm_core_utils/prompt_templates/common_utils.py b/litellm/litellm_core_utils/prompt_templates/common_utils.py
index 2485896184e..f2b03e72497 100644
--- a/litellm/litellm_core_utils/prompt_templates/common_utils.py
+++ b/litellm/litellm_core_utils/prompt_templates/common_utils.py
@@ -13,14 +13,6 @@ from pathlib import Path
 from types import MappingProxyType
 from typing import TYPE_CHECKING, Any, Final, Literal, TypeVar, cast
 
-from openai.types.chat.chat_completion_custom_tool_param import (
-    CustomFormatGrammar,
-    CustomFormatGrammarGrammar,
-)
-from openai.types.shared_params.custom_tool_input_format import (
-    Grammar as ResponsesGrammarFormat,
-)
-
 import litellm
 from litellm import verbose_logger
 from litellm.router_utils.batch_utils import InMemoryFile
@@ -59,7 +51,7 @@ if TYPE_CHECKING:
 
 
 def handle_any_messages_to_chat_completion_str_messages_conversion(
-    messages: Any,
+    messages: object,
 ) -> list[dict[str, str]]:
     """
     Handles any messages to chat completion str messages conversion
@@ -804,7 +796,7 @@ def extract_file_metadata(file_data: FileTypes) -> tuple[str | None, str | None]
     """
     filename: str | None = None
     content_type: str | None = None
-    file_content: Any = None
+    file_content: object = None
 
     if isinstance(file_data, tuple):
         if len(file_data) == 2:
@@ -1002,7 +994,7 @@ def unpack_defs(
 
     # Use iterative approach with queue to avoid recursion
     # Each item in queue is (node, parent_container, key/index, active_defs, ref_chain)
-    queue: Final[deque[tuple[Any, dict | list | None, str | int | None, dict, set]]] = deque(
+    queue: Final[deque[tuple[object, dict | list | None, str | int | None, dict, set]]] = deque(
         [(schema, None, None, root_defs, set())]
     )
     inlined_bytes = 0
@@ -1624,7 +1616,10 @@ def is_function_call(optional_params: dict) -> bool:
     return False
 
 
-def convert_custom_tool_format_to_chat_shape(format_obj: Mapping[str, Any]) -> Mapping[str, Any]:
+_CUSTOM_GRAMMAR_FIELDS: Final = ("definition", "syntax")
+
+
+def convert_custom_tool_format_to_chat_shape(format_obj: Mapping[str, object]) -> Mapping[str, object]:
     """
     Responses API grammar formats are flat ({"type": "grammar", "definition", "syntax"});
     Chat Completions wraps the same fields in a "grammar" object. Text formats are
@@ -1632,15 +1627,11 @@ def convert_custom_tool_format_to_chat_shape(format_obj: Mapping[str, Any]) -> M
     """
     if format_obj.get("type") != "grammar" or "grammar" in format_obj:
         return format_obj
-    grammar: Final = CustomFormatGrammarGrammar()
-    if "definition" in format_obj:
-        grammar["definition"] = format_obj["definition"]
-    if "syntax" in format_obj:
-        grammar["syntax"] = format_obj["syntax"]
-    return CustomFormatGrammar(type="grammar", grammar=grammar)
+    grammar: Final[Mapping[str, object]] = {key: format_obj[key] for key in _CUSTOM_GRAMMAR_FIELDS if key in format_obj}
+    return {"type": "grammar", "grammar": grammar}
 
 
-def convert_custom_tool_format_to_responses_shape(format_obj: Mapping[str, Any]) -> Mapping[str, Any]:
+def convert_custom_tool_format_to_responses_shape(format_obj: Mapping[str, object]) -> Mapping[str, object]:
     """
     Inverse of convert_custom_tool_format_to_chat_shape: unwrap the Chat Completions
     "grammar" object into the flat Responses API grammar shape.
@@ -1648,12 +1639,10 @@ def convert_custom_tool_format_to_responses_shape(format_obj: Mapping[str, Any])
     grammar: Final = format_obj.get("grammar")
     if format_obj.get("type") != "grammar" or not isinstance(grammar, dict):
         return format_obj
-    flat: Final = ResponsesGrammarFormat(type="grammar")
-    if "definition" in grammar:
-        flat["definition"] = grammar["definition"]
-    if "syntax" in grammar:
-        flat["syntax"] = grammar["syntax"]
-    return flat
+    return {
+        "type": "grammar",
+        **{key: grammar[key] for key in _CUSTOM_GRAMMAR_FIELDS if key in grammar},
+    }
 
 
 def get_file_ids_from_messages(messages: list[AllMessageValues]) -> list[str]:
diff --git a/litellm/llms/a2a/chat/guardrail_translation/handler.py b/litellm/llms/a2a/chat/guardrail_translation/handler.py
index 5c30ff4747a..92dc49ea9c1 100644
--- a/litellm/llms/a2a/chat/guardrail_translation/handler.py
+++ b/litellm/llms/a2a/chat/guardrail_translation/handler.py
@@ -125,7 +125,7 @@ class A2AGuardrailHandler(BaseTranslation):
         litellm_logging_obj: Optional["LiteLLMLoggingObj"] = None,
         user_api_key_dict: Optional["UserAPIKeyAuth"] = None,
         request_data: dict | None = None,
-    ) -> Any:
+    ) -> object:
         """
         Process A2A output response by applying guardrails to text content.
 
diff --git a/litellm/llms/anthropic/chat/transformation.py b/litellm/llms/anthropic/chat/transformation.py
index 0f99441a115..6899c334618 100644
--- a/litellm/llms/anthropic/chat/transformation.py
+++ b/litellm/llms/anthropic/chat/transformation.py
@@ -6,7 +6,7 @@ from types import MappingProxyType
 from typing import TYPE_CHECKING, Any, Final, NoReturn, cast
 
 import httpx
-from pydantic import ValidationError
+from pydantic import BaseModel, ValidationError
 from typing_extensions import ReadOnly, TypedDict
 
 import litellm
@@ -150,7 +150,7 @@ class _AnthropicToolResultBlock(TypedDict, total=False):
     content: ReadOnly[object]
 
 
-_ENUM_TYPE_CHECKS: Final[Mapping[str, Callable[[object], bool]]] = MappingProxyType(
+_ENUM_TYPE_CHECKS: Final[Mapping[object, Callable[[object], bool]]] = MappingProxyType(
     {
         "null": lambda v: v is None,
         "boolean": lambda v: isinstance(v, bool),
@@ -163,7 +163,7 @@ _ENUM_TYPE_CHECKS: Final[Mapping[str, Callable[[object], bool]]] = MappingProxyT
 )
 
 
-def _enum_conflicts_with_declared_type(schema: Mapping[str, Any]) -> bool:
+def _enum_conflicts_with_declared_type(schema: Mapping[str, object]) -> bool:
     """Whether ``schema``'s ``enum`` cannot match its declared ``type``."""
     enum_values: Final = schema.get("enum")
     declared_type: Final = schema.get("type")
@@ -658,7 +658,7 @@ class AnthropicConfig(AnthropicModelInfo, BaseConfig):
 
         return result
 
-    def get_json_schema_from_pydantic_object(self, response_format: Any | dict | None) -> dict | None:
+    def get_json_schema_from_pydantic_object(self, response_format: type[BaseModel] | dict | None) -> dict | None:
         return type_to_response_format_param(
             response_format, ref_template="/$defs/{model}"
         )  # Relevant issue: https://github.com/BerriAI/litellm/issues/7755
@@ -1061,7 +1061,7 @@ class AnthropicConfig(AnthropicModelInfo, BaseConfig):
 
     @staticmethod
     def _sanitize_tool_names_in_request(
-        optional_params: dict[str, Any],
+        optional_params: dict[str, object],
     ) -> tuple[dict[str, str], dict[str, str]]:
         """Sanitize ``optional_params['tools']`` and ``optional_params['tool_choice']``
         in place so every name matches Anthropic's ``^[a-zA-Z0-9_-]{1,128}$``.
@@ -1108,7 +1108,7 @@ class AnthropicConfig(AnthropicModelInfo, BaseConfig):
         #    so a caller reusing the same tool list/dicts across requests
         #    doesn't see its inputs permanently rewritten (which would also
         #    drop the original key from `forward` on the next request).
-        new_tools: Final[list[Any]] = []
+        new_tools: Final[list[object]] = []
         for t in tools:
             if (
                 isinstance(t, dict)
@@ -1431,7 +1431,7 @@ class AnthropicConfig(AnthropicModelInfo, BaseConfig):
 
                 entry_type = entry.get("type")
                 if entry_type == "compaction":
-                    anthropic_edit: dict[str, Any] = {"type": "compact_20260112"}
+                    anthropic_edit: dict[str, object] = {"type": "compact_20260112"}
                     compact_threshold = entry.get("compact_threshold")
                     # Rewrite to 'trigger' with correct nesting if threshold exists
                     if compact_threshold is not None and isinstance(compact_threshold, (int, float)):
@@ -2431,9 +2431,11 @@ class AnthropicConfig(AnthropicModelInfo, BaseConfig):
         code_by_id: Final[dict[str, str]] = {}
         for tc in tool_calls:
             try:
-                args = json.loads(tc.get("function", {}).get("arguments", "{}"))
+                args: object = json.loads(tc.get("function", {}).get("arguments", "{}"))
+                if not isinstance(args, Mapping):
+                    continue
                 call_id = tc.get("id")
-                command = args.get("command", "")
+                command: object = args.get("command", "")
                 if isinstance(call_id, str):
                     code_by_id[call_id] = command if isinstance(command, str) else ""
             except Exception:
@@ -2503,8 +2505,8 @@ class AnthropicConfig(AnthropicModelInfo, BaseConfig):
         tool_results: Sequence[_AnthropicToolResultBlock] | None,
         compaction_blocks: Sequence[object] | None,
         tool_calls: list[ChatCompletionToolCallChunk],
-    ) -> dict[str, Any]:
-        provider_specific_fields: Final[dict[str, Any]] = {
+    ) -> dict[str, object]:
+        provider_specific_fields: Final[dict[str, object]] = {
             "citations": citations,
             "thinking_blocks": thinking_blocks,
         }
diff --git a/litellm/llms/anthropic/common_utils.py b/litellm/llms/anthropic/common_utils.py
index 87c4ec8938e..7ec15ebd1f4 100644
--- a/litellm/llms/anthropic/common_utils.py
+++ b/litellm/llms/anthropic/common_utils.py
@@ -7,7 +7,7 @@ import re
 from collections.abc import Mapping, MutableMapping, Sequence
 from datetime import datetime, timezone
 from types import MappingProxyType
-from typing import Any, Final, Literal
+from typing import Any, Final, Literal, TypeVar
 
 import httpx
 from pydantic import BaseModel, ConfigDict, TypeAdapter, ValidationError
@@ -39,6 +39,8 @@ from litellm.types.llms.anthropic import (
 from litellm.types.llms.openai import AllMessageValues
 from litellm.types.proxy.model_listing import ModelInfoResponse
 
+_MessageT = TypeVar("_MessageT")
+
 DROP_FORCED_TOOL_CHOICE_WARNING: Final = (
     "Downgrading forced tool_choice to 'auto' for model=%s (drop_params=True): this model rejects tool_choice type "
     "'any'/'tool' with a 400 because thinking is always on and a forced call would skip it."
@@ -1074,7 +1076,7 @@ class AnthropicModelInfo(BaseLLMModelInfo):
         return AnthropicTokenCounter()
 
 
-def strip_advisor_blocks_from_messages(messages: list[Any], replace_with_text: bool = False) -> list[Any]:
+def strip_advisor_blocks_from_messages(messages: list[_MessageT], replace_with_text: bool = False) -> list[_MessageT]:
     """
     Remove (or replace) server_tool_use (name='advisor') and advisor_tool_result blocks
     from assistant message content.
@@ -1181,7 +1183,7 @@ def is_anthropic_invalid_thinking_block_error(error_text: str) -> bool:
     return "must contain thinking" in lower
 
 
-def strip_thinking_blocks_from_anthropic_messages(messages: list[Any]) -> list[Any]:
+def strip_thinking_blocks_from_anthropic_messages(messages: Sequence[object]) -> list[object]:
     """
     Return a new message list with thinking / redacted_thinking content blocks removed
     from each message. Used to recover from invalid thinking signatures on retry.
@@ -1189,7 +1191,7 @@ def strip_thinking_blocks_from_anthropic_messages(messages: list[Any]) -> list[A
     Messages whose content is a list and becomes empty after stripping are omitted,
     since Anthropic rejects empty content arrays.
     """
-    out: Final[list[Any]] = []
+    out: Final[list[object]] = []
     for m in messages:
         if not isinstance(m, dict):
             out.append(m)
diff --git a/litellm/llms/anthropic/experimental_pass_through/messages/agentic_streaming_iterator.py b/litellm/llms/anthropic/experimental_pass_through/messages/agentic_streaming_iterator.py
index 171f5156594..306041d9949 100644
--- a/litellm/llms/anthropic/experimental_pass_through/messages/agentic_streaming_iterator.py
+++ b/litellm/llms/anthropic/experimental_pass_through/messages/agentic_streaming_iterator.py
@@ -25,6 +25,9 @@ from litellm.constants import STREAM_SSE_KEEPALIVE_PING_BYTES
 
 if TYPE_CHECKING:
     from litellm.litellm_core_utils.litellm_logging import Logging as LiteLLMLoggingObj
+    from litellm.llms.base_llm.anthropic_messages.transformation import (
+        BaseAnthropicMessagesConfig,
+    )
 
 HOLD_BACK_PING_INTERVAL_SECONDS: Final = 15.0
 SERVER_FULFILLED_TOOL_LEAK_ERROR_SSE_BYTES: Final = (
@@ -182,7 +185,7 @@ class AgenticAnthropicStreamingIterator:
         http_handler: Any,
         model: str,
         messages: list[dict],
-        anthropic_messages_provider_config: Any,
+        anthropic_messages_provider_config: "BaseAnthropicMessagesConfig",
         anthropic_messages_optional_request_params: dict,
         logging_obj: "LiteLLMLoggingObj",
         custom_llm_provider: str,
@@ -402,7 +405,7 @@ class AgenticAnthropicStreamingIterator:
     @staticmethod
     def _rebuild_anthropic_response_from_sse(
         raw_bytes: list[bytes],
-    ) -> dict[str, Any] | None:
+    ) -> dict[str, object] | None:
         """
         Parse collected SSE bytes into an Anthropic Messages response dict.
 
@@ -416,17 +419,18 @@ class AgenticAnthropicStreamingIterator:
         """
         events: Final = _parse_sse_events(b"".join(raw_bytes))
 
-        response: Final[dict[str, Any]] = {
+        content: Final[list[dict[str, object]]] = []
+        response: Final[dict[str, object]] = {
             "id": "",
             "type": "message",
             "role": "assistant",
             "model": "",
-            "content": [],
+            "content": content,
             "stop_reason": None,
             "stop_sequence": None,
             "usage": {"input_tokens": 0, "output_tokens": 0},
         }
-        content_blocks: Final[dict[int, dict[str, Any]]] = {}
+        content_blocks: Final[dict[int, dict[str, object]]] = {}
         saw_message_start = False
 
         for event_type, data in events:
@@ -448,6 +452,6 @@ class AgenticAnthropicStreamingIterator:
         for idx in sorted(content_blocks.keys()):
             block = content_blocks[idx]
             block.pop("_partial_json", None)
-            response["content"].append(block)
+            content.append(block)
 
         return response
diff --git a/litellm/llms/anthropic/files/handler.py b/litellm/llms/anthropic/files/handler.py
index dfd62ca575b..e4c75a704ec 100644
--- a/litellm/llms/anthropic/files/handler.py
+++ b/litellm/llms/anthropic/files/handler.py
@@ -185,7 +185,11 @@ class AnthropicFilesHandler:
                 if not line.strip():
                     continue
 
-                anthropic_result = json.loads(line)
+                anthropic_result: object = json.loads(line)
+                if not isinstance(anthropic_result, dict):
+                    raise TypeError(
+                        f"Anthropic batch result line is not a JSON object: {type(anthropic_result).__name__}"
+                    )
                 custom_id = anthropic_result.get("custom_id", "")
                 result = anthropic_result.get("result", {})
                 result_type = result.get("type", "")
diff --git a/litellm/llms/bedrock/chat/converse_transformation.py b/litellm/llms/bedrock/chat/converse_transformation.py
index fa18361e44c..aabd4f1afdc 100644
--- a/litellm/llms/bedrock/chat/converse_transformation.py
+++ b/litellm/llms/bedrock/chat/converse_transformation.py
@@ -1037,7 +1037,7 @@ class AmazonConverseConfig(BaseConfig):
 
         return optional_params
 
-    def _map_request_metadata_param(self, value: Any, optional_params: dict) -> None:
+    def _map_request_metadata_param(self, value: object, optional_params: dict) -> None:
         if value is not None and isinstance(value, dict):
             self._validate_request_metadata(value)
             optional_params["requestMetadata"] = value
diff --git a/litellm/llms/chatgpt/responses/transformation.py b/litellm/llms/chatgpt/responses/transformation.py
index b96e06be3d8..9774b762396 100644
--- a/litellm/llms/chatgpt/responses/transformation.py
+++ b/litellm/llms/chatgpt/responses/transformation.py
@@ -1,5 +1,8 @@
+from collections.abc import Mapping
 from typing import TYPE_CHECKING, Any, Final
 
+import httpx
+
 from litellm.exceptions import AuthenticationError
 from litellm.litellm_core_utils.core_helpers import process_response_headers
 from litellm.litellm_core_utils.llm_response_utils.convert_dict_to_response import (
@@ -13,6 +16,7 @@ from litellm.responses.sse_output_recovery import (
     record_output_text_chunk,
 )
 from litellm.types.llms.openai import (
+    ResponseInputParam,
     ResponsesAPIResponse,
     ResponsesAPIStreamEvents,
 )
@@ -64,7 +68,7 @@ class ChatGPTResponsesAPIConfig(OpenAIResponsesAPIConfig):
     def transform_responses_api_request(
         self,
         model: str,
-        input: Any,
+        input: str | ResponseInputParam,
         response_api_optional_request_params: dict,
         litellm_params: GenericLiteLLMParams,
         headers: dict,
@@ -109,9 +113,9 @@ class ChatGPTResponsesAPIConfig(OpenAIResponsesAPIConfig):
     def transform_response_api_response(
         self,
         model: str,
-        raw_response: Any,
+        raw_response: httpx.Response,
         logging_obj: "LiteLLMLoggingObj",
-    ):
+    ) -> ResponsesAPIResponse:
         body_text: Final = raw_response.text or ""
         if not self._should_parse_as_sse(raw_response=raw_response, body_text=body_text):
             return super().transform_response_api_response(
@@ -135,7 +139,7 @@ class ChatGPTResponsesAPIConfig(OpenAIResponsesAPIConfig):
         self._attach_response_headers(completed_response=completed_response, raw_response=raw_response)
         return completed_response
 
-    def _should_parse_as_sse(self, raw_response: Any, body_text: str) -> bool:
+    def _should_parse_as_sse(self, raw_response: httpx.Response, body_text: str) -> bool:
         content_type: Final = (raw_response.headers or {}).get("content-type", "")
         if "text/event-stream" in content_type.lower():
             return True
@@ -150,8 +154,8 @@ class ChatGPTResponsesAPIConfig(OpenAIResponsesAPIConfig):
     def _extract_completed_response_from_sse(self, body_text: str) -> tuple[ResponsesAPIResponse | None, str | None]:
         completed_response = None
         error_message = None
-        streamed_output_items: Final[dict[int, dict]] = {}
-        text_only_output_items: Final[dict[int, dict]] = {}
+        streamed_output_items: Final[dict[int, dict[str, object]]] = {}
+        text_only_output_items: Final[dict[int, dict[str, object]]] = {}
         for chunk in body_text.splitlines():
             parsed_chunk = parse_sse_json_chunk(chunk)
             if parsed_chunk is None:
@@ -178,7 +182,7 @@ class ChatGPTResponsesAPIConfig(OpenAIResponsesAPIConfig):
                 # output_index, but text-only items at indices without a
                 # matching OUTPUT_ITEM_DONE must still be preserved (e.g.
                 # providers that emit only OUTPUT_TEXT_DONE for some indices).
-                merged_items: dict[int, dict] = {**text_only_output_items}
+                merged_items: dict[int, dict[str, object]] = {**text_only_output_items}
                 merged_items.update(streamed_output_items)
                 completed_response = self._build_completed_response_from_chunk(
                     parsed_chunk=parsed_chunk,
@@ -197,7 +201,7 @@ class ChatGPTResponsesAPIConfig(OpenAIResponsesAPIConfig):
         return completed_response, error_message
 
     def _build_completed_response_from_chunk(
-        self, parsed_chunk: dict[str, Any], streamed_output_items: dict[int, dict]
+        self, parsed_chunk: Mapping[str, object], streamed_output_items: Mapping[int, dict[str, object]]
     ) -> ResponsesAPIResponse | None:
         response_payload = parsed_chunk.get("response")
         if not isinstance(response_payload, dict):
@@ -223,7 +227,7 @@ class ChatGPTResponsesAPIConfig(OpenAIResponsesAPIConfig):
     def _attach_response_headers(
         self,
         completed_response: ResponsesAPIResponse,
-        raw_response: Any,
+        raw_response: httpx.Response,
     ) -> None:
         raw_headers: Final = dict(raw_response.headers)
         processed_headers: Final = process_response_headers(raw_headers)
diff --git a/litellm/llms/cohere/chat/transformation.py b/litellm/llms/cohere/chat/transformation.py
index 319603b0dad..fa46bd7f6cf 100644
--- a/litellm/llms/cohere/chat/transformation.py
+++ b/litellm/llms/cohere/chat/transformation.py
@@ -110,7 +110,7 @@ class CohereChatConfig(BaseConfig):
         tool_results: list | None = None,
         seed: int | None = None,
     ) -> None:
-        locals_: Final = locals().copy()
+        locals_: Final[dict[str, object]] = locals().copy()
         for key, value in locals_.items():
             if key != "self" and value is not None:
                 setattr(self.__class__, key, value)
diff --git a/litellm/llms/databricks/chat/transformation.py b/litellm/llms/databricks/chat/transformation.py
index 82c3b5d91d3..dd257cd68b0 100644
--- a/litellm/llms/databricks/chat/transformation.py
+++ b/litellm/llms/databricks/chat/transformation.py
@@ -3,7 +3,7 @@ Translates from OpenAI's `/v1/chat/completions` to Databricks' `/chat/completion
 """
 
 import os
-from collections.abc import AsyncIterator, Coroutine, Iterator, Mapping
+from collections.abc import AsyncIterator, Coroutine, Iterator, Mapping, Sequence
 from typing import TYPE_CHECKING, Any, Final, Literal, cast, overload
 
 import httpx
@@ -67,7 +67,7 @@ def _is_bare_assistant_message(message_dict: Mapping[str, object]) -> bool:
     )
 
 
-def _sanitize_empty_content(message_dict: dict[str, Any]) -> None:
+def _sanitize_empty_content(message_dict: dict[str, object]) -> None:
     """
     Remove or filter content so empty text blocks are not sent.
     Databricks Model Serving uses Anthropic Messages API spec and rejects empty text blocks.
@@ -430,7 +430,7 @@ class DatabricksConfig(DatabricksBase, OpenAILikeChatConfig, AnthropicConfig):
     @overload
     def _transform_messages(
         self, messages: list[AllMessageValues], model: str, is_async: Literal[True]
-    ) -> Coroutine[Any, Any, list[AllMessageValues]]: ...
+    ) -> Coroutine[object, object, list[AllMessageValues]]: ...
 
     @overload
     def _transform_messages(
@@ -442,7 +442,7 @@ class DatabricksConfig(DatabricksBase, OpenAILikeChatConfig, AnthropicConfig):
 
     def _transform_messages(
         self, messages: list[AllMessageValues], model: str, is_async: bool = False
-    ) -> list[AllMessageValues] | Coroutine[Any, Any, list[AllMessageValues]]:
+    ) -> list[AllMessageValues] | Coroutine[object, object, list[AllMessageValues]]:
         """
         Databricks does not support:
         - 'name' in user message.
@@ -564,7 +564,7 @@ class DatabricksConfig(DatabricksBase, OpenAILikeChatConfig, AnthropicConfig):
     @staticmethod
     def extract_citations(
         content: AllDatabricksContentValues | None,
-    ) -> list[Any] | None:
+    ) -> Sequence[Sequence[Mapping[str, object]]] | None:
         if content is None:
             return None
         citations: Final = []
diff --git a/litellm/llms/fireworks_ai/chat/transformation.py b/litellm/llms/fireworks_ai/chat/transformation.py
index 05160d83c12..1e9082a1ef1 100644
--- a/litellm/llms/fireworks_ai/chat/transformation.py
+++ b/litellm/llms/fireworks_ai/chat/transformation.py
@@ -1,6 +1,6 @@
 import json
 from collections.abc import AsyncIterator, Iterator, Mapping
-from typing import TYPE_CHECKING, Any, Final, Literal, cast
+from typing import TYPE_CHECKING, Final, Literal, cast
 
 import httpx
 
@@ -751,7 +751,7 @@ class FireworksAIConfig(FireworksAIMixin, OpenAIGPTConfig):
         streaming_response: Iterator[str] | AsyncIterator[str] | ModelResponse,
         sync_stream: bool,
         json_mode: bool | None = False,
-    ) -> Any:
+    ) -> "FireworksAIChatCompletionStreamingHandler":
         return FireworksAIChatCompletionStreamingHandler(
             streaming_response=streaming_response,
             sync_stream=sync_stream,
diff --git a/litellm/llms/gemini/count_tokens/handler.py b/litellm/llms/gemini/count_tokens/handler.py
index cb2be2c860e..c2f0ef473ae 100644
--- a/litellm/llms/gemini/count_tokens/handler.py
+++ b/litellm/llms/gemini/count_tokens/handler.py
@@ -84,7 +84,7 @@ class GoogleAIStudioTokenCounter:
         api_key: str | None = None,
         api_base: str | None = None,
         timeout: float | httpx.Timeout | None = None,
-        **kwargs,
+        **kwargs: object,
     ) -> dict[str, Any]:
         """
         Count tokens using Google Gen AI Studio countTokens endpoint.
diff --git a/litellm/llms/gemini/image_edit/transformation.py b/litellm/llms/gemini/image_edit/transformation.py
index e6c22dc60b4..31d3963c70c 100644
--- a/litellm/llms/gemini/image_edit/transformation.py
+++ b/litellm/llms/gemini/image_edit/transformation.py
@@ -1,4 +1,5 @@
 import base64
+from collections.abc import Mapping
 from io import BufferedReader, BytesIO
 from typing import TYPE_CHECKING, Any, Final, cast
 
@@ -44,7 +45,7 @@ class GeminiImageEditConfig(BaseImageEditConfig):
         image_edit_optional_params: ImageEditOptionalRequestParams,
         model: str,
         drop_params: bool,
-    ) -> dict[str, Any]:
+    ) -> dict[str, object]:
         return map_openai_image_params_to_gemini(
             params=image_edit_optional_params,
             model=model,
@@ -87,10 +88,10 @@ class GeminiImageEditConfig(BaseImageEditConfig):
         model: str,
         prompt: str | None,
         image: FileTypes | None,
-        image_edit_optional_request_params: dict[str, Any],
+        image_edit_optional_request_params: Mapping[str, object],
         litellm_params: GenericLiteLLMParams,
         headers: dict,
-    ) -> tuple[dict[str, Any], RequestFiles | None]:
+    ) -> tuple[dict[str, object], RequestFiles | None]:
         inline_parts: Final = self._prepare_inline_image_parts(image) if image else []
         if not inline_parts:
             raise ValueError("Gemini image edit requires at least one image.")
@@ -106,7 +107,7 @@ class GeminiImageEditConfig(BaseImageEditConfig):
             }
         ]
 
-        request_body: Final[dict[str, Any]] = {"contents": contents}
+        request_body: Final[dict[str, object]] = {"contents": contents}
 
         request_body["generationConfig"] = get_gemini_image_generation_config(
             model=model,
@@ -153,14 +154,14 @@ class GeminiImageEditConfig(BaseImageEditConfig):
             model_response.usage = transform_gemini_image_usage(response_json["usageMetadata"])
         return model_response
 
-    def _prepare_inline_image_parts(self, image: FileTypes | list[FileTypes]) -> list[dict[str, Any]]:
+    def _prepare_inline_image_parts(self, image: FileTypes | list[FileTypes]) -> list[dict[str, object]]:
         images: list[FileTypes]
         if isinstance(image, list):
             images = image
         else:
             images = [image]
 
-        inline_parts: Final[list[dict[str, Any]]] = []
+        inline_parts: Final[list[dict[str, object]]] = []
         for img in images:
             if img is None:
                 continue
diff --git a/litellm/llms/gigachat/chat/transformation.py b/litellm/llms/gigachat/chat/transformation.py
index 89920ebd27b..d9250ea8836 100644
--- a/litellm/llms/gigachat/chat/transformation.py
+++ b/litellm/llms/gigachat/chat/transformation.py
@@ -81,9 +81,17 @@ class GigaChatConfig(BaseConfig):
         repetition_penalty: float | None = None,
         profanity_check: bool | None = None,
     ) -> None:
-        locals_: Final = locals().copy()
-        for key, value in locals_.items():
-            if key != "self" and value is not None:
+        config_params: Final[Mapping[str, float | int | bool | None]] = MappingProxyType(
+            {
+                "temperature": temperature,
+                "top_p": top_p,
+                "max_tokens": max_tokens,
+                "repetition_penalty": repetition_penalty,
+                "profanity_check": profanity_check,
+            }
+        )
+        for key, value in config_params.items():
+            if value is not None:
                 setattr(self.__class__, key, value)
         # Instance variables for current request context
         self._current_credentials: str | None = None
diff --git a/litellm/llms/huggingface/embedding/transformation.py b/litellm/llms/huggingface/embedding/transformation.py
index f6fe7f2fa10..33b0e21e326 100644
--- a/litellm/llms/huggingface/embedding/transformation.py
+++ b/litellm/llms/huggingface/embedding/transformation.py
@@ -84,13 +84,13 @@ class HuggingFaceEmbeddingConfig(BaseConfig):
         typical_p: float | None = None,
         watermark: bool | None = None,
     ) -> None:
-        locals_: Final = locals().copy()
+        locals_: Final[dict[str, object]] = locals().copy()
         for key, value in locals_.items():
             if key != "self" and value is not None:
                 setattr(self.__class__, key, value)
 
     @classmethod
-    def get_config(cls):
+    def get_config(cls) -> dict[str, object]:
         return super().get_config()
 
     def get_special_options_params(self):
@@ -352,17 +352,17 @@ class HuggingFaceEmbeddingConfig(BaseConfig):
         model: str,
         data: dict,
         api_key: str | None = None,
-    ) -> list[dict[str, Any]]:
+    ) -> list[dict[str, str]]:
         streamed_response: Final = CustomStreamWrapper(
             completion_stream=response.iter_lines(),
             model=model,
             custom_llm_provider="huggingface",
             logging_obj=logging_obj,
         )
-        content = ""
+        content: str = ""
         for chunk in streamed_response:
             content += chunk["choices"][0]["delta"]["content"]
-        completion_response: Final[list[dict[str, Any]]] = [{"generated_text": content}]
+        completion_response: Final[list[dict[str, str]]] = [{"generated_text": content}]
         ## LOGGING
         logging_obj.post_call(
             input=data,
diff --git a/litellm/llms/openai/chat/guardrail_translation/handler.py b/litellm/llms/openai/chat/guardrail_translation/handler.py
index 58ff03e6a0d..665215303d9 100644
--- a/litellm/llms/openai/chat/guardrail_translation/handler.py
+++ b/litellm/llms/openai/chat/guardrail_translation/handler.py
@@ -17,7 +17,7 @@ This pattern can be replicated for other message formats (e.g., Anthropic).
 import json
 import time
 import uuid
-from collections.abc import Sequence
+from collections.abc import Mapping, Sequence
 from typing import TYPE_CHECKING, Any, Final, Union, cast
 
 from typing_extensions import NotRequired, ReadOnly, TypedDict
@@ -232,7 +232,7 @@ class OpenAIChatCompletionsHandler(BaseTranslation):
 
     def _extract_inputs(
         self,
-        message: dict[str, Any],
+        message: Mapping[str, object],
         msg_idx: int,
         texts_to_check: list[str],
         images_to_check: list[str],
@@ -293,7 +293,7 @@ class OpenAIChatCompletionsHandler(BaseTranslation):
 
     async def _apply_guardrail_responses_to_input_texts(
         self,
-        messages: list[dict[str, Any]],
+        messages: list[dict[str, object]],
         responses: list[str],
         task_mappings: list[tuple[int, int | None]],
     ) -> None:
@@ -318,12 +318,12 @@ class OpenAIChatCompletionsHandler(BaseTranslation):
 
             elif isinstance(content, list) and content_idx_optional is not None:
                 # Replace specific text item in list content
-                messages[msg_idx]["content"][content_idx_optional]["text"] = guardrail_response
+                content[content_idx_optional]["text"] = guardrail_response
 
     async def _apply_guardrail_responses_to_input_tool_calls(
         self,
-        messages: list[dict[str, Any]],
-        tool_calls: list[dict[str, Any]],
+        messages: Sequence[Mapping[str, object]],
+        tool_calls: Sequence[Mapping[str, object]],
         task_mappings: list[tuple[int, int]],
     ) -> None:
         """
@@ -375,7 +375,7 @@ class OpenAIChatCompletionsHandler(BaseTranslation):
 
         texts_to_check: Final[list[str]] = []
         images_to_check: Final[list[str]] = []
-        tool_calls_to_check: Final[list[dict[str, Any]]] = []
+        tool_calls_to_check: Final[list[dict[str, object]]] = []
         text_task_mappings: Final[list[tuple[int, int | None]]] = []
         tool_call_task_mappings: Final[list[tuple[int, int]]] = []
         # text_task_mappings: Track (choice_index, content_index) for each text
@@ -424,8 +424,8 @@ class OpenAIChatCompletionsHandler(BaseTranslation):
 
             guardrailed_texts: Final = guardrailed_inputs.get("texts", [])
             returned_tool_calls: Final = guardrailed_inputs.get("tool_calls")
-            guardrailed_tool_calls: Final[list[dict[str, Any]]] = (
-                cast(list[dict[str, Any]], returned_tool_calls)
+            guardrailed_tool_calls: Final[list[dict[str, object]]] = (
+                cast(list[dict[str, object]], returned_tool_calls)
                 if isinstance(returned_tool_calls, list) and len(returned_tool_calls) == len(tool_calls_to_check)
                 else tool_calls_to_check
             )
@@ -864,7 +864,7 @@ class OpenAIChatCompletionsHandler(BaseTranslation):
         choice_idx: int,
         texts_to_check: list[str],
         images_to_check: list[str],
-        tool_calls_to_check: list[dict[str, Any]],
+        tool_calls_to_check: list[dict[str, object]],
         text_task_mappings: list[tuple[int, int | None]],
         tool_call_task_mappings: list[tuple[int, int]],
     ) -> None:
diff --git a/litellm/llms/openai/videos/transformation.py b/litellm/llms/openai/videos/transformation.py
index 94dc30f41e5..9a4b030993f 100644
--- a/litellm/llms/openai/videos/transformation.py
+++ b/litellm/llms/openai/videos/transformation.py
@@ -237,7 +237,7 @@ class OpenAIVideoConfig(BaseVideoConfig):
         api_base: str,
         litellm_params: GenericLiteLLMParams,
         headers: dict,
-        extra_body: dict[str, Any] | None = None,
+        extra_body: dict[str, object] | None = None,
     ) -> tuple[str, dict]:
         """
         Transform the video remix request for OpenAI API.
@@ -252,7 +252,7 @@ class OpenAIVideoConfig(BaseVideoConfig):
         url: Final = f"{api_base.rstrip('/')}/{encoded_video_id}/remix"
 
         # Prepare the request data
-        data: Final = {"prompt": prompt}
+        data: Final[dict[str, object]] = {"prompt": prompt}
 
         # Add any extra body parameters
         if extra_body:
@@ -305,7 +305,7 @@ class OpenAIVideoConfig(BaseVideoConfig):
         after: str | None = None,
         limit: int | None = None,
         order: str | None = None,
-        extra_query: dict[str, Any] | None = None,
+        extra_query: dict[str, object] | None = None,
     ) -> tuple[str, dict]:
         """
         Transform the video list request for OpenAI API.
diff --git a/litellm/llms/openrouter/image_edit/transformation.py b/litellm/llms/openrouter/image_edit/transformation.py
index b01c25aad0c..3d46277a69e 100644
--- a/litellm/llms/openrouter/image_edit/transformation.py
+++ b/litellm/llms/openrouter/image_edit/transformation.py
@@ -90,20 +90,21 @@ class OpenRouterImageEditConfig(BaseImageEditConfig):
         drop_params: bool,
     ) -> dict:
         supported_params: Final = self.get_supported_openai_params(model)
-        mapped_params: Final[dict[str, Any]] = {}
+        mapped_params: Final[dict[str, object]] = {}
+        image_config: Final[dict[str, str]] = {}
 
         for key, value in image_edit_optional_params.items():
             if key in supported_params:
                 if key == "size":
                     if "image_config" not in mapped_params:
-                        mapped_params["image_config"] = {}
-                    mapped_params["image_config"]["aspect_ratio"] = self._map_size_to_aspect_ratio(cast(str, value))
+                        mapped_params["image_config"] = image_config
+                    image_config["aspect_ratio"] = self._map_size_to_aspect_ratio(cast(str, value))
                 elif key == "quality":
                     image_size = self._map_quality_to_image_size(cast(str, value))
                     if image_size:
                         if "image_config" not in mapped_params:
-                            mapped_params["image_config"] = {}
-                        mapped_params["image_config"]["image_size"] = image_size
+                            mapped_params["image_config"] = image_config
+                        image_config["image_size"] = image_size
                 else:
                     mapped_params[key] = value
 
diff --git a/litellm/llms/perplexity/embedding/transformation.py b/litellm/llms/perplexity/embedding/transformation.py
index a911fa62719..c93206db2bb 100644
--- a/litellm/llms/perplexity/embedding/transformation.py
+++ b/litellm/llms/perplexity/embedding/transformation.py
@@ -130,7 +130,7 @@ class PerplexityEmbeddingConfig(BaseEmbeddingConfig):
         if isinstance(embedding_value, str):
             raw_bytes: Final = base64.b64decode(embedding_value)
             count: Final = len(raw_bytes)
-            int8_values: Final = struct.unpack(f"{count}b", raw_bytes)
+            int8_values: Final[tuple[int, ...]] = struct.unpack(f"{count}b", raw_bytes)
             return [float(v) / 127.0 for v in int8_values]
         return embedding_value
 
diff --git a/litellm/llms/vertex_ai/gemini/transformation.py b/litellm/llms/vertex_ai/gemini/transformation.py
index 13e2238fdf6..e3cc3bbb2dc 100644
--- a/litellm/llms/vertex_ai/gemini/transformation.py
+++ b/litellm/llms/vertex_ai/gemini/transformation.py
@@ -179,7 +179,7 @@ def _apply_gemini_metadata(
     part: PartType,
     model: str | None,
     media_resolution_enum: dict[str, str] | None,
-    video_metadata: dict[str, Any] | None,
+    video_metadata: Mapping[str, object] | None,
 ) -> PartType:
     """
     Apply media_resolution and video_metadata parameters to a Gemini part.
@@ -480,7 +480,7 @@ def _process_gemini_media(
     format: str | None = None,
     media_resolution_enum: dict[str, str] | None = None,
     model: str | None = None,
-    video_metadata: dict[str, Any] | None = None,
+    video_metadata: Mapping[str, object] | None = None,
     vertex_project: str | None = None,
     vertex_credentials: object = None,
 ) -> PartType:
diff --git a/litellm/proxy/_experimental/mcp_server/mcp_server_manager.py b/litellm/proxy/_experimental/mcp_server/mcp_server_manager.py
index fb0c623473a..f640db7e5dc 100644
--- a/litellm/proxy/_experimental/mcp_server/mcp_server_manager.py
+++ b/litellm/proxy/_experimental/mcp_server/mcp_server_manager.py
@@ -5574,7 +5574,7 @@ class MCPServerManager:
     async def pre_call_tool_check(
         self,
         name: str,
-        arguments: dict[str, Any],
+        arguments: _ToolArguments,
         server_name: str,
         user_api_key_auth: UserAPIKeyAuth | None,
         proxy_logging_obj: ProxyLogging | None,
diff --git a/litellm/proxy/auth/auth_utils.py b/litellm/proxy/auth/auth_utils.py
index be65c3b39ec..bd248da52ef 100644
--- a/litellm/proxy/auth/auth_utils.py
+++ b/litellm/proxy/auth/auth_utils.py
@@ -166,7 +166,7 @@ def check_regex_or_str_match(request_body_value: Any, regex_str: str) -> bool:
 
 def _is_param_allowed(
     param: str,
-    request_body_value: Any,
+    request_body_value: object,
     configurable_clientside_auth_params: CONFIGURABLE_CLIENTSIDE_AUTH_PARAMS,
 ) -> bool:
     """
@@ -189,7 +189,7 @@ def _is_param_allowed(
 
 
 def _allow_model_level_clientside_configurable_parameters(
-    model: str, param: str, request_body_value: Any, llm_router: Router | None
+    model: str, param: str, request_body_value: object, llm_router: Router | None
 ) -> bool:
     """
     Check if model is allowed to use configurable client-side params
@@ -532,7 +532,7 @@ def is_request_body_safe(request_body: dict, general_settings: dict, llm_router:
     return True
 
 
-def _coerce_metadata_to_dict(value: Any) -> dict[str, Any] | None:
+def _coerce_metadata_to_dict(value: object) -> dict[str, object] | None:
     """Return ``value`` as a dict, parsing it from JSON if delivered as a string.
 
     Multipart/form-data and ``extra_body`` callers send ``litellm_metadata``
@@ -891,7 +891,7 @@ async def check_if_request_size_is_safe(request: Request) -> bool:
     return True
 
 
-async def check_response_size_is_safe(response: Any) -> bool:
+async def check_response_size_is_safe(response: object) -> bool:
     """
     Enterprise Only:
         - Checks if the response size is within the limit
@@ -1526,7 +1526,7 @@ def get_customer_user_header_from_mapping(user_id_mapping) -> list | None:
 
 
 def _get_customer_id_from_standard_headers(
-    request_headers: dict | None,
+    request_headers: Mapping[str, object] | None,
 ) -> str | None:
     """
     Check standard customer ID headers for a customer/end-user ID.
@@ -1552,7 +1552,7 @@ def _get_customer_id_from_standard_headers(
     return None
 
 
-def _coerce_user_id_to_str(value: Any) -> str | None:
+def _coerce_user_id_to_str(value: object) -> str | None:
     """Return a usable end-user identifier string, or None if the value isn't one.
 
     Always drops non-string structured values (dict/list/tuple/set) because
@@ -1579,7 +1579,7 @@ def _coerce_user_id_to_str(value: Any) -> str | None:
         # behind the flag preserves backwards compatibility for deployments
         # that intentionally pass JSON-encoded user identifiers.
         if litellm.validate_end_user_id_in_db and stripped[:1] in ("{", "["):
-            parsed: Final = safe_json_loads(stripped)
+            parsed: Final[object] = safe_json_loads(stripped)
             if isinstance(parsed, (dict, list)):
                 return None
         return stripped
@@ -1587,7 +1587,9 @@ def _coerce_user_id_to_str(value: Any) -> str | None:
     return None
 
 
-def get_end_user_id_from_request_body(request_body: dict, request_headers: dict | None = None) -> str | None:
+def get_end_user_id_from_request_body(
+    request_body: Mapping[str, object], request_headers: Mapping[str, object] | None = None
+) -> str | None:
     # Import general_settings here to avoid potential circular import issues at module level
     # and to ensure it's fetched at runtime.
     from litellm.proxy.proxy_server import general_settings
@@ -1636,7 +1638,7 @@ def get_end_user_id_from_request_body(request_body: dict, request_headers: dict
         if user_id_str:
             return user_id_str
 
-    def _as_dict(value: Any) -> dict:
+    def _as_dict(value: object) -> dict:
         # metadata / litellm_metadata can arrive as JSON strings from
         # multipart/form-data or extra_body; coerce so string-encoded
         # payloads can't evade end-user attribution.
@@ -1721,11 +1723,11 @@ _MODEL_ROUTING_ID_FIELDS: Final = (
 )
 
 
-def _append_model_candidates(candidates: list[str], value: Any) -> None:
+def _append_model_candidates(candidates: list[str], value: object) -> None:
     if value is None:
         return
 
-    values: Final = value if isinstance(value, (list, tuple, set)) else [value]
+    values: Final[tuple[object, ...]] = tuple(value) if isinstance(value, (list, tuple, set)) else (value,)
     for item in values:
         if item is None:
             continue
@@ -1766,7 +1768,7 @@ def _route_uses_model_routing_sources(route: str) -> bool:
 
 
 def _extract_models_from_managed_resource_id(
-    resource_id: Any,
+    resource_id: object,
     resource_id_field: str | None = None,
     llm_router: Router | None = None,
 ) -> list[str]:
diff --git a/litellm/proxy/client/cli/commands/configure.py b/litellm/proxy/client/cli/commands/configure.py
index 7988f8aef3c..539aa2581f5 100644
--- a/litellm/proxy/client/cli/commands/configure.py
+++ b/litellm/proxy/client/cli/commands/configure.py
@@ -98,13 +98,15 @@ def _preflight(target: str) -> None:
         raise click.ClickException(str(e)) from e
 
 
-def _start(ctx: click.Context, api_key: str | None, target: str = _CLAUDE_TARGET) -> tuple[StaticToken, _Listing]:
+def _start(
+    ctx: click.Context, base_url: str, api_key: str | None, target: str = _CLAUDE_TARGET
+) -> tuple[StaticToken, _Listing]:
     _preflight(target)
     try:
         credential: Final = resolve_credential(ctx, api_key)
     except ClaudeSettingsError as e:
         raise click.ClickException(str(e))
-    return credential, _listed_models(ctx.obj["base_url"], credential.token, target)
+    return credential, _listed_models(base_url, credential.token, target)
 
 
 def _listing_error(base_url: str, error: PiSyncError, target: str) -> str:
@@ -147,9 +149,7 @@ def _validated_model(model: str | None, listing: _Listing, base_url: str) -> str
     return starting
 
 
-def _apply_claude(ctx: click.Context, credential: StaticToken, listing: _Listing, model: str | None) -> None:
-    ctx_obj: Final[CliContextObj] = ctx.obj
-    base_url: Final = ctx_obj["base_url"]
+def _apply_claude(base_url: str, credential: StaticToken, listing: _Listing, model: str | None) -> None:
     listed: Final = listing.ids
     starting: Final = _validated_model(model, listing, base_url)
     settings_path: Final = claude_settings_path(os.environ)
@@ -214,8 +214,7 @@ def _pick_codex_model(listed: Sequence[str]) -> str:
     return str(inquirer.fuzzy(message="Model Codex starts on (type to filter):", choices=choices).execute())
 
 
-def _apply_codex(ctx: click.Context, credential: StaticToken, listing: _Listing, model: str) -> None:
-    base_url: Final[str] = ctx.obj["base_url"]
+def _apply_codex(base_url: str, credential: StaticToken, listing: _Listing, model: str) -> None:
     _validated_model(model, listing, base_url)
     settings_path: Final = codex_config_path(os.environ)
     try:
@@ -237,13 +236,12 @@ class _Setup:
 
 
 def _choose_setup(
-    ctx: click.Context,
+    base_url: str,
     target: str,
     credential: StaticToken,
     pick_model: Callable[[Sequence[str]], str | None],
     pick_codex_model: Callable[[Sequence[str]], str],
 ) -> _Setup:
-    base_url: Final[str] = ctx.obj["base_url"]
     listing: Final = _listed_models(base_url, credential.token, target)
     model: Final = (
         pick_model(tuple(item.source_model or item.id for item in listing.models))
@@ -270,12 +268,15 @@ def interactive_configure(
         credential: Final = resolve_credential(ctx, None)
     except ClaudeSettingsError as e:
         raise click.ClickException(str(e)) from e
-    setups: Final = tuple(_choose_setup(ctx, target, credential, pick_model, pick_codex_model) for target in targets)
+    base_url: Final[str] = ctx.obj["base_url"]
+    setups: Final = tuple(
+        _choose_setup(base_url, target, credential, pick_model, pick_codex_model) for target in targets
+    )
     for setup in setups:
         if setup.target == _CLAUDE_TARGET:
-            _apply_claude(ctx, credential, setup.listing, setup.model)
+            _apply_claude(base_url, credential, setup.listing, setup.model)
         elif setup.model is not None:
-            _apply_codex(ctx, credential, setup.listing, setup.model)
+            _apply_codex(base_url, credential, setup.listing, setup.model)
 
 
 class _ConnectionOptions(BaseModel):
@@ -283,7 +284,8 @@ class _ConnectionOptions(BaseModel):
     gateway_url: str | None = None
 
 
-def _connection_context(ctx: click.Context, api_key: str | None, gateway_url: str | None) -> click.Context:
+def _connection_settings(ctx: click.Context, api_key: str | None, gateway_url: str | None) -> CliContextObj:
+    """The context object a subcommand runs with: its own --api-key / --gateway-url over the group's, over `lite`'s."""
     ctx_obj: Final[CliContextObj] = ctx.obj
     group: Final = (
         _ConnectionOptions.model_validate(ctx.parent.params)
@@ -300,7 +302,11 @@ def _connection_context(ctx: click.Context, api_key: str | None, gateway_url: st
         "api_key": key if key is not None else ctx_obj.get("api_key"),
         "api_key_from_token_file": False if key is not None else ctx_obj.get("api_key_from_token_file", False),
     }
-    return click.Context(ctx.command, parent=ctx.parent, obj=connection)
+    return connection
+
+
+def _connection_context(ctx: click.Context, settings: CliContextObj) -> click.Context:
+    return click.Context(ctx.command, parent=ctx.parent, obj=settings)
 
 
 @click.group(name="configure", invoke_without_command=True)
@@ -316,19 +322,19 @@ def configure_group(ctx: click.Context, api_key: str | None, gateway_url: str |
     """
     if ctx.invoked_subcommand is not None:
         return
-    connection: Final = _connection_context(ctx, api_key, gateway_url)
+    settings: Final = _connection_settings(ctx, api_key, gateway_url)
+    connection: Final = _connection_context(ctx, settings)
     if not sys.stdin.isatty():
         raise click.ClickException(
             "`lite configure` asks questions, so it needs a terminal. Non-interactively, run "
             "`lite configure claude --api-key <key> --model <model>` or "
             "`lite configure codex --api-key <key> --model <model>`."
         )
-    prompted: Final = (
-        connection
-        if connection.obj.get("base_url_explicit")
-        else _connection_context(connection, None, click.prompt("Gateway URL", default=connection.obj["base_url"]))
-    )
-    interactive_configure(prompted)
+    if settings.get("base_url_explicit"):
+        interactive_configure(connection)
+        return
+    prompted: Final = _connection_settings(connection, None, click.prompt("Gateway URL", default=settings["base_url"]))
+    interactive_configure(_connection_context(connection, prompted))
 
 
 @click.group(name="unconfigure")
@@ -356,9 +362,9 @@ def configure_claude(ctx: click.Context, api_key: str | None, model: str | None,
     setting is kept, and what changed is recorded so `lite unconfigure claude` can put it back.
     Assumes the proxy is already running.
     """
-    connection: Final = _connection_context(ctx, api_key, gateway_url)
-    credential, listing = _start(connection, api_key)
-    _apply_claude(connection, credential, listing, model)
+    settings: Final = _connection_settings(ctx, api_key, gateway_url)
+    credential, listing = _start(_connection_context(ctx, settings), settings["base_url"], api_key)
+    _apply_claude(settings["base_url"], credential, listing, model)
 
 
 @configure_group.command(name="codex")
@@ -368,9 +374,9 @@ def configure_claude(ctx: click.Context, api_key: str | None, model: str | None,
 @click.pass_context
 def configure_codex(ctx: click.Context, api_key: str | None, gateway_url: str | None, model: str) -> None:
     """Route plain `codex` through the gateway until `lite unconfigure codex`."""
-    connection: Final = _connection_context(ctx, api_key, gateway_url)
-    credential, listing = _start(connection, api_key, _CODEX_TARGET)
-    _apply_codex(connection, credential, listing, model)
+    settings: Final = _connection_settings(ctx, api_key, gateway_url)
+    credential, listing = _start(_connection_context(ctx, settings), settings["base_url"], api_key, _CODEX_TARGET)
+    _apply_codex(settings["base_url"], credential, listing, model)
 
 
 @unconfigure_group.command(name="codex")
diff --git a/litellm/proxy/common_utils/callback_utils.py b/litellm/proxy/common_utils/callback_utils.py
index 561a53409f4..eafbb1ef95f 100644
--- a/litellm/proxy/common_utils/callback_utils.py
+++ b/litellm/proxy/common_utils/callback_utils.py
@@ -713,7 +713,7 @@ def strip_callback_config(metadata: dict[str, object] | None) -> dict[str, objec
     return {k: v for k, v in metadata.items() if k not in _CALLBACK_CONFIG_SLOTS}
 
 
-def encrypt_callback_vars(metadata: Any) -> Any:
+def encrypt_callback_vars(metadata: object) -> Any:
     """Return a deep copy of metadata with callback_vars values encrypted at rest.
 
     Idempotent: a value that already decrypts cleanly is left unchanged so
@@ -722,7 +722,7 @@ def encrypt_callback_vars(metadata: Any) -> Any:
     return _transform_callback_vars(metadata, _encrypt_if_plaintext)
 
 
-def decrypt_callback_vars(metadata: Any) -> Any:
+def decrypt_callback_vars(metadata: object) -> Any:
     """Return a deep copy of metadata with callback_vars values decrypted.
 
     Legacy plaintext rows pass through unchanged (decrypt failure → original).
@@ -730,7 +730,7 @@ def decrypt_callback_vars(metadata: Any) -> Any:
     return _transform_callback_vars(metadata, _decrypt_or_passthrough)
 
 
-def _transform_callback_vars(metadata: object, transform: Callable[[str, Any], Any]) -> object:
+def _transform_callback_vars(metadata: object, transform: Callable[[str, object], object]) -> object:
     if not isinstance(metadata, dict):
         return metadata
     out: Final = copy.deepcopy(metadata)
diff --git a/litellm/proxy/db/db_spend_update_writer.py b/litellm/proxy/db/db_spend_update_writer.py
index eaa03c5d7f7..19af995932a 100644
--- a/litellm/proxy/db/db_spend_update_writer.py
+++ b/litellm/proxy/db/db_spend_update_writer.py
@@ -15,7 +15,7 @@ import traceback
 from collections.abc import Mapping, Sequence
 from datetime import datetime, timedelta, timezone
 from types import MappingProxyType
-from typing import TYPE_CHECKING, Any, Final, Literal, Protocol, cast, overload
+from typing import TYPE_CHECKING, Any, Final, Literal, Protocol, TypeAlias, cast, overload
 
 import litellm
 from litellm._logging import verbose_proxy_logger
@@ -115,6 +115,20 @@ class _SpendBatch(Protocol):
     litellm_modelaccessgroupbudgettable: BatchTable
 
 
+_EntitySpendTable: TypeAlias = Literal["litellm_tagtable", "litellm_agentstable", "litellm_modelaccessgroupbudgettable"]
+
+
+def _entity_spend_table(batcher: _SpendBatch, table_accessor: _EntitySpendTable) -> BatchTable:
+    """The batch table an entity type's spend increments are written to."""
+    match table_accessor:
+        case "litellm_tagtable":
+            return batcher.litellm_tagtable
+        case "litellm_agentstable":
+            return batcher.litellm_agentstable
+        case "litellm_modelaccessgroupbudgettable":
+            return batcher.litellm_modelaccessgroupbudgettable
+
+
 class _SpendBatchManager(Protocol):
     async def __aenter__(self) -> _SpendBatch: ...
 
@@ -1750,7 +1764,7 @@ class DBSpendUpdateWriter:
     async def _update_entity_spend_in_db(
         entity_name: str,
         transactions: dict[str, float] | None,
-        table_accessor: Literal["litellm_tagtable", "litellm_agentstable", "litellm_modelaccessgroupbudgettable"],
+        table_accessor: _EntitySpendTable,
         where_field: str,
         n_retry_times: int,
         prisma_client: PrismaClient,
@@ -1784,7 +1798,7 @@ class DBSpendUpdateWriter:
                                     entity_id,
                                     response_cost,
                                 )
-                                getattr(batcher, table_accessor).update_many(
+                                _entity_spend_table(batcher, table_accessor).update_many(
                                     where={where_field: entity_id},
                                     data={"spend": {"increment": response_cost}},
                                 )
diff --git a/litellm/proxy/guardrails/guardrail_hooks/akto/akto.py b/litellm/proxy/guardrails/guardrail_hooks/akto/akto.py
index 2c27531cea1..a7f45a37ae6 100644
--- a/litellm/proxy/guardrails/guardrail_hooks/akto/akto.py
+++ b/litellm/proxy/guardrails/guardrail_hooks/akto/akto.py
@@ -11,10 +11,11 @@ import asyncio
 import json
 import os
 from datetime import datetime
-from typing import TYPE_CHECKING, Any, Final, Literal
+from typing import TYPE_CHECKING, Final, Literal
 
 import httpx
 from fastapi import HTTPException
+from typing_extensions import NotRequired, ReadOnly, TypedDict, Unpack
 
 from litellm._logging import verbose_proxy_logger
 from litellm.integrations.custom_guardrail import (
@@ -25,12 +26,34 @@ from litellm.llms.custom_httpx.http_handler import (
     get_async_httpx_client,
     httpxSpecialProvider,
 )
-from litellm.types.guardrails import GuardrailEventHooks
+from litellm.types.guardrails import GuardrailEventHooks, Mode
 from litellm.types.utils import GenericGuardrailAPIInputs
 
 if TYPE_CHECKING:
     from litellm.types.proxy.guardrails.guardrail_hooks.base import GuardrailConfigModel
 
+
+class _CustomGuardrailKwargs(TypedDict):
+    """Keyword arguments forwarded verbatim to CustomGuardrail.__init__."""
+
+    guardrail_name: NotRequired[ReadOnly[str | None]]
+    event_hook: NotRequired[ReadOnly[GuardrailEventHooks | list[GuardrailEventHooks] | Mode | None]]
+    default_on: NotRequired[ReadOnly[bool]]
+    mask_request_content: NotRequired[ReadOnly[bool]]
+    mask_response_content: NotRequired[ReadOnly[bool]]
+    violation_message_template: NotRequired[ReadOnly[str | None]]
+    end_session_after_n_fails: NotRequired[ReadOnly[int | None]]
+    on_violation: NotRequired[ReadOnly[str | None]]
+    realtime_violation_message: NotRequired[ReadOnly[str | None]]
+    on_sensitive_data: NotRequired[ReadOnly[str | None]]
+    sensitive_data_route_to_model: NotRequired[ReadOnly[str | None]]
+    sticky_session_routing: NotRequired[ReadOnly[bool]]
+    run_in_parallel: NotRequired[ReadOnly[bool]]
+    scan_raw_request: NotRequired[ReadOnly[bool]]
+    only_scan_new_messages: NotRequired[ReadOnly[bool]]
+    supported_event_hooks: NotRequired[ReadOnly[list[GuardrailEventHooks]]]
+
+
 HTTP_PROXY_PATH: Final = "/api/http-proxy"
 AKTO_CONNECTOR_NAME: Final = "litellm"
 DEFAULT_GUARDRAIL_TIMEOUT: Final = 5
@@ -66,7 +89,7 @@ class AktoGuardrail(CustomGuardrail):
         akto_vxlan_id: str | None = None,
         unreachable_fallback: Literal["fail_closed", "fail_open"] = "fail_closed",
         guardrail_timeout: int | None = None,
-        **kwargs: Any,
+        **kwargs: Unpack[_CustomGuardrailKwargs],
     ) -> None:
         """Initialize the Akto guardrail.
 
@@ -96,8 +119,11 @@ class AktoGuardrail(CustomGuardrail):
         self.akto_account_id = akto_account_id or os.environ.get("AKTO_ACCOUNT_ID", "1000000")
         self.akto_vxlan_id = akto_vxlan_id or os.environ.get("AKTO_VXLAN_ID", "0")
 
-        kwargs["supported_event_hooks"] = list(self.get_supported_event_hooks())
-        super().__init__(**kwargs)
+        init_kwargs: Final[_CustomGuardrailKwargs] = {
+            **kwargs,
+            "supported_event_hooks": list(self.get_supported_event_hooks()),
+        }
+        super().__init__(**init_kwargs)
 
         verbose_proxy_logger.debug(
             "Akto guardrail initialized: base_url=%s fallback=%s",
diff --git a/litellm/proxy/guardrails/guardrail_hooks/custom_code/custom_code_guardrail.py b/litellm/proxy/guardrails/guardrail_hooks/custom_code/custom_code_guardrail.py
index d5ef1e949b8..252b94b76c8 100644
--- a/litellm/proxy/guardrails/guardrail_hooks/custom_code/custom_code_guardrail.py
+++ b/litellm/proxy/guardrails/guardrail_hooks/custom_code/custom_code_guardrail.py
@@ -38,9 +38,10 @@ import asyncio
 import threading
 import time
 from collections.abc import Callable, Mapping
-from typing import TYPE_CHECKING, Any, Final, Literal, Optional, cast
+from typing import TYPE_CHECKING, Final, Literal, Optional, cast
 
 from fastapi import HTTPException
+from typing_extensions import TypedDict, Unpack
 
 from litellm._logging import verbose_proxy_logger
 from litellm.exceptions import ModifyResponseException
@@ -74,6 +75,10 @@ class CustomCodeExecutionError(CustomCodeGuardrailError):
     """Raised when custom code fails during execution."""
 
 
+class _CustomGuardrailOptions(TypedDict, total=False, extra_items=object):
+    """Base-class constructor options this guardrail forwards untouched to CustomGuardrail."""
+
+
 class CustomCodeGuardrailConfigModel(GuardrailConfigModel):
     """Configuration parameters for the custom code guardrail."""
 
@@ -109,7 +114,7 @@ class CustomCodeGuardrail(CustomGuardrail):
         self,
         custom_code: str,
         guardrail_name: str | None = "custom_code",
-        **kwargs: Any,
+        **kwargs: Unpack[_CustomGuardrailOptions],
     ) -> None:
         """
         Initialize the custom code guardrail.
diff --git a/litellm/proxy/guardrails/guardrail_hooks/lasso/lasso.py b/litellm/proxy/guardrails/guardrail_hooks/lasso/lasso.py
index cf5da27e9ca..63821428c62 100644
--- a/litellm/proxy/guardrails/guardrail_hooks/lasso/lasso.py
+++ b/litellm/proxy/guardrails/guardrail_hooks/lasso/lasso.py
@@ -121,7 +121,7 @@ class LassoGuardrail(CustomGuardrail):
         super().__init__(**kwargs)
 
     @staticmethod
-    def _get_field(obj: Any, field: str, default: object = None) -> Any:
+    def _get_field(obj: object, field: str, default: object = None) -> object:
         """Get a field from either a dict or a Pydantic object."""
         if isinstance(obj, dict):
             return obj.get(field, default)
@@ -130,7 +130,7 @@ class LassoGuardrail(CustomGuardrail):
     @staticmethod
     def _extract_tool_call_fields(
         call: object,
-    ) -> tuple[str | None, str | None, dict[str, object] | None]:
+    ) -> tuple[object, object, dict[str, object] | None]:
         """Extract (call_id, name, parsed_input) from a tool call.
 
         Handles both dict-style and Pydantic object-style tool_calls.
@@ -146,7 +146,7 @@ class LassoGuardrail(CustomGuardrail):
         input_data: dict[str, object] | None = None
         if args_str:
             try:
-                parsed = json.loads(args_str)
+                parsed = json.loads(args_str) if isinstance(args_str, (str, bytes, bytearray)) else None
             except (json.JSONDecodeError, TypeError):
                 parsed = None
             if isinstance(parsed, dict):
@@ -488,7 +488,7 @@ class LassoGuardrail(CustomGuardrail):
         while preserving the original structure.
         """
         # Index masked content by type so we can look up by id without caring about order.
-        masked_tool_use: Final[dict[str, dict[str, object]]] = {}
+        masked_tool_use: Final[dict[object, dict[str, object]]] = {}
         masked_tool_result: Final[dict[str, str]] = {}
         masked_text: Final[list[str]] = []
 
@@ -565,7 +565,7 @@ class LassoGuardrail(CustomGuardrail):
     def _update_tool_calls_from_masked(
         self,
         tool_calls: list[object],
-        masked_tool_use: dict[str, dict[str, object]],
+        masked_tool_use: Mapping[object, Mapping[str, object]],
     ) -> list[object]:
         """Replace tool_call arguments with masked values returned by Lasso."""
         updated: Final = []
@@ -922,7 +922,7 @@ class LassoGuardrail(CustomGuardrail):
     ) -> None:
         """Apply masking to the actual model response when mask=True and masked content is available."""
         # Index masked tool_use blocks by id for O(1) lookup.
-        masked_tool_use: Final[dict[str, dict[str, object]]] = {}
+        masked_tool_use: Final[dict[object, dict[str, object]]] = {}
         masked_text: Final[list[str]] = []
         for masked_msg in masked_messages:
             content = masked_msg.get("content")
diff --git a/litellm/proxy/guardrails/guardrail_hooks/vigil_guard/vigil_guard.py b/litellm/proxy/guardrails/guardrail_hooks/vigil_guard/vigil_guard.py
index a5945a39589..e807da7079e 100644
--- a/litellm/proxy/guardrails/guardrail_hooks/vigil_guard/vigil_guard.py
+++ b/litellm/proxy/guardrails/guardrail_hooks/vigil_guard/vigil_guard.py
@@ -3,7 +3,7 @@ from json import JSONDecodeError
 from typing import TYPE_CHECKING, Any, Final, Literal, Optional, Protocol, TypeAlias, cast
 
 import httpx
-from typing_extensions import ReadOnly, TypedDict
+from typing_extensions import ReadOnly, TypedDict, Unpack
 
 from litellm._logging import verbose_proxy_logger
 from litellm.exceptions import GuardrailRaisedException
@@ -18,7 +18,8 @@ from litellm.llms.custom_httpx.http_handler import (
 )
 from litellm.secret_managers.main import get_secret_str
 from litellm.types.guardrails import GuardrailEventHooks
-from litellm.types.utils import GenericGuardrailAPIInputs
+from litellm.types.llms.openai import ChatCompletionToolCallChunk
+from litellm.types.utils import ChatCompletionMessageToolCall, GenericGuardrailAPIInputs
 
 if TYPE_CHECKING:
     from litellm.litellm_core_utils.litellm_logging import (
@@ -53,6 +54,7 @@ _METADATA_ALLOWLIST: Final = (
 
 _FallbackMode: TypeAlias = Literal["fail_closed", "fail_open"]
 _MetadataValue: TypeAlias = str | int | float | Sequence[str | int | float]
+_ToolCalls: TypeAlias = list[ChatCompletionToolCallChunk] | list[ChatCompletionMessageToolCall]
 
 
 class _AnalyzePayload(TypedDict):
@@ -70,6 +72,12 @@ class _AnalysisView(TypedDict):
     analysis: ReadOnly[Mapping[str, object]]
 
 
+class _CustomGuardrailOptions(TypedDict, total=False, extra_items=object):
+    """Base-class constructor options this guardrail forwards untouched to CustomGuardrail."""
+
+    supported_event_hooks: ReadOnly[list[GuardrailEventHooks]]
+
+
 class _AsyncPostHandler(Protocol):
     def post(
         self,
@@ -93,7 +101,7 @@ class VigilGuardGuardrail(CustomGuardrail):
         unreachable_fallback: str | None = None,
         timeout: float | None = None,
         async_handler: _AsyncPostHandler | None = None,
-        **kwargs: Any,
+        **kwargs: Unpack[_CustomGuardrailOptions],
     ) -> None:
         resolved_base: Final = api_base or get_secret_str("VIGIL_GUARD_URL")
         if not resolved_base:
@@ -122,9 +130,12 @@ class VigilGuardGuardrail(CustomGuardrail):
             llm_provider=httpxSpecialProvider.GuardrailCallback,
         )
 
-        kwargs.setdefault("supported_event_hooks", list(self.get_supported_event_hooks()))
+        forwarded: Final[_CustomGuardrailOptions] = {
+            "supported_event_hooks": list(self.get_supported_event_hooks()),
+            **kwargs,
+        }
 
-        super().__init__(**kwargs)
+        super().__init__(**forwarded)
 
     @staticmethod
     def get_config_model() -> type["GuardrailConfigModel"] | None:
@@ -264,7 +275,7 @@ class VigilGuardGuardrail(CustomGuardrail):
         inputs: GenericGuardrailAPIInputs,
         source: str,
         final_texts: list[str],
-        final_tool_calls: Any,
+        final_tool_calls: _ToolCalls | None,
     ) -> GenericGuardrailAPIInputs:
         if self.unreachable_fallback == "fail_open":
             verbose_proxy_logger.error(
diff --git a/litellm/proxy/guardrails/guardrail_hooks/xecguard/xecguard.py b/litellm/proxy/guardrails/guardrail_hooks/xecguard/xecguard.py
index 831df43692b..f4330ad6aa9 100644
--- a/litellm/proxy/guardrails/guardrail_hooks/xecguard/xecguard.py
+++ b/litellm/proxy/guardrails/guardrail_hooks/xecguard/xecguard.py
@@ -196,9 +196,9 @@ class XecGuardGuardrail(CustomGuardrail):
     async def async_logging_hook(
         self,
         kwargs: dict,
-        result: Any,
+        result: object,
         call_type: str,
-    ) -> tuple[dict, Any]:
+    ) -> tuple[dict, object]:
         """Observe-only scan for logging_only mode.
 
         Never blocks, never raises - all errors are swallowed. Records a
@@ -275,9 +275,9 @@ class XecGuardGuardrail(CustomGuardrail):
     def logging_hook(
         self,
         kwargs: dict,
-        result: Any,
+        result: object,
         call_type: str,
-    ) -> tuple[dict, Any]:
+    ) -> tuple[dict, object]:
         """Sync counterpart to ``async_logging_hook``.
 
         Runs the async version on an available loop, swallowing every
@@ -433,7 +433,7 @@ class XecGuardGuardrail(CustomGuardrail):
         return {"role": role, "content": ""}
 
     @staticmethod
-    def _synthesize_user_from_inputs(inputs: Any) -> dict | None:
+    def _synthesize_user_from_inputs(inputs: object) -> dict | None:
         if not isinstance(inputs, dict):
             return None
         texts: Final = inputs.get("texts")
@@ -490,7 +490,7 @@ class XecGuardGuardrail(CustomGuardrail):
         return None
 
     @staticmethod
-    def _content_to_text(content: Any) -> str | None:
+    def _content_to_text(content: object) -> str | None:
         if isinstance(content, str) and content:
             return content
         if isinstance(content, list):
diff --git a/litellm/proxy/management_endpoints/model_management_endpoints.py b/litellm/proxy/management_endpoints/model_management_endpoints.py
index 2234e825090..50a498cf9bf 100644
--- a/litellm/proxy/management_endpoints/model_management_endpoints.py
+++ b/litellm/proxy/management_endpoints/model_management_endpoints.py
@@ -455,7 +455,6 @@ async def _auto_router_capability_slot(
 
 
 ENFORCE_RPM_TPM_ON_MODEL_ADD_SETTING: Final = "enforce_rpm_tpm_on_model_add"
-_REQUIRED_RATE_LIMIT_FIELDS: Final = ("rpm", "tpm")
 
 
 def _raise_if_rate_limits_required_but_missing(*, litellm_params: GenericLiteLLMParams, enforced: bool) -> None:
@@ -470,8 +469,8 @@ def _raise_if_rate_limits_required_but_missing(*, litellm_params: GenericLiteLLM
         return
     missing: Final = tuple(
         field
-        for field in _REQUIRED_RATE_LIMIT_FIELDS
-        if (value := getattr(litellm_params, field)) is None or value <= 0
+        for field, value in (("rpm", litellm_params.rpm), ("tpm", litellm_params.tpm))
+        if value is None or value <= 0
     )
     if not missing:
         return
diff --git a/litellm/proxy/pass_through_endpoints/llm_provider_handlers/vertex_passthrough_logging_handler.py b/litellm/proxy/pass_through_endpoints/llm_provider_handlers/vertex_passthrough_logging_handler.py
index 119a53c2411..ce44596c19c 100644
--- a/litellm/proxy/pass_through_endpoints/llm_provider_handlers/vertex_passthrough_logging_handler.py
+++ b/litellm/proxy/pass_through_endpoints/llm_provider_handlers/vertex_passthrough_logging_handler.py
@@ -28,6 +28,7 @@ from litellm.proxy.pass_through_endpoints.llm_provider_handlers.batch_attributio
     optional_str,
     request_tags_from_metadata,
 )
+from litellm.types.passthrough_endpoints.pass_through_endpoints import EndpointType
 from litellm.types.utils import (
     Choices,
     EmbeddingResponse,
@@ -47,8 +48,6 @@ else:
     PassThroughEndpointLogging = Any
     LiteLLMBatch = Any
 
-EndpointType = Any
-
 
 class VertexPassthroughLoggingHandler:
     @staticmethod
diff --git a/litellm/proxy/response_api_endpoints/endpoints.py b/litellm/proxy/response_api_endpoints/endpoints.py
index 5907ffc64eb..7f618526f11 100644
--- a/litellm/proxy/response_api_endpoints/endpoints.py
+++ b/litellm/proxy/response_api_endpoints/endpoints.py
@@ -1357,7 +1357,7 @@ async def _read_ws_model_from_first_frame(
     return model, first_message
 
 
-def _extract_model_from_first_ws_event(first_event: Any) -> str | None:
+def _extract_model_from_first_ws_event(first_event: object) -> str | None:
     """Extract model from a response.create WS event, handling flat and nested formats.
 
     Flat:   {"type": "response.create", "model": "gpt-4o", ...}
diff --git a/litellm/proxy/video_endpoints/endpoints.py b/litellm/proxy/video_endpoints/endpoints.py
index 66071c05b4f..fe966c2e31a 100644
--- a/litellm/proxy/video_endpoints/endpoints.py
+++ b/litellm/proxy/video_endpoints/endpoints.py
@@ -89,7 +89,7 @@ async def video_generation(
     # Process request using ProxyBaseLLMRequestProcessing
     processor: Final = ProxyBaseLLMRequestProcessing(data=data)
     try:
-        return await processor.base_process_llm_request(
+        generated: Final[object] = await processor.base_process_llm_request(
             request=request,
             fastapi_response=fastapi_response,
             user_api_key_dict=user_api_key_dict,
@@ -114,6 +114,8 @@ async def video_generation(
             proxy_logging_obj=proxy_logging_obj,
             version=version,
         )
+    else:
+        return generated
 
 
 @router.get(
@@ -174,7 +176,7 @@ async def video_list(
     # Process request using ProxyBaseLLMRequestProcessing
     processor: Final = ProxyBaseLLMRequestProcessing(data=data)
     try:
-        return await processor.base_process_llm_request(
+        listed: Final[object] = await processor.base_process_llm_request(
             request=request,
             fastapi_response=fastapi_response,
             user_api_key_dict=user_api_key_dict,
@@ -199,6 +201,8 @@ async def video_list(
             proxy_logging_obj=proxy_logging_obj,
             version=version,
         )
+    else:
+        return listed
 
 
 @router.get(
@@ -272,7 +276,7 @@ async def video_status(
     # Process request using ProxyBaseLLMRequestProcessing
     processor: Final = ProxyBaseLLMRequestProcessing(data=data)
     try:
-        return await processor.base_process_llm_request(
+        status: Final[object] = await processor.base_process_llm_request(
             request=request,
             fastapi_response=fastapi_response,
             user_api_key_dict=user_api_key_dict,
@@ -297,6 +301,8 @@ async def video_status(
             proxy_logging_obj=proxy_logging_obj,
             version=version,
         )
+    else:
+        return status
 
 
 @router.get(
@@ -478,7 +484,7 @@ async def video_remix(
     # Process request using ProxyBaseLLMRequestProcessing
     processor: Final = ProxyBaseLLMRequestProcessing(data=data)
     try:
-        return await processor.base_process_llm_request(
+        remixed: Final[object] = await processor.base_process_llm_request(
             request=request,
             fastapi_response=fastapi_response,
             user_api_key_dict=user_api_key_dict,
@@ -503,6 +509,8 @@ async def video_remix(
             proxy_logging_obj=proxy_logging_obj,
             version=version,
         )
+    else:
+        return remixed
 
 
 @router.post(
@@ -571,7 +579,7 @@ async def video_create_character(
 
     processor: Final = ProxyBaseLLMRequestProcessing(data=data)
     try:
-        response = await processor.base_process_llm_request(
+        response: object = await processor.base_process_llm_request(
             request=request,
             fastapi_response=fastapi_response,
             user_api_key_dict=user_api_key_dict,
@@ -678,7 +686,7 @@ async def video_get_character(
 
     processor: Final = ProxyBaseLLMRequestProcessing(data=data)
     try:
-        response = await processor.base_process_llm_request(
+        response: object = await processor.base_process_llm_request(
             request=request,
             fastapi_response=fastapi_response,
             user_api_key_dict=user_api_key_dict,
@@ -789,7 +797,7 @@ async def video_edit(
 
     processor: Final = ProxyBaseLLMRequestProcessing(data=data)
     try:
-        return await processor.base_process_llm_request(
+        edited: Final[object] = await processor.base_process_llm_request(
             request=request,
             fastapi_response=fastapi_response,
             user_api_key_dict=user_api_key_dict,
@@ -814,6 +822,8 @@ async def video_edit(
             proxy_logging_obj=proxy_logging_obj,
             version=version,
         )
+    else:
+        return edited
 
 
 @router.post(
@@ -884,7 +894,7 @@ async def video_extension(
 
     processor: Final = ProxyBaseLLMRequestProcessing(data=data)
     try:
-        return await processor.base_process_llm_request(
+        extended: Final[object] = await processor.base_process_llm_request(
             request=request,
             fastapi_response=fastapi_response,
             user_api_key_dict=user_api_key_dict,
@@ -909,3 +919,5 @@ async def video_extension(
             proxy_logging_obj=proxy_logging_obj,
             version=version,
         )
+    else:
+        return extended
diff --git a/litellm/responses/mcp/litellm_proxy_mcp_handler.py b/litellm/responses/mcp/litellm_proxy_mcp_handler.py
index a5021e2f777..c4bbf8c8b25 100644
--- a/litellm/responses/mcp/litellm_proxy_mcp_handler.py
+++ b/litellm/responses/mcp/litellm_proxy_mcp_handler.py
@@ -1266,14 +1266,14 @@ class LiteLLM_Proxy_MCP_Handler:
         return tool_execution_events
 
     @staticmethod
-    def _prepare_initial_call_params(call_params: dict[str, Any], should_auto_execute: bool) -> dict[str, Any]:
+    def _prepare_initial_call_params(call_params: Mapping[str, object], should_auto_execute: bool) -> dict[str, Any]:
         """
         Prepare call parameters for the initial LLM call.
 
         For auto-execute scenarios, we need to disable streaming for the initial call
         so we can process the tool calls before streaming the final response.
         """
-        initial_params: Final = call_params.copy()
+        initial_params: Final = dict(call_params)
 
         if should_auto_execute:
             # Disable streaming for initial call when auto-executing tools
@@ -1282,14 +1282,16 @@ class LiteLLM_Proxy_MCP_Handler:
         return initial_params
 
     @staticmethod
-    def _prepare_follow_up_call_params(call_params: dict[str, Any], original_stream_setting: bool) -> dict[str, Any]:
+    def _prepare_follow_up_call_params(
+        call_params: Mapping[str, object], original_stream_setting: bool
+    ) -> dict[str, Any]:
         """
         Prepare call parameters for the follow-up LLM call after tool execution.
 
         Restores the original streaming setting and removes tool_choice since
         we're now providing tool results, not requesting tool calls.
         """
-        follow_up_params: Final = call_params.copy()
+        follow_up_params: Final = dict(call_params)
 
         # Restore original streaming setting for follow-up call
         follow_up_params["stream"] = original_stream_setting
diff --git a/litellm/responses/streaming_iterator.py b/litellm/responses/streaming_iterator.py
index 40ff88fc557..e1cf7847972 100644
--- a/litellm/responses/streaming_iterator.py
+++ b/litellm/responses/streaming_iterator.py
@@ -2353,7 +2353,7 @@ class ManagedResponsesWebSocketHandler:
             await self.websocket.send_text(serialized)
 
     @staticmethod
-    def _build_base_call_kwargs(msg_obj: _MutableJsonObject) -> dict[str, Any]:
+    def _build_base_call_kwargs(msg_obj: _MutableJsonObject) -> dict[str, object]:
         """
         Extract Responses API params from the event, handling both wire formats:
           Nested: {"type": "response.create", "response": {"input": [...], ...}}
diff --git a/litellm/router_strategy/complexity_router/complexity_router.py b/litellm/router_strategy/complexity_router/complexity_router.py
index 9deccc9a468..eea0b2ec564 100644
--- a/litellm/router_strategy/complexity_router/complexity_router.py
+++ b/litellm/router_strategy/complexity_router/complexity_router.py
@@ -363,7 +363,7 @@ def _append_custom_keywords(base_keywords: list[str], custom_keywords: list[str]
     return [*base_keywords, *deduped_custom.values()]
 
 
-def _parent_session_kwargs(request_kwargs: Mapping[str, Any] | None) -> Mapping[str, Any]:
+def _parent_session_kwargs(request_kwargs: Mapping[str, object] | None) -> Mapping[str, Any]:
     kwargs: Final = request_kwargs or {}
     return {k: kwargs[k] for k in ("litellm_session_id", "litellm_trace_id") if kwargs.get(k) is not None}
 
@@ -1165,7 +1165,7 @@ class ComplexityRouter(CustomLogger):
         self,
         model_name: str,
         litellm_router_instance: Router,
-        complexity_router_config: dict[str, Any] | None = None,
+        complexity_router_config: Mapping[str, object] | None = None,
         default_model: str | None = None,
         derive_savings_baseline: bool = True,
     ):
@@ -1736,7 +1736,7 @@ class ComplexityRouter(CustomLogger):
         self,
         prompt: str,
         system_prompt: str | None,
-        request_kwargs: dict[str, Any] | None,  # mutable-ok: handed to _classify_with_llm as-is
+        request_kwargs: dict[str, object] | None,  # mutable-ok: handed to _classify_with_llm as-is
         messages: Sequence[Mapping[str, object]] | None,
     ) -> ClassificationOutcome:
         """Score locally, and only pay for the classifier call when the scorer did not confidently
@@ -1769,7 +1769,7 @@ class ComplexityRouter(CustomLogger):
         self,
         prompt: str,
         system_prompt: str | None,
-        request_kwargs: dict[str, Any] | None,  # mutable-ok: handed to _classify_with_llm as-is
+        request_kwargs: dict[str, object] | None,  # mutable-ok: handed to _classify_with_llm as-is
         messages: Sequence[Mapping[str, object]] | None,
     ) -> ClassificationOutcome:
         """Score locally, and only pay for the classifier when the score sits near a tier boundary.
@@ -1824,7 +1824,7 @@ class ComplexityRouter(CustomLogger):
         self,
         prompt: str,
         system_prompt: str | None,
-        request_kwargs: dict[str, Any] | None,  # mutable-ok: handed to _classify_with_llm as-is
+        request_kwargs: dict[str, object] | None,  # mutable-ok: handed to _classify_with_llm as-is
         messages: Sequence[Mapping[str, object]] | None,
         scored: ClassificationOutcome | None = None,
     ) -> ClassificationOutcome:
@@ -1902,8 +1902,8 @@ class ComplexityRouter(CustomLogger):
         self,
         prompt: str,
         system_prompt: str | None,
-        request_kwargs: dict[str, Any] | None,  # mutable-ok: handed to resolve_structured_messages as-is
-        raw_messages: list[dict[str, Any]] | None,  # mutable-ok: same shape _run_routing_plugins receives
+        request_kwargs: dict[str, object] | None,  # mutable-ok: handed to resolve_structured_messages as-is
+        raw_messages: list[dict[str, object]] | None,  # mutable-ok: same shape _run_routing_plugins receives
     ) -> ClassificationOutcome:
         from litellm.litellm_core_utils.prompt_templates.factory import resolve_structured_messages
         from litellm.types.router import RoutingContext
@@ -2262,8 +2262,8 @@ class ComplexityRouter(CustomLogger):
     async def _pick_model_for_tier(
         self,
         tier: ComplexityTier | str,
-        raw_messages: list[dict[str, Any]] | None,
-        resolved_messages: list[dict[str, Any]] | None,
+        raw_messages: list[dict[str, object]] | None,
+        resolved_messages: list[dict[str, object]] | None,
         request_kwargs: dict,
         allowed_models: tuple[str, ...] | None = None,
     ) -> str:
@@ -2373,7 +2373,7 @@ class ComplexityRouter(CustomLogger):
         self,
         classified_tier: ComplexityTier | str,
         user_message: str,
-        request_kwargs: dict[str, Any] | None = None,
+        request_kwargs: dict[str, object] | None = None,
         hard_floor: ComplexityTier | str | None = None,
         hard_ceiling: ComplexityTier | str | None = None,
         fit_filter: frozenset[str] | None = None,
@@ -2903,7 +2903,7 @@ class ComplexityRouter(CustomLogger):
     async def _gate_response_modality(
         self,
         response: PreRoutingHookResponse,
-        messages: list[dict[str, Any]] | None,  # mutable-ok: forwarded verbatim to the list-typed re-pick
+        messages: list[dict[str, object]] | None,  # mutable-ok: forwarded verbatim to the list-typed re-pick
         resolved_messages: Sequence[Mapping[str, object]] | None,
         request_kwargs: dict,  # mutable-ok: same shape the hook receives
         context_fit: _RequestContextFit | None = None,
@@ -3093,7 +3093,7 @@ class ComplexityRouter(CustomLogger):
     async def _gate_response_health(
         self,
         response: PreRoutingHookResponse,
-        messages: list[dict[str, Any]] | None,  # mutable-ok: forwarded verbatim to the list-typed re-pick
+        messages: list[dict[str, object]] | None,  # mutable-ok: forwarded verbatim to the list-typed re-pick
         input: str | list | None,  # mutable-ok: mirrors the owner's own input parameter, which this forwards verbatim
         resolved_messages: Sequence[Mapping[str, object]] | None,
         request_kwargs: dict,  # mutable-ok: same shape the hook receives
@@ -3405,9 +3405,9 @@ class ComplexityRouter(CustomLogger):
 
     def _resolve_messages(
         self,
-        messages: list[dict[str, Any]] | None,
+        messages: list[dict[str, object]] | None,
         request_kwargs: dict,
-    ) -> list[dict[str, Any]] | None:
+    ) -> list[dict[str, object]] | None:
         """
         Resolve messages from the request, converting from other formats if needed.
 
@@ -3422,7 +3422,7 @@ class ComplexityRouter(CustomLogger):
 
     @staticmethod
     def _extract_user_message_and_system_prompt(
-        messages: list[dict[str, Any]],
+        messages: Sequence[Mapping[str, object]],
     ) -> tuple[str | None, str | None]:
         """
         Deprecated: use _extract_current_ask_and_system_prompt instead.
@@ -3729,7 +3729,7 @@ class ComplexityRouter(CustomLogger):
         self,
         model: str,
         request_kwargs: dict,
-        messages: list[dict[str, Any]] | None = None,
+        messages: list[dict[str, object]] | None = None,
         input: str | list | None = None,
         specific_deployment: bool | None = False,
         conversation_continuing: bool = True,
diff --git a/litellm/types/router.py b/litellm/types/router.py
index c7363502017..f0d2405c88f 100644
--- a/litellm/types/router.py
+++ b/litellm/types/router.py
@@ -248,7 +248,7 @@ class ModelInfo(MirroredPricingParams):
         # Custom .get() method to access attributes with a default value if the attribute doesn't exist
         return getattr(self, key, default)
 
-    def __getitem__(self, key):
+    def __getitem__(self, key) -> object:
         # Allow dictionary-style access to attributes
         return getattr(self, key)
 
@@ -358,7 +358,7 @@ class GenericLiteLLMParams(CredentialLiteLLMParams, CustomPricingLiteLLMParams):
     model_config = ConfigDict(extra="allow", arbitrary_types_allowed=True)
     merge_reasoning_content_in_choices: bool | None = False
     model_info: dict | None = None
-    mock_response: str | ModelResponse | Exception | Any | None = None
+    mock_response: str | ModelResponse | Exception | object | None = None
 
     # tag-based routing
     tags: list[str] | None = None
@@ -435,7 +435,7 @@ class GenericLiteLLMParams(CredentialLiteLLMParams, CustomPricingLiteLLMParams):
         # Custom .get() method to access attributes with a default value if the attribute doesn't exist
         return getattr(self, key, default)
 
-    def __getitem__(self, key):
+    def __getitem__(self, key) -> object:
         # Allow dictionary-style access to attributes
         return getattr(self, key)
 
@@ -460,7 +460,7 @@ class LiteLLM_Params(GenericLiteLLMParams):
         # Custom .get() method to access attributes with a default value if the attribute doesn't exist
         return getattr(self, key, default)
 
-    def __getitem__(self, key):
+    def __getitem__(self, key) -> object:
         # Allow dictionary-style access to attributes
         return getattr(self, key)
 
@@ -1043,11 +1043,11 @@ class RoutingContext(BaseModel):
     plugins that need the exact original payload can read `raw_messages`.
     """
 
-    raw_messages: list[dict[str, Any]]
-    structured_messages: list[dict[str, Any]]
+    raw_messages: list[dict[str, object]]
+    structured_messages: list[dict[str, object]]
     candidate_models: list[str]
-    metadata: dict[str, Any] = Field(default_factory=dict)
-    signals: dict[str, Any] = Field(default_factory=dict)
+    metadata: dict[str, object] = Field(default_factory=dict)
+    signals: dict[str, object] = Field(default_factory=dict)
 
 
 @runtime_checkable
diff --git a/litellm/vector_stores/vector_store_registry.py b/litellm/vector_stores/vector_store_registry.py
index b71d6784873..c7aed77286c 100644
--- a/litellm/vector_stores/vector_store_registry.py
+++ b/litellm/vector_stores/vector_store_registry.py
@@ -112,9 +112,8 @@ class VectorStoreRegistry:
         Dynamically extracts all parameters defined in VECTOR_STORE_OPENAI_PARAMS.
         """
         # Get the list of supported param names from the Literal type
-        supported_params: Final = tuple(
-            param for param in get_args(VECTOR_STORE_OPENAI_PARAMS) if isinstance(param, str)
-        )
+        declared_params: Final[tuple[object, ...]] = get_args(VECTOR_STORE_OPENAI_PARAMS)
+        supported_params: Final = tuple(param for param in declared_params if isinstance(param, str))
 
         # Extract only the params that exist in the tool
         kwargs: Final = {param: tool.get(param) for param in supported_params if param in tool}

From 6e2c088bc265d17ae31a8924e0f1494d291f6cf5 Mon Sep 17 00:00:00 2001
From: mateo-berri <277851410+mateo-berri@users.noreply.github.com>
Date: Mon, 14 Sep 2026 11:13:42 +0000
Subject: [PATCH 10/55] chore(ui): regenerate dashboard API types

Picks up the user-endpoint docstring removal already on main.
---
 ui/litellm-dashboard/src/lib/http/schema.d.ts | 2 --
 1 file changed, 2 deletions(-)

diff --git a/ui/litellm-dashboard/src/lib/http/schema.d.ts b/ui/litellm-dashboard/src/lib/http/schema.d.ts
index 7eadaa6c991..839aa52fa84 100644
--- a/ui/litellm-dashboard/src/lib/http/schema.d.ts
+++ b/ui/litellm-dashboard/src/lib/http/schema.d.ts
@@ -16781,7 +16781,6 @@ export interface paths {
          *     - permissions: Optional[dict] - [Not Implemented Yet] User-specific permissions, eg. turning off pii masking.
          *     - metadata: Optional[dict] - Metadata for user, store information for user. Example metadata = {"team": "core-infra", "app": "app2", "email": "ishaan@berri.ai" }
          *     - max_parallel_requests: Optional[int] - Rate limit a user based on the number of parallel requests. Raises 429 error, if user's parallel requests > x.
-         *     - soft_budget: Optional[float] - Get alerts when user crosses given budget, doesn't block requests.
          *     - model_max_budget: Optional[dict] - Model-specific max budget for user. [Docs](https://docs.litellm.ai/docs/proxy/users#add-model-specific-budgets-to-keys)
          *     - budget_fallbacks: Optional[Dict[str, List[str]]] - Per-model fallback chain tried in order when that model's own `model_max_budget` is exceeded, e.g. {"gpt-4o": ["gpt-4o-mini"]}.
          *     - model_rpm_limit: Optional[float] - Model-specific rpm limit for user. [Docs](https://docs.litellm.ai/docs/proxy/users#add-model-specific-limits-to-keys)
@@ -16887,7 +16886,6 @@ export interface paths {
          *         - permissions: Optional[dict] - [Not Implemented Yet] User-specific permissions, eg. turning off pii masking.
          *         - metadata: Optional[dict] - Metadata for user, store information for user. Example metadata = {"team": "core-infra", "app": "app2", "email": "ishaan@berri.ai" }
          *         - max_parallel_requests: Optional[int] - Rate limit a user based on the number of parallel requests. Raises 429 error, if user's parallel requests > x.
-         *         - soft_budget: Optional[float] - Get alerts when user crosses given budget, doesn't block requests.
          *         - model_max_budget: Optional[dict] - Model-specific max budget for user. [Docs](https://docs.litellm.ai/docs/proxy/users#add-model-specific-budgets-to-keys)
          *         - budget_fallbacks: Optional[Dict[str, List[str]]] - Per-model fallback chain tried in order when that model's own `model_max_budget` is exceeded, e.g. {"gpt-4o": ["gpt-4o-mini"]}.
          *         - model_rpm_limit: Optional[float] - Model-specific rpm limit for user. [Docs](https://docs.litellm.ai/docs/proxy/users#add-model-specific-limits-to-keys)

From bbee8692a80bf2be2a917c88fb3fb2ba76b4e5a3 Mon Sep 17 00:00:00 2001
From: Tejas Chopra <tejas@Tejass-MacBook-Pro.local>
Date: Wed, 16 Sep 2026 21:27:45 -0700
Subject: [PATCH 11/55] fix(responses): stop agentic follow-up from passing
 request params twice

---
 litellm/llms/custom_httpx/llm_http_handler.py | 22 +++++-----
 .../custom_httpx/test_llm_http_handler.py     | 44 +++++++++++++++++++
 2 files changed, 56 insertions(+), 10 deletions(-)

diff --git a/litellm/llms/custom_httpx/llm_http_handler.py b/litellm/llms/custom_httpx/llm_http_handler.py
index 2fe4130a310..b4f2a74b3e6 100644
--- a/litellm/llms/custom_httpx/llm_http_handler.py
+++ b/litellm/llms/custom_httpx/llm_http_handler.py
@@ -5573,17 +5573,19 @@ class BaseLLMHTTPHandler:
 
         internal_keys: Final = {"litellm_logging_obj"}
         kwargs_for_followup: Final = {
-            k: v
-            for k, v in kwargs.items()
-            if not is_interception_internal_key(k, prefixes=NON_CODE_INTERPRETER_INTERCEPTION_INTERNAL_PREFIXES)
-            and k != "_code_interpreter_interception_converted_stream"
-            and k not in internal_keys
-            and k not in optional_params
+            **{
+                k: v
+                for k, v in kwargs.items()
+                if not is_interception_internal_key(k, prefixes=NON_CODE_INTERPRETER_INTERCEPTION_INTERNAL_PREFIXES)
+                and k != "_code_interpreter_interception_converted_stream"
+                and k not in internal_keys
+                and k not in optional_params
+            },
+            **{k: v for k, v in patch.kwargs.items() if k not in optional_params},
+            "_agentic_loop_depth": depth + 1,
+            "max_agentic_loops": max_loops,
+            "_agentic_loop_fingerprints": fingerprints + [fingerprint],
         }
-        kwargs_for_followup.update(patch.kwargs)
-        kwargs_for_followup["_agentic_loop_depth"] = depth + 1
-        kwargs_for_followup["max_agentic_loops"] = max_loops
-        kwargs_for_followup["_agentic_loop_fingerprints"] = fingerprints + [fingerprint]
 
         try:
             response: ResponsesAPIResponse | BaseResponsesAPIStreamingIterator = await litellm.aresponses(
diff --git a/tests/test_litellm/llms/custom_httpx/test_llm_http_handler.py b/tests/test_litellm/llms/custom_httpx/test_llm_http_handler.py
index c39779972c0..5d6060c7666 100644
--- a/tests/test_litellm/llms/custom_httpx/test_llm_http_handler.py
+++ b/tests/test_litellm/llms/custom_httpx/test_llm_http_handler.py
@@ -3713,3 +3713,47 @@ def test_image_edit_handler_keeps_the_sync_transform():
     assert config.transform_calls == ["sync"]
     assert captured["body"] == {"transformed_by": "sync"}
     assert response.data[0].b64_json == "sync"
+
+
+@pytest.mark.asyncio
+async def test_responses_agentic_followup_does_not_repeat_request_params_from_plan_kwargs(monkeypatch):
+    """A plan whose kwargs repeat a request param must not crash the Responses follow-up with a duplicate keyword"""
+    from litellm.integrations.custom_logger import CustomLogger
+    from litellm.types.integrations.custom_logger import AgenticLoopPlan, AgenticLoopRequestPatch
+
+    followup_calls: list[dict[str, object]] = []
+
+    async def fake_aresponses(**kwargs: object) -> str:
+        followup_calls.append(kwargs)
+        return "followup-response"
+
+    monkeypatch.setattr(litellm, "aresponses", fake_aresponses)
+    request_kwargs: Final = {"prompt_cache_key": "thread-1", "metadata": {"user": "u1"}}
+    plan: Final = AgenticLoopPlan(
+        run_agentic_loop=True,
+        request_patch=AgenticLoopRequestPatch(
+            model="gpt-5",
+            messages=[{"role": "user", "content": "x"}],
+            optional_params={"prompt_cache_key": "thread-1"},
+            kwargs=dict(request_kwargs),
+        ),
+    )
+
+    response: Final = await BaseLLMHTTPHandler()._execute_responses_agentic_plan(
+        plan=plan,
+        model="gpt-5",
+        response_api_optional_request_params={"prompt_cache_key": "thread-1"},
+        logging_obj=Mock(litellm_call_id="call-1"),
+        kwargs=dict(request_kwargs),
+        depth=0,
+        max_loops=3,
+        fingerprints=[],
+        fingerprint="fp",
+        callback=CustomLogger(),
+    )
+
+    assert response == "followup-response"
+    assert len(followup_calls) == 1
+    assert followup_calls[0]["prompt_cache_key"] == "thread-1"
+    assert followup_calls[0]["metadata"] == {"user": "u1"}
+    assert followup_calls[0]["_agentic_loop_depth"] == 1

From 067514bc76794fc3f9a66b9083f1cf52e6728427 Mon Sep 17 00:00:00 2001
From: Tejas Chopra <tejas@Tejass-MacBook-Pro.local>
Date: Wed, 16 Sep 2026 21:33:26 -0700
Subject: [PATCH 12/55] fix(responses): patch custom_tool_call_output in place
 on guardrail write-back

---
 .../guardrail_translation/handler.py          |  2 +-
 ...test_openai_responses_guardrail_handler.py | 50 +++++++++++++++++++
 2 files changed, 51 insertions(+), 1 deletion(-)

diff --git a/litellm/llms/openai/responses/guardrail_translation/handler.py b/litellm/llms/openai/responses/guardrail_translation/handler.py
index 1ab4811b8a0..9739ca95089 100644
--- a/litellm/llms/openai/responses/guardrail_translation/handler.py
+++ b/litellm/llms/openai/responses/guardrail_translation/handler.py
@@ -209,7 +209,7 @@ _TOOL_CALL_PAYLOAD_EVENT_TYPES: Final = _TOOL_CALL_PAYLOAD_DELTA_EVENT_TYPES | f
 )
 _OUTPUT_ITEM_EVENT_TYPES: Final = frozenset({"response.output_item.added", "response.output_item.done"})
 _PATCHABLE_ITEM_FIELDS: Final[Mapping[str, str]] = MappingProxyType(
-    {"function_call_output": "output", "message": "content"}
+    {"function_call_output": "output", "custom_tool_call_output": "output", "message": "content"}
 )
 
 _EMPTY_RESPONSES_REQUEST: Final[ResponsesAPIOptionalRequestParams] = {}
diff --git a/tests/test_litellm/llms/openai/responses/test_openai_responses_guardrail_handler.py b/tests/test_litellm/llms/openai/responses/test_openai_responses_guardrail_handler.py
index c714b5d378a..ea58a48a3d5 100644
--- a/tests/test_litellm/llms/openai/responses/test_openai_responses_guardrail_handler.py
+++ b/tests/test_litellm/llms/openai/responses/test_openai_responses_guardrail_handler.py
@@ -2223,6 +2223,56 @@ class TestStructuredMessagesWriteBack:
         }
         assert result["input"][3] == {"role": "user", "content": "What is the codename?"}
 
+    @pytest.mark.asyncio
+    async def test_codex_custom_tool_items_survive_tool_output_compression(self):
+        handler = OpenAIResponsesHandler()
+        additional_tools_item = {
+            "type": "additional_tools",
+            "tools": [{"type": "custom", "name": "exec", "description": "Run a JavaScript snippet"}],
+        }
+        reasoning_item = {
+            "id": "rs_456",
+            "type": "reasoning",
+            "summary": [],
+            "encrypted_content": "gAAAAA-signed-reasoning",
+        }
+        custom_tool_call_item = {
+            "id": "ctc_456",
+            "type": "custom_tool_call",
+            "call_id": "call_exec",
+            "name": "exec",
+            "input": 'const r = await tools.exec_command({"cmd": "cat memo.txt"});\ntext(r.output);',
+            "status": "completed",
+        }
+        data = {
+            "model": "gpt-5.6",
+            "input": [
+                additional_tools_item,
+                {"role": "user", "content": "What is the codename?"},
+                reasoning_item,
+                custom_tool_call_item,
+                {
+                    "type": "custom_tool_call_output",
+                    "call_id": "call_exec",
+                    "output": [
+                        {"type": "input_text", "text": "Script completed\nOutput:\n"},
+                        {"type": "input_text", "text": "memo " * 400},
+                    ],
+                },
+            ],
+        }
+
+        result = await handler.process_input_messages(data, ToolOutputRewriteGuardrail())
+
+        assert result["input"][0] is additional_tools_item
+        assert result["input"][1] == {"role": "user", "content": "What is the codename?"}
+        assert result["input"][2] is reasoning_item
+        assert result["input"][3] is custom_tool_call_item
+        assert result["input"][4]["type"] == "custom_tool_call_output"
+        assert result["input"][4]["call_id"] == "call_exec"
+        assert COMPRESSED_MARKER in str(result["input"][4]["output"])
+        assert len(result["input"]) == 5
+
     @pytest.mark.asyncio
     async def test_web_search_call_item_preserved_verbatim(self):
         handler = OpenAIResponsesHandler()

From 3298b416878ec8b2d409b47799f76e4f9bcbc0f7 Mon Sep 17 00:00:00 2001
From: Tejas Chopra <tejas@Tejass-MacBook-Pro.local>
Date: Wed, 16 Sep 2026 21:44:10 -0700
Subject: [PATCH 13/55] refactor(responses): build agentic follow-up kwargs as
 one frozen mapping

---
 litellm/llms/custom_httpx/llm_http_handler.py | 38 ++++++++++++-------
 1 file changed, 24 insertions(+), 14 deletions(-)

diff --git a/litellm/llms/custom_httpx/llm_http_handler.py b/litellm/llms/custom_httpx/llm_http_handler.py
index b4f2a74b3e6..50420ab3301 100644
--- a/litellm/llms/custom_httpx/llm_http_handler.py
+++ b/litellm/llms/custom_httpx/llm_http_handler.py
@@ -4,6 +4,7 @@ import ssl
 from collections.abc import AsyncIterator, Coroutine, Iterator, Mapping, Sequence
 from contextlib import asynccontextmanager
 from functools import lru_cache
+from itertools import chain
 from types import MappingProxyType, ModuleType
 from typing import TYPE_CHECKING, Any, Final, Literal, Optional, TypedDict, TypeVar, Union, cast, get_type_hints
 from urllib.parse import parse_qs, urlencode, urlparse, urlunparse
@@ -5572,20 +5573,29 @@ class BaseLLMHTTPHandler:
         }
 
         internal_keys: Final = {"litellm_logging_obj"}
-        kwargs_for_followup: Final = {
-            **{
-                k: v
-                for k, v in kwargs.items()
-                if not is_interception_internal_key(k, prefixes=NON_CODE_INTERPRETER_INTERCEPTION_INTERNAL_PREFIXES)
-                and k != "_code_interpreter_interception_converted_stream"
-                and k not in internal_keys
-                and k not in optional_params
-            },
-            **{k: v for k, v in patch.kwargs.items() if k not in optional_params},
-            "_agentic_loop_depth": depth + 1,
-            "max_agentic_loops": max_loops,
-            "_agentic_loop_fingerprints": fingerprints + [fingerprint],
-        }
+        kwargs_for_followup: Final = MappingProxyType(
+            {
+                key: value
+                for key, value in chain(
+                    (
+                        (k, v)
+                        for k, v in kwargs.items()
+                        if not is_interception_internal_key(
+                            k, prefixes=NON_CODE_INTERPRETER_INTERCEPTION_INTERNAL_PREFIXES
+                        )
+                        and k != "_code_interpreter_interception_converted_stream"
+                        and k not in internal_keys
+                        and k not in optional_params
+                    ),
+                    ((k, v) for k, v in patch.kwargs.items() if k not in optional_params),
+                    (
+                        ("_agentic_loop_depth", depth + 1),
+                        ("max_agentic_loops", max_loops),
+                        ("_agentic_loop_fingerprints", fingerprints + [fingerprint]),
+                    ),
+                )
+            }
+        )
 
         try:
             response: ResponsesAPIResponse | BaseResponsesAPIStreamingIterator = await litellm.aresponses(

From 3fe405a5ccdf568ce16d82bd08c4b98e936909bf Mon Sep 17 00:00:00 2001
From: ryan <ryan@berri.ai>
Date: Mon, 21 Sep 2026 18:48:35 +0000
Subject: [PATCH 14/55] feat(auth): breached password detection, self-service
 change-password and forced password reset

Cherry-pick of merge commit b3882d8e43 (PRs #39321, #39562, #40107), which landed on litellm_internal_staging instead of main.

Co-authored-by: ojensen-berri <ojensen@berri.ai>
Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
 .../migration.sql                             |   3 +
 .../litellm_proxy_extras/schema.prisma        |   2 +
 litellm/constants.py                          |   3 +
 litellm/models/user.py                        |   2 +
 litellm/proxy/_types.py                       |  31 +-
 litellm/proxy/auth/login_utils.py             |  87 ++-
 litellm/proxy/auth/password_policy.py         | 128 +++-
 litellm/proxy/auth/route_checks.py            |  27 +-
 .../internal_user_endpoints.py                |  62 +-
 .../password_endpoints.py                     | 126 ++++
 litellm/proxy/management_endpoints/ui_sso.py  |   1 +
 litellm/proxy/proxy_server.py                 |  16 +-
 litellm/proxy/schema.prisma                   |   2 +
 litellm/types/llms/custom_http.py             |   1 +
 litellm/types/proxy/ui_sso.py                 |   3 +-
 schema.prisma                                 |   2 +
 .../endpointaudit/coverage_allowlist.txt      |   1 +
 .../proxy/auth/test_login_utils.py            | 272 ++++++++
 .../proxy/auth/test_onboarding.py             | 144 +++-
 .../proxy/auth/test_password_policy.py        | 209 ++++++
 .../proxy/auth/test_route_checks.py           | 274 +++++---
 .../test_internal_user_endpoints.py           | 623 ++++++++----------
 .../test_password_endpoints.py                | 331 ++++++++++
 tests/test_litellm/proxy/test__types.py       |  42 ++
 tests/unit/models/test_models.py              |   6 +-
 .../ChangePasswordForm.integration.test.tsx   | 110 ++++
 .../change-password/ChangePasswordForm.tsx    | 120 ++++
 .../app/(dashboard)/change-password/page.tsx  |   7 +
 .../app/(dashboard)/hooks/useAuthorized.ts    |   2 +
 .../src/app/(dashboard)/layout.test.tsx       |  58 +-
 .../src/app/(dashboard)/layout.tsx            |  13 +-
 .../Navbar/UserDropdown/UserDropdown.test.tsx |  52 +-
 .../Navbar/UserDropdown/UserDropdown.tsx      |  23 +-
 .../SidebarAccountMenu.test.tsx               |  43 ++
 .../SidebarAccountMenu/SidebarAccountMenu.tsx |  24 +-
 .../src/components/leftnav.test.tsx           |   1 +
 .../src/components/networking.tsx             |  14 +
 .../src/contexts/AuthContext.tsx              |   4 +
 ui/litellm-dashboard/src/lib/http/schema.d.ts |  90 ++-
 39 files changed, 2456 insertions(+), 503 deletions(-)
 create mode 100644 litellm-proxy-extras/litellm_proxy_extras/migrations/20260921000000_add_password_reset_columns/migration.sql
 create mode 100644 litellm/proxy/management_endpoints/password_endpoints.py
 create mode 100644 tests/test_litellm/proxy/management_endpoints/test_password_endpoints.py
 create mode 100644 ui/litellm-dashboard/src/app/(dashboard)/change-password/ChangePasswordForm.integration.test.tsx
 create mode 100644 ui/litellm-dashboard/src/app/(dashboard)/change-password/ChangePasswordForm.tsx
 create mode 100644 ui/litellm-dashboard/src/app/(dashboard)/change-password/page.tsx

diff --git a/litellm-proxy-extras/litellm_proxy_extras/migrations/20260921000000_add_password_reset_columns/migration.sql b/litellm-proxy-extras/litellm_proxy_extras/migrations/20260921000000_add_password_reset_columns/migration.sql
new file mode 100644
index 00000000000..960b0d4d7eb
--- /dev/null
+++ b/litellm-proxy-extras/litellm_proxy_extras/migrations/20260921000000_add_password_reset_columns/migration.sql
@@ -0,0 +1,3 @@
+ALTER TABLE "LiteLLM_UserTable" ADD COLUMN IF NOT EXISTS "password_reset_required" BOOLEAN;
+
+ALTER TABLE "LiteLLM_UserTable" ADD COLUMN IF NOT EXISTS "last_breach_check_at" TIMESTAMP(3);
diff --git a/litellm-proxy-extras/litellm_proxy_extras/schema.prisma b/litellm-proxy-extras/litellm_proxy_extras/schema.prisma
index d2032cec0d0..bcafa6dbd0e 100644
--- a/litellm-proxy-extras/litellm_proxy_extras/schema.prisma
+++ b/litellm-proxy-extras/litellm_proxy_extras/schema.prisma
@@ -246,6 +246,8 @@ model LiteLLM_UserTable {
     organization_id String?
     object_permission_id String?
     password  String?
+    password_reset_required Boolean?
+    last_breach_check_at DateTime?
     teams    String[] @default([])
     user_role  String?
 		max_budget Float?
diff --git a/litellm/constants.py b/litellm/constants.py
index bbeb4846e27..b5b3647e525 100644
--- a/litellm/constants.py
+++ b/litellm/constants.py
@@ -2114,3 +2114,6 @@ BATCH_ENQUEUED_TOKEN_LIMIT_METADATA_KEY: Final = "batch_enqueued_token_limit"
 # Shared read-only empty mapping, for defaulting optional Mapping parameters without
 # constructing a fresh mutable dict at each call site.
 EMPTY_MAPPING: Final = MappingProxyType({})
+
+# API endpoint for breached password k-anonymity search
+HIBP_RANGE_API_BASE: Final = "https://api.pwnedpasswords.com/range"
diff --git a/litellm/models/user.py b/litellm/models/user.py
index 82f78c28078..92aca87d303 100644
--- a/litellm/models/user.py
+++ b/litellm/models/user.py
@@ -24,6 +24,8 @@ class LiteLLM_UserTable(LiteLLMPydanticObjectBase):
     organization_id: str | None = None
     object_permission_id: str | None = None
     password: str | None = Field(default=None, exclude=True)
+    password_reset_required: bool | None = None
+    last_breach_check_at: datetime | None = None
     teams: list[str] = []
     user_role: str | None = None
     max_budget: float | None = None
diff --git a/litellm/proxy/_types.py b/litellm/proxy/_types.py
index 3b34440d0bf..16b405d8e02 100644
--- a/litellm/proxy/_types.py
+++ b/litellm/proxy/_types.py
@@ -904,6 +904,7 @@ class LiteLLMRoutes(enum.Enum):
         "/claude_code_gateway/v1/traces",
         "/user/list",  # org admins checked in endpoint; non-admins get 403
         "/management/v1/users/bulk_delete",  # proxy admins delete anyone, org admins only their orgs' users; others 403
+        "/user/password/change",  # endpoint only ever writes the caller's own row
         "/model/{model_id}/update",
         "/prompt/list",
         "/prompt/info",
@@ -1864,6 +1865,17 @@ class NewUserRequest(GenerateRequestBase):
     send_invite_email: bool | None = None
     sso_user_id: str | None = None
     organizations: list[str] | None = None
+    password: str | None = None
+
+    @field_validator("password")
+    @classmethod
+    def password_not_supported(cls, value: str | None) -> str | None:
+        if value is not None:
+            raise ValueError(
+                "password cannot be set via /user/new. Users set their own password through an "
+                "invitation link (POST /invitation/new)."
+            )
+        return value
 
 
 class NewUserResponse(GenerateKeyResponse):
@@ -1886,7 +1898,8 @@ class NewUserResponse(GenerateKeyResponse):
 
 
 class UpdateUserRequestNoUserIDorEmail(GenerateRequestBase):  # shared with BulkUpdateUserRequest
-    password: str | None = None
+    # repr=False keeps the plaintext out of management-endpoint alerts, which str() the request model
+    password: str | None = Field(default=None, repr=False)
     spend: float | None = None
     metadata: dict | None = None
     user_alias: str | None = None
@@ -1916,6 +1929,16 @@ class UpdateUserRequest(UpdateUserRequestNoUserIDorEmail):
         return values
 
 
+class ChangePasswordRequest(LiteLLMPydanticObjectBase):
+    current_password: str = Field(repr=False)
+    new_password: str = Field(repr=False)
+
+
+class ChangePasswordResponse(LiteLLMPydanticObjectBase):
+    user_id: str
+    message: str
+
+
 class DeleteUserRequest(LiteLLMPydanticObjectBase):
     user_ids: list[str]  # required
 
@@ -3937,6 +3960,12 @@ class AllCallbacks(LiteLLMPydanticObjectBase):
     )
 
 
+class HTTPExceptionErrorDetail(TypedDict):
+    """The `{"error": <message>}` shape most proxy endpoints raise as `HTTPException.detail`."""
+
+    error: ReadOnly[str]
+
+
 class SpendLogsRouterMetadata(TypedDict):
     """
     Router provenance stamped on spend logs for deployments flagged with
diff --git a/litellm/proxy/auth/login_utils.py b/litellm/proxy/auth/login_utils.py
index e0d599b0017..0dddb16b531 100644
--- a/litellm/proxy/auth/login_utils.py
+++ b/litellm/proxy/auth/login_utils.py
@@ -10,14 +10,16 @@ import secrets
 from collections.abc import Mapping
 from datetime import datetime, timedelta, timezone
 from types import MappingProxyType
-from typing import Final, Literal, cast
+from typing import TYPE_CHECKING, Final, Literal, cast
 
 import jwt
 from fastapi import HTTPException
 
 import litellm
+from litellm._logging import verbose_proxy_logger
 from litellm.constants import LITELLM_PROXY_ADMIN_NAME, LITELLM_UI_SESSION_DURATION
 from litellm.litellm_core_utils.duration_parser import duration_in_seconds
+from litellm.llms.custom_httpx.http_handler import AsyncHTTPHandler
 from litellm.proxy._types import (
     LiteLLM_UserTable,
     LitellmUserRoles,
@@ -28,6 +30,7 @@ from litellm.proxy._types import (
 )
 from litellm.proxy.auth.auth_utils import is_sso_provider_fully_configured
 from litellm.proxy.auth.login_throttle import LoginAttempt, LoginThrottle
+from litellm.proxy.auth.password_policy import is_breach_check_enabled, is_password_breached
 from litellm.proxy.management_endpoints.internal_user_endpoints import user_update
 from litellm.proxy.management_endpoints.key_management_endpoints import (
     generate_key_helper_fn,
@@ -50,6 +53,56 @@ INVALID_UI_CREDENTIALS_MESSAGE: Final = (
 )
 INVALID_USER_PASSWORD_MESSAGE: Final = "Invalid credentials used to access UI. Check the password set for your user"
 
+if TYPE_CHECKING:
+    from prisma import types as prisma_types
+
+BREACH_RECHECK_INTERVAL: Final = timedelta(hours=24)
+PASSWORD_RESET_ALLOWED_ROUTES: Final = ("/user/password/change",)
+
+
+def _breach_recheck_due(last_breach_check_at: datetime | None) -> bool:
+    if last_breach_check_at is None:
+        return True
+    last_checked_utc: Final = (
+        last_breach_check_at
+        if last_breach_check_at.tzinfo is not None
+        else last_breach_check_at.replace(tzinfo=timezone.utc)
+    )
+    return datetime.now(timezone.utc) - last_checked_utc >= BREACH_RECHECK_INTERVAL
+
+
+async def screen_login_password_for_breach(
+    user_id: str,
+    password: str,
+    last_breach_check_at: datetime | None,
+    general_settings: Mapping[str, object],
+    prisma_client: PrismaClient,
+    client: AsyncHTTPHandler | None = None,
+) -> bool:
+    """Screens a successfully verified login password against HIBP, stamps
+    ``password_reset_required`` when breached, and returns whether a breach was
+    found so the login it runs in can restrict the session it is about to mint.
+    Fails open (HIBP or DB trouble never fails the login) and rechecks a given
+    user at most once per ``BREACH_RECHECK_INTERVAL``."""
+    if not is_breach_check_enabled(general_settings):
+        return False
+    if not _breach_recheck_due(last_breach_check_at):
+        return False
+    breached: Final = await is_password_breached(password, general_settings, client)
+    checked_at: Final = datetime.now(timezone.utc)
+    breached_update: Final[prisma_types.LiteLLM_UserTableUpdateInput] = {
+        "last_breach_check_at": checked_at,
+        "password_reset_required": True,
+    }
+    recheck_update: Final[prisma_types.LiteLLM_UserTableUpdateInput] = {"last_breach_check_at": checked_at}
+    update_data: Final = breached_update if breached else recheck_update
+    find_user: Final[prisma_types.LiteLLM_UserTableWhereInput] = {"user_id": user_id}
+    try:
+        await UserRepository(prisma_client).table.update(where=find_user, data=update_data)
+    except Exception as e:  # noqa: BLE001  # a failed stamp must never surface into the login
+        verbose_proxy_logger.warning("Login-time breach screening could not update user %s: %s", user_id, e)
+    return breached
+
 
 async def _rehash_password_if_needed(user_id: str, password: str, stored: str) -> None:
     """Rehash legacy password (SHA256) to scrypt on successful login."""
@@ -137,6 +190,7 @@ class LoginResult:
     user_email: str | None
     user_role: str
     login_method: Literal["sso", "username_password"]
+    password_reset_required: bool
 
     def __init__(
         self,
@@ -145,12 +199,14 @@ class LoginResult:
         user_email: str | None,
         user_role: str,
         login_method: Literal["sso", "username_password"] = "username_password",
+        password_reset_required: bool = False,
     ):
         self.user_id = user_id
         self.key = key
         self.user_email = user_email
         self.user_role = user_role
         self.login_method = login_method
+        self.password_reset_required = password_reset_required
 
 
 async def authenticate_user(
@@ -356,21 +412,26 @@ async def _sign_in(
 
         if verify_password(password, _password):
             await _rehash_password_if_needed(_user_row.user_id, password, _password)
+            breached_now: Final = prisma_client is not None and await screen_login_password_for_breach(
+                user_id=_user_row.user_id,
+                password=password,
+                last_breach_check_at=getattr(_user_row, "last_breach_check_at", None),
+                general_settings=general_settings,
+                prisma_client=prisma_client,
+            )
+            password_reset_required: Final = breached_now or getattr(_user_row, "password_reset_required", None) is True
             if os.getenv("DATABASE_URL") is not None:
                 response = await generate_key_helper_fn(
                     llm_router=None,
                     request_type="key",
-                    **{
-                        "user_role": user_role,
-                        "duration": LITELLM_UI_SESSION_DURATION,
-                        "key_max_budget": litellm.max_ui_session_budget,
-                        "models": [],
-                        "aliases": {},
-                        "config": {},
-                        "spend": 0,
-                        "user_id": user_id,
-                        "team_id": "litellm-dashboard",
-                    },
+                    user_role=user_role,
+                    duration=LITELLM_UI_SESSION_DURATION,
+                    key_max_budget=litellm.max_ui_session_budget,
+                    spend=0,
+                    user_id=user_id,
+                    team_id="litellm-dashboard",
+                    allowed_routes=list(PASSWORD_RESET_ALLOWED_ROUTES) if password_reset_required else None,
+                    metadata={"password_reset_required": True} if password_reset_required else {},
                 )
             else:
                 raise ProxyException(
@@ -390,6 +451,7 @@ async def _sign_in(
                 user_email=user_email,
                 user_role=cast(str, user_role),
                 login_method="username_password",
+                password_reset_required=password_reset_required,
             )
         else:
             await attempt.failed()
@@ -460,4 +522,5 @@ def create_ui_token_object(
         auth_header_name=general_settings.get("litellm_key_header_name", "Authorization"),
         disabled_non_admin_personal_key_creation=disabled_non_admin_personal_key_creation,
         server_root_path=get_server_root_path(),
+        password_reset_required=login_result.password_reset_required,
     )
diff --git a/litellm/proxy/auth/password_policy.py b/litellm/proxy/auth/password_policy.py
index ab7a565894a..7f06a0993d3 100644
--- a/litellm/proxy/auth/password_policy.py
+++ b/litellm/proxy/auth/password_policy.py
@@ -4,13 +4,28 @@ Applied at every path that persists a new or changed password for a DB-backed
 user (``/user/update``, ``/user/bulk_update``, and the invitation onboarding
 claim flow), so the strength bar is configured in one place instead of
 per-endpoint.
+
+Also screens new passwords against known data breaches via the
+haveibeenpwned.com (HIBP) k-anonymity range API: only the first 5 characters
+of the password's SHA-1 hash ever leave the proxy, and the check fails open
+(allows the password) when HIBP is unreachable.
 """
 
-from collections.abc import Mapping
+import asyncio
+import hashlib
+from collections.abc import Mapping, Sequence
 from dataclasses import dataclass
+from types import MappingProxyType
 from typing import Final
 
+from litellm._logging import verbose_proxy_logger
+from litellm._version import version
+from litellm.constants import HIBP_RANGE_API_BASE
+from litellm.llms.custom_httpx.http_handler import AsyncHTTPHandler, get_async_httpx_client
 from litellm.proxy._types import ProxyErrorTypes, ProxyException
+from litellm.types.llms.custom_http import httpxSpecialProvider
+
+HIBP_TIMEOUT_SECONDS: Final = 5.0
 
 DEFAULT_MIN_LENGTH: Final = 12
 MIN_ALLOWED_LENGTH: Final = 8
@@ -90,3 +105,114 @@ def validate_password_policy(password: str, general_settings: Mapping[str, objec
         param="password",
         code=400,
     )
+
+
+def _hibp_client() -> AsyncHTTPHandler:
+    return get_async_httpx_client(
+        llm_provider=httpxSpecialProvider.PasswordBreachCheck,
+        params={"timeout": HIBP_TIMEOUT_SECONDS},  # mutable-ok: callee takes a bare dict (PEP 589)
+    )
+
+
+def _is_suffix_in_range_response(response_body: str, hash_suffix: str) -> bool:
+    for line in response_body.upper().splitlines():
+        entry_suffix, _, count = line.strip().partition(":")
+        if entry_suffix == hash_suffix:
+            return int(count.strip() or "0") > 0
+    return False
+
+
+async def _is_password_breached(password: str, client: AsyncHTTPHandler) -> bool:
+    # usedforsecurity=False: SHA-1 is only a lookup key into the HIBP dataset, so no security property rests on it
+    sha1_hex: Final = hashlib.sha1(password.encode("utf-8"), usedforsecurity=False).hexdigest().upper()
+    headers: Final = {  # mutable-ok: callee takes a bare dict (PEP 589)
+        "Add-Padding": "true",
+        "User-Agent": f"litellm-proxy/{version}",
+    }
+    try:
+        response: Final = await client.get(
+            f"{HIBP_RANGE_API_BASE}/{sha1_hex[:5]}",
+            headers=headers,
+        )
+        response.raise_for_status()
+        breached: Final = _is_suffix_in_range_response(response.text, sha1_hex[5:])
+    except Exception as e:  # noqa: BLE001  # fail-open: any HIBP failure skips the check, never breaks the caller
+        verbose_proxy_logger.warning("Breached-password check skipped, HIBP lookup failed: %s", e)
+        return False
+    return breached
+
+
+def is_breach_check_enabled(general_settings: Mapping[str, object]) -> bool:
+    return general_settings.get("password_policy_check_breached_passwords", True) is not False
+
+
+async def is_password_breached(
+    password: str,
+    general_settings: Mapping[str, object],
+    client: AsyncHTTPHandler | None = None,
+) -> bool:
+    """False when the check is disabled, the password is absent from the HIBP
+    corpus, or HIBP is unreachable (fail open)."""
+    if not is_breach_check_enabled(general_settings):
+        return False
+    return await _is_password_breached(password, client if client is not None else _hibp_client())
+
+
+def breached_password_error() -> ProxyException:
+    return ProxyException(
+        message=(
+            "This password appears in known data breaches and cannot be used. Please choose a different password."
+        ),
+        type=ProxyErrorTypes.validation_error,
+        param="password",
+        code=400,
+    )
+
+
+async def validate_password_not_breached(
+    password: str,
+    general_settings: Mapping[str, object],
+    client: AsyncHTTPHandler | None = None,
+) -> None:
+    """Raise ``ProxyException`` (400) if ``password`` appears in a known data breach.
+
+    Fails open: an unreachable or misbehaving HIBP allows the password."""
+    if not await is_password_breached(password, general_settings, client):
+        return
+    raise breached_password_error()
+
+
+def _strength_verdict(password: str, general_settings: Mapping[str, object]) -> ProxyException | None:
+    try:
+        validate_password_policy(password, general_settings)
+    except ProxyException as e:
+        return e
+    return None
+
+
+async def validate_passwords_bulk(
+    passwords: Sequence[str],
+    general_settings: Mapping[str, object],
+    client: AsyncHTTPHandler | None = None,
+) -> Mapping[str, ProxyException | None]:
+    """Per-unique-password policy verdicts for a batch: the ProxyException to
+    surface, or None when the password is acceptable.
+
+    Deduplicates first, then issues every needed HIBP lookup concurrently, so a
+    batch caller pays one HIBP timeout window in the worst case instead of one
+    per password (each lookup still fails open independently)."""
+    unique_passwords: Final = tuple(dict.fromkeys(passwords))
+    strength_verdicts: Final[Mapping[str, ProxyException | None]] = MappingProxyType(
+        {password: _strength_verdict(password, general_settings) for password in unique_passwords}
+    )
+    to_screen: Final = tuple(password for password in unique_passwords if strength_verdicts[password] is None)
+    breached_flags: Final = await asyncio.gather(
+        *(is_password_breached(password, general_settings, client) for password in to_screen)
+    )
+    breached_passwords: Final = frozenset(password for password, breached in zip(to_screen, breached_flags) if breached)
+    return MappingProxyType(
+        {
+            password: breached_password_error() if password in breached_passwords else strength_verdicts[password]
+            for password in unique_passwords
+        }
+    )
diff --git a/litellm/proxy/auth/route_checks.py b/litellm/proxy/auth/route_checks.py
index 1b9fd7c42bf..afddb4866a9 100644
--- a/litellm/proxy/auth/route_checks.py
+++ b/litellm/proxy/auth/route_checks.py
@@ -194,6 +194,16 @@ class RouteChecks:
         if denied_auth_enforced_pass_through_route:
             raise RouteChecks._auth_pass_through_denied_exception(route=route)
 
+        if valid_token.metadata.get("password_reset_required") is True:
+            raise HTTPException(
+                status_code=status.HTTP_403_FORBIDDEN,
+                detail=(
+                    "This account's password must be changed before the session can be used: "
+                    "it was either found in a known data breach or set by an admin. "
+                    "Change it via POST /user/password/change (UI: /ui/change-password), then log in again."
+                ),
+            )
+
         raise HTTPException(
             status_code=status.HTTP_403_FORBIDDEN,
             detail=f"Virtual key is not allowed to call this route. Only allowed to call routes: {valid_token.allowed_routes}. Tried to call route: {route}",
@@ -812,7 +822,8 @@ class RouteChecks:
              in the codebase is automatically readable by Admin Viewer
              without needing to remember to add it to an allowlist.
           3. Unsafe HTTP method (POST/PUT/PATCH/DELETE):
-             - Allow `/user/update` only when restricted to user_email/password.
+             - Allow `/user/update` only when restricted to user_email.
+             - Allow `/user/password/change` (endpoint only writes the caller's own row).
              - Block all explicit writes in `_ADMIN_VIEWER_BLOCKED_WRITE_ROUTES`.
              - Otherwise allow only if the route is in admin_viewer_routes /
                global_spend_tracking_routes (legacy explicit-allow set).
@@ -832,10 +843,10 @@ class RouteChecks:
                 if request_data is not None and isinstance(request_data, dict):
                     _params_updated: Final = request_data.keys()
                     for param in _params_updated:
-                        if param not in ["user_email", "password"]:
+                        if param != "user_email":
                             raise HTTPException(
                                 status_code=status.HTTP_403_FORBIDDEN,
-                                detail=f"user not allowed to access this route, role= {_user_role}. Trying to access: {route} and updating invalid param: {param}. only user_email and password can be updated",
+                                detail=f"user not allowed to access this route, role= {_user_role}. Trying to access: {route} and updating invalid param: {param}. only user_email can be updated",
                             )
             elif RouteChecks.check_route_access(route=route, allowed_routes=_PROXY_ADMIN_VIEW_ONLY_BLOCKED_ROUTES) or (
                 route.startswith("/key/") and route.endswith(_PROXY_ADMIN_VIEW_ONLY_BLOCKED_KEY_SUFFIXES)
@@ -854,21 +865,25 @@ class RouteChecks:
             return
 
         # ── Unsafe HTTP method: explicit checks ──────────────────────────
-        # Allow `/user/update` for self-service email / password change.
+        # Allow `/user/update` for self-service email change.
         if route == "/user/update":
             if request_data is not None and isinstance(request_data, dict):
                 for param in request_data:
-                    if param not in ["user_email", "password"]:
+                    if param != "user_email":
                         raise HTTPException(
                             status_code=status.HTTP_403_FORBIDDEN,
                             detail=(
                                 f"user not allowed to access this route, role= {_user_role}. "
                                 f"Trying to access: {route} and updating invalid param: {param}. "
-                                "only user_email and password can be updated"
+                                "only user_email can be updated"
                             ),
                         )
             return
 
+        # Self-service password change; the endpoint only writes the caller's own row.
+        if route == "/user/password/change":
+            return
+
         # Hard-block known write routes regardless of HTTP method (defensive
         # — these are POSTs in practice, but pinning them here protects
         # against future GET-shaped writes).
diff --git a/litellm/proxy/management_endpoints/internal_user_endpoints.py b/litellm/proxy/management_endpoints/internal_user_endpoints.py
index 1c986305c21..285be23bdf6 100644
--- a/litellm/proxy/management_endpoints/internal_user_endpoints.py
+++ b/litellm/proxy/management_endpoints/internal_user_endpoints.py
@@ -28,6 +28,7 @@ from typing_extensions import ReadOnly, TypedDict
 import litellm
 from litellm._logging import verbose_proxy_logger
 from litellm._uuid import uuid
+from litellm.llms.custom_httpx.http_handler import AsyncHTTPHandler
 from litellm.proxy._types import *
 from litellm.proxy.auth.auth_checks import (
     delete_cache_key_objects,
@@ -35,7 +36,11 @@ from litellm.proxy.auth.auth_checks import (
     get_team_object,
     get_user_object,
 )
-from litellm.proxy.auth.password_policy import validate_password_policy
+from litellm.proxy.auth.password_policy import (
+    validate_password_not_breached,
+    validate_password_policy,
+    validate_passwords_bulk,
+)
 from litellm.proxy.auth.user_api_key_auth import user_api_key_auth
 from litellm.proxy.common_utils.auth_cache_invalidation_pubsub import evict_and_broadcast
 from litellm.proxy.common_utils.user_api_key_cache import (
@@ -173,11 +178,23 @@ def _team_membership_table(
     return team_membership_table
 
 
-def _hash_password_in_dict(data: dict, general_settings: Mapping[str, object]) -> None:
-    """Validate and hash password field in-place if present."""
+async def _hash_password_in_dict(
+    data: dict, general_settings: Mapping[str, object], password_prevalidated: bool = False
+) -> None:
+    """Validate and hash password field in-place if present.
+
+    ``password_prevalidated`` skips the policy checks for callers that already
+    validated the password (the bulk path screens its whole batch upfront).
+
+    An admin-set password is known to whoever set it, so the user is also
+    flagged for a forced password change at next login."""
     if "password" in data and data["password"] is not None:
-        validate_password_policy(data["password"], general_settings)
+        if not password_prevalidated:
+            validate_password_policy(data["password"], general_settings)
+            await validate_password_not_breached(data["password"], general_settings)
         data["password"] = hash_password(data["password"])
+        data["password_reset_required"] = True
+        data["last_breach_check_at"] = None
 
 
 def _strip_password_from_response(response) -> None:
@@ -505,6 +522,7 @@ async def new_user(
     - prompts: Optional[List[str]] - List of allowed prompts for the user. If specified, the user will only be able to use these specific prompts.
     - organizations: List[str] - List of organization id's the user is a member of
     - budget_limits: Optional[list] - List of concurrent budget windows for the user. Each window specifies a budget_limit, time_period, and optional budget_duration. Example - [{"budget_limit": 10.0, "time_period": "1d"}, {"budget_limit": 50.0, "time_period": "7d"}].
+    - password: Optional[str] - Not supported; any value is rejected with a 422. Users set their own password through an invitation link (POST /invitation/new).
     Returns:
     - key: (str) The generated api key for the user
     - expires: (datetime) Datetime object for when key expires.
@@ -524,7 +542,7 @@ async def new_user(
     ```
     """
     try:
-        from litellm.proxy.proxy_server import _license_check, general_settings, prisma_client
+        from litellm.proxy.proxy_server import _license_check, prisma_client
 
         if prisma_client is None:
             raise HTTPException(status_code=400, detail=CommonProxyErrors.db_not_connected_error.value)
@@ -572,7 +590,7 @@ async def new_user(
         # generate_key_helper_fn only forwards object_permission_id, so without this the entitlement
         # the caller sent would be dropped on the floor.
         data_json = await _set_object_permission(data_json=data_json, prisma_client=prisma_client)
-        _hash_password_in_dict(data_json, general_settings)
+        data_json.pop("password", None)
         teams = data.teams
         if teams is None:
             teams = check_if_default_team_set()
@@ -1438,6 +1456,7 @@ async def _update_single_user_helper(
     user_request: UpdateUserRequest,
     user_api_key_dict: UserAPIKeyAuth,
     litellm_changed_by: str | None = None,
+    password_prevalidated: bool = False,
 ) -> dict[str, Any]:
     """
     Helper function to update a single user.
@@ -1460,7 +1479,7 @@ async def _update_single_user_helper(
 
     data_json: Final[dict] = user_request.model_dump(exclude_unset=True)
     non_default_values = _update_internal_user_params(data_json=data_json, data=user_request)
-    _hash_password_in_dict(non_default_values, general_settings)
+    await _hash_password_in_dict(non_default_values, general_settings, password_prevalidated=password_prevalidated)
 
     existing_user_row: BaseModel | None = None
     if user_request.user_id:
@@ -1641,7 +1660,7 @@ async def user_update(
     Parameters:
         - user_id: Optional[str] - Specify a user id. If not set, a unique id will be generated.
         - user_email: Optional[str] - Specify a user email.
-        - password: Optional[str] - Specify a user password.
+        - password: Optional[str] - Set the user's password (admin only). Must satisfy the configured password policy. The user is required to change it at their next login. Users change their own password with POST /user/password/change.
         - user_alias: Optional[str] - A descriptive name for you to know who this user id refers to.
         - teams: Optional[list] - specify a list of team id's a user belongs to.
         - send_invite_email: Optional[bool] - Specify if an invite email should be sent.
@@ -1709,19 +1728,38 @@ async def bulk_update_processed_users(
     users_to_update: list[UpdateUserRequest],
     user_api_key_dict: UserAPIKeyAuth,
     litellm_changed_by: str | None = None,
+    hibp_client: AsyncHTTPHandler | None = None,
 ) -> BulkUpdateUserResponse:
+    from litellm.proxy.proxy_server import general_settings
+
     results: Final[list[UserUpdateResult]] = []
     successful_updates = 0
     failed_updates = 0
 
+    # Screen the batch's passwords upfront and concurrently: done per-user
+    # inside the loop below, each HIBP lookup would be awaited serially and a
+    # degraded-slow HIBP could stretch a full batch to minutes, timing out the
+    # request after some updates already persisted.
+    password_verdicts: Final = await validate_passwords_bulk(
+        tuple(u.password for u in users_to_update if u.password is not None),
+        general_settings,
+        client=hibp_client,
+    )
+
     # Process each user update independently
     try:
         for user_request in users_to_update:
             try:
+                if (
+                    user_request.password is not None
+                    and (password_error := password_verdicts.get(user_request.password)) is not None
+                ):
+                    raise password_error
                 response = await _update_single_user_helper(
                     user_request=user_request,
                     user_api_key_dict=user_api_key_dict,
                     litellm_changed_by=litellm_changed_by,
+                    password_prevalidated=True,
                 )
                 # Record success
                 results.append(
@@ -1859,6 +1897,14 @@ async def bulk_user_update(
                 status_code=403,
                 detail="Only proxy admins can update all users at once.",
             )
+        if data.user_updates.password is not None:
+            bulk_password_error: Final[HTTPExceptionErrorDetail] = {
+                "error": (
+                    "Setting one password for all users is not supported. "
+                    "Use per-user updates via the 'users' list instead."
+                )
+            }
+            raise HTTPException(status_code=400, detail=bulk_password_error)
         # Optimized path for updating all users directly in database
         all_users_in_db: Final = await _user_table(prisma_client).find_many(order={"created_at": "desc"})
 
diff --git a/litellm/proxy/management_endpoints/password_endpoints.py b/litellm/proxy/management_endpoints/password_endpoints.py
new file mode 100644
index 00000000000..bd3c9722d4d
--- /dev/null
+++ b/litellm/proxy/management_endpoints/password_endpoints.py
@@ -0,0 +1,126 @@
+"""
+Self-service password management.
+
+/user/password/change
+
+Deliberately NOT wrapped in `management_endpoint_wrapper`: the wrapper emits
+request kwargs to OTEL spans, which would log plaintext passwords. The audit
+signal is emitted by hand below, with field names only, never values.
+"""
+
+from typing import TYPE_CHECKING, Final
+
+from fastapi import APIRouter, Depends, HTTPException
+
+from litellm._logging import verbose_proxy_logger
+from litellm.proxy._types import (
+    ChangePasswordRequest,
+    ChangePasswordResponse,
+    CommonProxyErrors,
+    HTTPExceptionErrorDetail,
+    LitellmTableNames,
+    UserAPIKeyAuth,
+)
+from litellm.proxy.auth.password_policy import validate_password_not_breached, validate_password_policy
+from litellm.proxy.auth.user_api_key_auth import user_api_key_auth
+from litellm.proxy.management_helpers.audit_logs import create_object_audit_log
+from litellm.proxy.utils import hash_password, verify_password
+from litellm.repositories.prisma_protocols import TableActions
+from litellm.repositories.user_repository import UserRepository
+
+if TYPE_CHECKING:
+    from prisma import models as prisma_models
+    from prisma import types as prisma_types
+
+    from litellm.proxy.utils import PrismaClient
+
+router: Final = APIRouter()
+
+_PASSWORD_CHANGED_AUDIT_VALUES: Final = '{"fields_changed": ["password"]}'
+
+
+def _error_detail(message: str) -> HTTPExceptionErrorDetail:
+    detail: Final[HTTPExceptionErrorDetail] = {"error": message}
+    return detail
+
+
+def _user_table(
+    prisma_client: "PrismaClient | None",
+) -> "TableActions[prisma_models.LiteLLM_UserTable]":
+    user_table: Final[TableActions[prisma_models.LiteLLM_UserTable]] = UserRepository(prisma_client).table
+    return user_table
+
+
+@router.post(
+    "/user/password/change",
+    tags=("Internal User management",),
+    dependencies=(Depends(user_api_key_auth),),
+)
+async def change_password(
+    data: ChangePasswordRequest,
+    user_api_key_dict: UserAPIKeyAuth = Depends(user_api_key_auth),
+) -> ChangePasswordResponse:
+    """
+    Change the calling user's own password.
+
+    Requires the current password. The new password must satisfy the
+    configured password policy (`general_settings.password_policy_*`: minimum
+    length, character classes, and, when enabled, breached-password screening
+    via haveibeenpwned.com). A successful change lifts any pending forced
+    password reset (`password_reset_required`) on the account.
+
+    Parameters:
+    - current_password: str - The user's current password.
+    - new_password: str - The password to change to.
+    """
+    from litellm.proxy.proxy_server import general_settings, litellm_proxy_admin_name, prisma_client
+
+    if prisma_client is None:
+        raise HTTPException(
+            status_code=500,
+            detail=_error_detail(CommonProxyErrors.db_not_connected_error.value),
+        )
+
+    user_id: Final = user_api_key_dict.user_id
+    if user_id is None:
+        raise HTTPException(
+            status_code=400,
+            detail=_error_detail("No user is associated with this session, so there is no password to change."),
+        )
+
+    find_user: Final[prisma_types.LiteLLM_UserTableWhereInput] = {"user_id": user_id}
+    user_row: Final = await _user_table(prisma_client).find_first(where=find_user)
+    stored_password: Final = user_row.password if user_row is not None else None
+    if stored_password is None:
+        raise HTTPException(
+            status_code=400,
+            detail=_error_detail(
+                "This account has no password set, so there is no password to change. "
+                "Passwords are set through an invitation link (POST /invitation/new)."
+            ),
+        )
+
+    if not verify_password(data.current_password, stored_password):
+        raise HTTPException(status_code=400, detail=_error_detail("Current password is incorrect."))
+
+    validate_password_policy(data.new_password, general_settings)
+    await validate_password_not_breached(data.new_password, general_settings)
+
+    password_update: Final[prisma_types.LiteLLM_UserTableUpdateInput] = {
+        "password": hash_password(data.new_password),
+        "password_reset_required": False,
+        "last_breach_check_at": None,
+    }
+    await _user_table(prisma_client).update(where=find_user, data=password_update)
+
+    verbose_proxy_logger.info("Password changed via /user/password/change for user_id=%s", user_id)
+    await create_object_audit_log(
+        object_id=user_id,
+        action="updated",
+        litellm_changed_by=None,
+        user_api_key_dict=user_api_key_dict,
+        litellm_proxy_admin_name=litellm_proxy_admin_name,
+        table_name=LitellmTableNames.USER_TABLE_NAME,
+        after_value=_PASSWORD_CHANGED_AUDIT_VALUES,
+    )
+    return ChangePasswordResponse(user_id=user_id, message="Password updated successfully.")
diff --git a/litellm/proxy/management_endpoints/ui_sso.py b/litellm/proxy/management_endpoints/ui_sso.py
index 00cf357d89d..7859c678c07 100644
--- a/litellm/proxy/management_endpoints/ui_sso.py
+++ b/litellm/proxy/management_endpoints/ui_sso.py
@@ -3665,6 +3665,7 @@ class SSOAuthenticationHandler:
             auth_header_name=general_settings.get("litellm_key_header_name", "Authorization"),
             disabled_non_admin_personal_key_creation=disabled_non_admin_personal_key_creation,
             server_root_path=get_server_root_path(),
+            password_reset_required=False,
         )
 
         from litellm.proxy.auth.login_utils import encode_ui_session_jwt
diff --git a/litellm/proxy/proxy_server.py b/litellm/proxy/proxy_server.py
index 3a06753834a..638d685d3e0 100644
--- a/litellm/proxy/proxy_server.py
+++ b/litellm/proxy/proxy_server.py
@@ -359,7 +359,7 @@ from litellm.proxy.auth.model_checks import (
     get_mcp_server_ids,
     get_team_models,
 )
-from litellm.proxy.auth.password_policy import validate_password_policy
+from litellm.proxy.auth.password_policy import validate_password_not_breached, validate_password_policy
 from litellm.proxy.auth.user_api_key_auth import (
     _fetch_global_spend_with_event_coordination,
     user_api_key_auth,
@@ -601,6 +601,9 @@ from litellm.proxy.management_endpoints.model_management_endpoints import (
 from litellm.proxy.management_endpoints.organization_endpoints import (
     router as organization_router,
 )
+from litellm.proxy.management_endpoints.password_endpoints import (
+    router as password_management_router,
+)
 from litellm.proxy.management_endpoints.router_settings_endpoints import (
     router as router_settings_router,
 )
@@ -16614,6 +16617,7 @@ async def onboarding(invite_link: str, request: Request):
         auth_header_name=general_settings.get("litellm_key_header_name", "Authorization"),
         disabled_non_admin_personal_key_creation=disabled_non_admin_personal_key_creation,
         server_root_path=get_server_root_path(),
+        password_reset_required=False,
     )
     jwt_token: Final = jwt.encode(
         cast(dict, returned_ui_token_object),
@@ -16724,6 +16728,7 @@ async def _generate_onboarding_ui_session_token(user_obj: _UserTableRow) -> str:
         auth_header_name=general_settings.get("litellm_key_header_name", "Authorization"),
         disabled_non_admin_personal_key_creation=disabled_non_admin_personal_key_creation,
         server_root_path=get_server_root_path(),
+        password_reset_required=False,
     )
     assert master_key is not None
     return jwt.encode(
@@ -16794,6 +16799,7 @@ async def claim_onboarding_link(data: InvitationClaim, request: Request):
         )
 
     validate_password_policy(data.password, general_settings)
+    await validate_password_not_breached(data.password, general_settings)
     hashed_pw: Final = hash_password(data.password)
     current_time = litellm.utils.get_utc_datetime()
     async with prisma_client.db.tx() as tx:
@@ -16813,7 +16819,12 @@ async def claim_onboarding_link(data: InvitationClaim, request: Request):
 
         ### UPDATE USER OBJECT ###
         user_obj: Final[_UserTableRow | None] = await tx.litellm_usertable.update(
-            where={"user_id": invite_obj.user_id}, data={"password": hashed_pw}
+            where={"user_id": invite_obj.user_id},
+            data={
+                "password": hashed_pw,
+                "password_reset_required": False,
+                "last_breach_check_at": None,
+            },
         )
 
         if user_obj is None:
@@ -19251,6 +19262,7 @@ app.include_router(pass_through_router)
 app.include_router(health_router)
 app.include_router(key_management_router)
 app.include_router(internal_user_router)
+app.include_router(password_management_router)
 app.include_router(team_router)
 app.include_router(ui_sso_router)
 app.include_router(organization_router)
diff --git a/litellm/proxy/schema.prisma b/litellm/proxy/schema.prisma
index d2032cec0d0..bcafa6dbd0e 100644
--- a/litellm/proxy/schema.prisma
+++ b/litellm/proxy/schema.prisma
@@ -246,6 +246,8 @@ model LiteLLM_UserTable {
     organization_id String?
     object_permission_id String?
     password  String?
+    password_reset_required Boolean?
+    last_breach_check_at DateTime?
     teams    String[] @default([])
     user_role  String?
 		max_budget Float?
diff --git a/litellm/types/llms/custom_http.py b/litellm/types/llms/custom_http.py
index d80d7410aae..793893451df 100644
--- a/litellm/types/llms/custom_http.py
+++ b/litellm/types/llms/custom_http.py
@@ -31,6 +31,7 @@ class httpxSpecialProvider(str, Enum):
     UI = "ui"
     Sandbox = "sandbox"
     ModelCostMap = "model_cost_map"
+    PasswordBreachCheck = "password_breach_check"
 
 
 VerifyTypes = str | bool | ssl.SSLContext
diff --git a/litellm/types/proxy/ui_sso.py b/litellm/types/proxy/ui_sso.py
index 0d7e0b99cf0..03b0b92a4d1 100644
--- a/litellm/types/proxy/ui_sso.py
+++ b/litellm/types/proxy/ui_sso.py
@@ -1,6 +1,6 @@
 from typing import Literal
 
-from typing_extensions import TypedDict
+from typing_extensions import ReadOnly, TypedDict
 
 
 class ReturnedUITokenObject(TypedDict):
@@ -17,6 +17,7 @@ class ReturnedUITokenObject(TypedDict):
     auth_header_name: str
     disabled_non_admin_personal_key_creation: bool
     server_root_path: str  # e.g. `/litellm`
+    password_reset_required: ReadOnly[bool]
 
 
 class ParsedOpenIDResult(TypedDict, total=False):
diff --git a/schema.prisma b/schema.prisma
index d2032cec0d0..bcafa6dbd0e 100644
--- a/schema.prisma
+++ b/schema.prisma
@@ -246,6 +246,8 @@ model LiteLLM_UserTable {
     organization_id String?
     object_permission_id String?
     password  String?
+    password_reset_required Boolean?
+    last_breach_check_at DateTime?
     teams    String[] @default([])
     user_role  String?
 		max_budget Float?
diff --git a/terraform/provider/tools/endpointaudit/coverage_allowlist.txt b/terraform/provider/tools/endpointaudit/coverage_allowlist.txt
index 4ea64b152f1..f8277c83a64 100644
--- a/terraform/provider/tools/endpointaudit/coverage_allowlist.txt
+++ b/terraform/provider/tools/endpointaudit/coverage_allowlist.txt
@@ -86,6 +86,7 @@ POST /team/key/bulk_update
 POST /team/permissions_bulk_update
 POST /team/{team_id}/disable_logging
 POST /user/bulk_update
+POST /user/password/change
 
 # Alternate method or path for functionality the provider already manages elsewhere
 GET /credentials/by_model/{model_id}
diff --git a/tests/test_litellm/proxy/auth/test_login_utils.py b/tests/test_litellm/proxy/auth/test_login_utils.py
index 55ece36252d..d41b90fe566 100644
--- a/tests/test_litellm/proxy/auth/test_login_utils.py
+++ b/tests/test_litellm/proxy/auth/test_login_utils.py
@@ -5,12 +5,15 @@ This module tests the refactored login logic that was moved from proxy_server.py
 to login_utils.py for better reusability.
 """
 
+import hashlib
 import os
 from collections.abc import Mapping
 from contextlib import ExitStack
 from typing import TYPE_CHECKING, Final
+from datetime import datetime, timedelta, timezone
 from unittest.mock import AsyncMock, MagicMock, patch
 
+import httpx
 import pytest
 
 if TYPE_CHECKING:
@@ -34,6 +37,7 @@ def _unlimited_throttle():
 
 
 from litellm.constants import LITELLM_PROXY_ADMIN_NAME
+from litellm.llms.custom_httpx.http_handler import AsyncHTTPHandler
 from litellm.proxy._types import (
     LiteLLM_UserTable,
     LitellmUserRoles,
@@ -46,8 +50,13 @@ from litellm.proxy.auth.login_utils import (
     authenticate_user,
     get_ui_credentials,
     is_env_credential_login_enabled,
+    screen_login_password_for_breach,
 )
 
+# Successful DB-user logins schedule the background HIBP screen; disable it so
+# no test ever does live network I/O to haveibeenpwned.com from CI.
+_POLICY_NO_BREACH_CHECK = {"password_policy_check_breached_passwords": False}
+
 
 def test_get_ui_credentials_prefers_explicit_password():
     """The configured UI password should be returned when available."""
@@ -326,6 +335,7 @@ async def test_authenticate_user_email_case_insensitive_login():
                 master_key=master_key,
                 prisma_client=mock_prisma_client,
                 throttle=_unlimited_throttle(),
+                general_settings=_POLICY_NO_BREACH_CHECK,
             )
             result_lower = await authenticate_user(
                 username=stored_email,
@@ -333,6 +343,7 @@ async def test_authenticate_user_email_case_insensitive_login():
                 master_key=master_key,
                 prisma_client=mock_prisma_client,
                 throttle=_unlimited_throttle(),
+                general_settings=_POLICY_NO_BREACH_CHECK,
             )
 
     assert result_mixed.user_id == result_lower.user_id == "test-user-123"
@@ -576,6 +587,7 @@ async def test_authenticate_user_database_login_with_non_ascii_password():
                 master_key=master_key,
                 prisma_client=mock_prisma_client,
                 throttle=_unlimited_throttle(),
+                general_settings=_POLICY_NO_BREACH_CHECK,
             )
 
             assert isinstance(result, LoginResult)
@@ -2064,3 +2076,263 @@ class TestIsEnvCredentialLoginEnabled:
         with ExitStack() as stack:
             _patch_sso_configured(stack, configured=False)
             assert is_env_credential_login_enabled({"disable_password_login_when_sso_enabled": True}) is True
+
+
+def _db_user_row(*, password: str, password_reset_required: bool | None = None, last_breach_check_at=None):
+    hashed = hash_token(token=password)
+    row = MagicMock()
+    row.user_id = "reset-user-1"
+    row.user_email = "reset@example.com"
+    row.password = hashed
+    row.user_role = LitellmUserRoles.INTERNAL_USER
+    row.password_reset_required = password_reset_required
+    row.last_breach_check_at = last_breach_check_at
+    return row
+
+
+def _prisma_with_user(row) -> MagicMock:
+    mock_prisma_client = MagicMock()
+    mock_prisma_client.db.litellm_usertable.find_first = AsyncMock(return_value=row)
+    mock_prisma_client.db.litellm_usertable.update = AsyncMock(return_value=row)
+    return mock_prisma_client
+
+
+_DB_LOGIN_ENV = {
+    "DATABASE_URL": "postgresql://test:test@localhost/test",
+    "UI_USERNAME": "admin",
+    "UI_PASSWORD": "admin-password",
+}
+
+
+class TestPasswordResetRequiredSessionMinting:
+    """A user flagged `password_reset_required` must receive a UI session key
+    restricted to the change-password endpoint (server-side enforcement, so a
+    script driving the management API with the session key is blocked too);
+    an unflagged user must keep getting an unrestricted key."""
+
+    async def _login(self, mock_prisma_client) -> tuple[LoginResult, dict]:
+        with patch.dict(os.environ, _DB_LOGIN_ENV):
+            with patch(  # test-quality-ok: asserting the minted key's restriction requires seeing its kwargs
+                "litellm.proxy.auth.login_utils.generate_key_helper_fn",
+                new_callable=AsyncMock,
+                return_value={"token": "session-token"},
+            ) as mock_generate_key:
+                result = await authenticate_user(
+                    username="reset@example.com",
+                    password="Str0ng!Passw0rd",
+                    master_key="sk-1234",
+                    prisma_client=mock_prisma_client,
+                    general_settings=_POLICY_NO_BREACH_CHECK,
+                )
+        return result, mock_generate_key.call_args.kwargs
+
+    @pytest.mark.asyncio
+    async def test_flagged_user_gets_key_restricted_to_change_password(self):
+        row = _db_user_row(password="Str0ng!Passw0rd", password_reset_required=True)
+        result, key_kwargs = await self._login(_prisma_with_user(row))
+
+        assert key_kwargs["allowed_routes"] == ["/user/password/change"]
+        assert key_kwargs["metadata"] == {"password_reset_required": True}
+        assert result.password_reset_required is True
+
+    @pytest.mark.asyncio
+    async def test_unflagged_user_gets_unrestricted_key(self):
+        row = _db_user_row(password="Str0ng!Passw0rd", password_reset_required=None)
+        result, key_kwargs = await self._login(_prisma_with_user(row))
+
+        assert key_kwargs["allowed_routes"] is None
+        assert not key_kwargs["metadata"]
+        assert result.password_reset_required is False
+
+    async def _login_with_screen_result(self, mock_prisma_client, breached: bool) -> tuple[LoginResult, dict, dict]:
+        with patch.dict(os.environ, _DB_LOGIN_ENV):
+            with patch(  # test-quality-ok: asserting the minted key's restriction requires seeing its kwargs
+                "litellm.proxy.auth.login_utils.generate_key_helper_fn",
+                new_callable=AsyncMock,
+                return_value={"token": "session-token"},
+            ) as mock_generate_key:
+                with (
+                    patch(  # test-quality-ok: authenticate_user has no HIBP client seam; the screen itself is tested against MockTransport below
+                        "litellm.proxy.auth.login_utils.screen_login_password_for_breach",
+                        new_callable=AsyncMock,
+                        return_value=breached,
+                    ) as mock_screen
+                ):
+                    result = await authenticate_user(
+                        username="reset@example.com",
+                        password="Str0ng!Passw0rd",
+                        master_key="sk-1234",
+                        prisma_client=mock_prisma_client,
+                        general_settings=_POLICY_NO_BREACH_CHECK,
+                    )
+        return result, mock_generate_key.call_args.kwargs, mock_screen.call_args.kwargs
+
+    @pytest.mark.asyncio
+    async def test_login_screens_with_row_state_before_minting(self):
+        """The login must hand the screen the row's recheck timestamp, or the
+        24h throttle can never work."""
+        checked_at = datetime.now(timezone.utc) - timedelta(hours=1)
+        row = _db_user_row(password="Str0ng!Passw0rd", last_breach_check_at=checked_at)
+        mock_prisma_client = _prisma_with_user(row)
+
+        _, _, screen_kwargs = await self._login_with_screen_result(mock_prisma_client, breached=False)
+
+        assert screen_kwargs["user_id"] == "reset-user-1"
+        assert screen_kwargs["password"] == "Str0ng!Passw0rd"
+        assert screen_kwargs["last_breach_check_at"] == checked_at
+        assert screen_kwargs["prisma_client"] is mock_prisma_client
+
+    @pytest.mark.asyncio
+    async def test_fresh_breach_hit_restricts_the_current_session(self):
+        """A breach found during THIS login must restrict THIS session, not
+        just the next one."""
+        row = _db_user_row(password="Str0ng!Passw0rd", password_reset_required=None)
+        mock_prisma_client = _prisma_with_user(row)
+
+        result, key_kwargs, _ = await self._login_with_screen_result(mock_prisma_client, breached=True)
+
+        assert key_kwargs["allowed_routes"] == ["/user/password/change"]
+        assert key_kwargs["metadata"] == {"password_reset_required": True}
+        assert result.password_reset_required is True
+
+
+def _sha1_upper(password: str) -> str:
+    return hashlib.sha1(password.encode("utf-8"), usedforsecurity=False).hexdigest().upper()
+
+
+def _client_with_transport(handler) -> AsyncHTTPHandler:
+    http_handler = AsyncHTTPHandler()
+    http_handler.client = httpx.AsyncClient(transport=httpx.MockTransport(handler))
+    return http_handler
+
+
+def _client_returning_breach_hit(password: str) -> AsyncHTTPHandler:
+    body = f"{_sha1_upper(password)[5:]}:42"
+    return _client_with_transport(lambda request: httpx.Response(200, text=body))
+
+
+def _client_returning_no_hit() -> AsyncHTTPHandler:
+    return _client_with_transport(lambda request: httpx.Response(200, text="0000000000000000000000000000000000A:3"))
+
+
+def _client_never_called() -> AsyncHTTPHandler:
+    def handler(request: httpx.Request) -> httpx.Response:
+        raise AssertionError(f"unexpected HTTP call to {request.url}")
+
+    return _client_with_transport(handler)
+
+
+class TestScreenLoginPasswordForBreach:
+    """The awaited login-time screen: flags a breached password for a forced
+    reset, stamps the recheck timestamp, rechecks at most every 24h, returns
+    the breach verdict so the login can restrict the session it is minting,
+    and never raises into the login."""
+
+    @pytest.mark.asyncio
+    async def test_breached_password_sets_reset_flag_and_timestamp(self):
+        password = "Password123!"
+        mock_prisma_client = _prisma_with_user(None)
+
+        breached = await screen_login_password_for_breach(
+            user_id="reset-user-1",
+            password=password,
+            last_breach_check_at=None,
+            general_settings={},
+            prisma_client=mock_prisma_client,
+            client=_client_returning_breach_hit(password),
+        )
+
+        assert breached is True
+        update_kwargs = mock_prisma_client.db.litellm_usertable.update.call_args.kwargs
+        assert update_kwargs["where"] == {"user_id": "reset-user-1"}
+        assert update_kwargs["data"]["password_reset_required"] is True
+        assert isinstance(update_kwargs["data"]["last_breach_check_at"], datetime)
+
+    @pytest.mark.asyncio
+    async def test_clean_password_stamps_timestamp_without_flag(self):
+        mock_prisma_client = _prisma_with_user(None)
+
+        breached = await screen_login_password_for_breach(
+            user_id="reset-user-1",
+            password="Str0ng!Passw0rd",
+            last_breach_check_at=None,
+            general_settings={},
+            prisma_client=mock_prisma_client,
+            client=_client_returning_no_hit(),
+        )
+
+        assert breached is False
+        update_kwargs = mock_prisma_client.db.litellm_usertable.update.call_args.kwargs
+        assert "password_reset_required" not in update_kwargs["data"]
+        assert isinstance(update_kwargs["data"]["last_breach_check_at"], datetime)
+
+    @pytest.mark.asyncio
+    async def test_skips_hibp_when_checked_within_24_hours(self):
+        mock_prisma_client = _prisma_with_user(None)
+
+        breached = await screen_login_password_for_breach(
+            user_id="reset-user-1",
+            password="Password123!",
+            last_breach_check_at=datetime.now(timezone.utc) - timedelta(hours=23),
+            general_settings={},
+            prisma_client=mock_prisma_client,
+            client=_client_never_called(),
+        )
+
+        assert breached is False
+        mock_prisma_client.db.litellm_usertable.update.assert_not_called()
+
+    @pytest.mark.asyncio
+    async def test_rechecks_when_last_check_is_older_than_24_hours(self):
+        password = "Password123!"
+        mock_prisma_client = _prisma_with_user(None)
+
+        breached = await screen_login_password_for_breach(
+            user_id="reset-user-1",
+            password=password,
+            last_breach_check_at=datetime.now(timezone.utc) - timedelta(hours=25),
+            general_settings={},
+            prisma_client=mock_prisma_client,
+            client=_client_returning_breach_hit(password),
+        )
+
+        assert breached is True
+        assert (
+            mock_prisma_client.db.litellm_usertable.update.call_args.kwargs["data"]["password_reset_required"] is True
+        )
+
+    @pytest.mark.asyncio
+    async def test_skips_hibp_when_check_disabled(self):
+        mock_prisma_client = _prisma_with_user(None)
+
+        breached = await screen_login_password_for_breach(
+            user_id="reset-user-1",
+            password="Password123!",
+            last_breach_check_at=None,
+            general_settings=_POLICY_NO_BREACH_CHECK,
+            prisma_client=mock_prisma_client,
+            client=_client_never_called(),
+        )
+
+        assert breached is False
+        mock_prisma_client.db.litellm_usertable.update.assert_not_called()
+
+    @pytest.mark.asyncio
+    async def test_db_failure_never_raises_but_still_reports_the_breach(self):
+        """A failed flag write must not fail the login, but the breach verdict
+        still has to restrict the session being minted right now."""
+        password = "Password123!"
+        mock_prisma_client = _prisma_with_user(None)
+        mock_prisma_client.db.litellm_usertable.update = AsyncMock(side_effect=RuntimeError("db down"))
+
+        assert (
+            await screen_login_password_for_breach(
+                user_id="reset-user-1",
+                password=password,
+                last_breach_check_at=None,
+                general_settings={},
+                prisma_client=mock_prisma_client,
+                client=_client_returning_breach_hit(password),
+            )
+            is True
+        )
diff --git a/tests/test_litellm/proxy/auth/test_onboarding.py b/tests/test_litellm/proxy/auth/test_onboarding.py
index 524b655b465..0454aea1239 100644
--- a/tests/test_litellm/proxy/auth/test_onboarding.py
+++ b/tests/test_litellm/proxy/auth/test_onboarding.py
@@ -8,15 +8,20 @@ Covers the security behavior of:
                                   session key only after the password is written
 """
 
+import hashlib
 from datetime import timedelta
 from unittest.mock import AsyncMock, MagicMock, patch
 
+import httpx
 import jwt
 import pytest
+import respx
 from fastapi import HTTPException
 
 import litellm
-from litellm.proxy._types import InvitationClaim
+from litellm.proxy._types import InvitationClaim, ProxyException
+
+_POLICY_NO_BREACH_CHECK = {"password_policy_check_breached_passwords": False}
 
 # ---------------------------------------------------------------------------
 # Helpers
@@ -386,7 +391,9 @@ async def test_claim_token_rejects_concurrent_reuse_before_password_write():
     with (
         patch("litellm.proxy.proxy_server.prisma_client", prisma),
         patch("litellm.proxy.proxy_server.master_key", "sk-test"),
-        patch("litellm.proxy.proxy_server.general_settings", {}),
+        patch(  # test-quality-ok: claim_onboarding_link reads proxy_server module globals; no injection seam
+            "litellm.proxy.proxy_server.general_settings", _POLICY_NO_BREACH_CHECK
+        ),
         patch(
             "litellm.proxy.proxy_server.generate_key_helper_fn",
             new_callable=AsyncMock,
@@ -426,7 +433,9 @@ async def test_claim_token_sets_accepted_at_after_password_written():
     with (
         patch("litellm.proxy.proxy_server.prisma_client", prisma),
         patch("litellm.proxy.proxy_server.master_key", "sk-test"),
-        patch("litellm.proxy.proxy_server.general_settings", {}),
+        patch(  # test-quality-ok: claim_onboarding_link reads proxy_server module globals; no injection seam
+            "litellm.proxy.proxy_server.general_settings", _POLICY_NO_BREACH_CHECK
+        ),
         patch("litellm.proxy.proxy_server.premium_user", False),
         patch(
             "litellm.proxy.proxy_server.generate_key_helper_fn",
@@ -454,6 +463,10 @@ async def test_claim_token_sets_accepted_at_after_password_written():
     call_kwargs = prisma.db.litellm_usertable.update.call_args
     assert call_kwargs.kwargs["where"] == {"user_id": "user-123"}
     assert "password" in call_kwargs.kwargs["data"]
+    # A freshly claimed, policy-screened password lifts any pending forced
+    # reset and re-arms the login-time breach screen.
+    assert call_kwargs.kwargs["data"]["password_reset_required"] is False
+    assert call_kwargs.kwargs["data"]["last_breach_check_at"] is None
 
     # is_accepted was flipped to True on the invitation link
     prisma.db.litellm_invitationlink.update.assert_called_once()
@@ -483,7 +496,9 @@ async def test_claim_token_rolls_back_invite_when_session_key_mint_fails():
     with (
         patch("litellm.proxy.proxy_server.prisma_client", prisma),
         patch("litellm.proxy.proxy_server.master_key", "sk-test"),
-        patch("litellm.proxy.proxy_server.general_settings", {}),
+        patch(  # test-quality-ok: claim_onboarding_link reads proxy_server module globals; no injection seam
+            "litellm.proxy.proxy_server.general_settings", _POLICY_NO_BREACH_CHECK
+        ),
         patch(
             "litellm.proxy.proxy_server.generate_key_helper_fn",
             new_callable=AsyncMock,
@@ -505,3 +520,124 @@ async def test_claim_token_rolls_back_invite_when_session_key_mint_fails():
     }
     assert rollback_kwargs["data"]["accepted_at"] is None
     assert rollback_kwargs["data"]["is_accepted"] is False
+
+
+# ---------------------------------------------------------------------------
+# POST /onboarding/claim_token - password policy
+# ---------------------------------------------------------------------------
+
+
+def _hibp_url_for(password: str) -> str:
+    sha1 = hashlib.sha1(password.encode("utf-8"), usedforsecurity=False).hexdigest().upper()
+    return f"https://api.pwnedpasswords.com/range/{sha1[:5]}"
+
+
+def _hibp_suffix_for(password: str) -> str:
+    return hashlib.sha1(password.encode("utf-8"), usedforsecurity=False).hexdigest().upper()[5:]
+
+
+@pytest.mark.asyncio
+async def test_claim_token_rejects_short_password_before_consuming_invite():
+    """Default policy requires 12 characters; the invite must stay claimable."""
+    from litellm.proxy.proxy_server import claim_onboarding_link
+
+    invite = _make_invite(is_accepted=False)
+    prisma = _make_prisma(invite, _make_user())
+    request = _make_claim_request(_make_onboarding_token())
+    data = InvitationClaim(
+        invitation_link="invite-abc",
+        user_id="user-123",
+        password="Sh0rt!pw",
+    )
+
+    with (
+        patch("litellm.proxy.proxy_server.prisma_client", prisma),  # test-quality-ok: claim_onboarding_link reads proxy_server module globals; no injection seam
+        patch("litellm.proxy.proxy_server.master_key", "sk-test"),  # test-quality-ok: same as above
+        patch("litellm.proxy.proxy_server.general_settings", {}),  # test-quality-ok: same as above
+    ):
+        with pytest.raises(ProxyException) as exc_info:
+            await claim_onboarding_link(data=data, request=request)
+
+    assert exc_info.value.code == "400"
+    assert "at least 12 characters" in exc_info.value.message
+    prisma.db.litellm_invitationlink.update_many.assert_not_called()
+    prisma.db.litellm_usertable.update.assert_not_called()
+
+
+@pytest.mark.asyncio
+@respx.mock
+async def test_claim_token_rejects_breached_password_before_consuming_invite():
+    """A password found in the HIBP corpus must be rejected and never stored."""
+    from litellm.proxy.proxy_server import claim_onboarding_link
+
+    password = "P@ssword123456"
+    respx.get(_hibp_url_for(password)).mock(
+        return_value=httpx.Response(200, text=f"{_hibp_suffix_for(password)}:1387")
+    )
+
+    invite = _make_invite(is_accepted=False)
+    prisma = _make_prisma(invite, _make_user())
+    request = _make_claim_request(_make_onboarding_token())
+    data = InvitationClaim(
+        invitation_link="invite-abc",
+        user_id="user-123",
+        password=password,
+    )
+
+    with (
+        patch("litellm.proxy.proxy_server.prisma_client", prisma),  # test-quality-ok: claim_onboarding_link reads proxy_server module globals; no injection seam
+        patch("litellm.proxy.proxy_server.master_key", "sk-test"),  # test-quality-ok: same as above
+        patch("litellm.proxy.proxy_server.general_settings", {}),  # test-quality-ok: same as above
+    ):
+        with pytest.raises(ProxyException) as exc_info:
+            await claim_onboarding_link(data=data, request=request)
+
+    assert exc_info.value.code == "400"
+    assert "data breaches" in exc_info.value.message
+    prisma.db.litellm_invitationlink.update_many.assert_not_called()
+    prisma.db.litellm_usertable.update.assert_not_called()
+
+
+@pytest.mark.asyncio
+@respx.mock
+async def test_claim_token_fails_open_when_hibp_unreachable():
+    """An HIBP outage must never block onboarding: the claim proceeds."""
+    from litellm.proxy.proxy_server import claim_onboarding_link
+
+    password = "NewP@ssw0rd-2026"
+    respx.get(_hibp_url_for(password)).mock(side_effect=httpx.ConnectError("no route to host"))
+
+    invite = _make_invite(is_accepted=False)
+    user = _make_user()
+    prisma = _make_prisma(invite, user)
+    request = _make_claim_request(_make_onboarding_token())
+    data = InvitationClaim(
+        invitation_link="invite-abc",
+        user_id="user-123",
+        password=password,
+    )
+
+    with (
+        patch("litellm.proxy.proxy_server.prisma_client", prisma),  # test-quality-ok: claim_onboarding_link reads proxy_server module globals; no injection seam
+        patch("litellm.proxy.proxy_server.master_key", "sk-test"),  # test-quality-ok: same as above
+        patch("litellm.proxy.proxy_server.general_settings", {}),  # test-quality-ok: same as above
+        patch("litellm.proxy.proxy_server.premium_user", False),  # test-quality-ok: same as above
+        patch(  # test-quality-ok: same as above
+            "litellm.proxy.proxy_server.generate_key_helper_fn",
+            new_callable=AsyncMock,
+            return_value={"token": "sk-generated-key", "user_id": "user-123"},
+        ),
+        patch(  # test-quality-ok: same as above
+            "litellm.proxy.proxy_server.get_custom_url",
+            return_value="http://localhost:4000/",
+        ),
+        patch(  # test-quality-ok: same as above
+            "litellm.proxy.proxy_server.get_disabled_non_admin_personal_key_creation",
+            return_value=False,
+        ),
+        patch("litellm.proxy.proxy_server.get_server_root_path", return_value=""),  # test-quality-ok: same as above
+    ):
+        result = await claim_onboarding_link(data=data, request=request)
+
+    assert "token" in result
+    prisma.db.litellm_usertable.update.assert_called_once()
diff --git a/tests/test_litellm/proxy/auth/test_password_policy.py b/tests/test_litellm/proxy/auth/test_password_policy.py
index f6e7d443907..f9f5025b57f 100644
--- a/tests/test_litellm/proxy/auth/test_password_policy.py
+++ b/tests/test_litellm/proxy/auth/test_password_policy.py
@@ -2,22 +2,56 @@
 Tests for the configurable password-strength policy in
 `litellm.proxy.auth.password_policy`, enforced on every path that persists a
 new or changed password for a locally-managed user.
+
+The breach-check (HIBP) tests inject a real AsyncHTTPHandler wrapping an
+httpx.MockTransport, so no network is touched and nothing is monkeypatched.
 """
 
+import asyncio
+import hashlib
+
+import httpx
 import pytest
 
+from litellm.llms.custom_httpx.http_handler import AsyncHTTPHandler
 from litellm.proxy._types import ProxyErrorTypes, ProxyException
 from litellm.proxy.auth.password_policy import (
     DEFAULT_MIN_LENGTH,
     MIN_ALLOWED_LENGTH,
     PasswordPolicy,
     get_password_policy,
+    validate_password_not_breached,
     validate_password_policy,
+    validate_passwords_bulk,
 )
 
 STRONG_PASSWORD = "Str0ng!Passw0rd"
 
 
+def _sha1_upper(password: str) -> str:
+    return hashlib.sha1(password.encode("utf-8"), usedforsecurity=False).hexdigest().upper()
+
+
+def _client_with_transport(handler) -> AsyncHTTPHandler:
+    http_handler = AsyncHTTPHandler()
+    http_handler.client = httpx.AsyncClient(transport=httpx.MockTransport(handler))
+    return http_handler
+
+
+def _client_never_called() -> AsyncHTTPHandler:
+    def handler(request: httpx.Request) -> httpx.Response:
+        raise AssertionError(f"unexpected HTTP call to {request.url}")
+
+    return _client_with_transport(handler)
+
+
+def _client_returning(body: str, status_code: int = 200) -> AsyncHTTPHandler:
+    def handler(request: httpx.Request) -> httpx.Response:
+        return httpx.Response(status_code, text=body)
+
+    return _client_with_transport(handler)
+
+
 def test_get_password_policy_defaults_to_pif_baseline():
     policy = get_password_policy({})
     assert policy == PasswordPolicy(
@@ -134,3 +168,178 @@ def test_validate_password_policy_rejects_unicode_letter_as_special_character():
 def test_validate_password_policy_accepts_real_special_character_with_unicode_letters():
     """Same base password as the rejection test above, plus an actual symbol."""
     assert validate_password_policy("Passwörd1234!", {}) is None
+
+
+@pytest.mark.asyncio
+async def test_breach_check_skipped_when_disabled():
+    result = await validate_password_not_breached(
+        password="password12345",  # breached in reality, but the check is off
+        general_settings={"password_policy_check_breached_passwords": False},
+        client=_client_never_called(),
+    )
+    assert result is None
+
+
+@pytest.mark.asyncio
+async def test_rejects_breached_password():
+    password = "correct horse battery staple"
+    sha1 = _sha1_upper(password)
+    body = f"AAAA000000000000000000000000000000A:0\r\n{sha1[5:]}:42\r\nBBBB000000000000000000000000000000B:7"
+
+    with pytest.raises(ProxyException) as exc_info:
+        await validate_password_not_breached(password=password, general_settings={}, client=_client_returning(body))
+    assert exc_info.value.code == "400"
+    assert exc_info.value.type == ProxyErrorTypes.validation_error
+    assert exc_info.value.param == "password"
+    assert "data breaches" in exc_info.value.message
+
+
+@pytest.mark.asyncio
+async def test_only_sha1_prefix_leaves_the_proxy():
+    password = "a very secret password"
+    sha1 = _sha1_upper(password)
+    captured_requests: list[httpx.Request] = []
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        captured_requests.append(request)
+        return httpx.Response(200, text="0000000000000000000000000000000000A:1")
+
+    result = await validate_password_not_breached(
+        password=password, general_settings={}, client=_client_with_transport(handler)
+    )
+    assert result is None
+
+    (request,) = captured_requests
+    assert request.url.path == f"/range/{sha1[:5]}"
+    assert sha1[5:] not in str(request.url)
+    assert request.headers["Add-Padding"] == "true"
+    assert "litellm" in request.headers["User-Agent"]
+
+
+@pytest.mark.asyncio
+async def test_ignores_padding_entries_with_zero_count():
+    """HIBP padding entries (requested via Add-Padding) carry count 0 and must
+    not be treated as breaches when they collide with the password's suffix."""
+    password = "a padded-away password"
+    sha1 = _sha1_upper(password)
+
+    result = await validate_password_not_breached(
+        password=password, general_settings={}, client=_client_returning(f"{sha1[5:]}:0")
+    )
+    assert result is None
+
+
+@pytest.mark.asyncio
+async def test_accepts_password_absent_from_breach_corpus():
+    result = await validate_password_not_breached(
+        password="a genuinely novel password",
+        general_settings={},
+        client=_client_returning("0018A45C4D1DEF81644B54AB7F969B88D65:1\r\n00D4F6E8FA6EECAD2A3AA415EEC418D38EC:2"),
+    )
+    assert result is None
+
+
+@pytest.mark.asyncio
+async def test_breach_check_fails_open_on_network_error():
+    def handler(request: httpx.Request) -> httpx.Response:
+        raise httpx.ConnectError("no route to host")
+
+    result = await validate_password_not_breached(
+        password="password12345",  # breached, but HIBP is unreachable
+        general_settings={},
+        client=_client_with_transport(handler),
+    )
+    assert result is None
+
+
+@pytest.mark.asyncio
+async def test_breach_check_fails_open_on_http_error_status():
+    result = await validate_password_not_breached(
+        password="password12345",
+        general_settings={},
+        client=_client_returning("service unavailable", status_code=503),
+    )
+    assert result is None
+
+
+@pytest.mark.asyncio
+async def test_breach_check_fails_open_on_malformed_response_body():
+    result = await validate_password_not_breached(
+        password="password12345",
+        general_settings={},
+        client=_client_returning(f"{_sha1_upper('password12345')[5:]}:not-a-number"),
+    )
+    assert result is None
+
+
+@pytest.mark.asyncio
+async def test_validate_passwords_bulk_screens_concurrently():
+    """All HIBP lookups for a batch must be in flight at once: each handler
+    call stalls until every expected request has arrived, and a handler that
+    gives up waiting reports the password as breached. Serial awaiting (the
+    old per-user behavior) leaves each earlier request waiting forever for the
+    later ones, so every verdict comes back as a breach and the test fails."""
+    passwords = ("Uniqu3!Passw0rd-a", "Uniqu3!Passw0rd-b", "Uniqu3!Passw0rd-c")
+    suffix_by_prefix = {_sha1_upper(p)[:5]: _sha1_upper(p)[5:] for p in passwords}
+    all_arrived = asyncio.Event()
+    arrivals: list[str] = []
+
+    async def handler(request: httpx.Request) -> httpx.Response:
+        arrivals.append(request.url.path)
+        if len(arrivals) == len(passwords):
+            all_arrived.set()
+        try:
+            await asyncio.wait_for(all_arrived.wait(), timeout=5)
+        except TimeoutError:
+            return httpx.Response(200, text=f"{suffix_by_prefix[request.url.path.rsplit('/', 1)[-1]]}:1")
+        return httpx.Response(200, text="0000000000000000000000000000000000A:1")
+
+    verdicts = await validate_passwords_bulk(passwords, {}, client=_client_with_transport(handler))
+    assert set(arrivals) == {f"/range/{prefix}" for prefix in suffix_by_prefix}
+    assert all(verdicts[p] is None for p in passwords)
+
+
+@pytest.mark.asyncio
+async def test_validate_passwords_bulk_deduplicates_lookups():
+    """500 users sharing one password must cost exactly one HIBP lookup."""
+    password = "Sh@red-Passw0rd!"
+    request_count = 0
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        nonlocal request_count
+        request_count += 1
+        return httpx.Response(200, text="0000000000000000000000000000000000A:1")
+
+    verdicts = await validate_passwords_bulk((password,) * 500, {}, client=_client_with_transport(handler))
+    assert request_count == 1
+    assert verdicts == {password: None}
+
+
+@pytest.mark.asyncio
+async def test_validate_passwords_bulk_mixed_verdicts():
+    """Weak passwords are rejected without an HIBP lookup; breached ones get
+    the breach error; acceptable ones map to None."""
+    breached = "Br3ached!Passw0rd"
+    clean = "Cl3an!!Passw0rd42"
+    weak = "short1!"
+    breached_sha1 = _sha1_upper(breached)
+    looked_up_prefixes: list[str] = []
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        looked_up_prefixes.append(request.url.path.rsplit("/", 1)[-1])
+        if request.url.path == f"/range/{breached_sha1[:5]}":
+            return httpx.Response(200, text=f"{breached_sha1[5:]}:99")
+        return httpx.Response(200, text="0000000000000000000000000000000000A:1")
+
+    verdicts = await validate_passwords_bulk((breached, clean, weak), {}, client=_client_with_transport(handler))
+    assert _sha1_upper(weak)[:5] not in looked_up_prefixes
+    assert verdicts[clean] is None
+    assert "data breaches" in verdicts[breached].message
+    assert verdicts[breached].code == "400"
+    assert "12 characters" in verdicts[weak].message
+
+
+@pytest.mark.asyncio
+async def test_validate_passwords_bulk_empty_batch_makes_no_lookups():
+    verdicts = await validate_passwords_bulk((), {}, client=_client_never_called())
+    assert verdicts == {}
diff --git a/tests/test_litellm/proxy/auth/test_route_checks.py b/tests/test_litellm/proxy/auth/test_route_checks.py
index 603a8686692..8382c7842b0 100644
--- a/tests/test_litellm/proxy/auth/test_route_checks.py
+++ b/tests/test_litellm/proxy/auth/test_route_checks.py
@@ -3,7 +3,6 @@ from datetime import datetime
 from typing import Final
 from unittest.mock import MagicMock, patch
 
-
 import pytest
 from fastapi import HTTPException, Request
 
@@ -39,7 +38,7 @@ def test_non_admin_config_update_route_rejected():
     request.query_params = {}
 
     # Test that calling /config/update route raises HTTPException with 403 status
-    with pytest.raises(Exception, match='Only proxy admin can be used to generate, delete, update') as exc_info:
+    with pytest.raises(Exception, match="Only proxy admin can be used to generate, delete, update") as exc_info:
         RouteChecks.non_proxy_admin_allowed_routes_check(
             user_obj=user_obj,
             _user_role=LitellmUserRoles.INTERNAL_USER.value,
@@ -50,9 +49,8 @@ def test_non_admin_config_update_route_rejected():
         )
 
     # Verify the exception is raised with the correct message
-    assert (
-        "Only proxy admin can be used to generate, delete, update info for new keys/users/teams"
-        in str(exc_info.value)
+    assert "Only proxy admin can be used to generate, delete, update info for new keys/users/teams" in str(
+        exc_info.value
     )
     assert "Route=/config/update" in str(exc_info.value)
     assert "Your role=internal_user" in str(exc_info.value)
@@ -131,7 +129,7 @@ def test_user_banner_update_rejected_for_non_admin():
     request = MagicMock(spec=Request)
     request.query_params = {}
 
-    with pytest.raises(Exception, match='Only proxy admin can be used to generate, delete, update') as exc_info:
+    with pytest.raises(Exception, match="Only proxy admin can be used to generate, delete, update") as exc_info:
         RouteChecks.non_proxy_admin_allowed_routes_check(
             user_obj=user_obj,
             _user_role=LitellmUserRoles.INTERNAL_USER.value,
@@ -706,9 +704,7 @@ def test_virtual_key_llm_api_route_includes_passthrough_prefix(route):
 
     valid_token = UserAPIKeyAuth(user_id="test_user", allowed_routes=["llm_api_routes"])
 
-    result = RouteChecks.is_virtual_key_allowed_to_call_route(
-        route=route, valid_token=valid_token
-    )
+    result = RouteChecks.is_virtual_key_allowed_to_call_route(route=route, valid_token=valid_token)
 
     assert result is True
 
@@ -733,9 +729,7 @@ def test_virtual_key_llm_api_routes_allows_google_routes(route):
 
     valid_token = UserAPIKeyAuth(user_id="test_user", allowed_routes=["llm_api_routes"])
 
-    result = RouteChecks.is_virtual_key_allowed_to_call_route(
-        route=route, valid_token=valid_token
-    )
+    result = RouteChecks.is_virtual_key_allowed_to_call_route(route=route, valid_token=valid_token)
 
     assert result is True
 
@@ -805,18 +799,14 @@ def test_google_routes_with_dynamic_model_names_accessible_to_internal_users():
         )
         # If no exception is raised, the test passes
     except Exception as e:
-        pytest.fail(
-            f"Internal user should be able to access Google generateContent route. Got error: {str(e)}"
-        )
+        pytest.fail(f"Internal user should be able to access Google generateContent route. Got error: {e!s}")
 
 
 def test_virtual_key_allowed_routes_with_multiple_litellm_routes_member_names():
     """Test that virtual key works with multiple LiteLLMRoutes member names in allowed_routes"""
 
     # Create a UserAPIKeyAuth with multiple LiteLLMRoutes member names
-    valid_token = UserAPIKeyAuth(
-        user_id="test_user", allowed_routes=["openai_routes", "info_routes"]
-    )
+    valid_token = UserAPIKeyAuth(user_id="test_user", allowed_routes=["openai_routes", "info_routes"])
 
     # Test that routes from both groups are allowed
     result1 = RouteChecks.is_virtual_key_allowed_to_call_route(
@@ -870,13 +860,9 @@ def test_virtual_key_allowed_routes_with_no_member_names_only_explicit():
     )
 
     # Test that explicit routes are allowed
-    result1 = RouteChecks.is_virtual_key_allowed_to_call_route(
-        route="/chat/completions", valid_token=valid_token
-    )
+    result1 = RouteChecks.is_virtual_key_allowed_to_call_route(route="/chat/completions", valid_token=valid_token)
 
-    result2 = RouteChecks.is_virtual_key_allowed_to_call_route(
-        route="/custom/route", valid_token=valid_token
-    )
+    result2 = RouteChecks.is_virtual_key_allowed_to_call_route(route="/custom/route", valid_token=valid_token)
 
     assert result1 is True
     assert result2 is True
@@ -1274,9 +1260,7 @@ def test_virtual_key_without_llm_api_routes_cannot_access_pass_through():
             )
 
         assert exc_info.value.status_code == 403
-        assert "Virtual key is not allowed to call this route" in str(
-            exc_info.value.detail
-        )
+        assert "Virtual key is not allowed to call this route" in str(exc_info.value.detail)
 
 
 def test_check_passthrough_route_access_key_metadata_exact_match():
@@ -1735,9 +1719,7 @@ def test_videos_route_accessible_to_internal_users():
         )
         # If no exception is raised, the test passes
     except Exception as e:
-        pytest.fail(
-            f"Internal user should be able to access /v1/videos route. Got error: {str(e)}"
-        )
+        pytest.fail(f"Internal user should be able to access /v1/videos route. Got error: {e!s}")
 
 
 def test_videos_route_with_virtual_key_llm_api_routes():
@@ -1759,12 +1741,8 @@ def test_videos_route_with_virtual_key_llm_api_routes():
     ]
 
     for route in test_routes:
-        result = RouteChecks.is_virtual_key_allowed_to_call_route(
-            route=route, valid_token=valid_token
-        )
-        assert (
-            result is True
-        ), f"Virtual key with llm_api_routes should be able to access {route}"
+        result = RouteChecks.is_virtual_key_allowed_to_call_route(route=route, valid_token=valid_token)
+        assert result is True, f"Virtual key with llm_api_routes should be able to access {route}"
 
 
 def test_non_proxy_admin_wildcard_allowed_routes():
@@ -1835,9 +1813,7 @@ def test_proxy_admin_viewer_can_access_global_spend_tags():
         )
         # If no exception is raised, the test passes
     except Exception as e:
-        pytest.fail(
-            f"proxy_admin_viewer should be able to access /global/spend/tags route. Got error: {str(e)}"
-        )
+        pytest.fail(f"proxy_admin_viewer should be able to access /global/spend/tags route. Got error: {e!s}")
 
 
 # Routes returning proxy-wide spend across every team / customer / api_key.
@@ -1865,7 +1841,7 @@ def test_internal_user_blocked_from_global_spend_routes(route):
     request = MagicMock(spec=Request)
     request.query_params = {}
 
-    with pytest.raises(Exception, match='Only proxy admin can be used to generate, delete, update') as exc_info:
+    with pytest.raises(Exception, match="Only proxy admin can be used to generate, delete, update") as exc_info:
         RouteChecks.non_proxy_admin_allowed_routes_check(
             user_obj=user_obj,
             _user_role=LitellmUserRoles.INTERNAL_USER.value,
@@ -1894,7 +1870,7 @@ def test_internal_user_view_only_blocked_from_global_spend_routes(route):
     request = MagicMock(spec=Request)
     request.query_params = {}
 
-    with pytest.raises(Exception, match='Only proxy admin can be used to generate, delete, update') as exc_info:
+    with pytest.raises(Exception, match="Only proxy admin can be used to generate, delete, update") as exc_info:
         RouteChecks.non_proxy_admin_allowed_routes_check(
             user_obj=user_obj,
             _user_role=LitellmUserRoles.INTERNAL_USER_VIEW_ONLY.value,
@@ -1996,9 +1972,7 @@ def test_proxy_admin_viewer_can_access_audit_logs(route):
             request_data={},
         )
     except Exception as e:
-        pytest.fail(
-            f"proxy_admin_viewer should be able to access {route} route. Got error: {str(e)}"
-        )
+        pytest.fail(f"proxy_admin_viewer should be able to access {route} route. Got error: {e!s}")
 
 
 # ── Admin Viewer parity: Logs page endpoints ──────────────────────────────────
@@ -2061,9 +2035,7 @@ def test_proxy_admin_viewer_can_access_logs_page_endpoints(route):
             request_data={},
         )
     except Exception as e:
-        pytest.fail(
-            f"proxy_admin_viewer should be able to access {route}. Got error: {str(e)}"
-        )
+        pytest.fail(f"proxy_admin_viewer should be able to access {route}. Got error: {e!s}")
 
 
 @pytest.mark.parametrize(
@@ -2173,7 +2145,7 @@ def test_internal_user_blocked_from_admin_viewer_logs_routes(route):
     if route not in INTERNAL_USER_BLOCKED_SUBSET:
         return
 
-    with pytest.raises(Exception, match='Only proxy admin can be used to generate, delete, update') as exc_info:
+    with pytest.raises(Exception, match="Only proxy admin can be used to generate, delete, update") as exc_info:
         RouteChecks.non_proxy_admin_allowed_routes_check(
             user_obj=user_obj,
             _user_role=LitellmUserRoles.INTERNAL_USER.value,
@@ -2249,9 +2221,7 @@ def test_proxy_admin_viewer_can_access_settings_read_endpoints(route):
             request_data={},
         )
     except Exception as e:
-        pytest.fail(
-            f"proxy_admin_viewer should be able to access {route}. Got error: {str(e)}"
-        )
+        pytest.fail(f"proxy_admin_viewer should be able to access {route}. Got error: {e!s}")
 
 
 # ── Admin Viewer parity: default-allow GET semantics ─────────────────────────
@@ -2450,9 +2420,7 @@ class TestModelsRouteExemptFromDisableLLMEndpoints:
         )
         local_file = os.path.abspath(local_file)
 
-        spec = importlib.util.spec_from_file_location(
-            "local_enterprise_route_checks", local_file
-        )
+        spec = importlib.util.spec_from_file_location("local_enterprise_route_checks", local_file)
         mod = importlib.util.module_from_spec(spec)
         spec.loader.exec_module(mod)
         return mod.EnterpriseRouteChecks
@@ -2463,9 +2431,7 @@ class TestModelsRouteExemptFromDisableLLMEndpoints:
         EnterpriseRouteChecks = self._get_enterprise_route_checks()
 
         with (
-            patch.object(
-                EnterpriseRouteChecks, "is_llm_api_route_disabled", return_value=True
-            ),
+            patch.object(EnterpriseRouteChecks, "is_llm_api_route_disabled", return_value=True),
             patch.object(
                 EnterpriseRouteChecks,
                 "is_management_routes_disabled",
@@ -2481,9 +2447,7 @@ class TestModelsRouteExemptFromDisableLLMEndpoints:
         EnterpriseRouteChecks = self._get_enterprise_route_checks()
 
         with (
-            patch.object(
-                EnterpriseRouteChecks, "is_llm_api_route_disabled", return_value=True
-            ),
+            patch.object(EnterpriseRouteChecks, "is_llm_api_route_disabled", return_value=True),
             patch.object(
                 EnterpriseRouteChecks,
                 "is_management_routes_disabled",
@@ -2499,9 +2463,7 @@ class TestModelsRouteExemptFromDisableLLMEndpoints:
         EnterpriseRouteChecks = self._get_enterprise_route_checks()
 
         with (
-            patch.object(
-                EnterpriseRouteChecks, "is_llm_api_route_disabled", return_value=True
-            ),
+            patch.object(EnterpriseRouteChecks, "is_llm_api_route_disabled", return_value=True),
             patch.object(
                 EnterpriseRouteChecks,
                 "is_management_routes_disabled",
@@ -2512,9 +2474,7 @@ class TestModelsRouteExemptFromDisableLLMEndpoints:
                 EnterpriseRouteChecks.should_call_route("/v1/chat/completions")
 
             assert exc_info.value.status_code == 403
-            assert "LLM API routes are disabled for this instance." in str(
-                exc_info.value.detail
-            )
+            assert "LLM API routes are disabled for this instance." in str(exc_info.value.detail)
 
     @patch("litellm.proxy.proxy_server.premium_user", True)
     def test_should_embeddings_still_blocked_when_llm_api_disabled(self):
@@ -2522,9 +2482,7 @@ class TestModelsRouteExemptFromDisableLLMEndpoints:
         EnterpriseRouteChecks = self._get_enterprise_route_checks()
 
         with (
-            patch.object(
-                EnterpriseRouteChecks, "is_llm_api_route_disabled", return_value=True
-            ),
+            patch.object(EnterpriseRouteChecks, "is_llm_api_route_disabled", return_value=True),
             patch.object(
                 EnterpriseRouteChecks,
                 "is_management_routes_disabled",
@@ -2542,9 +2500,7 @@ class TestModelsRouteExemptFromDisableLLMEndpoints:
         EnterpriseRouteChecks = self._get_enterprise_route_checks()
 
         with (
-            patch.object(
-                EnterpriseRouteChecks, "is_llm_api_route_disabled", return_value=False
-            ),
+            patch.object(EnterpriseRouteChecks, "is_llm_api_route_disabled", return_value=False),
             patch.object(
                 EnterpriseRouteChecks,
                 "is_management_routes_disabled",
@@ -2563,9 +2519,7 @@ def test_route_in_additional_public_routes_wildcard_match():
     from litellm.proxy.auth.auth_utils import route_in_additonal_public_routes
 
     with (
-        patch(
-            "litellm.proxy.proxy_server.general_settings", {"public_routes": ["/api/*"]}
-        ),
+        patch("litellm.proxy.proxy_server.general_settings", {"public_routes": ["/api/*"]}),
         patch("litellm.proxy.proxy_server.premium_user", True),
     ):
         # Wildcard should match subpaths
@@ -2657,7 +2611,7 @@ def test_non_admin_non_team_admin_cannot_access_config_update_but_can_attempt_re
     )
 
     # /config/update is still blocked
-    with pytest.raises(Exception, match='Only proxy admin can be used to generate, delete, update') as exc_info:
+    with pytest.raises(Exception, match="Only proxy admin can be used to generate, delete, update") as exc_info:
         RouteChecks.non_proxy_admin_allowed_routes_check(
             user_obj=user_obj,
             _user_role=LitellmUserRoles.INTERNAL_USER.value,
@@ -2745,8 +2699,6 @@ def test_available_roles_accessible_to_non_admin_users(user_role):
 # ── _user_is_org_admin tests ──────────────────────────────────────────────────
 
 
-
-
 def _make_org_admin_user(org_id: str) -> LiteLLM_UserTable:
     membership = LiteLLM_OrganizationMembershipTable(
         user_id="org-admin-user",
@@ -2869,9 +2821,7 @@ async def test_add_team_org_context_noop_when_org_id_already_present():
         raise AssertionError("must not resolve when organization_id is present")
 
     body = {"team_id": "team-1", "organization_id": "org-explicit"}
-    out = await add_team_org_context_to_request_body(
-        route="/team/update", request_body=body, fetch_team_org_id=fetch
-    )
+    out = await add_team_org_context_to_request_body(route="/team/update", request_body=body, fetch_team_org_id=fetch)
     assert out == body
 
 
@@ -2883,9 +2833,7 @@ async def test_add_team_org_context_noop_for_other_routes():
         raise AssertionError("must not resolve for a non-opted-in route")
 
     body = {"team_id": "team-1"}
-    out = await add_team_org_context_to_request_body(
-        route="/team/delete", request_body=body, fetch_team_org_id=fetch
-    )
+    out = await add_team_org_context_to_request_body(route="/team/delete", request_body=body, fetch_team_org_id=fetch)
     assert out == body
 
 
@@ -2898,9 +2846,7 @@ async def test_add_team_org_context_noop_when_team_has_no_org():
         return None
 
     body = {"team_id": "team-1"}
-    out = await add_team_org_context_to_request_body(
-        route="/team/update", request_body=body, fetch_team_org_id=fetch
-    )
+    out = await add_team_org_context_to_request_body(route="/team/update", request_body=body, fetch_team_org_id=fetch)
     assert out == body
 
 
@@ -3171,9 +3117,7 @@ async def test_initialize_pass_through_registers_wildcard_for_auth_subpath():
             # Removing the endpoint should clean up openai_routes
             # remove_endpoint_routes takes endpoint_id (UUID portion of
             # the route key "{id}:exact:{path}:{methods}")
-            registered = (
-                InitPassThroughEndpointHelpers.get_all_registered_pass_through_routes()
-            )
+            registered = InitPassThroughEndpointHelpers.get_all_registered_pass_through_routes()
             endpoint_ids = {k.split(":")[0] for k in registered}
             for eid in endpoint_ids:
                 InitPassThroughEndpointHelpers.remove_endpoint_routes(eid)
@@ -3183,9 +3127,7 @@ async def test_initialize_pass_through_registers_wildcard_for_auth_subpath():
         LiteLLMRoutes.openai_routes.value[:] = original_routes
         # Clean up any routes registered during this test to avoid
         # polluting the module-level _registered_pass_through_routes
-        registered = (
-            InitPassThroughEndpointHelpers.get_all_registered_pass_through_routes()
-        )
+        registered = InitPassThroughEndpointHelpers.get_all_registered_pass_through_routes()
         for k in registered:
             InitPassThroughEndpointHelpers.remove_endpoint_routes(k.split(":")[0])
 
@@ -3216,8 +3158,7 @@ def test_provider_name_substring_not_classified_as_llm_route(route):
     from litellm.proxy.auth.route_checks import RouteChecks
 
     assert RouteChecks.is_llm_api_route(route=route) is False, (
-        f"{route!r} should NOT be classified as an LLM API route — "
-        "provider-name substring match bypass"
+        f"{route!r} should NOT be classified as an LLM API route — provider-name substring match bypass"
     )
 
 
@@ -3239,9 +3180,7 @@ def test_legitimate_passthrough_routes_still_classified_as_llm_route(route):
     """Legitimate passthrough routes must still pass is_llm_api_route."""
     from litellm.proxy.auth.route_checks import RouteChecks
 
-    assert (
-        RouteChecks.is_llm_api_route(route=route) is True
-    ), f"{route!r} should be classified as an LLM API route"
+    assert RouteChecks.is_llm_api_route(route=route) is True, f"{route!r} should be classified as an LLM API route"
 
 
 @pytest.mark.parametrize(
@@ -3299,7 +3238,7 @@ def test_internal_user_blocked_from_search_tool_writes(route):
     request = MagicMock(spec=Request)
     request.query_params = {}
 
-    with pytest.raises(Exception, match='Only proxy admin can be used to generate, delete, update') as exc_info:
+    with pytest.raises(Exception, match="Only proxy admin can be used to generate, delete, update") as exc_info:
         RouteChecks.non_proxy_admin_allowed_routes_check(
             user_obj=user_obj,
             _user_role=LitellmUserRoles.INTERNAL_USER.value,
@@ -3675,12 +3614,7 @@ def test_agent_inference_routes_stay_llm_api(route):
 def test_agent_routes_union_still_covers_both_halves(route):
     """Keys configured with allowed_routes=["agent_routes"] must keep both halves."""
 
-    assert (
-        RouteChecks.check_route_access(
-            route=route, allowed_routes=LiteLLMRoutes.agent_routes.value
-        )
-        is True
-    )
+    assert RouteChecks.check_route_access(route=route, allowed_routes=LiteLLMRoutes.agent_routes.value) is True
 
 
 @pytest.mark.parametrize("route", AGENT_MANAGEMENT_ROUTES)
@@ -3734,6 +3668,136 @@ def test_agent_registry_route_gate_open_to_non_admin_roles(user_role, method, ro
         valid_token=valid_token,
         request_data={},
     )
+
+
+def test_proxy_admin_viewer_user_update_password_param_rejected():
+    """The self-service /user/update password carve-out is closed: non-admins
+    change their own password through /user/password/change, which verifies
+    the current password. Admin password sets don't pass through this check."""
+    with pytest.raises(HTTPException) as exc_info:
+        RouteChecks._check_proxy_admin_viewer_access(
+            route="/user/update",
+            _user_role=LitellmUserRoles.PROXY_ADMIN_VIEW_ONLY.value,
+            request_data={"password": "hunter2hunter2"},
+        )
+    assert exc_info.value.status_code == 403
+    assert "password" in str(exc_info.value.detail)
+
+
+def test_proxy_admin_viewer_user_update_user_email_still_allowed():
+    request = MagicMock(spec=Request)
+    request.method = "POST"
+
+    allowed = RouteChecks._check_proxy_admin_viewer_access(
+        route="/user/update",
+        _user_role=LitellmUserRoles.PROXY_ADMIN_VIEW_ONLY.value,
+        request_data={"user_email": "viewer@example.com"},
+        request=request,
+    )
+
+    assert allowed is None
+
+
+def test_proxy_admin_viewer_can_change_own_password():
+    request = MagicMock(spec=Request)
+    request.method = "POST"
+
+    allowed = RouteChecks._check_proxy_admin_viewer_access(
+        route="/user/password/change",
+        _user_role=LitellmUserRoles.PROXY_ADMIN_VIEW_ONLY.value,
+        request_data={"current_password": "a", "new_password": "b"},
+        request=request,
+    )
+
+    assert allowed is None
+
+
+@pytest.mark.parametrize(
+    "user_role",
+    [
+        LitellmUserRoles.INTERNAL_USER.value,
+        LitellmUserRoles.INTERNAL_USER_VIEW_ONLY.value,
+    ],
+)
+def test_non_admin_roles_can_change_own_password(user_role):
+    valid_token = UserAPIKeyAuth(user_id="test_user", user_role=user_role)
+    request = MagicMock(spec=Request)
+    request.method = "POST"
+    request.query_params = {}
+
+    allowed = RouteChecks.non_proxy_admin_allowed_routes_check(
+        user_obj=LiteLLM_UserTable(user_id="test_user", user_role=user_role),
+        _user_role=user_role,
+        route="/user/password/change",
+        request=request,
+        valid_token=valid_token,
+        request_data={"current_password": "a", "new_password": "b"},
+    )
+
+    assert allowed is None
+
+
+def _password_reset_session_token() -> UserAPIKeyAuth:
+    """The UI session key `authenticate_user` mints for a user flagged
+    `password_reset_required`."""
+    return UserAPIKeyAuth(
+        user_id="flagged_user",
+        allowed_routes=["/user/password/change"],
+        metadata={"password_reset_required": True},
+    )
+
+
+def test_password_reset_session_can_reach_change_password():
+    result = RouteChecks.is_virtual_key_allowed_to_call_route(
+        route="/user/password/change",
+        valid_token=_password_reset_session_token(),
+    )
+
+    assert result is True
+
+
+@pytest.mark.parametrize(
+    "route",
+    [
+        "/user/info",
+        "/key/generate",
+        "/user/update",
+        "/chat/completions",
+    ],
+)
+def test_password_reset_session_is_blocked_everywhere_else_with_reset_message(route):
+    """Server-side enforcement of the forced reset: a script that logs in via
+    /v2/login and drives the management API with the session key must get a 403
+    naming the remediation endpoint, on every route but the change-password one."""
+    with pytest.raises(HTTPException) as exc_info:
+        RouteChecks.is_virtual_key_allowed_to_call_route(
+            route=route,
+            valid_token=_password_reset_session_token(),
+        )
+
+    assert exc_info.value.status_code == 403
+    assert "password must be changed" in str(exc_info.value.detail)
+    assert "/user/password/change" in str(exc_info.value.detail)
+
+
+def test_restricted_key_without_reset_marker_keeps_generic_message():
+    """The reset-specific 403 must not leak onto ordinary allowed_routes keys."""
+    valid_token = UserAPIKeyAuth(
+        user_id="test_user",
+        allowed_routes=["/chat/completions"],
+    )
+
+    with pytest.raises(HTTPException) as exc_info:
+        RouteChecks.is_virtual_key_allowed_to_call_route(
+            route="/user/info",
+            valid_token=valid_token,
+        )
+
+    assert exc_info.value.status_code == 403
+    assert "password must be changed" not in str(exc_info.value.detail)
+    assert "not allowed to call this route" in str(exc_info.value.detail)
+
+
 TEAM_CALLBACK_ROUTES = (
     "/team/06bda574-5ca9-43d3-beb8-3b23c2f17112/callback",
     "/team/06bda574-5ca9-43d3-beb8-3b23c2f17112/callback/langfuse",
diff --git a/tests/test_litellm/proxy/management_endpoints/test_internal_user_endpoints.py b/tests/test_litellm/proxy/management_endpoints/test_internal_user_endpoints.py
index b8f1aa0330b..6e11dbb6bae 100644
--- a/tests/test_litellm/proxy/management_endpoints/test_internal_user_endpoints.py
+++ b/tests/test_litellm/proxy/management_endpoints/test_internal_user_endpoints.py
@@ -1,13 +1,18 @@
+import hashlib
 import json
 from datetime import datetime, timezone
 from types import SimpleNamespace
 from typing import Final
 
+import httpx
 import pytest
+import respx
 from fastapi import HTTPException
 from fastapi.testclient import TestClient
 from pytest_mock import MockerFixture
 
+from litellm.llms.custom_httpx.http_handler import AsyncHTTPHandler
+
 from litellm.proxy._types import (
     LiteLLM_UserTableFiltered,
     LitellmUserRoles,
@@ -67,9 +72,7 @@ async def test_ui_view_users_with_null_email(mocker, caplog):
 
     # Proxy admin: no org filter, no get_user_object call
     response = await ui_view_users(
-        user_api_key_dict=UserAPIKeyAuth(
-            user_id="test_user", user_role=LitellmUserRoles.PROXY_ADMIN
-        ),
+        user_api_key_dict=UserAPIKeyAuth(user_id="test_user", user_role=LitellmUserRoles.PROXY_ADMIN),
         user_id="test_user",
         user_email=None,
         team_id=None,
@@ -77,9 +80,7 @@ async def test_ui_view_users_with_null_email(mocker, caplog):
         page_size=50,
     )
 
-    assert response == [
-        LiteLLM_UserTableFiltered(user_id="test-user-null-email", user_email=None)
-    ]
+    assert response == [LiteLLM_UserTableFiltered(user_id="test-user-null-email", user_email=None)]
 
 
 @pytest.mark.asyncio
@@ -103,9 +104,7 @@ async def test_ui_view_users_proxy_admin_no_org_filter(mocker):
     mocker.patch("litellm.proxy.proxy_server.prisma_client", mock_prisma_client)
 
     await ui_view_users(
-        user_api_key_dict=UserAPIKeyAuth(
-            user_id="admin", user_role=LitellmUserRoles.PROXY_ADMIN
-        ),
+        user_api_key_dict=UserAPIKeyAuth(user_id="admin", user_role=LitellmUserRoles.PROXY_ADMIN),
         user_id=None,
         user_email="foo",
         team_id=None,
@@ -128,9 +127,7 @@ async def test_ui_view_users_org_admin_filtered_by_org(mocker):
     async def mock_find_many(*args, **kwargs):
         where = kwargs.get("where") or {}
         assert "organization_memberships" in where
-        assert where["organization_memberships"] == {
-            "some": {"organization_id": {"in": [org_id]}}
-        }
+        assert where["organization_memberships"] == {"some": {"organization_id": {"in": [org_id]}}}
         return []
 
     mock_prisma_client.db.litellm_usertable.find_many = mock_find_many
@@ -268,9 +265,7 @@ async def test_ui_view_users_flag_on_team_admin_org_team(mocker):
     async def mock_find_many(*args, **kwargs):
         where = kwargs.get("where") or {}
         assert "organization_memberships" in where
-        assert where["organization_memberships"] == {
-            "some": {"organization_id": {"in": [org_id]}}
-        }
+        assert where["organization_memberships"] == {"some": {"organization_id": {"in": [org_id]}}}
         return []
 
     mock_prisma_client.db.litellm_usertable.find_many = mock_find_many
@@ -401,9 +396,7 @@ async def test_ui_view_users_flag_on_team_admin_org_member_no_team_id(mocker):
     async def mock_find_many(*args, **kwargs):
         where = kwargs.get("where") or {}
         assert "organization_memberships" in where
-        assert where["organization_memberships"] == {
-            "some": {"organization_id": {"in": [org_id]}}
-        }
+        assert where["organization_memberships"] == {"some": {"organization_id": {"in": [org_id]}}}
         return []
 
     mock_prisma_client.db.litellm_usertable.find_many = mock_find_many
@@ -462,9 +455,7 @@ async def test_ui_view_users_flag_on_team_admin_not_in_org_resolves_via_key_team
     async def mock_find_many(*args, **kwargs):
         where = kwargs.get("where") or {}
         assert "organization_memberships" in where
-        assert where["organization_memberships"] == {
-            "some": {"organization_id": {"in": [org_id]}}
-        }
+        assert where["organization_memberships"] == {"some": {"organization_id": {"in": [org_id]}}}
         return []
 
     mock_prisma_client.db.litellm_usertable.find_many = mock_find_many
@@ -507,9 +498,7 @@ async def test_ui_view_users_flag_on_team_admin_not_in_org_resolves_via_key_team
 
     # No team_id query param, but team_id on the API key
     response = await ui_view_users(
-        user_api_key_dict=UserAPIKeyAuth(
-            user_id="team-admin-no-org", user_role=None, team_id=tid
-        ),
+        user_api_key_dict=UserAPIKeyAuth(user_id="team-admin-no-org", user_role=None, team_id=tid),
         user_id=None,
         user_email="u",
         team_id=None,
@@ -538,13 +527,9 @@ def test_user_daily_activity_types():
     # Assert all fields in SpendMetrics are reported in DailySpendMetadata as "total_"
     for field in spend_metrics.__dict__:
         if field.startswith("total_"):
-            assert hasattr(
-                daily_spend_metadata, field
-            ), f"Field {field} is not reported in DailySpendMetadata"
+            assert hasattr(daily_spend_metadata, field), f"Field {field} is not reported in DailySpendMetadata"
         else:
-            assert not hasattr(
-                daily_spend_metadata, field
-            ), f"Field {field} is reported in DailySpendMetadata"
+            assert not hasattr(daily_spend_metadata, field), f"Field {field} is reported in DailySpendMetadata"
 
 
 @pytest.mark.asyncio
@@ -591,9 +576,7 @@ async def test_get_users_includes_timestamps(mocker):
 
     # Call get_users function directly with proxy admin auth
     admin_key = UserAPIKeyAuth(user_id="admin", user_role=LitellmUserRoles.PROXY_ADMIN)
-    response = await get_users(
-        page=1, page_size=1, user_api_key_dict=admin_key, organization_ids=None
-    )
+    response = await get_users(page=1, page_size=1, user_api_key_dict=admin_key, organization_ids=None)
 
     print("user /list response: ", response)
 
@@ -654,14 +637,10 @@ async def test_get_users_redacts_scim_enterprise_metadata(mocker):
     )
 
     admin_key = UserAPIKeyAuth(user_id="admin", user_role=LitellmUserRoles.PROXY_ADMIN)
-    response = await get_users(
-        page=1, page_size=1, user_api_key_dict=admin_key, organization_ids=None
-    )
+    response = await get_users(page=1, page_size=1, user_api_key_dict=admin_key, organization_ids=None)
 
     listed = response["users"][0]
-    assert listed.metadata == {
-        "scim_metadata": {"givenName": "Jane", "familyName": "Doe"}
-    }
+    assert listed.metadata == {"scim_metadata": {"givenName": "Jane", "familyName": "Doe"}}
     assert "scim_enterprise" not in (listed.metadata or {})
 
 
@@ -853,9 +832,7 @@ async def test_new_user_license_over_limit(mocker):
     mocker.patch("litellm.proxy.proxy_server._license_check", mock_license_check)
 
     # Create test request data
-    user_request = NewUserRequest(
-        user_email="test@example.com", user_role="internal_user"
-    )
+    user_request = NewUserRequest(user_email="test@example.com", user_role="internal_user")
 
     # Mock user_api_key_dict
     mock_user_api_key_dict = UserAPIKeyAuth(user_id="test_admin")
@@ -916,9 +893,7 @@ async def test_new_user_license_gate_counts_only_billable_users(mocker):
     request = NewUserRequest(user_role="internal_user")
 
     # 2 active + 3 deactivated -> billable 2, not over max_users 2: gate passes
-    mocker.patch(
-        "litellm.proxy.proxy_server.prisma_client", _prisma(total=5, deactivated=3)
-    )
+    mocker.patch("litellm.proxy.proxy_server.prisma_client", _prisma(total=5, deactivated=3))
     with pytest.raises(ProxyException) as passed:
         await new_user(data=request, user_api_key_dict=admin)
     assert key_gen.call_count == 1
@@ -926,9 +901,7 @@ async def test_new_user_license_gate_counts_only_billable_users(mocker):
 
     # 3 active, 0 deactivated -> billable 3, over max_users 2: gate blocks
     key_gen.reset_mock()
-    mocker.patch(
-        "litellm.proxy.proxy_server.prisma_client", _prisma(total=3, deactivated=0)
-    )
+    mocker.patch("litellm.proxy.proxy_server.prisma_client", _prisma(total=3, deactivated=0))
     with pytest.raises(ProxyException) as blocked:
         await new_user(data=request, user_api_key_dict=admin)
     assert blocked.value.code == 403 or blocked.value.code == "403"
@@ -978,14 +951,10 @@ async def test_new_user_non_admin_cannot_create_admin(mocker):
     mocker.patch("litellm.proxy.proxy_server._license_check", mock_license_check)
 
     # Test Case 1: INTERNAL_USER trying to create PROXY_ADMIN
-    user_request = NewUserRequest(
-        user_email="admin@example.com", user_role=LitellmUserRoles.PROXY_ADMIN
-    )
+    user_request = NewUserRequest(user_email="admin@example.com", user_role=LitellmUserRoles.PROXY_ADMIN)
 
     # Mock user_api_key_dict with non-admin role
-    mock_user_api_key_dict = UserAPIKeyAuth(
-        user_id="test_internal_user", user_role=LitellmUserRoles.INTERNAL_USER
-    )
+    mock_user_api_key_dict = UserAPIKeyAuth(user_id="test_internal_user", user_role=LitellmUserRoles.INTERNAL_USER)
 
     # Call new_user function and expect ProxyException
     with pytest.raises(ProxyException) as exc_info:
@@ -993,9 +962,7 @@ async def test_new_user_non_admin_cannot_create_admin(mocker):
 
     # Verify the exception details
     assert exc_info.value.code == 403 or exc_info.value.code == "403"
-    assert "Only proxy admins can create administrative users" in str(
-        exc_info.value.message
-    )
+    assert "Only proxy admins can create administrative users" in str(exc_info.value.message)
     assert "proxy_admin" in str(exc_info.value.message)
     assert "proxy_admin_viewer" in str(exc_info.value.message)
     assert str(LitellmUserRoles.PROXY_ADMIN) in str(exc_info.value.message)
@@ -1008,15 +975,11 @@ async def test_new_user_non_admin_cannot_create_admin(mocker):
     )
 
     with pytest.raises(ProxyException) as exc_info2:
-        await new_user(
-            data=user_request_viewer, user_api_key_dict=mock_user_api_key_dict
-        )
+        await new_user(data=user_request_viewer, user_api_key_dict=mock_user_api_key_dict)
 
     # Verify the exception details
     assert exc_info2.value.code == 403 or exc_info2.value.code == "403"
-    assert "Only proxy admins can create administrative users" in str(
-        exc_info2.value.message
-    )
+    assert "Only proxy admins can create administrative users" in str(exc_info2.value.message)
     assert str(LitellmUserRoles.PROXY_ADMIN_VIEW_ONLY) in str(exc_info2.value.message)
 
 
@@ -1055,9 +1018,7 @@ async def test_new_user_non_admin_permissions_non_empty_rejected(mocker):
         user_role=LitellmUserRoles.INTERNAL_USER,
         permissions={"get_spend_routes": True},
     )
-    caller = UserAPIKeyAuth(
-        user_id="org-admin", user_role=LitellmUserRoles.ORG_ADMIN
-    )
+    caller = UserAPIKeyAuth(user_id="org-admin", user_role=LitellmUserRoles.ORG_ADMIN)
 
     with pytest.raises(ProxyException) as exc_info:
         await new_user(data=data, user_api_key_dict=caller)
@@ -1101,9 +1062,7 @@ async def test_new_user_non_admin_permissions_explicit_empty_rejected(mocker):
         permissions={},
     )
     assert "permissions" in data.model_fields_set
-    caller = UserAPIKeyAuth(
-        user_id="org-admin", user_role=LitellmUserRoles.ORG_ADMIN
-    )
+    caller = UserAPIKeyAuth(user_id="org-admin", user_role=LitellmUserRoles.ORG_ADMIN)
 
     with pytest.raises(ProxyException) as exc_info:
         await new_user(data=data, user_api_key_dict=caller)
@@ -1156,9 +1115,7 @@ async def test_new_user_non_admin_omits_permissions_succeeds(mocker):
         user_role=LitellmUserRoles.INTERNAL_USER,
     )
     assert "permissions" not in data.model_fields_set
-    caller = UserAPIKeyAuth(
-        user_id="org-admin", user_role=LitellmUserRoles.ORG_ADMIN
-    )
+    caller = UserAPIKeyAuth(user_id="org-admin", user_role=LitellmUserRoles.ORG_ADMIN)
 
     result = await new_user(data=data, user_api_key_dict=caller)
     assert result is not None
@@ -1232,14 +1189,10 @@ async def test_update_single_user_non_admin_permissions_rejected(mocker):
         user_id="alice",
         permissions={"get_spend_routes": True},
     )
-    caller = UserAPIKeyAuth(
-        user_id="org-admin", user_role=LitellmUserRoles.ORG_ADMIN
-    )
+    caller = UserAPIKeyAuth(user_id="org-admin", user_role=LitellmUserRoles.ORG_ADMIN)
 
     with pytest.raises(HTTPException) as exc_info:
-        await _update_single_user_helper(
-            user_request=data, user_api_key_dict=caller
-        )
+        await _update_single_user_helper(user_request=data, user_api_key_dict=caller)
     assert exc_info.value.status_code == 403
     assert "permissions" in str(exc_info.value.detail)
 
@@ -1261,14 +1214,10 @@ async def test_update_single_user_non_admin_permissions_explicit_empty_rejected(
 
     data = UpdateUserRequest(user_id="alice", permissions={})
     assert "permissions" in data.model_fields_set
-    caller = UserAPIKeyAuth(
-        user_id="org-admin", user_role=LitellmUserRoles.ORG_ADMIN
-    )
+    caller = UserAPIKeyAuth(user_id="org-admin", user_role=LitellmUserRoles.ORG_ADMIN)
 
     with pytest.raises(HTTPException) as exc_info:
-        await _update_single_user_helper(
-            user_request=data, user_api_key_dict=caller
-        )
+        await _update_single_user_helper(user_request=data, user_api_key_dict=caller)
     assert exc_info.value.status_code == 403
     assert "permissions" in str(exc_info.value.detail)
 
@@ -1324,15 +1273,11 @@ async def test_user_info_url_encoding_plus_character(mocker):
     mock_request.url.query = "user_id=machine-user+alp-air-admin-b58-b@tempus.com"
 
     # Mock user_api_key_dict
-    mock_user_api_key_dict = UserAPIKeyAuth(
-        user_id="test_admin", user_role="proxy_admin"
-    )
+    mock_user_api_key_dict = UserAPIKeyAuth(user_id="test_admin", user_role="proxy_admin")
 
     # Call user_info function with the URL-decoded user_id (as FastAPI would pass it)
     # FastAPI would normally convert + to space, but our fix should handle this
-    decoded_user_id = (
-        "machine-user alp-air-admin-b58-b@tempus.com"  # What FastAPI gives us
-    )
+    decoded_user_id = "machine-user alp-air-admin-b58-b@tempus.com"  # What FastAPI gives us
     expected_user_id = "machine-user+alp-air-admin-b58-b@tempus.com"
 
     response = await user_info(
@@ -1383,9 +1328,7 @@ async def test_user_info_nonexistent_user(mocker):
     mock_request = mocker.MagicMock(spec=Request)
 
     # Mock user_api_key_dict
-    mock_user_api_key_dict = UserAPIKeyAuth(
-        user_id="test_admin", user_role="proxy_admin"
-    )
+    mock_user_api_key_dict = UserAPIKeyAuth(user_id="test_admin", user_role="proxy_admin")
 
     # Call user_info function with a non-existent user_id
     nonexistent_user_id = "nonexistent-user@example.com"
@@ -1423,14 +1366,10 @@ async def test_user_info_no_user_id_view_only_admin_gets_proxy_admin_payload(moc
         mock_get_user_info_for_proxy_admin,
     )
 
-    viewer = UserAPIKeyAuth(
-        user_id="viewer", user_role=LitellmUserRoles.PROXY_ADMIN_VIEW_ONLY.value
-    )
+    viewer = UserAPIKeyAuth(user_id="viewer", user_role=LitellmUserRoles.PROXY_ADMIN_VIEW_ONLY.value)
     mock_request = mocker.MagicMock(spec=Request)
 
-    response = await user_info(
-        user_id=None, user_api_key_dict=viewer, request=mock_request
-    )
+    response = await user_info(user_id=None, user_api_key_dict=viewer, request=mock_request)
 
     mock_get_user_info_for_proxy_admin.assert_awaited_once_with(user_api_key_dict=viewer)
     assert response is admin_payload
@@ -1457,9 +1396,7 @@ async def test_new_user_default_teams_flow(mocker):
     mock_prisma_client.db.litellm_usertable.count = mock_count
     persisted_user_row = mocker.MagicMock()
     persisted_user_row.teams = ["96fed65b-0182-4ff4-8429-2721cd7d42af"]
-    mock_prisma_client.db.litellm_usertable.find_unique = mocker.AsyncMock(
-        return_value=persisted_user_row
-    )
+    mock_prisma_client.db.litellm_usertable.find_unique = mocker.AsyncMock(return_value=persisted_user_row)
 
     # Mock duplicate checks to pass
     async def mock_check_duplicate_user_email(*args, **kwargs):
@@ -1527,26 +1464,20 @@ async def test_new_user_default_teams_flow(mocker):
         )
 
         # Create test request data WITHOUT teams (teams should come from defaults)
-        user_request = NewUserRequest(
-            user_email="test@example.com", user_role="internal_user"
-        )
+        user_request = NewUserRequest(user_email="test@example.com", user_role="internal_user")
 
         # Mock user_api_key_dict
         mock_user_api_key_dict = UserAPIKeyAuth(user_id="test_admin")
 
         # Call new_user function
-        response = await new_user(
-            data=user_request, user_api_key_dict=mock_user_api_key_dict
-        )
+        response = await new_user(data=user_request, user_api_key_dict=mock_user_api_key_dict)
 
         # Verify generate_key_helper_fn was called WITHOUT teams
         mock_generate_key_helper_fn.assert_called_once()
         call_kwargs = mock_generate_key_helper_fn.call_args.kwargs
 
         # Teams should be removed from the data passed to generate_key_helper_fn
-        assert (
-            "teams" not in call_kwargs
-        ), "Teams should not be passed to generate_key_helper_fn"
+        assert "teams" not in call_kwargs, "Teams should not be passed to generate_key_helper_fn"
         assert call_kwargs["request_type"] == "user"
         assert call_kwargs["user_email"] == "test@example.com"
         assert call_kwargs["user_role"] == "internal_user"
@@ -1591,24 +1522,16 @@ def test_update_internal_new_user_params_proxy_admin_role():
 
     try:
         # Create test data with PROXY_ADMIN role
-        data = NewUserRequest(
-            user_email="admin@example.com", user_role=LitellmUserRoles.PROXY_ADMIN.value
-        )
+        data = NewUserRequest(user_email="admin@example.com", user_role=LitellmUserRoles.PROXY_ADMIN.value)
         data_json = data.model_dump(exclude_unset=True)
 
         # Call the function
         result = _update_internal_new_user_params(data_json=data_json, data=data)
 
         # Assertions - default params should NOT be applied for PROXY_ADMIN
-        assert (
-            "max_budget" not in result
-        ), "Default max_budget should NOT be applied to PROXY_ADMIN"
-        assert (
-            "models" not in result
-        ), "Default models should NOT be applied to PROXY_ADMIN"
-        assert (
-            "tpm_limit" not in result
-        ), "Default tpm_limit should NOT be applied to PROXY_ADMIN"
+        assert "max_budget" not in result, "Default max_budget should NOT be applied to PROXY_ADMIN"
+        assert "models" not in result, "Default models should NOT be applied to PROXY_ADMIN"
+        assert "tpm_limit" not in result, "Default tpm_limit should NOT be applied to PROXY_ADMIN"
 
         # These should still work
         assert result["user_email"] == "admin@example.com"
@@ -1722,15 +1645,9 @@ async def test_check_duplicate_user_email_case_insensitive(mocker):
         user_email_clause = where_clause.get("user_email", {})
 
         # Check that the query structure is correct for case insensitive search
-        assert (
-            "equals" in user_email_clause
-        ), "Query should use 'equals' for case insensitive search"
-        assert (
-            user_email_clause.get("mode") == "insensitive"
-        ), "Query should use 'insensitive' mode"
-        assert (
-            user_email_clause.get("equals") == "user@example.com"
-        ), "Query should search for the provided email"
+        assert "equals" in user_email_clause, "Query should use 'equals' for case insensitive search"
+        assert user_email_clause.get("mode") == "insensitive", "Query should use 'insensitive' mode"
+        assert user_email_clause.get("equals") == "user@example.com", "Query should search for the provided email"
 
         return mock_existing_user  # Return existing user to simulate duplicate
 
@@ -1741,9 +1658,7 @@ async def test_check_duplicate_user_email_case_insensitive(mocker):
         await _check_duplicate_user_email("user@example.com", mock_prisma_client)
 
     assert exc_info.value.status_code == 409
-    assert "User with email User@Example.com already exists" in str(
-        exc_info.value.detail
-    )
+    assert "User with email User@Example.com already exists" in str(exc_info.value.detail)
 
     # Test Case 2: No duplicate found
     async def mock_find_first_no_duplicate(*args, **kwargs):
@@ -1768,9 +1683,7 @@ async def test_check_duplicate_user_email_case_insensitive(mocker):
         pytest.fail(f"Should not raise exception when no duplicate found, but got: {e}")
 
     # Test Case 3: None email should not cause issues
-    await _check_duplicate_user_email(
-        None, mock_prisma_client
-    )  # Should not raise exception
+    await _check_duplicate_user_email(None, mock_prisma_client)  # Should not raise exception
 
 
 @pytest.mark.asyncio
@@ -1880,9 +1793,7 @@ def test_process_keys_for_user_info_filters_dashboard_keys(monkeypatch):
 
     # Verify dashboard key is not in results
     result_team_ids = [key.get("team_id") for key in result]
-    assert (
-        UI_SESSION_TOKEN_TEAM_ID not in result_team_ids
-    ), "Dashboard key should be filtered out"
+    assert UI_SESSION_TOKEN_TEAM_ID not in result_team_ids, "Dashboard key should be filtered out"
 
     # Verify regular keys are included
     assert "regular-team" in result_team_ids, "Regular team key should be included"
@@ -1892,9 +1803,7 @@ def test_process_keys_for_user_info_filters_dashboard_keys(monkeypatch):
     result_tokens = [key.get("token") for key in result]
     assert "sk-regular-token" in result_tokens, "Regular key should be included"
     assert "sk-no-team-token" in result_tokens, "No-team key should be included"
-    assert (
-        "sk-dashboard-token" not in result_tokens
-    ), "Dashboard key should not be included"
+    assert "sk-dashboard-token" not in result_tokens, "Dashboard key should not be included"
 
 
 def test_process_keys_for_user_info_handles_none_keys(monkeypatch):
@@ -2419,9 +2328,7 @@ async def test_get_user_daily_activity_non_admin_cannot_view_other_users(monkeyp
         )
 
     assert exc_info.value.status_code == 403
-    assert "Non-admin users can only view their own spend data" in str(
-        exc_info.value.detail
-    )
+    assert "Non-admin users can only view their own spend data" in str(exc_info.value.detail)
 
     # Case 2: Non-admin omits user_id — should default to their own user_id
     mock_response = MagicMock()
@@ -2708,14 +2615,10 @@ async def test_delete_user_cleans_up_created_by_invitation_links(mocker):
     async def mock_find_unique(*args, **kwargs):
         return mock_user_row
 
-    mock_prisma_client.db.litellm_usertable.find_unique = mocker.AsyncMock(
-        side_effect=mock_find_unique
-    )
+    mock_prisma_client.db.litellm_usertable.find_unique = mocker.AsyncMock(side_effect=mock_find_unique)
 
     # Mock find_many for teams (no teams)
-    mock_prisma_client.db.litellm_teamtable.find_many = mocker.AsyncMock(
-        return_value=[]
-    )
+    mock_prisma_client.db.litellm_teamtable.find_many = mocker.AsyncMock(return_value=[])
 
     # Mock all delete_many calls
     mock_prisma_client.db.litellm_verificationtoken.find_many = mocker.AsyncMock(
@@ -2741,9 +2644,7 @@ async def test_delete_user_cleans_up_created_by_invitation_links(mocker):
 
     # Call delete_user
     data = DeleteUserRequest(user_ids=["admin-creator"])
-    user_api_key_dict = UserAPIKeyAuth(
-        user_id="proxy-admin", user_role=LitellmUserRoles.PROXY_ADMIN
-    )
+    user_api_key_dict = UserAPIKeyAuth(user_id="proxy-admin", user_role=LitellmUserRoles.PROXY_ADMIN)
 
     await delete_user(data=data, user_api_key_dict=user_api_key_dict)
 
@@ -2752,9 +2653,7 @@ async def test_delete_user_cleans_up_created_by_invitation_links(mocker):
     call_kwargs = mock_prisma_client.db.litellm_invitationlink.delete_many.call_args
     where_clause = call_kwargs.kwargs.get("where") or call_kwargs[1].get("where")
 
-    assert (
-        "OR" in where_clause
-    ), "Should use OR to match user_id, created_by, and updated_by"
+    assert "OR" in where_clause, "Should use OR to match user_id, created_by, and updated_by"
     or_conditions = where_clause["OR"]
     assert len(or_conditions) == 3, "Should have 3 OR conditions"
 
@@ -2875,9 +2774,7 @@ async def test_delete_user_rejects_org_admin_deleting_outside_scope(mocker):
     async def mock_find_unique(*args, **kwargs):
         return mock_target_user
 
-    mock_prisma_client.db.litellm_usertable.find_unique = mocker.AsyncMock(
-        side_effect=mock_find_unique
-    )
+    mock_prisma_client.db.litellm_usertable.find_unique = mocker.AsyncMock(side_effect=mock_find_unique)
 
     # Caller (org_admin_user) administers org-A.
     caller_membership = mocker.MagicMock()
@@ -2903,16 +2800,12 @@ async def test_delete_user_rejects_org_admin_deleting_outside_scope(mocker):
             return [caller_membership]
         return []
 
-    mock_prisma_client.db.litellm_organizationmembership.find_many = mocker.AsyncMock(
-        side_effect=mock_find_memberships
-    )
+    mock_prisma_client.db.litellm_organizationmembership.find_many = mocker.AsyncMock(side_effect=mock_find_memberships)
 
     mocker.patch("litellm.proxy.proxy_server.prisma_client", mock_prisma_client)
 
     data = DeleteUserRequest(user_ids=["victim"])
-    user_api_key_dict = UserAPIKeyAuth(
-        user_id="org_admin_user", user_role=LitellmUserRoles.ORG_ADMIN
-    )
+    user_api_key_dict = UserAPIKeyAuth(user_id="org_admin_user", user_role=LitellmUserRoles.ORG_ADMIN)
 
     with pytest.raises(HTTPException) as exc:
         await delete_user(data=data, user_api_key_dict=user_api_key_dict)
@@ -2920,11 +2813,8 @@ async def test_delete_user_rejects_org_admin_deleting_outside_scope(mocker):
 
     # Critical: no delete_many calls should have executed.
     assert (
-        not hasattr(
-            mock_prisma_client.db.litellm_verificationtoken.delete_many, "mock_calls"
-        )
-        or len(mock_prisma_client.db.litellm_verificationtoken.delete_many.mock_calls)
-        == 0
+        not hasattr(mock_prisma_client.db.litellm_verificationtoken.delete_many, "mock_calls")
+        or len(mock_prisma_client.db.litellm_verificationtoken.delete_many.mock_calls) == 0
     )
 
 
@@ -2943,9 +2833,7 @@ async def test_user_update_rejects_silent_create_for_non_proxy_admin(mocker):
 
     mock_prisma_client = mocker.MagicMock()
     # user_email lookup yields None → would silently create pre-fix.
-    mock_prisma_client.db.litellm_usertable.find_first = mocker.AsyncMock(
-        return_value=None
-    )
+    mock_prisma_client.db.litellm_usertable.find_first = mocker.AsyncMock(return_value=None)
     mocker.patch("litellm.proxy.proxy_server.prisma_client", mock_prisma_client)
 
     user_request = UpdateUserRequest(
@@ -2959,9 +2847,7 @@ async def test_user_update_rejects_silent_create_for_non_proxy_admin(mocker):
     )
 
     with pytest.raises(HTTPException) as exc:
-        await _update_single_user_helper(
-            user_request=user_request, user_api_key_dict=org_admin
-        )
+        await _update_single_user_helper(user_request=user_request, user_api_key_dict=org_admin)
     assert exc.value.status_code == 404
 
 
@@ -3005,17 +2891,13 @@ async def test_user_info_v2_proxy_admin_can_query_any_user(mocker):
             return mock_user_row
         return None
 
-    mock_prisma_client.db.litellm_usertable.find_unique = mocker.AsyncMock(
-        side_effect=mock_find_unique
-    )
+    mock_prisma_client.db.litellm_usertable.find_unique = mocker.AsyncMock(side_effect=mock_find_unique)
 
     mocker.patch("litellm.proxy.proxy_server.prisma_client", mock_prisma_client)
 
     mock_request = mocker.MagicMock(spec=Request)
 
-    admin_key = UserAPIKeyAuth(
-        user_id="admin-user", user_role=LitellmUserRoles.PROXY_ADMIN
-    )
+    admin_key = UserAPIKeyAuth(user_id="admin-user", user_role=LitellmUserRoles.PROXY_ADMIN)
 
     response = await user_info_v2(
         request=mock_request,
@@ -3069,17 +2951,13 @@ async def test_user_info_v2_redacts_scim_enterprise_metadata(mocker):
             return mock_user_row
         return None
 
-    mock_prisma_client.db.litellm_usertable.find_unique = mocker.AsyncMock(
-        side_effect=mock_find_unique
-    )
+    mock_prisma_client.db.litellm_usertable.find_unique = mocker.AsyncMock(side_effect=mock_find_unique)
 
     mocker.patch("litellm.proxy.proxy_server.prisma_client", mock_prisma_client)
 
     mock_request = mocker.MagicMock(spec=Request)
 
-    admin_key = UserAPIKeyAuth(
-        user_id="admin-user", user_role=LitellmUserRoles.PROXY_ADMIN
-    )
+    admin_key = UserAPIKeyAuth(user_id="admin-user", user_role=LitellmUserRoles.PROXY_ADMIN)
 
     response = await user_info_v2(
         request=mock_request,
@@ -3088,9 +2966,7 @@ async def test_user_info_v2_redacts_scim_enterprise_metadata(mocker):
     )
 
     assert isinstance(response, UserInfoV2Response)
-    assert response.metadata == {
-        "scim_metadata": {"givenName": "Jane", "familyName": "Doe"}
-    }
+    assert response.metadata == {"scim_metadata": {"givenName": "Jane", "familyName": "Doe"}}
     assert "scim_enterprise" not in (response.metadata or {})
 
 
@@ -3159,17 +3035,13 @@ async def test_user_info_v2_internal_user_can_query_self(mocker):
             return mock_user_row
         return None
 
-    mock_prisma_client.db.litellm_usertable.find_unique = mocker.AsyncMock(
-        side_effect=mock_find_unique
-    )
+    mock_prisma_client.db.litellm_usertable.find_unique = mocker.AsyncMock(side_effect=mock_find_unique)
 
     mocker.patch("litellm.proxy.proxy_server.prisma_client", mock_prisma_client)
 
     mock_request = mocker.MagicMock(spec=Request)
 
-    user_key = UserAPIKeyAuth(
-        user_id="self-user", user_role=LitellmUserRoles.INTERNAL_USER
-    )
+    user_key = UserAPIKeyAuth(user_id="self-user", user_role=LitellmUserRoles.INTERNAL_USER)
 
     response = await user_info_v2(
         request=mock_request,
@@ -3204,17 +3076,13 @@ async def test_user_info_v2_internal_user_cannot_query_other(mocker):
             return mock_caller_row
         return None
 
-    mock_prisma_client.db.litellm_usertable.find_unique = mocker.AsyncMock(
-        side_effect=mock_find_unique
-    )
+    mock_prisma_client.db.litellm_usertable.find_unique = mocker.AsyncMock(side_effect=mock_find_unique)
 
     mocker.patch("litellm.proxy.proxy_server.prisma_client", mock_prisma_client)
 
     mock_request = mocker.MagicMock(spec=Request)
 
-    user_key = UserAPIKeyAuth(
-        user_id="caller-user", user_role=LitellmUserRoles.INTERNAL_USER
-    )
+    user_key = UserAPIKeyAuth(user_id="caller-user", user_role=LitellmUserRoles.INTERNAL_USER)
 
     with pytest.raises(ProxyException) as exc_info:
         await user_info_v2(
@@ -3261,17 +3129,13 @@ async def test_user_info_v2_no_user_id_defaults_to_self(mocker):
             return mock_user_row
         return None
 
-    mock_prisma_client.db.litellm_usertable.find_unique = mocker.AsyncMock(
-        side_effect=mock_find_unique
-    )
+    mock_prisma_client.db.litellm_usertable.find_unique = mocker.AsyncMock(side_effect=mock_find_unique)
 
     mocker.patch("litellm.proxy.proxy_server.prisma_client", mock_prisma_client)
 
     mock_request = mocker.MagicMock(spec=Request)
 
-    user_key = UserAPIKeyAuth(
-        user_id="my-user-id", user_role=LitellmUserRoles.INTERNAL_USER
-    )
+    user_key = UserAPIKeyAuth(user_id="my-user-id", user_role=LitellmUserRoles.INTERNAL_USER)
 
     # Call without user_id
     response = await user_info_v2(
@@ -3299,17 +3163,13 @@ async def test_user_info_v2_nonexistent_user_returns_404(mocker):
     async def mock_find_unique(*args, **kwargs):
         return None
 
-    mock_prisma_client.db.litellm_usertable.find_unique = mocker.AsyncMock(
-        side_effect=mock_find_unique
-    )
+    mock_prisma_client.db.litellm_usertable.find_unique = mocker.AsyncMock(side_effect=mock_find_unique)
 
     mocker.patch("litellm.proxy.proxy_server.prisma_client", mock_prisma_client)
 
     mock_request = mocker.MagicMock(spec=Request)
 
-    admin_key = UserAPIKeyAuth(
-        user_id="admin-user", user_role=LitellmUserRoles.PROXY_ADMIN
-    )
+    admin_key = UserAPIKeyAuth(user_id="admin-user", user_role=LitellmUserRoles.PROXY_ADMIN)
 
     with pytest.raises(ProxyException) as exc_info:
         await user_info_v2(
@@ -3357,17 +3217,13 @@ async def test_user_info_v2_response_shape(mocker):
     async def mock_find_unique(*args, **kwargs):
         return mock_user_row
 
-    mock_prisma_client.db.litellm_usertable.find_unique = mocker.AsyncMock(
-        side_effect=mock_find_unique
-    )
+    mock_prisma_client.db.litellm_usertable.find_unique = mocker.AsyncMock(side_effect=mock_find_unique)
 
     mocker.patch("litellm.proxy.proxy_server.prisma_client", mock_prisma_client)
 
     mock_request = mocker.MagicMock(spec=Request)
 
-    admin_key = UserAPIKeyAuth(
-        user_id="admin-user", user_role=LitellmUserRoles.PROXY_ADMIN
-    )
+    admin_key = UserAPIKeyAuth(user_id="admin-user", user_role=LitellmUserRoles.PROXY_ADMIN)
 
     response = await user_info_v2(
         request=mock_request,
@@ -3402,9 +3258,7 @@ async def test_user_info_v2_response_shape(mocker):
 
     # The dashboard's user edit form hydrates its per-model budget rows from
     # these two, so dropping them makes a save replace the user's budgets.
-    assert response_dict["model_max_budget"] == {
-        "gpt-3.5-turbo": {"budget_limit": 5.0, "time_period": "30d"}
-    }
+    assert response_dict["model_max_budget"] == {"gpt-3.5-turbo": {"budget_limit": 5.0, "time_period": "30d"}}
     assert response_dict["model_max_budget_usage"] == {
         "gpt-3.5-turbo": {"current_spend": 0.0, "budget_limit": 5.0, "time_period": "30d"}
     }
@@ -3463,9 +3317,7 @@ async def test_user_info_v2_team_admin_can_query_team_member(mocker):
             return mock_target
         return None
 
-    mock_prisma_client.db.litellm_usertable.find_unique = mocker.AsyncMock(
-        side_effect=mock_find_unique
-    )
+    mock_prisma_client.db.litellm_usertable.find_unique = mocker.AsyncMock(side_effect=mock_find_unique)
 
     # Mock team with caller as admin
     mock_team = mocker.MagicMock()
@@ -3482,17 +3334,13 @@ async def test_user_info_v2_team_admin_can_query_team_member(mocker):
     async def mock_find_many_teams(*args, **kwargs):
         return [mock_team]
 
-    mock_prisma_client.db.litellm_teamtable.find_many = mocker.AsyncMock(
-        side_effect=mock_find_many_teams
-    )
+    mock_prisma_client.db.litellm_teamtable.find_many = mocker.AsyncMock(side_effect=mock_find_many_teams)
 
     mocker.patch("litellm.proxy.proxy_server.prisma_client", mock_prisma_client)
 
     mock_request = mocker.MagicMock(spec=Request)
 
-    team_admin_key = UserAPIKeyAuth(
-        user_id="team-admin-user", user_role=LitellmUserRoles.INTERNAL_USER
-    )
+    team_admin_key = UserAPIKeyAuth(user_id="team-admin-user", user_role=LitellmUserRoles.INTERNAL_USER)
 
     response = await user_info_v2(
         request=mock_request,
@@ -3532,9 +3380,7 @@ async def test_user_info_v2_team_admin_cannot_query_non_team_member(mocker):
             return mock_target
         return None
 
-    mock_prisma_client.db.litellm_usertable.find_unique = mocker.AsyncMock(
-        side_effect=mock_find_unique
-    )
+    mock_prisma_client.db.litellm_usertable.find_unique = mocker.AsyncMock(side_effect=mock_find_unique)
 
     # Mock team where caller is admin
     mock_team = mocker.MagicMock()
@@ -3550,17 +3396,13 @@ async def test_user_info_v2_team_admin_cannot_query_non_team_member(mocker):
     async def mock_find_many_teams(*args, **kwargs):
         return [mock_team]
 
-    mock_prisma_client.db.litellm_teamtable.find_many = mocker.AsyncMock(
-        side_effect=mock_find_many_teams
-    )
+    mock_prisma_client.db.litellm_teamtable.find_many = mocker.AsyncMock(side_effect=mock_find_many_teams)
 
     mocker.patch("litellm.proxy.proxy_server.prisma_client", mock_prisma_client)
 
     mock_request = mocker.MagicMock(spec=Request)
 
-    team_admin_key = UserAPIKeyAuth(
-        user_id="team-admin-user", user_role=LitellmUserRoles.INTERNAL_USER
-    )
+    team_admin_key = UserAPIKeyAuth(user_id="team-admin-user", user_role=LitellmUserRoles.INTERNAL_USER)
 
     with pytest.raises(ProxyException) as exc_info:
         await user_info_v2(
@@ -3610,18 +3452,14 @@ async def test_user_info_v2_url_encoding_plus_character(mocker):
             return mock_user_row
         return None
 
-    mock_prisma_client.db.litellm_usertable.find_unique = mocker.AsyncMock(
-        side_effect=mock_find_unique
-    )
+    mock_prisma_client.db.litellm_usertable.find_unique = mocker.AsyncMock(side_effect=mock_find_unique)
 
     mocker.patch("litellm.proxy.proxy_server.prisma_client", mock_prisma_client)
 
     mock_request = mocker.MagicMock(spec=Request)
     mock_request.url.query = f"user_id={expected_user_id}"
 
-    admin_key = UserAPIKeyAuth(
-        user_id="admin-user", user_role=LitellmUserRoles.PROXY_ADMIN
-    )
+    admin_key = UserAPIKeyAuth(user_id="admin-user", user_role=LitellmUserRoles.PROXY_ADMIN)
 
     # Simulate FastAPI converting + to space
     decoded_user_id = "machine-user admin@example.com"
@@ -3718,9 +3556,7 @@ def test_enforce_user_info_access_admin_bypass():
         _enforce_user_info_access,
     )
 
-    admin = UserAPIKeyAuth(
-        user_id="admin", user_role=LitellmUserRoles.PROXY_ADMIN.value
-    )
+    admin = UserAPIKeyAuth(user_id="admin", user_role=LitellmUserRoles.PROXY_ADMIN.value)
     # Should not raise even when querying a different user
     _enforce_user_info_access(user_id="someone_else", user_api_key_dict=admin)
 
@@ -3759,9 +3595,7 @@ def test_enforce_user_info_access_owner_allowed():
         _enforce_user_info_access,
     )
 
-    user = UserAPIKeyAuth(
-        user_id="alice", user_role=LitellmUserRoles.INTERNAL_USER.value
-    )
+    user = UserAPIKeyAuth(user_id="alice", user_role=LitellmUserRoles.INTERNAL_USER.value)
     _enforce_user_info_access(user_id="alice", user_api_key_dict=user)
 
 
@@ -3773,9 +3607,7 @@ def test_enforce_user_info_access_no_user_id_allowed():
         _enforce_user_info_access,
     )
 
-    user = UserAPIKeyAuth(
-        user_id="alice", user_role=LitellmUserRoles.INTERNAL_USER.value
-    )
+    user = UserAPIKeyAuth(user_id="alice", user_role=LitellmUserRoles.INTERNAL_USER.value)
     _enforce_user_info_access(user_id=None, user_api_key_dict=user)
 
 
@@ -3832,9 +3664,7 @@ async def test_ghsa_wvg4_non_admin_cannot_self_escalate_max_budget(mocker, budge
         "max_budget": 100,
     }
     existing_user.user_id = "user-1"
-    mock_prisma_client.db.litellm_usertable.find_first = mocker.AsyncMock(
-        return_value=existing_user
-    )
+    mock_prisma_client.db.litellm_usertable.find_first = mocker.AsyncMock(return_value=existing_user)
     mocker.patch("litellm.proxy.proxy_server.prisma_client", mock_prisma_client)
 
     user_request = UpdateUserRequest.model_validate({"user_id": "user-1", budget_field: budget_value})
@@ -3844,9 +3674,7 @@ async def test_ghsa_wvg4_non_admin_cannot_self_escalate_max_budget(mocker, budge
     )
 
     with pytest.raises(HTTPException) as exc:
-        await _update_single_user_helper(
-            user_request=user_request, user_api_key_dict=caller
-        )
+        await _update_single_user_helper(user_request=user_request, user_api_key_dict=caller)
     assert exc.value.status_code == 403
     assert budget_field in str(exc.value.detail)
     mock_prisma_client.update_data.assert_not_called()
@@ -3868,9 +3696,7 @@ async def test_ghsa_wvg4_non_admin_cannot_self_escalate_spend(mocker):
         "spend": 50.0,
     }
     existing_user.user_id = "user-1"
-    mock_prisma_client.db.litellm_usertable.find_first = mocker.AsyncMock(
-        return_value=existing_user
-    )
+    mock_prisma_client.db.litellm_usertable.find_first = mocker.AsyncMock(return_value=existing_user)
     mocker.patch("litellm.proxy.proxy_server.prisma_client", mock_prisma_client)
 
     user_request = UpdateUserRequest(
@@ -3883,9 +3709,7 @@ async def test_ghsa_wvg4_non_admin_cannot_self_escalate_spend(mocker):
     )
 
     with pytest.raises(HTTPException) as exc:
-        await _update_single_user_helper(
-            user_request=user_request, user_api_key_dict=caller
-        )
+        await _update_single_user_helper(user_request=user_request, user_api_key_dict=caller)
     assert exc.value.status_code == 403
     assert "spend" in str(exc.value.detail)
 
@@ -3904,12 +3728,8 @@ async def test_ghsa_wvg4_proxy_admin_can_update_user_budget(mocker):
         "max_budget": 100,
     }
     existing_user.user_id = "target-user"
-    mock_prisma_client.db.litellm_usertable.find_first = mocker.AsyncMock(
-        return_value=existing_user
-    )
-    mock_prisma_client.update_data = mocker.AsyncMock(
-        return_value={"user_id": "target-user", "max_budget": 500}
-    )
+    mock_prisma_client.db.litellm_usertable.find_first = mocker.AsyncMock(return_value=existing_user)
+    mock_prisma_client.update_data = mocker.AsyncMock(return_value={"user_id": "target-user", "max_budget": 500})
     mock_prisma_client.jsonify_object = mocker.MagicMock(side_effect=lambda x: x)
     mocker.patch("litellm.proxy.proxy_server.prisma_client", mock_prisma_client)
     mocker.patch("litellm.proxy.proxy_server.litellm_proxy_admin_name", "admin")
@@ -3923,9 +3743,7 @@ async def test_ghsa_wvg4_proxy_admin_can_update_user_budget(mocker):
         user_role=LitellmUserRoles.PROXY_ADMIN,
     )
 
-    result = await _update_single_user_helper(
-        user_request=user_request, user_api_key_dict=admin_caller
-    )
+    result = await _update_single_user_helper(user_request=user_request, user_api_key_dict=admin_caller)
     assert result is not None
 
 
@@ -3941,12 +3759,8 @@ async def test_admin_user_update_spend_invalidates_counter(mocker):
     existing_user = mocker.MagicMock()
     existing_user.model_dump.return_value = {"user_id": "target-user", "spend": 50.0}
     existing_user.user_id = "target-user"
-    mock_prisma_client.db.litellm_usertable.find_first = mocker.AsyncMock(
-        return_value=existing_user
-    )
-    mock_prisma_client.update_data = mocker.AsyncMock(
-        return_value={"user_id": "target-user", "spend": -25.0}
-    )
+    mock_prisma_client.db.litellm_usertable.find_first = mocker.AsyncMock(return_value=existing_user)
+    mock_prisma_client.update_data = mocker.AsyncMock(return_value={"user_id": "target-user", "spend": -25.0})
     mock_prisma_client.jsonify_object = mocker.MagicMock(side_effect=lambda x: x)
     mocker.patch("litellm.proxy.proxy_server.prisma_client", mock_prisma_client)
     mocker.patch("litellm.proxy.proxy_server.litellm_proxy_admin_name", "admin")
@@ -3961,13 +3775,9 @@ async def test_admin_user_update_spend_invalidates_counter(mocker):
     # without raising the recurring budget ceiling. Future changes should
     # continue allowing negative spend counters.
     user_request = UpdateUserRequest(user_id="target-user", spend=-25)
-    admin_caller = UserAPIKeyAuth(
-        user_id="admin-1", user_role=LitellmUserRoles.PROXY_ADMIN
-    )
+    admin_caller = UserAPIKeyAuth(user_id="admin-1", user_role=LitellmUserRoles.PROXY_ADMIN)
 
-    await _update_single_user_helper(
-        user_request=user_request, user_api_key_dict=admin_caller
-    )
+    await _update_single_user_helper(user_request=user_request, user_api_key_dict=admin_caller)
     mock_invalidate.assert_awaited_once_with(counter_key="spend:user:target-user")
 
 
@@ -3984,9 +3794,7 @@ async def test_user_update_rejects_non_finite_spend(mocker):
     existing_user = mocker.MagicMock()
     existing_user.model_dump.return_value = {"user_id": "target-user", "spend": 50.0}
     existing_user.user_id = "target-user"
-    mock_prisma_client.db.litellm_usertable.find_first = mocker.AsyncMock(
-        return_value=existing_user
-    )
+    mock_prisma_client.db.litellm_usertable.find_first = mocker.AsyncMock(return_value=existing_user)
     mock_prisma_client.update_data = mocker.AsyncMock()
     mocker.patch("litellm.proxy.proxy_server.prisma_client", mock_prisma_client)
     mocker.patch("litellm.proxy.proxy_server.litellm_proxy_admin_name", "admin")
@@ -3996,14 +3804,10 @@ async def test_user_update_rejects_non_finite_spend(mocker):
     )
 
     user_request = UpdateUserRequest(user_id="target-user", spend=float("nan"))
-    admin_caller = UserAPIKeyAuth(
-        user_id="admin-1", user_role=LitellmUserRoles.PROXY_ADMIN
-    )
+    admin_caller = UserAPIKeyAuth(user_id="admin-1", user_role=LitellmUserRoles.PROXY_ADMIN)
 
     with pytest.raises(HTTPException) as exc:
-        await _update_single_user_helper(
-            user_request=user_request, user_api_key_dict=admin_caller
-        )
+        await _update_single_user_helper(user_request=user_request, user_api_key_dict=admin_caller)
     assert exc.value.status_code == 400
     mock_prisma_client.update_data.assert_not_called()
     mock_invalidate.assert_not_awaited()
@@ -4023,9 +3827,7 @@ async def test_resolve_user_email_metadata_maps_page_user_ids_to_email(mocker):
     mock_prisma_client = mocker.MagicMock()
     find_many = mocker.AsyncMock(
         return_value=[
-            SimpleNamespace(
-                user_id="u1", user_email="alice@example.com", user_alias="Alice"
-            ),
+            SimpleNamespace(user_id="u1", user_email="alice@example.com", user_alias="Alice"),
             SimpleNamespace(user_id="u2", user_email=None, user_alias="bob-alias"),
         ]
     )
@@ -4224,19 +4026,13 @@ def _object_permission_mocks(mocker, existing_object_permission_id=None):
     }
     existing_user.user_id = "target-user"
     existing_user.object_permission_id = existing_object_permission_id
-    mock_prisma_client.db.litellm_usertable.find_first = mocker.AsyncMock(
-        return_value=existing_user
-    )
-    mock_prisma_client.db.litellm_objectpermissiontable.find_unique = mocker.AsyncMock(
-        return_value=None
-    )
+    mock_prisma_client.db.litellm_usertable.find_first = mocker.AsyncMock(return_value=existing_user)
+    mock_prisma_client.db.litellm_objectpermissiontable.find_unique = mocker.AsyncMock(return_value=None)
     mock_prisma_client.db.litellm_objectpermissiontable.upsert = mocker.AsyncMock(
         return_value=SimpleNamespace(object_permission_id="perm-new")
     )
     mock_prisma_client.db.litellm_mcpservertable.find_many = mocker.AsyncMock(return_value=[])
-    mock_prisma_client.update_data = mocker.AsyncMock(
-        return_value={"user_id": "target-user"}
-    )
+    mock_prisma_client.update_data = mocker.AsyncMock(return_value={"user_id": "target-user"})
     mock_prisma_client.jsonify_object = mocker.MagicMock(side_effect=lambda x: x)
     mocker.patch("litellm.proxy.proxy_server.prisma_client", mock_prisma_client)
     mocker.patch("litellm.proxy.proxy_server.litellm_proxy_admin_name", "admin")
@@ -4272,9 +4068,7 @@ async def test_user_update_persists_mcp_entitlement_and_links_it(mocker):
                 "mcp_tool_permissions": {"github": ["list_issues"]},
             },
         ),
-        user_api_key_dict=UserAPIKeyAuth(
-            user_id="admin-1", user_role=LitellmUserRoles.PROXY_ADMIN
-        ),
+        user_api_key_dict=UserAPIKeyAuth(user_id="admin-1", user_role=LitellmUserRoles.PROXY_ADMIN),
     )
 
     upsert_kwargs = mock_prisma_client.db.litellm_objectpermissiontable.upsert.call_args.kwargs
@@ -4308,9 +4102,7 @@ async def test_user_update_invalidates_the_cached_entitlement(mocker):
             user_id="target-user",
             object_permission={"mcp_tool_permissions": {"github": []}},
         ),
-        user_api_key_dict=UserAPIKeyAuth(
-            user_id="admin-1", user_role=LitellmUserRoles.PROXY_ADMIN
-        ),
+        user_api_key_dict=UserAPIKeyAuth(user_id="admin-1", user_role=LitellmUserRoles.PROXY_ADMIN),
     )
 
     deleted = {call.kwargs["key"] for call in cache.async_delete_cache.call_args_list}
@@ -4343,9 +4135,7 @@ async def test_admin_can_clear_a_users_mcp_entitlement(mocker):
 
     await _update_single_user_helper(
         user_request=UpdateUserRequest(user_id="target-user", object_permission={}),
-        user_api_key_dict=UserAPIKeyAuth(
-            user_id="admin-1", user_role=LitellmUserRoles.PROXY_ADMIN
-        ),
+        user_api_key_dict=UserAPIKeyAuth(user_id="admin-1", user_role=LitellmUserRoles.PROXY_ADMIN),
     )
 
     written = mock_prisma_client.update_data.call_args.kwargs["data"]
@@ -4382,9 +4172,7 @@ async def test_user_update_invalidates_both_the_old_and_new_permission_rows(mock
             user_id="target-user",
             object_permission={"mcp_tool_permissions": {"github": ["list_issues"]}},
         ),
-        user_api_key_dict=UserAPIKeyAuth(
-            user_id="admin-1", user_role=LitellmUserRoles.PROXY_ADMIN
-        ),
+        user_api_key_dict=UserAPIKeyAuth(user_id="admin-1", user_role=LitellmUserRoles.PROXY_ADMIN),
     )
 
     deleted = {call.kwargs["key"] for call in cache.async_delete_cache.call_args_list}
@@ -4415,9 +4203,7 @@ async def test_non_admin_cannot_clear_their_own_mcp_entitlement(mocker):
     with pytest.raises(HTTPException) as exc:
         await _update_single_user_helper(
             user_request=UpdateUserRequest(user_id="target-user", object_permission={}),
-            user_api_key_dict=UserAPIKeyAuth(
-                user_id="target-user", user_role=LitellmUserRoles.INTERNAL_USER
-            ),
+            user_api_key_dict=UserAPIKeyAuth(user_id="target-user", user_role=LitellmUserRoles.INTERNAL_USER),
         )
 
     assert exc.value.status_code == 403
@@ -4445,9 +4231,7 @@ async def test_non_admin_cannot_rewrite_their_own_mcp_entitlement(mocker):
                 user_id="target-user",
                 object_permission={"mcp_servers": [], "mcp_tool_permissions": {}},
             ),
-            user_api_key_dict=UserAPIKeyAuth(
-                user_id="target-user", user_role=LitellmUserRoles.INTERNAL_USER
-            ),
+            user_api_key_dict=UserAPIKeyAuth(user_id="target-user", user_role=LitellmUserRoles.INTERNAL_USER),
         )
 
     assert exc.value.status_code == 403
@@ -4464,9 +4248,7 @@ async def test_new_user_persists_the_requested_mcp_entitlement(mocker):
         return_value=SimpleNamespace(object_permission_id="perm-created")
     )
     mock_prisma_client.db.litellm_mcpservertable.find_many = mocker.AsyncMock(return_value=[])
-    mock_prisma_client.db.litellm_usertable.find_first = mocker.AsyncMock(
-        return_value=None
-    )
+    mock_prisma_client.db.litellm_usertable.find_first = mocker.AsyncMock(return_value=None)
     mock_prisma_client.db.litellm_usertable.count = mocker.AsyncMock(return_value=0)
     mocker.patch("litellm.proxy.proxy_server.prisma_client", mock_prisma_client)
     mocker.patch(
@@ -4475,9 +4257,7 @@ async def test_new_user_persists_the_requested_mcp_entitlement(mocker):
     )
     mock_generate = mocker.patch(
         "litellm.proxy.management_endpoints.internal_user_endpoints.generate_key_helper_fn",
-        new=mocker.AsyncMock(
-            return_value={"user_id": "new-human", "token": "sk-x", "expires": None}
-        ),
+        new=mocker.AsyncMock(return_value={"user_id": "new-human", "token": "sk-x", "expires": None}),
     )
     mocker.patch(
         "litellm.proxy.hooks.user_management_event_hooks.UserManagementEventHooks.async_user_created_hook",
@@ -4489,9 +4269,7 @@ async def test_new_user_persists_the_requested_mcp_entitlement(mocker):
             user_id="new-human",
             object_permission={"mcp_tool_permissions": {"github": ["list_issues"]}},
         ),
-        user_api_key_dict=UserAPIKeyAuth(
-            user_id="admin-1", user_role=LitellmUserRoles.PROXY_ADMIN
-        ),
+        user_api_key_dict=UserAPIKeyAuth(user_id="admin-1", user_role=LitellmUserRoles.PROXY_ADMIN),
     )
 
     created = mock_prisma_client.db.litellm_objectpermissiontable.create.call_args.kwargs["data"]
@@ -4533,16 +4311,12 @@ async def test_user_info_v2_returns_the_mcp_entitlement(mocker):
     response = await user_info_v2(
         request=SimpleNamespace(query_params={}),
         user_id="human-1",
-        user_api_key_dict=UserAPIKeyAuth(
-            user_id="admin-1", user_role=LitellmUserRoles.PROXY_ADMIN
-        ),
+        user_api_key_dict=UserAPIKeyAuth(user_id="admin-1", user_role=LitellmUserRoles.PROXY_ADMIN),
     )
 
     assert response.object_permission is not None
     assert response.object_permission.mcp_servers == ["github"]
-    assert response.object_permission.mcp_tool_permissions == {
-        "github": ["list_issues"]
-    }
+    assert response.object_permission.mcp_tool_permissions == {"github": ["list_issues"]}
 
 
 @pytest.mark.asyncio
@@ -4558,9 +4332,7 @@ async def test_user_info_v2_returns_the_mcp_entitlement(mocker):
     ],
     ids=["supplied", "omitted", "empty"],
 )
-async def test_user_new_persists_model_max_budget(
-    monkeypatch, model_max_budget, expected_written
-):
+async def test_user_new_persists_model_max_budget(monkeypatch, model_max_budget, expected_written):
     """
     /user/new used to echo model_max_budget back while writing {} to the user row,
     so a per-model budget looked configured and was read by nothing.
@@ -4674,6 +4446,11 @@ async def test_user_update_hashes_and_persists_strong_password(_admin_prisma, mo
         _update_single_user_helper,
     )
 
+    mocker.patch(  # test-quality-ok: same module-global mocking every test in this file already uses
+        "litellm.proxy.proxy_server.general_settings",
+        {"password_policy_check_breached_passwords": False},
+    )
+
     mock_prisma_client = _admin_prisma
     existing_user = mocker.MagicMock()
     existing_user.model_dump.return_value = {"user_id": "target-user"}
@@ -4691,3 +4468,149 @@ async def test_user_update_hashes_and_persists_strong_password(_admin_prisma, mo
     written_data = mock_prisma_client.update_data.call_args.kwargs["data"]
     assert written_data.get("password") is not None
     assert written_data["password"] != strong_password
+    # An admin-set password is known to the admin, so the user must be forced
+    # to change it at next login and the breach screen re-armed.
+    assert written_data["password_reset_required"] is True
+    assert written_data["last_breach_check_at"] is None
+
+
+@pytest.mark.asyncio
+@respx.mock
+async def test_user_update_rejects_breached_password(_admin_prisma):
+    """A strength-passing password found in the HIBP corpus must be rejected
+    before it ever reaches the DB write."""
+    from litellm.proxy.management_endpoints.internal_user_endpoints import (
+        _update_single_user_helper,
+    )
+
+    password = "Str0ng!Passw0rd"
+    sha1 = hashlib.sha1(password.encode("utf-8"), usedforsecurity=False).hexdigest().upper()
+    respx.get(f"https://api.pwnedpasswords.com/range/{sha1[:5]}").mock(
+        return_value=httpx.Response(200, text=f"{sha1[5:]}:1387")
+    )
+
+    user_request = UpdateUserRequest(user_id="target-user", password=password)
+    admin_caller = UserAPIKeyAuth(user_id="admin-1", user_role=LitellmUserRoles.PROXY_ADMIN)
+
+    with pytest.raises(ProxyException) as exc_info:
+        await _update_single_user_helper(user_request=user_request, user_api_key_dict=admin_caller)
+
+    assert exc_info.value.code == "400"
+    assert "data breaches" in exc_info.value.message
+    _admin_prisma.db.litellm_usertable.find_first.assert_not_called()
+
+
+@pytest.mark.asyncio
+async def test_bulk_update_all_users_rejects_a_password(_admin_prisma):
+    """The all_users fast path writes user_updates straight to update_many,
+    bypassing _update_single_user_helper. A password riding along would be
+    stored as unvalidated plaintext on every row, so it must be rejected
+    before any DB access."""
+    from fastapi import HTTPException
+
+    from litellm.proxy._types import UpdateUserRequestNoUserIDorEmail
+    from litellm.proxy.management_endpoints.internal_user_endpoints import bulk_user_update
+    from litellm.types.proxy.management_endpoints.internal_user_endpoints import (
+        BulkUpdateUserRequest,
+    )
+
+    data = BulkUpdateUserRequest(
+        all_users=True,
+        user_updates=UpdateUserRequestNoUserIDorEmail(password="Str0ng!Passw0rd"),
+    )
+    admin_caller = UserAPIKeyAuth(user_id="admin-1", user_role=LitellmUserRoles.PROXY_ADMIN)
+
+    with pytest.raises(HTTPException) as exc_info:
+        await bulk_user_update(data=data, user_api_key_dict=admin_caller)
+
+    assert exc_info.value.status_code == 400
+    assert "not supported" in str(exc_info.value.detail)
+    _admin_prisma.db.litellm_usertable.find_many.assert_not_called()
+    _admin_prisma.db.litellm_usertable.update_many.assert_not_called()
+
+
+def _hibp_client_with_handler(handler) -> AsyncHTTPHandler:
+    """A real AsyncHTTPHandler over httpx.MockTransport (the DI seam used
+    throughout test_password_policy.py), so no network is touched."""
+    http_handler = AsyncHTTPHandler()
+    http_handler.client = httpx.AsyncClient(transport=httpx.MockTransport(handler))
+    return http_handler
+
+
+@pytest.mark.asyncio
+async def test_bulk_update_breached_password_fails_only_that_user(_admin_prisma, mocker):
+    """In a bulk batch, a breached password fails only its own entry, before
+    any DB write for it; sibling entries with acceptable passwords persist."""
+    from litellm.proxy.management_endpoints.internal_user_endpoints import (
+        bulk_update_processed_users,
+    )
+
+    breached = "Br3ached!Passw0rd"
+    clean = "NewP@ssw0rd123"
+    breached_sha1 = hashlib.sha1(breached.encode("utf-8"), usedforsecurity=False).hexdigest().upper()
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        if request.url.path == f"/range/{breached_sha1[:5]}":
+            return httpx.Response(200, text=f"{breached_sha1[5:]}:1387")
+        return httpx.Response(200, text="0000000000000000000000000000000000A:1")
+
+    mock_prisma_client = _admin_prisma
+    existing_user = mocker.MagicMock()
+    existing_user.model_dump.return_value = {"user_id": "user-clean"}
+    existing_user.user_id = "user-clean"
+    mock_prisma_client.db.litellm_usertable.find_first = mocker.AsyncMock(return_value=existing_user)
+    mock_prisma_client.update_data = mocker.AsyncMock(return_value={"user_id": "user-clean"})
+    mock_prisma_client.jsonify_object = mocker.MagicMock(side_effect=lambda x: x)
+
+    admin_caller = UserAPIKeyAuth(user_id="admin-1", user_role=LitellmUserRoles.PROXY_ADMIN)
+    response = await bulk_update_processed_users(
+        users_to_update=[
+            UpdateUserRequest(user_id="user-breached", password=breached),
+            UpdateUserRequest(user_id="user-clean", password=clean),
+        ],
+        user_api_key_dict=admin_caller,
+        hibp_client=_hibp_client_with_handler(handler),
+    )
+
+    assert response.successful_updates == 1
+    assert response.failed_updates == 1
+    by_user = {r.user_id: r for r in response.results}
+    assert by_user["user-breached"].success is False
+    assert "data breaches" in by_user["user-breached"].error
+    assert by_user["user-clean"].success is True
+    (write_call,) = mock_prisma_client.update_data.call_args_list
+    assert write_call.kwargs["user_id"] == "user-clean"
+
+
+@pytest.mark.asyncio
+async def test_bulk_update_screens_shared_password_with_single_lookup(_admin_prisma, mocker):
+    """A batch where every user gets the same password costs one HIBP lookup,
+    not one per user (the serial per-user checks this regresses against)."""
+    from litellm.proxy.management_endpoints.internal_user_endpoints import (
+        bulk_update_processed_users,
+    )
+
+    lookup_count = 0
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        nonlocal lookup_count
+        lookup_count += 1
+        return httpx.Response(200, text="0000000000000000000000000000000000A:1")
+
+    mock_prisma_client = _admin_prisma
+    existing_user = mocker.MagicMock()
+    existing_user.model_dump.return_value = {"user_id": "user-0"}
+    existing_user.user_id = "user-0"
+    mock_prisma_client.db.litellm_usertable.find_first = mocker.AsyncMock(return_value=existing_user)
+    mock_prisma_client.update_data = mocker.AsyncMock(return_value={"user_id": "user-0"})
+    mock_prisma_client.jsonify_object = mocker.MagicMock(side_effect=lambda x: x)
+
+    admin_caller = UserAPIKeyAuth(user_id="admin-1", user_role=LitellmUserRoles.PROXY_ADMIN)
+    response = await bulk_update_processed_users(
+        users_to_update=[UpdateUserRequest(user_id=f"user-{i}", password="NewP@ssw0rd123") for i in range(5)],
+        user_api_key_dict=admin_caller,
+        hibp_client=_hibp_client_with_handler(handler),
+    )
+
+    assert response.successful_updates == 5
+    assert lookup_count == 1
diff --git a/tests/test_litellm/proxy/management_endpoints/test_password_endpoints.py b/tests/test_litellm/proxy/management_endpoints/test_password_endpoints.py
new file mode 100644
index 00000000000..bd154ebab41
--- /dev/null
+++ b/tests/test_litellm/proxy/management_endpoints/test_password_endpoints.py
@@ -0,0 +1,331 @@
+"""
+Tests for POST /user/password/change (litellm/proxy/management_endpoints/password_endpoints.py).
+
+HIBP traffic is intercepted with respx; no test here touches the network.
+"""
+
+import hashlib
+from unittest.mock import AsyncMock, MagicMock, patch
+
+import httpx
+import pytest
+import respx
+from fastapi import HTTPException
+
+from litellm.proxy._types import LitellmTableNames, ProxyErrorTypes, ProxyException, UserAPIKeyAuth
+from litellm.proxy.management_endpoints.password_endpoints import change_password
+from litellm.proxy.utils import hash_password, verify_password
+
+CURRENT_PASSWORD = "OldP@ssw0rd-2026"
+NEW_PASSWORD = "NewP@ssw0rd-2026"
+
+_POLICY_NO_BREACH_CHECK = {"password_policy_check_breached_passwords": False}
+
+
+def _make_user_row(password: str | None) -> MagicMock:
+    user = MagicMock()
+    user.user_id = "user-123"
+    user.password = password
+    return user
+
+
+def _make_prisma(user: MagicMock | None) -> MagicMock:
+    prisma = MagicMock()
+    prisma.db.litellm_usertable.find_first = AsyncMock(return_value=user)
+    prisma.db.litellm_usertable.update = AsyncMock(return_value=user)
+    return prisma
+
+
+def _caller(user_id: str | None = "user-123") -> UserAPIKeyAuth:
+    return UserAPIKeyAuth(user_id=user_id)
+
+
+def _hibp_url_for(password: str) -> str:
+    sha1 = hashlib.sha1(password.encode(), usedforsecurity=False).hexdigest().upper()
+    return f"https://api.pwnedpasswords.com/range/{sha1[:5]}"
+
+
+def _hibp_suffix_for(password: str) -> str:
+    return hashlib.sha1(password.encode(), usedforsecurity=False).hexdigest().upper()[5:]
+
+
+@pytest.mark.asyncio
+async def test_change_password_success_writes_new_scrypt_hash():
+    from litellm.proxy._types import ChangePasswordRequest
+
+    prisma = _make_prisma(_make_user_row(hash_password(CURRENT_PASSWORD)))
+
+    with (
+        patch(  # test-quality-ok: change_password reads proxy_server module globals; no injection seam
+            "litellm.proxy.proxy_server.prisma_client", prisma
+        ),
+        patch(  # test-quality-ok: change_password reads proxy_server module globals; no injection seam
+            "litellm.proxy.proxy_server.general_settings", _POLICY_NO_BREACH_CHECK
+        ),
+    ):
+        response = await change_password(
+            data=ChangePasswordRequest(current_password=CURRENT_PASSWORD, new_password=NEW_PASSWORD),
+            user_api_key_dict=_caller(),
+        )
+
+    assert response.user_id == "user-123"
+    update_kwargs = prisma.db.litellm_usertable.update.call_args.kwargs
+    assert update_kwargs["where"] == {"user_id": "user-123"}
+    stored = update_kwargs["data"]["password"]
+    assert stored != NEW_PASSWORD
+    assert verify_password(NEW_PASSWORD, stored)
+    # A successful change lifts any pending forced reset and re-arms the
+    # login-time breach screen for the new password.
+    assert update_kwargs["data"]["password_reset_required"] is False
+    assert update_kwargs["data"]["last_breach_check_at"] is None
+
+
+@pytest.mark.asyncio
+async def test_change_password_rejects_wrong_current_password():
+    from litellm.proxy._types import ChangePasswordRequest
+
+    prisma = _make_prisma(_make_user_row(hash_password(CURRENT_PASSWORD)))
+
+    with (
+        patch(  # test-quality-ok: change_password reads proxy_server module globals; no injection seam
+            "litellm.proxy.proxy_server.prisma_client", prisma
+        ),
+        patch(  # test-quality-ok: change_password reads proxy_server module globals; no injection seam
+            "litellm.proxy.proxy_server.general_settings", _POLICY_NO_BREACH_CHECK
+        ),
+    ):
+        with pytest.raises(HTTPException) as exc_info:
+            await change_password(
+                data=ChangePasswordRequest(current_password="not-the-password", new_password=NEW_PASSWORD),
+                user_api_key_dict=_caller(),
+            )
+
+    assert exc_info.value.status_code == 400
+    assert "Current password is incorrect" in exc_info.value.detail["error"]
+    prisma.db.litellm_usertable.update.assert_not_called()
+
+
+@pytest.mark.asyncio
+async def test_change_password_rejects_session_without_user():
+    from litellm.proxy._types import ChangePasswordRequest
+
+    prisma = _make_prisma(user=None)
+
+    with (
+        patch(  # test-quality-ok: change_password reads proxy_server module globals; no injection seam
+            "litellm.proxy.proxy_server.prisma_client", prisma
+        ),
+        patch(  # test-quality-ok: change_password reads proxy_server module globals; no injection seam
+            "litellm.proxy.proxy_server.general_settings", _POLICY_NO_BREACH_CHECK
+        ),
+    ):
+        with pytest.raises(HTTPException) as exc_info:
+            await change_password(
+                data=ChangePasswordRequest(current_password=CURRENT_PASSWORD, new_password=NEW_PASSWORD),
+                user_api_key_dict=_caller(user_id=None),
+            )
+
+    assert exc_info.value.status_code == 400
+    prisma.db.litellm_usertable.find_first.assert_not_called()
+    prisma.db.litellm_usertable.update.assert_not_called()
+
+
+@pytest.mark.asyncio
+async def test_change_password_rejects_account_without_password():
+    """SSO users and the env-credential admin have no DB password row to change."""
+    from litellm.proxy._types import ChangePasswordRequest
+
+    prisma = _make_prisma(_make_user_row(password=None))
+
+    with (
+        patch(  # test-quality-ok: change_password reads proxy_server module globals; no injection seam
+            "litellm.proxy.proxy_server.prisma_client", prisma
+        ),
+        patch(  # test-quality-ok: change_password reads proxy_server module globals; no injection seam
+            "litellm.proxy.proxy_server.general_settings", _POLICY_NO_BREACH_CHECK
+        ),
+    ):
+        with pytest.raises(HTTPException) as exc_info:
+            await change_password(
+                data=ChangePasswordRequest(current_password=CURRENT_PASSWORD, new_password=NEW_PASSWORD),
+                user_api_key_dict=_caller(),
+            )
+
+    assert exc_info.value.status_code == 400
+    assert "no password set" in exc_info.value.detail["error"]
+    prisma.db.litellm_usertable.update.assert_not_called()
+
+
+@pytest.mark.asyncio
+async def test_change_password_enforces_min_length():
+    from litellm.proxy._types import ChangePasswordRequest
+
+    prisma = _make_prisma(_make_user_row(hash_password(CURRENT_PASSWORD)))
+
+    with (
+        patch(  # test-quality-ok: change_password reads proxy_server module globals; no injection seam
+            "litellm.proxy.proxy_server.prisma_client", prisma
+        ),
+        patch(  # test-quality-ok: change_password reads proxy_server module globals; no injection seam
+            "litellm.proxy.proxy_server.general_settings", _POLICY_NO_BREACH_CHECK
+        ),
+    ):
+        with pytest.raises(ProxyException) as exc_info:
+            await change_password(
+                data=ChangePasswordRequest(current_password=CURRENT_PASSWORD, new_password="Short1!"),
+                user_api_key_dict=_caller(),
+            )
+
+    assert exc_info.value.code == "400"
+    assert exc_info.value.type == ProxyErrorTypes.validation_error
+    assert exc_info.value.param == "password"
+    assert "at least 12 characters" in exc_info.value.message
+    prisma.db.litellm_usertable.update.assert_not_called()
+
+
+@pytest.mark.asyncio
+@respx.mock
+async def test_change_password_rejects_breached_password():
+    """With the default policy, the new password is screened against HIBP."""
+    from litellm.proxy._types import ChangePasswordRequest
+
+    breached_password = "Password123!"
+    respx.get(_hibp_url_for(breached_password)).mock(
+        return_value=httpx.Response(200, text=f"{_hibp_suffix_for(breached_password)}:1")
+    )
+    prisma = _make_prisma(_make_user_row(hash_password(CURRENT_PASSWORD)))
+
+    with (
+        patch(  # test-quality-ok: change_password reads proxy_server module globals; no injection seam
+            "litellm.proxy.proxy_server.prisma_client", prisma
+        ),
+        patch(  # test-quality-ok: change_password reads proxy_server module globals; no injection seam
+            "litellm.proxy.proxy_server.general_settings", {}
+        ),
+    ):
+        with pytest.raises(ProxyException) as exc_info:
+            await change_password(
+                data=ChangePasswordRequest(current_password=CURRENT_PASSWORD, new_password=breached_password),
+                user_api_key_dict=_caller(),
+            )
+
+    assert exc_info.value.code == "400"
+    assert exc_info.value.type == ProxyErrorTypes.validation_error
+    assert exc_info.value.param == "password"
+    assert "data breaches" in exc_info.value.message
+    prisma.db.litellm_usertable.update.assert_not_called()
+
+
+@pytest.mark.asyncio
+@respx.mock
+async def test_change_password_verifies_current_password_before_hibp_lookup():
+    """A caller who fails current-password verification must not trigger any
+    HIBP traffic. The HIBP check fails open on errors, so an unmocked lookup
+    could not prove ordering; instead the route is registered and asserted
+    uncalled."""
+    from litellm.proxy._types import ChangePasswordRequest
+
+    hibp_route = respx.get(_hibp_url_for(NEW_PASSWORD)).mock(return_value=httpx.Response(200, text=""))
+    prisma = _make_prisma(_make_user_row(hash_password(CURRENT_PASSWORD)))
+
+    with (
+        patch(  # test-quality-ok: change_password reads proxy_server module globals; no injection seam
+            "litellm.proxy.proxy_server.prisma_client", prisma
+        ),
+        patch(  # test-quality-ok: change_password reads proxy_server module globals; no injection seam
+            "litellm.proxy.proxy_server.general_settings", {}
+        ),
+    ):
+        with pytest.raises(HTTPException) as exc_info:
+            await change_password(
+                data=ChangePasswordRequest(current_password="not-the-password", new_password=NEW_PASSWORD),
+                user_api_key_dict=_caller(),
+            )
+
+    assert exc_info.value.status_code == 400
+    assert "Current password is incorrect" in exc_info.value.detail["error"]
+    assert not hibp_route.called
+    prisma.db.litellm_usertable.update.assert_not_called()
+
+
+@pytest.mark.asyncio
+async def test_change_password_success_emits_redacted_audit_log():
+    """A successful change must land in the audit trail as field names only;
+    the plaintext passwords must never reach the audit call."""
+    from litellm.proxy._types import ChangePasswordRequest
+
+    prisma = _make_prisma(_make_user_row(hash_password(CURRENT_PASSWORD)))
+    audit_mock = AsyncMock()
+
+    with (
+        patch(  # test-quality-ok: change_password reads proxy_server module globals; no injection seam
+            "litellm.proxy.proxy_server.prisma_client", prisma
+        ),
+        patch(  # test-quality-ok: change_password reads proxy_server module globals; no injection seam
+            "litellm.proxy.proxy_server.general_settings", _POLICY_NO_BREACH_CHECK
+        ),
+        patch(  # test-quality-ok: audit sink is a module-level import; no injection seam
+            "litellm.proxy.management_endpoints.password_endpoints.create_object_audit_log", audit_mock
+        ),
+    ):
+        await change_password(
+            data=ChangePasswordRequest(current_password=CURRENT_PASSWORD, new_password=NEW_PASSWORD),
+            user_api_key_dict=_caller(),
+        )
+
+    audit_mock.assert_awaited_once()
+    audit_kwargs = audit_mock.await_args.kwargs
+    assert audit_kwargs["object_id"] == "user-123"
+    assert audit_kwargs["action"] == "updated"
+    assert audit_kwargs["table_name"] == LitellmTableNames.USER_TABLE_NAME
+    assert audit_kwargs["after_value"] == '{"fields_changed": ["password"]}'
+    assert CURRENT_PASSWORD not in str(audit_kwargs)
+    assert NEW_PASSWORD not in str(audit_kwargs)
+
+
+@pytest.mark.asyncio
+async def test_change_password_failure_emits_no_audit_log():
+    from litellm.proxy._types import ChangePasswordRequest
+
+    prisma = _make_prisma(_make_user_row(hash_password(CURRENT_PASSWORD)))
+    audit_mock = AsyncMock()
+
+    with (
+        patch(  # test-quality-ok: change_password reads proxy_server module globals; no injection seam
+            "litellm.proxy.proxy_server.prisma_client", prisma
+        ),
+        patch(  # test-quality-ok: change_password reads proxy_server module globals; no injection seam
+            "litellm.proxy.proxy_server.general_settings", _POLICY_NO_BREACH_CHECK
+        ),
+        patch(  # test-quality-ok: audit sink is a module-level import; no injection seam
+            "litellm.proxy.management_endpoints.password_endpoints.create_object_audit_log", audit_mock
+        ),
+    ):
+        with pytest.raises(HTTPException):
+            await change_password(
+                data=ChangePasswordRequest(current_password="not-the-password", new_password=NEW_PASSWORD),
+                user_api_key_dict=_caller(),
+            )
+
+    audit_mock.assert_not_awaited()
+
+
+@pytest.mark.asyncio
+async def test_change_password_requires_db():
+    from litellm.proxy._types import ChangePasswordRequest
+
+    with (
+        patch(  # test-quality-ok: change_password reads proxy_server module globals; no injection seam
+            "litellm.proxy.proxy_server.prisma_client", None
+        ),
+        patch(  # test-quality-ok: change_password reads proxy_server module globals; no injection seam
+            "litellm.proxy.proxy_server.general_settings", _POLICY_NO_BREACH_CHECK
+        ),
+    ):
+        with pytest.raises(HTTPException) as exc_info:
+            await change_password(
+                data=ChangePasswordRequest(current_password=CURRENT_PASSWORD, new_password=NEW_PASSWORD),
+                user_api_key_dict=_caller(),
+            )
+
+    assert exc_info.value.status_code == 500
diff --git a/tests/test_litellm/proxy/test__types.py b/tests/test_litellm/proxy/test__types.py
index 9e1486ce90f..f5abe0561db 100644
--- a/tests/test_litellm/proxy/test__types.py
+++ b/tests/test_litellm/proxy/test__types.py
@@ -5,11 +5,13 @@ from pydantic import ValidationError
 
 from litellm.proxy._types import (
     ROLES_WITHIN_ORG,
+    ChangePasswordRequest,
     GenerateKeyRequest,
     KeyRequest,
     LiteLLM_AuditLogs,
     LiteLLM_TeamMembership,
     LitellmUserRoles,
+    NewUserRequest,
     OrganizationMemberUpdateRequest,
     ResetSpendRequest,
     UpdateKeyRequest,
@@ -335,3 +337,43 @@ def test_virtual_key_mapping_counts_as_configured_when_any_issuer_sets_the_claim
     )
 
     assert jwt_auth.is_virtual_key_mapping_configured() is is_configured
+
+
+def test_new_user_request_loudly_rejects_a_password():
+    """
+    /user/new has never persisted a password (the field used to be silently
+    dropped). Sending one must now fail visibly so the dead path cannot be
+    revived without going through the password policy.
+    """
+    with pytest.raises(ValidationError, match="invitation link"):
+        NewUserRequest(user_email="alice@example.com", password="hunter2hunter2")
+
+
+def test_new_user_request_without_password_still_works():
+    request = NewUserRequest(user_email="alice@example.com")
+    assert request.password is None
+
+
+def test_update_user_request_accepts_a_password():
+    """Admins set user passwords through /user/update; the value must survive
+    model validation so the endpoint can policy-check and hash it."""
+    request = UpdateUserRequest(user_id="user-123", password="hunter2hunter2")
+    assert request.password == "hunter2hunter2"
+
+
+def test_update_user_request_password_hidden_from_repr():
+    """management_endpoint_wrapper string-formats endpoint kwargs into Slack
+    alerts, so the model's repr/str must never contain the plaintext password."""
+    request = UpdateUserRequest(user_id="user-123", password="hunter2hunter2")
+    assert "hunter2hunter2" not in repr(request)
+    assert "hunter2hunter2" not in str(request)
+
+
+def test_change_password_request_passwords_hidden_from_repr():
+    """Any accidental str()/repr() of the request model (debug logs, exception
+    handlers, a future management_endpoint_wrapper) must never contain either
+    plaintext password."""
+    request = ChangePasswordRequest(current_password="hunter2hunter2", new_password="NewP@ssw0rd-2026")
+    for rendered in (repr(request), str(request)):
+        assert "hunter2hunter2" not in rendered
+        assert "NewP@ssw0rd-2026" not in rendered
diff --git a/tests/unit/models/test_models.py b/tests/unit/models/test_models.py
index b8bf55f1b4a..ab456bb1624 100644
--- a/tests/unit/models/test_models.py
+++ b/tests/unit/models/test_models.py
@@ -324,6 +324,8 @@ class TestUser:
         assert user_no_models.has_model_access("any-model")
 
     def test_password_hash_excluded_from_serialization(self):
+        import json
+
         from litellm.proxy._types import LiteLLM_UserTableWithKeyCount
 
         secret = "$2b$12$abcdefghijklmnopqrstuv"
@@ -331,12 +333,12 @@ class TestUser:
 
         assert user.password == secret
         assert "password" not in user.model_dump()
-        assert "password" not in user.model_dump_json()
+        assert "password" not in json.loads(user.model_dump_json())
 
         with_keys = LiteLLM_UserTableWithKeyCount(user_id="u1", user_email="a@b.c", password=secret, key_count=2)
         assert with_keys.password == secret
         assert "password" not in with_keys.model_dump()
-        assert "password" not in with_keys.model_dump_json()
+        assert "password" not in json.loads(with_keys.model_dump_json())
 
 
 class TestVerificationToken:
diff --git a/ui/litellm-dashboard/src/app/(dashboard)/change-password/ChangePasswordForm.integration.test.tsx b/ui/litellm-dashboard/src/app/(dashboard)/change-password/ChangePasswordForm.integration.test.tsx
new file mode 100644
index 00000000000..c4cf8ebcf9d
--- /dev/null
+++ b/ui/litellm-dashboard/src/app/(dashboard)/change-password/ChangePasswordForm.integration.test.tsx
@@ -0,0 +1,110 @@
+import { fireEvent, render, screen, waitFor } from "@testing-library/react";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import ChangePasswordForm from "./ChangePasswordForm";
+
+const mockChangePasswordCall = vi.fn();
+const mockToastSuccess = vi.fn();
+const mockClearTokenCookies = vi.fn();
+let mockPasswordResetRequired = false;
+
+vi.mock("@/components/networking", () => ({
+  changePasswordCall: (...args: unknown[]) => mockChangePasswordCall(...args),
+  getProxyBaseUrl: () => "",
+}));
+
+vi.mock("@/app/(dashboard)/hooks/useAuthorized", () => ({
+  default: () => ({ accessToken: "sk-session-token", passwordResetRequired: mockPasswordResetRequired }),
+}));
+
+vi.mock("@/lib/toast", () => ({
+  toast: {
+    success: (...args: unknown[]) => mockToastSuccess(...args),
+    fromError: vi.fn(),
+  },
+}));
+
+vi.mock("@/utils/cookieUtils", () => ({
+  clearTokenCookies: (...args: unknown[]) => mockClearTokenCookies(...args),
+}));
+
+const fillForm = (values: { current: string; next: string; confirm: string }) => {
+  fireEvent.change(screen.getByLabelText("Current Password"), { target: { value: values.current } });
+  fireEvent.change(screen.getByLabelText("New Password"), { target: { value: values.next } });
+  fireEvent.change(screen.getByLabelText("Confirm New Password"), { target: { value: values.confirm } });
+};
+
+const submit = () => fireEvent.click(screen.getByRole("button", { name: "Change Password" }));
+
+describe("ChangePasswordForm", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockPasswordResetRequired = false;
+  });
+
+  it("sends the current and new password to the change endpoint and resets on success", async () => {
+    mockChangePasswordCall.mockResolvedValue({ user_id: "user-123", message: "Password updated successfully." });
+    render(<ChangePasswordForm />);
+
+    fillForm({ current: "OldP@ssw0rd-2026", next: "NewP@ssw0rd-2026", confirm: "NewP@ssw0rd-2026" });
+    submit();
+
+    expect(await screen.findByLabelText("Current Password")).toHaveValue("");
+    expect(mockChangePasswordCall).toHaveBeenCalledWith("sk-session-token", "OldP@ssw0rd-2026", "NewP@ssw0rd-2026");
+    expect(mockToastSuccess).toHaveBeenCalled();
+  });
+
+  it("blocks submission when the confirmation does not match", async () => {
+    render(<ChangePasswordForm />);
+
+    fillForm({ current: "OldP@ssw0rd-2026", next: "NewP@ssw0rd-2026", confirm: "Different-2026" });
+    submit();
+
+    expect(await screen.findByText("New passwords do not match")).toBeInTheDocument();
+    expect(mockChangePasswordCall).not.toHaveBeenCalled();
+  });
+
+  it("shows the proxy's rejection message unwrapped", async () => {
+    mockChangePasswordCall.mockRejectedValue(new Error("{'error': 'Current password is incorrect.'}"));
+    render(<ChangePasswordForm />);
+
+    fillForm({ current: "wrong-password", next: "NewP@ssw0rd-2026", confirm: "NewP@ssw0rd-2026" });
+    submit();
+
+    expect(await screen.findByText("Current password is incorrect.")).toBeInTheDocument();
+    expect(mockToastSuccess).not.toHaveBeenCalled();
+  });
+
+  describe("forced password reset", () => {
+    it("shows the forced-reset warning only when the session is flagged", () => {
+      mockPasswordResetRequired = true;
+      render(<ChangePasswordForm />);
+
+      expect(screen.getByText(/must be changed before you can use the dashboard/)).toBeInTheDocument();
+    });
+
+    it("hides the forced-reset warning for a normal session", () => {
+      render(<ChangePasswordForm />);
+
+      expect(screen.queryByText(/must be changed before you can use the dashboard/)).not.toBeInTheDocument();
+    });
+
+    it("signs the user out to re-login after a successful forced change", async () => {
+      mockPasswordResetRequired = true;
+      mockChangePasswordCall.mockResolvedValue({ user_id: "user-123", message: "Password updated successfully." });
+      const replaceMock = vi.fn();
+      const realLocation = window.location;
+      Object.defineProperty(window, "location", { configurable: true, value: { replace: replaceMock } });
+
+      try {
+        render(<ChangePasswordForm />);
+        fillForm({ current: "OldP@ssw0rd-2026", next: "NewP@ssw0rd-2026", confirm: "NewP@ssw0rd-2026" });
+        submit();
+
+        await waitFor(() => expect(replaceMock).toHaveBeenCalledWith("/ui/login/"));
+        expect(mockClearTokenCookies).toHaveBeenCalled();
+      } finally {
+        Object.defineProperty(window, "location", { configurable: true, value: realLocation });
+      }
+    });
+  });
+});
diff --git a/ui/litellm-dashboard/src/app/(dashboard)/change-password/ChangePasswordForm.tsx b/ui/litellm-dashboard/src/app/(dashboard)/change-password/ChangePasswordForm.tsx
new file mode 100644
index 00000000000..05a6bf3ae94
--- /dev/null
+++ b/ui/litellm-dashboard/src/app/(dashboard)/change-password/ChangePasswordForm.tsx
@@ -0,0 +1,120 @@
+"use client";
+
+import React, { useState } from "react";
+import { CircleAlert } from "lucide-react";
+import { z } from "zod/v4";
+import useAuthorized from "@/app/(dashboard)/hooks/useAuthorized";
+import { Alert, AlertTitle } from "@/components/shared/Alert";
+import { PasswordInput } from "@/components/shared/PasswordInput";
+import { FormField } from "@/components/shared/form/FormField";
+import { Button } from "@/components/ui/button";
+import { Card, CardContent } from "@/components/ui/card";
+import { FieldGroup } from "@/components/ui/field";
+import { UiLoadingSpinner } from "@/components/ui/ui-loading-spinner";
+import { changePasswordCall, getProxyBaseUrl } from "@/components/networking";
+import { extractProxyErrorMessage } from "@/lib/http/client";
+import { useZodForm } from "@/lib/forms/useZodForm";
+import { toast } from "@/lib/toast";
+import { clearTokenCookies } from "@/utils/cookieUtils";
+import { getLoginUrl } from "@/utils/returnUrlUtils";
+
+const changePasswordSchema = z
+  .object({
+    currentPassword: z.string().min(1, "Current password is required"),
+    newPassword: z.string().min(1, "New password is required"),
+    confirmNewPassword: z.string().min(1, "Confirm your new password"),
+  })
+  .refine((values) => values.newPassword === values.confirmNewPassword, {
+    message: "New passwords do not match",
+    path: ["confirmNewPassword"],
+  });
+
+type ChangePasswordValues = z.infer<typeof changePasswordSchema>;
+
+export function ChangePasswordForm() {
+  const { accessToken, passwordResetRequired } = useAuthorized();
+  const form = useZodForm(changePasswordSchema, {
+    defaultValues: { currentPassword: "", newPassword: "", confirmNewPassword: "" },
+  });
+  const [isPending, setIsPending] = useState(false);
+  const [submitError, setSubmitError] = useState<string | null>(null);
+
+  const handleSubmit = async (values: ChangePasswordValues) => {
+    if (!accessToken) return;
+    setSubmitError(null);
+    setIsPending(true);
+    try {
+      await changePasswordCall(accessToken, values.currentPassword, values.newPassword);
+      if (passwordResetRequired) {
+        // The session key was minted restricted; only a fresh login lifts it.
+        toast.success("Password updated. Please log in with your new password.");
+        clearTokenCookies();
+        window.location.replace(getLoginUrl(getProxyBaseUrl()));
+        return;
+      }
+      toast.success("Password updated");
+      form.reset();
+    } catch (error) {
+      setSubmitError(extractProxyErrorMessage(error));
+    } finally {
+      setIsPending(false);
+    }
+  };
+
+  return (
+    <div className="mx-auto mt-10 w-full max-w-md">
+      <Card>
+        <CardContent>
+          <h3 className="text-2xl font-semibold text-foreground">Change Password</h3>
+          <p className="text-sm text-muted-foreground">
+            Enter your current password and choose a new one. The new password must meet this proxy&apos;s password
+            policy.
+          </p>
+
+          {passwordResetRequired && (
+            <Alert variant="warning" className="mt-4">
+              <CircleAlert />
+              <AlertTitle>
+                Your password must be changed before you can use the dashboard: it was either found in a known data
+                breach or set by an administrator as a temporary password. After updating it, you will be signed out to
+                log in again.
+              </AlertTitle>
+            </Alert>
+          )}
+
+          <form className="mb-2 mt-8" onSubmit={form.handleSubmit(handleSubmit)}>
+            <FieldGroup>
+              <FormField control={form.control} name="currentPassword" label="Current Password">
+                {({ ref, ...field }) => <PasswordInput {...field} ref={ref} autoComplete="current-password" />}
+              </FormField>
+
+              <FormField control={form.control} name="newPassword" label="New Password">
+                {({ ref, ...field }) => <PasswordInput {...field} ref={ref} autoComplete="new-password" />}
+              </FormField>
+
+              <FormField control={form.control} name="confirmNewPassword" label="Confirm New Password">
+                {({ ref, ...field }) => <PasswordInput {...field} ref={ref} autoComplete="new-password" />}
+              </FormField>
+            </FieldGroup>
+
+            {submitError && (
+              <Alert variant="error" className="mt-6">
+                <CircleAlert />
+                <AlertTitle>{submitError}</AlertTitle>
+              </Alert>
+            )}
+
+            <div className="mt-8">
+              <Button type="submit" disabled={isPending}>
+                {isPending && <UiLoadingSpinner className="size-4" role="img" aria-label="loading" />}
+                Change Password
+              </Button>
+            </div>
+          </form>
+        </CardContent>
+      </Card>
+    </div>
+  );
+}
+
+export default ChangePasswordForm;
diff --git a/ui/litellm-dashboard/src/app/(dashboard)/change-password/page.tsx b/ui/litellm-dashboard/src/app/(dashboard)/change-password/page.tsx
new file mode 100644
index 00000000000..0a6ae926ceb
--- /dev/null
+++ b/ui/litellm-dashboard/src/app/(dashboard)/change-password/page.tsx
@@ -0,0 +1,7 @@
+"use client";
+
+import ChangePasswordForm from "./ChangePasswordForm";
+
+export default function ChangePasswordPage() {
+  return <ChangePasswordForm />;
+}
diff --git a/ui/litellm-dashboard/src/app/(dashboard)/hooks/useAuthorized.ts b/ui/litellm-dashboard/src/app/(dashboard)/hooks/useAuthorized.ts
index 40d1ec09d1f..581ee8b2580 100644
--- a/ui/litellm-dashboard/src/app/(dashboard)/hooks/useAuthorized.ts
+++ b/ui/litellm-dashboard/src/app/(dashboard)/hooks/useAuthorized.ts
@@ -50,7 +50,9 @@ const useAuthorized = () => {
     isViewOnly: isViewOnlySessionRole(decoded?.user_role),
     premiumUser: decoded?.premium_user ?? null,
     disabledPersonalKeyCreation: decoded?.disabled_non_admin_personal_key_creation ?? null,
+    loginMethod: decoded?.login_method ?? null,
     showSSOBanner: decoded?.login_method === "username_password",
+    passwordResetRequired: decoded?.password_reset_required === true,
   };
 };
 
diff --git a/ui/litellm-dashboard/src/app/(dashboard)/layout.test.tsx b/ui/litellm-dashboard/src/app/(dashboard)/layout.test.tsx
index 3fe34610260..ae6575e2349 100644
--- a/ui/litellm-dashboard/src/app/(dashboard)/layout.test.tsx
+++ b/ui/litellm-dashboard/src/app/(dashboard)/layout.test.tsx
@@ -1,4 +1,4 @@
-import { describe, it, expect, vi, beforeEach } from "vitest";
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
 import { render, screen, waitFor } from "@testing-library/react";
 import { AuthProvider } from "@/contexts/AuthContext";
 import Layout from "./layout";
@@ -117,4 +117,60 @@ describe("(dashboard) Layout", () => {
     expect(screen.queryByTestId("dashboard-header")).not.toBeInTheDocument();
     expect(screen.queryByTestId("sidebar")).not.toBeInTheDocument();
   });
+
+  describe("forced password reset routing", () => {
+    const sessionCookie = (claims: Record<string, unknown>) => {
+      const encode = (part: Record<string, unknown>) =>
+        btoa(JSON.stringify(part)).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+      const exp = Math.floor(Date.now() / 1000) + 3600;
+      return `${encode({ alg: "HS256", typ: "JWT" })}.${encode({ ...claims, exp })}.sig`;
+    };
+
+    afterEach(() => {
+      document.cookie = "token=; Max-Age=0; Path=/";
+    });
+
+    it("routes a session flagged password_reset_required to the change-password page", async () => {
+      const flaggedClaims = {
+        user_id: "flagged-user",
+        key: "sk-session",
+        login_method: "username_password",
+        password_reset_required: true,
+      };
+      document.cookie = `token=${sessionCookie(flaggedClaims)}; Path=/`;
+
+      render(
+        <AuthProvider>
+          <Layout>
+            <div data-testid="page-content" />
+          </Layout>
+        </AuthProvider>,
+      );
+
+      pendingUiConfig.resolve();
+
+      await waitFor(() => expect(replaceMock).toHaveBeenCalledWith(expect.stringContaining("/change-password")));
+    });
+
+    it("does not reroute an unflagged session", async () => {
+      document.cookie = `token=${sessionCookie({
+        user_id: "normal-user",
+        key: "sk-session",
+        login_method: "username_password",
+      })}; Path=/`;
+
+      render(
+        <AuthProvider>
+          <Layout>
+            <div data-testid="page-content" />
+          </Layout>
+        </AuthProvider>,
+      );
+
+      pendingUiConfig.resolve();
+
+      expect(await screen.findByTestId("page-content")).toBeInTheDocument();
+      expect(replaceMock).not.toHaveBeenCalled();
+    });
+  });
 });
diff --git a/ui/litellm-dashboard/src/app/(dashboard)/layout.tsx b/ui/litellm-dashboard/src/app/(dashboard)/layout.tsx
index fa6df7f176a..309d7dd1ac2 100644
--- a/ui/litellm-dashboard/src/app/(dashboard)/layout.tsx
+++ b/ui/litellm-dashboard/src/app/(dashboard)/layout.tsx
@@ -7,7 +7,7 @@ import LoadingScreen from "@/components/common_components/LoadingScreen";
 import { ThemeProvider } from "@/contexts/ThemeContext";
 import { useAuth } from "@/contexts/AuthContext";
 import SidebarProvider from "@/app/(dashboard)/components/SidebarProvider";
-import { useRouter, useSearchParams } from "next/navigation";
+import { usePathname, useRouter, useSearchParams } from "next/navigation";
 import { DebugWarningBanner } from "@/components/DebugWarningBanner";
 import { NoRedisWarningBanner } from "@/components/NoRedisWarningBanner";
 import { EnvCredentialLoginWarningBanner } from "@/components/EnvCredentialLoginWarningBanner";
@@ -146,7 +146,8 @@ function DashboardShell({ children }: { children: React.ReactNode }) {
 function LayoutContent({ children }: { children: React.ReactNode }) {
   const router = useRouter();
   const searchParams = useSearchParams();
-  const { accessToken, authLoading } = useAuth();
+  const pathname = usePathname();
+  const { accessToken, authLoading, passwordResetRequired } = useAuth();
   const isInvitationFlow = Boolean(searchParams.get("invitation_id"));
 
   // Legacy invitation links point at /ui/?invitation_id=; the onboarding form now lives at its own
@@ -157,6 +158,14 @@ function LayoutContent({ children }: { children: React.ReactNode }) {
     }
   }, [authLoading, isInvitationFlow, router, searchParams]);
 
+  // A session flagged for a forced password reset can only reach the change-password
+  // endpoint server-side; keep the UI on the matching page.
+  useEffect(() => {
+    if (!authLoading && passwordResetRequired && !pathname?.endsWith("/change-password")) {
+      router.replace(uiHref("change-password"));
+    }
+  }, [authLoading, passwordResetRequired, pathname, router]);
+
   if (authLoading || isInvitationFlow) {
     return <LoadingScreen />;
   }
diff --git a/ui/litellm-dashboard/src/components/Navbar/UserDropdown/UserDropdown.test.tsx b/ui/litellm-dashboard/src/components/Navbar/UserDropdown/UserDropdown.test.tsx
index cad5ced340e..4bdf0da3407 100644
--- a/ui/litellm-dashboard/src/components/Navbar/UserDropdown/UserDropdown.test.tsx
+++ b/ui/litellm-dashboard/src/components/Navbar/UserDropdown/UserDropdown.test.tsx
@@ -3,13 +3,25 @@ import { beforeEach, describe, expect, it, vi } from "vitest";
 import { renderWithProviders, screen, waitFor } from "../../../../tests/test-utils";
 import UserDropdown from "./UserDropdown";
 
-let mockUseAuthorizedImpl = () => ({
+let mockUseAuthorizedImpl: () => {
+  userId: string | null;
+  userEmail: string | null;
+  userRoleLabel: string;
+  premiumUser: boolean;
+  loginMethod?: string | null;
+} = () => ({
   userId: "test-user-id",
   userEmail: "test@example.com",
   userRoleLabel: "Admin",
   premiumUser: false,
 });
 
+const mockRouterPush = vi.fn();
+
+vi.mock("next/navigation", () => ({
+  useRouter: () => ({ push: mockRouterPush }),
+}));
+
 let mockUseDisableShowPromptsImpl = () => false;
 
 let mockGetLocalStorageItemImpl = (key: string): string | null => {
@@ -143,6 +155,44 @@ describe("UserDropdown", () => {
     expect(mockOnLogout).toHaveBeenCalledTimes(1);
   });
 
+  it("should navigate to the change-password page for username/password sessions", async () => {
+    mockUseAuthorizedImpl = () => ({
+      userId: "test-user-id",
+      userEmail: "test@example.com",
+      userRoleLabel: "Admin",
+      premiumUser: false,
+      loginMethod: "username_password",
+    });
+    const user = userEvent.setup();
+    renderWithProviders(<UserDropdown onLogout={mockOnLogout} />);
+
+    await user.click(getAccountTrigger());
+
+    await user.click(await screen.findByText("Change Password"));
+
+    expect(mockRouterPush).toHaveBeenCalledWith(expect.stringContaining("change-password"));
+  });
+
+  it("should hide the change-password entry for SSO sessions", async () => {
+    mockUseAuthorizedImpl = () => ({
+      userId: "test-user-id",
+      userEmail: "test@example.com",
+      userRoleLabel: "Admin",
+      premiumUser: false,
+      loginMethod: "sso",
+    });
+    const user = userEvent.setup();
+    renderWithProviders(<UserDropdown onLogout={mockOnLogout} />);
+
+    await user.click(getAccountTrigger());
+
+    await waitFor(() => {
+      expect(screen.getAllByText("test@example.com").length).toBeGreaterThan(0);
+    });
+
+    expect(screen.queryByText("Change Password")).not.toBeInTheDocument();
+  });
+
   it("should toggle hide new feature indicators switch", async () => {
     const user = userEvent.setup();
     renderWithProviders(<UserDropdown onLogout={mockOnLogout} />);
diff --git a/ui/litellm-dashboard/src/components/Navbar/UserDropdown/UserDropdown.tsx b/ui/litellm-dashboard/src/components/Navbar/UserDropdown/UserDropdown.tsx
index 95f76dbb2cc..9c02defc778 100644
--- a/ui/litellm-dashboard/src/components/Navbar/UserDropdown/UserDropdown.tsx
+++ b/ui/litellm-dashboard/src/components/Navbar/UserDropdown/UserDropdown.tsx
@@ -9,7 +9,9 @@ import {
   setLocalStorageItem,
 } from "@/utils/localStorageUtils";
 import { navAccountDisplayName } from "@/components/Navbar/navDisplayName";
-import { ChevronDown, ChevronsUpDown, Crown, LogOut, Mail, ShieldCheck, User } from "lucide-react";
+import { uiHref } from "@/utils/uiHref";
+import { ChevronDown, ChevronsUpDown, Crown, KeyRound, LogOut, Mail, ShieldCheck, User } from "lucide-react";
+import { useRouter } from "next/navigation";
 import { Avatar, AvatarFallback } from "@/components/ui/avatar";
 import { Badge } from "@/components/ui/badge";
 import { Popover, PopoverContent, PopoverTrigger } from "@/components/ui/popover";
@@ -63,7 +65,9 @@ interface UserDropdownProps {
 }
 
 const UserDropdown: React.FC<UserDropdownProps> = ({ onLogout, variant = "navbar", collapsed = false }) => {
-  const { userId, userEmail, userRoleLabel: userRole, premiumUser } = useAuthorized();
+  const { userId, userEmail, userRoleLabel: userRole, premiumUser, loginMethod } = useAuthorized();
+  const router = useRouter();
+  const [open, setOpen] = useState(false);
   const disableShowPrompts = useDisableShowPrompts();
   const disableBlogPosts = useDisableBlogPosts();
   const disableBouncingIcon = useDisableBouncingIcon();
@@ -197,7 +201,7 @@ const UserDropdown: React.FC<UserDropdownProps> = ({ onLogout, variant = "navbar
   const displayName = navAccountDisplayName(userEmail, userId);
 
   return (
-    <Popover>
+    <Popover open={open} onOpenChange={setOpen}>
       {variant === "sidebar" ? (
         <PopoverTrigger
           render={
@@ -258,6 +262,19 @@ const UserDropdown: React.FC<UserDropdownProps> = ({ onLogout, variant = "navbar
       >
         {renderUserInfoSection()}
         <Separator />
+        {loginMethod === "username_password" && (
+          <button
+            type="button"
+            onClick={() => {
+              setOpen(false);
+              router.push(uiHref("change-password"));
+            }}
+            className="flex w-full items-center gap-2 rounded-sm px-2 py-1.5 text-sm hover:bg-accent"
+          >
+            <KeyRound className="size-4" />
+            Change Password
+          </button>
+        )}
         <button
           type="button"
           onClick={onLogout}
diff --git a/ui/litellm-dashboard/src/components/SidebarAccountMenu/SidebarAccountMenu.test.tsx b/ui/litellm-dashboard/src/components/SidebarAccountMenu/SidebarAccountMenu.test.tsx
index 9d56a889ed4..d9d6605dff7 100644
--- a/ui/litellm-dashboard/src/components/SidebarAccountMenu/SidebarAccountMenu.test.tsx
+++ b/ui/litellm-dashboard/src/components/SidebarAccountMenu/SidebarAccountMenu.test.tsx
@@ -9,6 +9,7 @@ interface AuthMock {
   userRoleLabel: string;
   premiumUser: boolean;
   accessToken: string;
+  loginMethod?: string | null;
 }
 
 let mockUseAuthorizedImpl: () => AuthMock = () => ({
@@ -19,6 +20,12 @@ let mockUseAuthorizedImpl: () => AuthMock = () => ({
   accessToken: "test-token",
 });
 
+const mockRouterPush = vi.fn();
+
+vi.mock("next/navigation", () => ({
+  useRouter: () => ({ push: mockRouterPush }),
+}));
+
 let mockUseDisableShowPromptsImpl = () => false;
 let mockUseDisableBouncingIconImpl = () => false;
 let mockHealthDataImpl = (): { litellm_version?: string } | undefined => ({ litellm_version: "1.99.0" });
@@ -201,6 +208,42 @@ describe("SidebarAccountMenu", () => {
     expect(mockOnLogout).toHaveBeenCalledTimes(1);
   });
 
+  it("should navigate to the change-password page for username/password sessions", async () => {
+    mockUseAuthorizedImpl = () => ({
+      userId: "test-user-id",
+      userEmail: "test@example.com",
+      userRoleLabel: "Admin",
+      premiumUser: false,
+      accessToken: "test-token",
+      loginMethod: "username_password",
+    });
+    const user = userEvent.setup();
+    renderWithProviders(<SidebarAccountMenu onLogout={mockOnLogout} />);
+
+    await openMenu(user);
+
+    await user.click(screen.getByRole("button", { name: /change password/i }));
+
+    expect(mockRouterPush).toHaveBeenCalledWith(expect.stringContaining("change-password"));
+  });
+
+  it("should hide the change-password entry for SSO sessions", async () => {
+    mockUseAuthorizedImpl = () => ({
+      userId: "test-user-id",
+      userEmail: "test@example.com",
+      userRoleLabel: "Admin",
+      premiumUser: false,
+      accessToken: "test-token",
+      loginMethod: "sso",
+    });
+    const user = userEvent.setup();
+    renderWithProviders(<SidebarAccountMenu onLogout={mockOnLogout} />);
+
+    await openMenu(user);
+
+    expect(screen.queryByRole("button", { name: /change password/i })).not.toBeInTheDocument();
+  });
+
   it("should toggle hide new feature indicators on", async () => {
     const user = userEvent.setup();
     renderWithProviders(<SidebarAccountMenu onLogout={mockOnLogout} />);
diff --git a/ui/litellm-dashboard/src/components/SidebarAccountMenu/SidebarAccountMenu.tsx b/ui/litellm-dashboard/src/components/SidebarAccountMenu/SidebarAccountMenu.tsx
index ea0b82869cd..e697cc6f34a 100644
--- a/ui/litellm-dashboard/src/components/SidebarAccountMenu/SidebarAccountMenu.tsx
+++ b/ui/litellm-dashboard/src/components/SidebarAccountMenu/SidebarAccountMenu.tsx
@@ -14,7 +14,9 @@ import { Popover, PopoverContent, PopoverTrigger } from "@/components/ui/popover
 import { Separator } from "@/components/ui/separator";
 import { Switch } from "@/components/ui/switch";
 import { cn } from "@/lib/cva.config";
-import { ChevronsUpDown, Crown, IdCard, LogOut, Mail, ShieldCheck } from "lucide-react";
+import { uiHref } from "@/utils/uiHref";
+import { ChevronsUpDown, Crown, IdCard, KeyRound, LogOut, Mail, ShieldCheck } from "lucide-react";
+import { useRouter } from "next/navigation";
 import React from "react";
 
 const RELEASE_NOTES_URL = "https://docs.litellm.ai/release_notes";
@@ -81,7 +83,9 @@ interface SidebarAccountMenuProps {
 }
 
 const SidebarAccountMenu: React.FC<SidebarAccountMenuProps> = ({ onLogout, collapsed = false }) => {
-  const { userId, userEmail, userRoleLabel: userRole, premiumUser, accessToken } = useAuthorized();
+  const { userId, userEmail, userRoleLabel: userRole, premiumUser, accessToken, loginMethod } = useAuthorized();
+  const router = useRouter();
+  const [open, setOpen] = React.useState(false);
   const { data: healthData } = useHealthReadinessDetails(accessToken);
   const version = healthData?.litellm_version;
   const disableShowPrompts = useDisableShowPrompts();
@@ -136,7 +140,7 @@ const SidebarAccountMenu: React.FC<SidebarAccountMenuProps> = ({ onLogout, colla
   const triggerLabel = `Account menu — ${userRole ?? "Unknown role"} — signed in as ${userEmail || userId || "unknown"}`;
 
   return (
-    <Popover>
+    <Popover open={open} onOpenChange={setOpen}>
       <PopoverTrigger
         className={cn(
           "flex w-full items-center rounded-lg border border-transparent transition-colors hover:bg-sidebar-accent",
@@ -235,6 +239,20 @@ const SidebarAccountMenu: React.FC<SidebarAccountMenuProps> = ({ onLogout, colla
 
         <Separator />
 
+        {loginMethod === "username_password" && (
+          <Button
+            variant="ghost"
+            onClick={() => {
+              setOpen(false);
+              router.push(uiHref("change-password"));
+            }}
+            className="h-[42px] w-full justify-start gap-2.5 rounded-none px-3 text-sm font-medium text-foreground"
+          >
+            <KeyRound className="size-[19px] text-muted-foreground" />
+            Change Password
+          </Button>
+        )}
+
         <Button
           variant="ghost"
           onClick={onLogout}
diff --git a/ui/litellm-dashboard/src/components/leftnav.test.tsx b/ui/litellm-dashboard/src/components/leftnav.test.tsx
index 6eb0218c41d..5fa6e9728cf 100644
--- a/ui/litellm-dashboard/src/components/leftnav.test.tsx
+++ b/ui/litellm-dashboard/src/components/leftnav.test.tsx
@@ -21,6 +21,7 @@ const navState = vi.hoisted(() => ({ pathname: "/ui/api-keys" }));
 
 vi.mock("next/navigation", () => ({
   usePathname: () => navState.pathname,
+  useRouter: () => ({ push: vi.fn() }),
 }));
 
 const { mockUseAuthorized, mockUseOrganizations } = vi.hoisted(() => {
diff --git a/ui/litellm-dashboard/src/components/networking.tsx b/ui/litellm-dashboard/src/components/networking.tsx
index ab1203cf440..178bbeb947f 100644
--- a/ui/litellm-dashboard/src/components/networking.tsx
+++ b/ui/litellm-dashboard/src/components/networking.tsx
@@ -1595,6 +1595,20 @@ export const claimOnboardingToken = async (
   }
 };
 
+export const changePasswordCall = async (
+  accessToken: string,
+  currentPassword: string,
+  newPassword: string,
+): Promise<{ user_id: string; message: string }> => {
+  return await apiClient.post(`/user/password/change`, {
+    accessToken,
+    body: {
+      current_password: currentPassword,
+      new_password: newPassword,
+    },
+  });
+};
+
 export const regenerateKeyCall = async (accessToken: string, keyToRegenerate: string, formData: any) => {
   try {
     const url = proxyBaseUrl
diff --git a/ui/litellm-dashboard/src/contexts/AuthContext.tsx b/ui/litellm-dashboard/src/contexts/AuthContext.tsx
index 123feb18a6c..c68c8b9d81a 100644
--- a/ui/litellm-dashboard/src/contexts/AuthContext.tsx
+++ b/ui/litellm-dashboard/src/contexts/AuthContext.tsx
@@ -24,6 +24,7 @@ type AuthContextValue = {
   premiumUser: boolean;
   disabledPersonalKeyCreation: boolean;
   showSSOBanner: boolean;
+  passwordResetRequired: boolean;
 
   setToken: React.Dispatch<React.SetStateAction<string | null>>;
   setUserID: React.Dispatch<React.SetStateAction<string | null>>;
@@ -46,6 +47,7 @@ export function AuthProvider({ children }: { children: React.ReactNode }) {
   const [premiumUser, setPremiumUser] = useState(false);
   const [disabledPersonalKeyCreation, setDisabledPersonalKeyCreation] = useState(false);
   const [showSSOBanner, setShowSSOBanner] = useState(true);
+  const [passwordResetRequired, setPasswordResetRequired] = useState(false);
 
   // Load runtime UI config (populates proxyBaseUrl etc.) before clearing
   // authLoading, so any consumer that builds proxy-rooted URLs from authLoading=false
@@ -124,6 +126,7 @@ export function AuthProvider({ children }: { children: React.ReactNode }) {
     if (decoded.user_id) {
       setUserID(decoded.user_id);
     }
+    setPasswordResetRequired(decoded.password_reset_required === true);
   }, [token]);
 
   const value: AuthContextValue = {
@@ -136,6 +139,7 @@ export function AuthProvider({ children }: { children: React.ReactNode }) {
     premiumUser,
     disabledPersonalKeyCreation,
     showSSOBanner,
+    passwordResetRequired,
     setToken,
     setUserID,
     setUserRole,
diff --git a/ui/litellm-dashboard/src/lib/http/schema.d.ts b/ui/litellm-dashboard/src/lib/http/schema.d.ts
index 29b7cd206eb..b12e5b68c49 100644
--- a/ui/litellm-dashboard/src/lib/http/schema.d.ts
+++ b/ui/litellm-dashboard/src/lib/http/schema.d.ts
@@ -17312,6 +17312,7 @@ export interface paths {
          *     - prompts: Optional[List[str]] - List of allowed prompts for the user. If specified, the user will only be able to use these specific prompts.
          *     - organizations: List[str] - List of organization id's the user is a member of
          *     - budget_limits: Optional[list] - List of concurrent budget windows for the user. Each window specifies a budget_limit, time_period, and optional budget_duration. Example - [{"budget_limit": 10.0, "time_period": "1d"}, {"budget_limit": 50.0, "time_period": "7d"}].
+         *     - password: Optional[str] - Not supported; any value is rejected with a 422. Users set their own password through an invitation link (POST /invitation/new).
          *     Returns:
          *     - key: (str) The generated api key for the user
          *     - expires: (datetime) Datetime object for when key expires.
@@ -17334,6 +17335,36 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/user/password/change": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Change Password
+         * @description Change the calling user's own password.
+         *
+         *     Requires the current password. The new password must satisfy the
+         *     configured password policy (`general_settings.password_policy_*`: minimum
+         *     length, character classes, and, when enabled, breached-password screening
+         *     via haveibeenpwned.com). A successful change lifts any pending forced
+         *     password reset (`password_reset_required`) on the account.
+         *
+         *     Parameters:
+         *     - current_password: str - The user's current password.
+         *     - new_password: str - The password to change to.
+         */
+        post: operations["change_password_user_password_change_post"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/user/spend/report": {
         parameters: {
             query?: never;
@@ -17381,7 +17412,7 @@ export interface paths {
          *     Parameters:
          *         - user_id: Optional[str] - Specify a user id. If not set, a unique id will be generated.
          *         - user_email: Optional[str] - Specify a user email.
-         *         - password: Optional[str] - Specify a user password.
+         *         - password: Optional[str] - Set the user's password (admin only). Must satisfy the configured password policy. The user is required to change it at their next login. Users change their own password with POST /user/password/change.
          *         - user_alias: Optional[str] - A descriptive name for you to know who this user id refers to.
          *         - teams: Optional[list] - specify a list of team id's a user belongs to.
          *         - send_invite_email: Optional[bool] - Specify if an invite email should be sent.
@@ -25901,6 +25932,20 @@ export interface components {
              */
             threshold_step: number;
         };
+        /** ChangePasswordRequest */
+        ChangePasswordRequest: {
+            /** Current Password */
+            current_password: string;
+            /** New Password */
+            new_password: string;
+        };
+        /** ChangePasswordResponse */
+        ChangePasswordResponse: {
+            /** Message */
+            message: string;
+            /** User Id */
+            user_id: string;
+        };
         /** ChatCompletionAnnotation */
         ChatCompletionAnnotation: {
             /**
@@ -31604,6 +31649,8 @@ export interface components {
             budget_reset_at?: string | null;
             /** Created At */
             created_at?: string | null;
+            /** Last Breach Check At */
+            last_breach_check_at?: string | null;
             /** Max Budget */
             max_budget?: number | null;
             /** Max Parallel Requests */
@@ -31638,6 +31685,8 @@ export interface components {
             organization_id?: string | null;
             /** Organization Memberships */
             organization_memberships?: components["schemas"]["LiteLLM_OrganizationMembershipTable"][] | null;
+            /** Password Reset Required */
+            password_reset_required?: boolean | null;
             /**
              * Policies
              * @default []
@@ -31697,6 +31746,8 @@ export interface components {
              * @default 0
              */
             key_count: number;
+            /** Last Breach Check At */
+            last_breach_check_at?: string | null;
             /** Max Budget */
             max_budget?: number | null;
             /** Max Parallel Requests */
@@ -31731,6 +31782,8 @@ export interface components {
             organization_id?: string | null;
             /** Organization Memberships */
             organization_memberships?: components["schemas"]["LiteLLM_OrganizationMembershipTable"][] | null;
+            /** Password Reset Required */
+            password_reset_required?: boolean | null;
             /**
              * Policies
              * @default []
@@ -34327,6 +34380,8 @@ export interface components {
             object_permission?: components["schemas"]["LiteLLM_ObjectPermissionBase"] | null;
             /** Organizations */
             organizations?: string[] | null;
+            /** Password */
+            password?: string | null;
             /**
              * Permissions
              * @default {}
@@ -63569,6 +63624,39 @@ export interface operations {
             };
         };
     };
+    change_password_user_password_change_post: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["ChangePasswordRequest"];
+            };
+        };
+        responses: {
+            /** @description Successful Response */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ChangePasswordResponse"];
+                };
+            };
+            /** @description Validation Error */
+            422: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["HTTPValidationError"];
+                };
+            };
+        };
+    };
     get_user_spend_report_user_spend_report_get: {
         parameters: {
             query?: {

From 07c9355f4ea1650cad904932fa90fe42eb48ebb9 Mon Sep 17 00:00:00 2001
From: ryan <ryan@berri.ai>
Date: Mon, 21 Sep 2026 18:49:31 +0000
Subject: [PATCH 15/55] fix(ui): regenerate schema.d.ts against main

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
 ui/litellm-dashboard/src/lib/http/schema.d.ts | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/ui/litellm-dashboard/src/lib/http/schema.d.ts b/ui/litellm-dashboard/src/lib/http/schema.d.ts
index b12e5b68c49..e2165bdc021 100644
--- a/ui/litellm-dashboard/src/lib/http/schema.d.ts
+++ b/ui/litellm-dashboard/src/lib/http/schema.d.ts
@@ -25283,6 +25283,8 @@ export interface components {
             object_permission?: components["schemas"]["LiteLLM_ObjectPermissionBase"] | null;
             /** Organizations */
             organizations?: string[] | null;
+            /** Password */
+            password?: string | null;
             /**
              * Permissions
              * @default {}

From 6bfbc7dba4cbf70417ba98d7792bc18005d44486 Mon Sep 17 00:00:00 2001
From: ryan <ryan@berri.ai>
Date: Mon, 21 Sep 2026 18:53:39 +0000
Subject: [PATCH 16/55] test(auth): pass throttle to authenticate_user in
 reset-required tests

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
 tests/test_litellm/proxy/auth/test_login_utils.py | 9 ++++++++-
 1 file changed, 8 insertions(+), 1 deletion(-)

diff --git a/tests/test_litellm/proxy/auth/test_login_utils.py b/tests/test_litellm/proxy/auth/test_login_utils.py
index d41b90fe566..ada231a3e95 100644
--- a/tests/test_litellm/proxy/auth/test_login_utils.py
+++ b/tests/test_litellm/proxy/auth/test_login_utils.py
@@ -733,7 +733,12 @@ async def _db_login(throttle, username: str, password: str, *, correct: bool):
         ),
     ):
         return await authenticate_user(
-            username=username, password=password, master_key="sk-master", prisma_client=MagicMock(), throttle=throttle
+            username=username,
+            password=password,
+            master_key="sk-master",
+            prisma_client=MagicMock(),
+            throttle=throttle,
+            general_settings=_POLICY_NO_BREACH_CHECK,
         )
 
 
@@ -2122,6 +2127,7 @@ class TestPasswordResetRequiredSessionMinting:
                     password="Str0ng!Passw0rd",
                     master_key="sk-1234",
                     prisma_client=mock_prisma_client,
+                    throttle=_unlimited_throttle(),
                     general_settings=_POLICY_NO_BREACH_CHECK,
                 )
         return result, mock_generate_key.call_args.kwargs
@@ -2163,6 +2169,7 @@ class TestPasswordResetRequiredSessionMinting:
                         password="Str0ng!Passw0rd",
                         master_key="sk-1234",
                         prisma_client=mock_prisma_client,
+                        throttle=_unlimited_throttle(),
                         general_settings=_POLICY_NO_BREACH_CHECK,
                     )
         return result, mock_generate_key.call_args.kwargs, mock_screen.call_args.kwargs

From ec55ab1ddb1ff656498314887510890c2320b812 Mon Sep 17 00:00:00 2001
From: ryan <ryan@berri.ai>
Date: Mon, 21 Sep 2026 18:57:48 +0000
Subject: [PATCH 17/55] refactor(auth): use Annotated dependency in
 change_password to satisfy strict gate

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
 litellm/proxy/management_endpoints/password_endpoints.py | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/litellm/proxy/management_endpoints/password_endpoints.py b/litellm/proxy/management_endpoints/password_endpoints.py
index bd3c9722d4d..a2466c83ef9 100644
--- a/litellm/proxy/management_endpoints/password_endpoints.py
+++ b/litellm/proxy/management_endpoints/password_endpoints.py
@@ -8,7 +8,7 @@ request kwargs to OTEL spans, which would log plaintext passwords. The audit
 signal is emitted by hand below, with field names only, never values.
 """
 
-from typing import TYPE_CHECKING, Final
+from typing import TYPE_CHECKING, Annotated, Final
 
 from fastapi import APIRouter, Depends, HTTPException
 
@@ -58,7 +58,7 @@ def _user_table(
 )
 async def change_password(
     data: ChangePasswordRequest,
-    user_api_key_dict: UserAPIKeyAuth = Depends(user_api_key_auth),
+    user_api_key_dict: Annotated[UserAPIKeyAuth, Depends(user_api_key_auth)],
 ) -> ChangePasswordResponse:
     """
     Change the calling user's own password.

From 2074273faf21d58a681fb34c6a4039d86f3ffa72 Mon Sep 17 00:00:00 2001
From: ryan <ryan@berri.ai>
Date: Mon, 21 Sep 2026 19:06:00 +0000
Subject: [PATCH 18/55] test(proxy): give the faked login user the breach-check
 columns

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
 tests/test_litellm/proxy/proxy_server/test_routes_login_sso.py | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/tests/test_litellm/proxy/proxy_server/test_routes_login_sso.py b/tests/test_litellm/proxy/proxy_server/test_routes_login_sso.py
index 88f8be4e49a..8daea8d0ad2 100644
--- a/tests/test_litellm/proxy/proxy_server/test_routes_login_sso.py
+++ b/tests/test_litellm/proxy/proxy_server/test_routes_login_sso.py
@@ -10,6 +10,7 @@ Routes covered:
 
 from __future__ import annotations
 
+from datetime import datetime, timezone
 from unittest.mock import AsyncMock, MagicMock
 
 from .conftest import normalize
@@ -510,6 +511,8 @@ def _db_user(monkeypatch, email: str):
     user.user_email = email
     user.user_role = "internal_user"
     user.password = "scrypt:stored"
+    user.password_reset_required = None
+    user.last_breach_check_at = datetime.now(timezone.utc)
     repo = MagicMock()
     repo.return_value.table.find_first = AsyncMock(return_value=user)
     monkeypatch.setattr(ps, "prisma_client", MagicMock())

From 86960fb127a6d7fe508e6632f4f189a047c46a65 Mon Sep 17 00:00:00 2001
From: shivam <shivam@berri.ai>
Date: Mon, 21 Sep 2026 19:11:38 +0000
Subject: [PATCH 19/55] fix(router): walk every entry of a fallback list after
 a mid-stream failure

A fallback hop that dies before its first chunk surfaces inside the streaming
iterator, where the chain lookup is keyed by the hop's own group. That group has
no chain of its own, so the remaining entries of the original list were never
tried. Resume the original group's chain as the last lookup key; attempted_targets
already skips the entries that were tried.

Resolves LIT-7400

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
 .../router_utils/fallback_event_handlers.py   | 12 ++-
 .../test_fallback_event_handlers.py           |  8 ++
 tests/test_litellm/test_router.py             | 75 +++++++++++++++++++
 3 files changed, 92 insertions(+), 3 deletions(-)

diff --git a/litellm/router_utils/fallback_event_handlers.py b/litellm/router_utils/fallback_event_handlers.py
index d0abaed4d3a..156195f0587 100644
--- a/litellm/router_utils/fallback_event_handlers.py
+++ b/litellm/router_utils/fallback_event_handlers.py
@@ -307,13 +307,19 @@ def fallbacks_disabled_for_request(kwargs: Mapping[str, Any]) -> bool:
 def fallback_lookup_groups(kwargs: Mapping[str, object], model_group: str | None) -> tuple[str, ...]:
     """
     Ordered keys for resolving a fallback chain: the tier a pre-routing hook selected wins,
-    then the routed group, then the requested group. The routed group differs when Claude Code
-    session affinity remaps a subagent's concrete model to its bound router.
+    then the routed group, then the requested group, then the group the request was
+    originally for. The routed group differs when Claude Code session affinity remaps a
+    subagent's concrete model to its bound router. The original group differs on a fallback
+    hop that fails after `run_async_fallback` already returned its stream: the hop has no
+    chain of its own, so it resumes the original group's chain, and `attempted_targets` keeps
+    the entries already tried from being repeated.
     """
     metadata: Final = kwargs.get(get_metadata_variable_name_from_kwargs(kwargs))
     routed_group_value: Final = metadata.get("model_group") if isinstance(metadata, Mapping) else None
     routed_group: Final = routed_group_value if isinstance(routed_group_value, str) else None
-    ordered: Final = (get_pre_routing_selection(kwargs), routed_group, model_group)
+    original_group_value: Final = metadata.get("original_model_group") if isinstance(metadata, Mapping) else None
+    original_group: Final = original_group_value if isinstance(original_group_value, str) else None
+    ordered: Final = (get_pre_routing_selection(kwargs), routed_group, model_group, original_group)
     return tuple(dict.fromkeys(group for group in ordered if group))
 
 
diff --git a/tests/test_litellm/router_utils/test_fallback_event_handlers.py b/tests/test_litellm/router_utils/test_fallback_event_handlers.py
index dfe06bffd09..69772561172 100644
--- a/tests/test_litellm/router_utils/test_fallback_event_handlers.py
+++ b/tests/test_litellm/router_utils/test_fallback_event_handlers.py
@@ -1305,6 +1305,14 @@ class TestOrderedFallbackLookupGroups:
             "requested-model",
         )
 
+    def test_fallback_hop_resumes_the_original_groups_chain_last(self):
+        from litellm.router_utils.fallback_event_handlers import fallback_lookup_groups
+
+        kwargs = {"metadata": {"model_group": "fb1", "original_model_group": "primary"}}
+
+        assert fallback_lookup_groups(kwargs, "fb1") == ("fb1", "primary")
+        assert fallback_lookup_groups({"metadata": {"original_model_group": 42}}, "fb1") == ("fb1",)
+
     def test_first_resolving_group_wins_and_generic_idx_survives_a_miss(self):
         from litellm.router_utils.fallback_event_handlers import (
             get_fallback_model_group_for_lookup_groups,
diff --git a/tests/test_litellm/test_router.py b/tests/test_litellm/test_router.py
index 8310d30d90e..cf143744067 100644
--- a/tests/test_litellm/test_router.py
+++ b/tests/test_litellm/test_router.py
@@ -3447,6 +3447,81 @@ def test_completion_streaming_iterator_adopts_the_deployment_that_served_a_neste
     assert result._hidden_params["model_id"] == "served-deployment"
 
 
+@pytest.mark.asyncio
+async def test_acompletion_mid_stream_fallback_walks_every_entry_of_the_configured_list():
+    """LIT-7400: fallbacks=[{primary: [fb1, fb2]}] must reach fb2 when fb1 dies before its first chunk.
+
+    run_async_fallback returns as soon as fb1's stream wrapper exists, so fb1's failure surfaces
+    inside the streaming iterator, where the lookup is keyed by fb1. That key has no chain of its
+    own, so the iterator has to resume the chain of the group the request was originally for.
+    """
+    from unittest.mock import MagicMock, patch
+
+    from litellm.exceptions import MidStreamFallbackError
+    from litellm.litellm_core_utils.streaming_handler import CustomStreamWrapper
+
+    attempted_model_groups: list[str] = []
+
+    class FailingStream(CustomStreamWrapper):
+        def __init__(self, model: str):
+            super().__init__(
+                completion_stream=object(), model=model, custom_llm_provider="openai", logging_obj=MagicMock()
+            )
+
+        def __aiter__(self):
+            return self
+
+        async def __anext__(self):
+            raise MidStreamFallbackError(
+                message=f"provider 500 from {self.model}",
+                model=self.model,
+                llm_provider="openai",
+                generated_content="",
+                is_pre_first_chunk=True,
+                original_exception=litellm.InternalServerError(
+                    message=f"provider 500 from {self.model}", model=self.model, llm_provider="openai"
+                ),
+            )
+
+    class OkStream(FailingStream):
+        def __init__(self, model: str):
+            super().__init__(model)
+            self._chunks = iter(
+                [litellm.ModelResponseStream(choices=[{"index": 0, "delta": {"content": f"ok-from-{model}"}}])]
+            )
+
+        async def __anext__(self):
+            try:
+                return next(self._chunks)
+            except StopIteration:
+                raise StopAsyncIteration from None
+
+    async def fake_acompletion(**kwargs):
+        attempted_model_groups.append(kwargs["metadata"]["model_group"])
+        if "fb2" in kwargs["model"]:
+            return OkStream(kwargs["model"])
+        return FailingStream(kwargs["model"])
+
+    router = litellm.Router(
+        model_list=[
+            {"model_name": "primary", "litellm_params": {"model": "openai/primary-model", "api_key": "fake-key"}},
+            {"model_name": "fb1", "litellm_params": {"model": "openai/fb1-model", "api_key": "fake-key"}},
+            {"model_name": "fb2", "litellm_params": {"model": "openai/fb2-model", "api_key": "fake-key"}},
+        ],
+        fallbacks=[{"primary": ["fb1", "fb2"]}],
+        num_retries=0,
+    )
+
+    with patch("litellm.acompletion", side_effect=fake_acompletion):
+        response = await router.acompletion(model="primary", messages=[{"role": "user", "content": "hi"}], stream=True)
+        content: Final = "".join(
+            [chunk.choices[0].delta.content or "" async for chunk in response if chunk is not None]
+        )
+
+    assert content == "ok-from-openai/fb2-model"
+    assert attempted_model_groups == ["primary", "fb1", "fb2"]
+
+
 def test_completion_streaming_iterator_adopts_fallback_response_headers():
     """LIT-6767, sync counterpart of the fallback-adoption test."""
     from unittest.mock import MagicMock, patch

From 1098604ed661ee54b66ec7a378a6163f589b10df Mon Sep 17 00:00:00 2001
From: Joshua Valluru <326636767+joshua-berri@users.noreply.github.com>
Date: Mon, 21 Sep 2026 12:24:15 -0700
Subject: [PATCH 20/55] refactor(mcp): extract explicit operation context and
 dispatch

---
 .github/workflows/test-linting.yml            |    4 +
 Makefile                                      |    1 +
 .../_experimental/mcp_server/contracts.py     |   95 +
 .../mcp_server/legacy_callbacks.py            |   83 +
 .../mcp_server/mcp_server_manager.py          |  129 +-
 .../_experimental/mcp_server/operations.py    | 3102 +++++++++++++++++
 .../mcp_server/rest_endpoints.py              |   13 +-
 .../proxy/_experimental/mcp_server/server.py  | 3059 ++--------------
 .../_experimental/mcp_server/tool_search.py   |   11 +-
 litellm/proxy/_types.py                       |    2 +
 scripts/check_mcp_operation_boundary.py       |   65 +
 scripts/pre_commit_lint.sh                    |    3 +
 .../mcp_server/test_byok_oauth_endpoints.py   |   19 +-
 .../mcp_server/test_contracts.py              |   60 +
 .../mcp_server/test_mcp_block_recording.py    |    5 +-
 .../mcp_server/test_mcp_hook_extra_headers.py |    6 +-
 .../test_mcp_oauth_passthrough_tools.py       |   61 +-
 .../mcp_server/test_mcp_proxy_mode.py         |    8 +-
 .../mcp_server/test_mcp_server.py             |  385 +-
 .../mcp_server/test_mcp_server_manager.py     |  174 +-
 .../mcp_server/test_mcp_stale_session.py      |   40 +-
 .../mcp_server/test_mcp_tool_search.py        |   40 +-
 .../mcp_server/test_mcp_toolset_scope.py      |    2 +-
 .../mcp_server/test_openapi_tool_auth.py      |   75 +-
 .../mcp_server/test_operations.py             |  343 ++
 .../mcp_server/test_rest_endpoints.py         |   13 +-
 .../test_check_mcp_operation_boundary.py      |   52 +
 27 files changed, 4624 insertions(+), 3226 deletions(-)
 create mode 100644 litellm/proxy/_experimental/mcp_server/contracts.py
 create mode 100644 litellm/proxy/_experimental/mcp_server/legacy_callbacks.py
 create mode 100644 litellm/proxy/_experimental/mcp_server/operations.py
 create mode 100644 scripts/check_mcp_operation_boundary.py
 create mode 100644 tests/test_litellm/proxy/_experimental/mcp_server/test_contracts.py
 create mode 100644 tests/test_litellm/proxy/_experimental/mcp_server/test_operations.py
 create mode 100644 tests/test_litellm/test_check_mcp_operation_boundary.py

diff --git a/.github/workflows/test-linting.yml b/.github/workflows/test-linting.yml
index 06d369eabcd..592d8edf6b8 100644
--- a/.github/workflows/test-linting.yml
+++ b/.github/workflows/test-linting.yml
@@ -130,6 +130,10 @@ jobs:
           echo "File content around line 43:"
           head -50 litellm/litellm_core_utils/custom_logger_registry.py | tail -10
 
+      - name: Check MCP operation boundary
+        if: steps.changes.outputs.decision != 'skip'
+        run: uv run --no-sync python scripts/check_mcp_operation_boundary.py
+
       - name: Run Ruff linting
         if: steps.changes.outputs.decision != 'skip'
         run: |
diff --git a/Makefile b/Makefile
index 0e9d2bbf82c..ab7fab6aa99 100644
--- a/Makefile
+++ b/Makefile
@@ -164,6 +164,7 @@ lint-format-check-changed: $(LINT_DEP_INSTALL) $(LINT_DEP_BASE)
 
 # Linting targets
 lint-ruff: $(LINT_DEP_INSTALL)
+	$(UV_RUN) python scripts/check_mcp_operation_boundary.py
 	cd litellm && $(UV_RUN) ruff check . && cd ..
 	$(UV_RUN) ruff check --config ruff-tests.toml tests
 
diff --git a/litellm/proxy/_experimental/mcp_server/contracts.py b/litellm/proxy/_experimental/mcp_server/contracts.py
new file mode 100644
index 00000000000..c3129d171ad
--- /dev/null
+++ b/litellm/proxy/_experimental/mcp_server/contracts.py
@@ -0,0 +1,95 @@
+from collections.abc import Mapping
+from copy import deepcopy
+from dataclasses import dataclass, field
+from datetime import datetime
+from types import MappingProxyType
+from typing import Final, Protocol
+
+from litellm.proxy._types import UserAPIKeyAuth
+from litellm.types.mcp_server.mcp_server_manager import MCPServer
+
+
+def copy_caller(auth: UserAPIKeyAuth | None) -> UserAPIKeyAuth | None:
+    if auth is None:
+        return None
+    span: Final = auth.parent_otel_span
+    return deepcopy(auth, {id(span): span} if span is not None else None)  # mutable-ok: deepcopy mutates its memo
+
+
+@dataclass(frozen=True, slots=True)
+class OperationContext:
+    _caller: UserAPIKeyAuth | None = field(repr=False)
+    mcp_auth_header: str | None = field(default=None, repr=False)
+    mcp_servers: tuple[str, ...] | None = None
+    mcp_server_auth_headers: Mapping[str, Mapping[str, str]] | None = field(default=None, repr=False)
+    oauth2_headers: Mapping[str, str] | None = field(default=None, repr=False)
+    raw_headers: Mapping[str, str] | None = field(default=None, repr=False)
+    client_ip: str | None = None
+    mcp_proxy_mode: bool = False
+
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "_caller", copy_caller(self._caller))
+        object.__setattr__(self, "mcp_servers", tuple(self.mcp_servers) if self.mcp_servers is not None else None)
+        object.__setattr__(
+            self,
+            "oauth2_headers",
+            MappingProxyType(dict(self.oauth2_headers)) if self.oauth2_headers is not None else None,
+        )
+        object.__setattr__(
+            self, "raw_headers", MappingProxyType(dict(self.raw_headers)) if self.raw_headers is not None else None
+        )
+        object.__setattr__(
+            self,
+            "mcp_server_auth_headers",
+            MappingProxyType(
+                {key: MappingProxyType(dict(value)) for key, value in self.mcp_server_auth_headers.items()}
+            )
+            if self.mcp_server_auth_headers is not None
+            else None,
+        )
+
+    @property
+    def user_api_key_auth(self) -> UserAPIKeyAuth | None:
+        return copy_caller(self._caller)
+
+    def legacy_auth(
+        self,
+    ) -> tuple[
+        UserAPIKeyAuth | None,
+        str | None,
+        list[str] | None,  # mutable-ok: detached legacy server-list payload
+        dict[str, dict[str, str]] | None,  # mutable-ok: legacy auth dispatch requires concrete dict headers
+        dict[str, str] | None,  # mutable-ok: detached legacy header payload
+        dict[str, str] | None,  # mutable-ok: detached legacy header payload
+        str | None,
+    ]:
+        return (
+            self.user_api_key_auth,
+            self.mcp_auth_header,
+            list(self.mcp_servers) if self.mcp_servers is not None else None,  # mutable-ok: legacy policy list input
+            {
+                key: dict(value) for key, value in self.mcp_server_auth_headers.items()
+            }  # mutable-ok: legacy auth dispatch checks concrete dict headers
+            if self.mcp_server_auth_headers is not None
+            else None,
+            dict(self.oauth2_headers)
+            if self.oauth2_headers is not None
+            else None,  # mutable-ok: legacy OAuth header input
+            dict(self.raw_headers) if self.raw_headers is not None else None,  # mutable-ok: legacy request header input
+            self.client_ip,
+        )
+
+
+class ProgressCallback(Protocol):
+    async def __call__(self, progress: float, total: float | None, /) -> None: ...
+
+
+@dataclass(frozen=True, slots=True)
+class AuthorizedToolCall:
+    name: str
+    arguments: Mapping[str, object]
+    allowed_mcp_servers: tuple[MCPServer, ...]
+    start_time: datetime
+    host_progress_callback: ProgressCallback | None
+    guardrail_context: Mapping[str, object] | None
+    logging_data: Mapping[str, object]
diff --git a/litellm/proxy/_experimental/mcp_server/legacy_callbacks.py b/litellm/proxy/_experimental/mcp_server/legacy_callbacks.py
new file mode 100644
index 00000000000..4424907c28a
--- /dev/null
+++ b/litellm/proxy/_experimental/mcp_server/legacy_callbacks.py
@@ -0,0 +1,83 @@
+from collections.abc import Mapping
+from typing import Final, Protocol
+
+from mcp.client.session import ClientRequestContext
+from mcp.types import (
+    CreateMessageRequestParams,
+    CreateMessageResult,
+    CreateMessageResultWithTools,
+    ElicitRequestParams,
+    ElicitResult,
+    ErrorData,
+)
+
+from litellm.proxy._experimental.mcp_server.contracts import OperationContext
+from litellm.proxy._types import UserAPIKeyAuth
+
+
+class SamplingCallback(Protocol):
+    async def __call__(
+        self, context: ClientRequestContext, params: CreateMessageRequestParams, /
+    ) -> CreateMessageResult | CreateMessageResultWithTools | ErrorData: ...
+
+
+class ElicitationCallback(Protocol):
+    async def __call__(self, context: object, params: ElicitRequestParams, /) -> ElicitResult | ErrorData: ...
+
+
+def create_sampling_callback(
+    user_api_key_auth: UserAPIKeyAuth | None = None,
+    raw_headers: Mapping[str, str] | None = None,
+    client_ip: str | None = None,
+    operation_context: OperationContext | None = None,
+) -> SamplingCallback:
+    from litellm.proxy._experimental.mcp_server.server import get_active_auth_context
+
+    auth: Final = get_active_auth_context() if operation_context is None else None
+    captured: Final = (
+        operation_context
+        if operation_context is not None
+        else OperationContext(
+            _caller=user_api_key_auth if user_api_key_auth is not None else (auth.user_api_key_auth if auth else None),
+            raw_headers=raw_headers if raw_headers is not None else (auth.raw_headers if auth else None),
+            client_ip=client_ip if client_ip is not None else (auth.client_ip if auth else None),
+        )
+    )
+
+    async def callback(
+        context: ClientRequestContext, params: CreateMessageRequestParams
+    ) -> CreateMessageResult | CreateMessageResultWithTools | ErrorData:
+        import litellm
+        from litellm.proxy._experimental.mcp_server.sampling_handler import handle_sampling_create_message
+
+        return await handle_sampling_create_message(
+            context=context,
+            params=params,
+            default_model=getattr(litellm, "default_mcp_sampling_model", None),
+            user_api_key_auth=captured.user_api_key_auth,
+            raw_headers=dict(captured.raw_headers)
+            if captured.raw_headers is not None
+            else None,  # mutable-ok: handler consumes an owned request header dict
+            client_ip=captured.client_ip,
+        )
+
+    return callback
+
+
+def create_elicitation_callback() -> ElicitationCallback:
+    from litellm.proxy._experimental.mcp_server.server import get_active_mcp_session
+
+    downstream_session: Final = get_active_mcp_session()
+    downstream_capabilities: Final = getattr(downstream_session, "capabilities", None)
+
+    async def callback(context: object, params: ElicitRequestParams) -> ElicitResult | ErrorData:
+        from litellm.proxy._experimental.mcp_server.elicitation_handler import handle_elicitation_request
+
+        return await handle_elicitation_request(
+            context=context,
+            params=params,
+            downstream_session=downstream_session,
+            downstream_capabilities=downstream_capabilities,
+        )
+
+    return callback
diff --git a/litellm/proxy/_experimental/mcp_server/mcp_server_manager.py b/litellm/proxy/_experimental/mcp_server/mcp_server_manager.py
index b293ab5a206..264d7cf19aa 100644
--- a/litellm/proxy/_experimental/mcp_server/mcp_server_manager.py
+++ b/litellm/proxy/_experimental/mcp_server/mcp_server_manager.py
@@ -73,6 +73,7 @@ from litellm.proxy._experimental.mcp_server.auth.user_api_key_auth_mcp import (
     MCPServerAccess,
     _is_mcp_admitted_user_subject,
 )
+from litellm.proxy._experimental.mcp_server.contracts import OperationContext
 from litellm.proxy._experimental.mcp_server.elicitation_handler import (
     MCP_ELICITATION_AVAILABLE,
 )
@@ -195,9 +196,6 @@ from litellm.types.mcp_server.mcp_server_manager import (
 from litellm.types.utils import CallTypes
 
 if TYPE_CHECKING:
-    from mcp.client.session import ClientRequestContext
-    from mcp.types import CreateMessageRequestParams
-
     from litellm.litellm_core_utils.litellm_logging import Logging as LiteLLMLoggingObj
     from litellm.types.mcp_server.mcp_toolset import MCPToolset
 
@@ -1218,7 +1216,7 @@ async def _resolve_byok_mcp_auth_header(
     if not mcp_server.is_byok:
         return mcp_auth_header
 
-    from litellm.proxy._experimental.mcp_server.server import (
+    from litellm.proxy._experimental.mcp_server.operations import (
         _check_byok_credential,
         _get_byok_credential,
     )
@@ -1577,77 +1575,25 @@ def _normalize_mcp_server_cost_info(mcp_info: MCPInfo) -> None:
     mcp_info["mcp_server_cost_info"] = normalized
 
 
-def _create_sampling_callback(user_api_key_auth: UserAPIKeyAuth | None = None):
-    """
-    Create a sampling callback for MCP ClientSession.
-    Returns a callable that handles sampling/createMessage requests from
-    upstream MCP servers by routing them through litellm.acompletion().
-    """
+def _create_sampling_callback(
+    user_api_key_auth: UserAPIKeyAuth | None = None,
+    raw_headers: Mapping[str, str] | None = None,
+    client_ip: str | None = None,
+    operation_context: OperationContext | None = None,
+):
     if not MCP_SAMPLING_AVAILABLE:
         return None
+    from litellm.proxy._experimental.mcp_server.legacy_callbacks import create_sampling_callback
 
-    async def _sampling_callback(
-        context: "ClientRequestContext",
-        params: "CreateMessageRequestParams",
-    ):
-        import litellm
-        from litellm.proxy._experimental.mcp_server.sampling_handler import (
-            handle_sampling_create_message,
-        )
-        from litellm.proxy._experimental.mcp_server.server import (
-            get_active_auth_context,
-        )
-
-        auth_context: Final = get_active_auth_context()
-        resolved_auth: Final = user_api_key_auth or (auth_context.user_api_key_auth if auth_context else None)
-        # Forward original HTTP headers and client IP so that
-        # header-dependent guardrails, tag-based routing, trace
-        # correlation, and forward_llm_provider_auth_headers work
-        # correctly for sampling sub-calls.
-        _raw_headers: Final = getattr(auth_context, "raw_headers", None)
-        _client_ip: Final = getattr(auth_context, "client_ip", None)
-
-        return await handle_sampling_create_message(
-            context=context,
-            params=params,
-            default_model=getattr(litellm, "default_mcp_sampling_model", None),
-            user_api_key_auth=resolved_auth,
-            raw_headers=_raw_headers,
-            client_ip=_client_ip,
-        )
-
-    return _sampling_callback
+    return create_sampling_callback(user_api_key_auth, raw_headers, client_ip, operation_context)
 
 
 def _create_elicitation_callback():
-    """
-    Create an elicitation callback for MCP ClientSession.
-    Returns a callable that handles elicitation/create requests from
-    upstream MCP servers. In gateway mode, this relays to the downstream
-    client; in tool bridge mode, it returns a decline response.
-    """
     if not MCP_ELICITATION_AVAILABLE:
         return None
+    from litellm.proxy._experimental.mcp_server.legacy_callbacks import create_elicitation_callback
 
-    async def _elicitation_callback(context, params):
-        from litellm.proxy._experimental.mcp_server.elicitation_handler import (
-            handle_elicitation_request,
-        )
-        from litellm.proxy._experimental.mcp_server.server import get_active_mcp_session
-
-        # In Gateway mode, we relay the elicitation request to the downstream client
-        # that triggered the current operation.
-        downstream_session: Final = get_active_mcp_session()
-        downstream_capabilities = getattr(downstream_session, "capabilities", None) if downstream_session else None
-
-        return await handle_elicitation_request(
-            context=context,
-            params=params,
-            downstream_session=downstream_session,
-            downstream_capabilities=downstream_capabilities,
-        )
-
-    return _elicitation_callback
+    return create_elicitation_callback()
 
 
 def _record_mcp_guardrail_evaluations(
@@ -3373,17 +3319,13 @@ class MCPServerManager:
         listable but uninvokable.
 
         Empty inside a toolset scope: toolset_mcp_route / dynamic_mcp_route set
-        ``_mcp_active_toolset_id`` before calling the handler, pinning the request to the toolset's
+        the caller's server-only ``mcp_toolset_id`` before calling the handler, pinning the request to the toolset's
         own servers (checking op.mcp_toolsets==[] instead would false-positive on DB-default rows
         where Postgres initialises the column to ARRAY[]::TEXT[]).
 
         ``allow_all_server_ids`` / ``submitted_server_ids`` are injectable so the server union,
         which precomputes both for its fallback path, does not compute them twice."""
-        from litellm.proxy._experimental.mcp_server.mcp_context import (  # noqa: PLC0415
-            _mcp_active_toolset_id,
-        )
-
-        if _mcp_active_toolset_id.get() is not None:
+        if user_api_key_auth is not None and user_api_key_auth.mcp_toolset_id is not None:
             return set()
         if allow_all_server_ids is None:
             allow_all_server_ids = self.get_allow_all_keys_server_ids()
@@ -4151,6 +4093,8 @@ class MCPServerManager:
         subject_token: str | None = None,
         user_api_key_auth: UserAPIKeyAuth | None = None,
         cred_provider: UpstreamCredentialProvider | None = None,
+        raw_headers: Mapping[str, str] | None = None,
+        client_ip: str | None = None,
     ) -> MCPClient:
         """
         Create an MCPClient instance for the given server.
@@ -4199,7 +4143,13 @@ class MCPServerManager:
 
         # Create sampling and elicitation callbacks for this client
         sampling_cb = (
-            _create_sampling_callback(user_api_key_auth=user_api_key_auth) if resolved_server.allow_sampling else None
+            _create_sampling_callback(
+                operation_context=OperationContext(
+                    _caller=user_api_key_auth, raw_headers=raw_headers, client_ip=client_ip
+                )
+            )
+            if resolved_server.allow_sampling
+            else None
         )
         elicitation_cb: Final = _create_elicitation_callback() if resolved_server.allow_elicitation else None
 
@@ -4344,6 +4294,7 @@ class MCPServerManager:
         raw_headers: dict[str, str] | None = None,
         user_api_key_auth: UserAPIKeyAuth | None = None,
         oauth2_headers: dict[str, str] | None = None,
+        client_ip: str | None = None,
     ) -> list[MCPTool]:
         """
         Helper method to get tools from a single MCP server with prefixed names.
@@ -4433,6 +4384,8 @@ class MCPServerManager:
                 stdio_env=stdio_env,
                 subject_token=subject_token,
                 user_api_key_auth=user_api_key_auth,
+                raw_headers=raw_headers,
+                client_ip=client_ip,
             )
 
             ## HANDLE OPENAPI TOOLS
@@ -4543,6 +4496,7 @@ class MCPServerManager:
         extra_headers: dict[str, str] | None = None,
         add_prefix: bool = True,
         raw_headers: dict[str, str] | None = None,
+        client_ip: str | None = None,
     ) -> list[Prompt]:
         try:
             headers: Final = (
@@ -4563,6 +4517,8 @@ class MCPServerManager:
                 stdio_env=stdio_env,
                 subject_token=subject_token,
                 user_api_key_auth=user_api_key_auth,
+                raw_headers=raw_headers,
+                client_ip=client_ip,
             )
             credential_fingerprint: Final = await client.discovery_auth_fingerprint()
             key: Final = self._discovery_key(
@@ -4586,6 +4542,7 @@ class MCPServerManager:
         extra_headers: dict[str, str] | None = None,
         add_prefix: bool = True,
         raw_headers: dict[str, str] | None = None,
+        client_ip: str | None = None,
     ) -> list[Resource]:
         try:
             headers: Final = (
@@ -4606,6 +4563,8 @@ class MCPServerManager:
                 stdio_env=stdio_env,
                 subject_token=subject_token,
                 user_api_key_auth=user_api_key_auth,
+                raw_headers=raw_headers,
+                client_ip=client_ip,
             )
             credential_fingerprint: Final = await client.discovery_auth_fingerprint()
             key: Final = self._discovery_key(
@@ -4629,6 +4588,7 @@ class MCPServerManager:
         extra_headers: dict[str, str] | None = None,
         add_prefix: bool = True,
         raw_headers: dict[str, str] | None = None,
+        client_ip: str | None = None,
     ) -> list[ResourceTemplate]:
         try:
             headers: Final = (
@@ -4649,6 +4609,8 @@ class MCPServerManager:
                 stdio_env=stdio_env,
                 subject_token=subject_token,
                 user_api_key_auth=user_api_key_auth,
+                raw_headers=raw_headers,
+                client_ip=client_ip,
             )
             credential_fingerprint: Final = await client.discovery_auth_fingerprint()
             key: Final = self._discovery_key(
@@ -4672,6 +4634,7 @@ class MCPServerManager:
         mcp_auth_header: str | dict[str, str] | None = None,
         extra_headers: dict[str, str] | None = None,
         raw_headers: dict[str, str] | None = None,
+        client_ip: str | None = None,
     ) -> ReadResourceResult:
         """Read resource contents from a specific MCP server."""
 
@@ -4692,6 +4655,9 @@ class MCPServerManager:
             extra_headers=extra_headers,
             stdio_env=stdio_env,
             subject_token=subject_token,
+            raw_headers=raw_headers,
+            client_ip=client_ip,
+            user_api_key_auth=user_api_key_auth,
         )
 
         return await client.read_resource(url)
@@ -4705,6 +4671,7 @@ class MCPServerManager:
         mcp_auth_header: str | dict[str, str] | None = None,
         extra_headers: dict[str, str] | None = None,
         raw_headers: dict[str, str] | None = None,
+        client_ip: str | None = None,
     ) -> GetPromptResult:
         """Fetch a specific prompt definition from a single MCP server."""
 
@@ -4725,6 +4692,9 @@ class MCPServerManager:
             extra_headers=extra_headers,
             stdio_env=stdio_env,
             subject_token=subject_token,
+            raw_headers=raw_headers,
+            client_ip=client_ip,
+            user_api_key_auth=user_api_key_auth,
         )
 
         get_prompt_request_params: Final = GetPromptRequestParams(
@@ -5805,6 +5775,8 @@ class MCPServerManager:
         stdio_env: dict[str, str] | None,
         subject_token: str | None,
         user_api_key_auth: UserAPIKeyAuth | None,
+        raw_headers: Mapping[str, str] | None = None,
+        client_ip: str | None = None,
     ) -> CallToolResult:
         """Call a token_exchange (OBO) tool; on an upstream 401/403 re-mint the token once and retry.
 
@@ -5830,6 +5802,8 @@ class MCPServerManager:
                 stdio_env=stdio_env,
                 subject_token=subject_token,
                 user_api_key_auth=user_api_key_auth,
+                raw_headers=raw_headers,
+                client_ip=client_ip,
             )
             return await retry_client.call_tool(call_tool_params, host_progress_callback=host_progress_callback)
 
@@ -5847,6 +5821,7 @@ class MCPServerManager:
         host_progress_callback: Callable | None = None,
         hook_extra_headers: dict[str, str] | None = None,
         user_api_key_auth: UserAPIKeyAuth | None = None,
+        client_ip: str | None = None,
     ) -> CallToolResult:
         """
         Call a regular MCP tool using the MCP client.
@@ -5991,6 +5966,8 @@ class MCPServerManager:
             stdio_env=stdio_env,
             subject_token=subject_token,
             user_api_key_auth=user_api_key_auth,
+            raw_headers=raw_headers,
+            client_ip=client_ip,
         )
 
         call_tool_params: Final = MCPCallToolRequestParams(
@@ -6014,6 +5991,8 @@ class MCPServerManager:
                         stdio_env=stdio_env,
                         subject_token=subject_token,
                         user_api_key_auth=user_api_key_auth,
+                        raw_headers=raw_headers,
+                        client_ip=client_ip,
                     )
 
             tool_call_coro = _obo_call_tool_limited()
@@ -6189,7 +6168,7 @@ class MCPServerManager:
             return oauth2_headers
 
         try:
-            from litellm.proxy._experimental.mcp_server.server import (  # noqa: PLC0415
+            from litellm.proxy._experimental.mcp_server.operations import (  # noqa: PLC0415
                 _get_user_oauth_extra_headers_from_db,
             )
 
@@ -6295,6 +6274,7 @@ class MCPServerManager:
         host_progress_callback: Callable | None = None,
         litellm_logging_obj: "LiteLLMLoggingObj | None" = None,
         guardrail_context: Mapping[str, object] | None = None,
+        client_ip: str | None = None,
     ) -> CallToolResult:
         """
         Call a tool with the given name and arguments
@@ -6421,6 +6401,7 @@ class MCPServerManager:
                 mcp_server_auth_headers=mcp_server_auth_headers,
                 oauth2_headers=oauth2_headers,
                 raw_headers=raw_headers,
+                client_ip=client_ip,
                 proxy_logging_obj=proxy_logging_obj,
                 host_progress_callback=host_progress_callback,
                 hook_extra_headers=hook_result.get("extra_headers"),
diff --git a/litellm/proxy/_experimental/mcp_server/operations.py b/litellm/proxy/_experimental/mcp_server/operations.py
new file mode 100644
index 00000000000..3ee4f37add7
--- /dev/null
+++ b/litellm/proxy/_experimental/mcp_server/operations.py
@@ -0,0 +1,3102 @@
+"""Shared MCP operation policy and dispatch."""
+
+import asyncio
+import traceback
+import types
+import uuid
+from collections.abc import Mapping, Sequence
+from datetime import datetime
+from typing import Any, Final, NoReturn, TypeAlias, assert_never, overload
+
+from fastapi import HTTPException
+from mcp import ReadResourceResult, Resource
+from mcp.types import (
+    CallToolRequest,
+    CallToolRequestParams,
+    CallToolResult,
+    GetPromptRequest,
+    GetPromptRequestParams,
+    GetPromptResult,
+    ListPromptsRequest,
+    ListPromptsResult,
+    ListResourcesRequest,
+    ListResourcesResult,
+    ListResourceTemplatesRequest,
+    ListResourceTemplatesResult,
+    ListToolsRequest,
+    ListToolsResult,
+    PaginatedRequestParams,
+    Prompt,
+    ReadResourceRequest,
+    ReadResourceRequestParams,
+    ResourceTemplate,
+    TextContent,
+)
+from mcp.types import Tool as MCPTool
+from pydantic import AnyUrl, ConfigDict, Field, TypeAdapter
+from typing_extensions import ReadOnly, TypedDict
+
+from litellm._logging import verbose_logger
+from litellm.constants import (
+    MAXIMUM_TRACEBACK_LINES_TO_LOG,
+)
+from litellm.litellm_core_utils.litellm_logging import Logging as LiteLLMLoggingObj
+from litellm.proxy._experimental.mcp_server.auth.user_api_key_auth_mcp import (
+    MCPRequestHandler,
+)
+from litellm.proxy._experimental.mcp_server.byok_credential_cache import (
+    byok_credential_cache,
+    byok_credential_cache_key,
+    cache_byok_credential,
+    get_cached_byok_credential,
+)
+from litellm.proxy._experimental.mcp_server.contracts import (
+    AuthorizedToolCall,
+    OperationContext,
+    ProgressCallback,
+)
+from litellm.proxy._experimental.mcp_server.db import OAuthCredentialPayload
+from litellm.proxy._experimental.mcp_server.exceptions import (
+    MCPToolResultError,
+    MCPUpstreamAuthError,
+)
+from litellm.proxy._experimental.mcp_server.faults.list_outcomes import (
+    SERVER_OUTCOMES_META_KEY,
+    AggregateToolListing,
+    ServerListOk,
+    ServerOutcome,
+    classify_list_exception,
+    outcome_wire_value,
+)
+from litellm.proxy._experimental.mcp_server.mcp_server_manager import (
+    MCPServerManager,
+    _caller_authorization_fans_out,
+    _client_forwarded_authorization_headers,
+    _resolve_openapi_tool_auth,
+    _should_strip_caller_authorization,
+    global_mcp_server_manager,
+)
+from litellm.proxy._experimental.mcp_server.oauth_utils import (
+    _redact_mcp_resource_url,
+    get_byok_www_authenticate,
+)
+from litellm.proxy._experimental.mcp_server.openapi_to_mcp_generator import (
+    _request_auth_header,
+    _request_extra_headers,
+    _request_resolved_auth_headers,
+)
+from litellm.proxy._experimental.mcp_server.tool_registry import (
+    global_mcp_tool_registry,
+)
+from litellm.proxy._experimental.mcp_server.utils import (
+    MCP_TOOL_PREFIX_SEPARATOR,
+    MCPMissingUserEnvVarsError,
+    add_server_prefix_to_name,
+    build_synthetic_mcp_request,
+    extract_mcp_tool_result_error_message,
+    get_server_prefix,
+    is_tool_name_prefixed,
+    iter_known_server_prefixes,
+    logging_safe_mcp_headers,
+    match_known_tool_name,
+    normalize_server_name,
+    split_server_prefix_from_name,
+    strip_known_server_prefix,
+)
+from litellm.proxy._types import (
+    UserAPIKeyAuth,
+)
+from litellm.proxy.common_utils.auth_cache_invalidation_pubsub import (
+    publish_auth_cache_invalidation,
+)
+from litellm.proxy.litellm_pre_call_utils import (
+    LiteLLMProxyRequestSetup,
+    get_chain_id_from_headers,
+)
+from litellm.types.mcp import (
+    DEFAULT_CREDENTIAL_HEADER,
+    MCPAuth,
+    without_header,
+)
+from litellm.types.mcp_server.mcp_server_manager import MCPInfo, MCPServer
+from litellm.types.utils import CallTypes, StandardLoggingMCPToolCall
+from litellm.utils import Rules, client, function_setup
+
+__all__ = (
+    "_MCP_CREDENTIAL_REQUEST_FIELDS",
+    "ListMCPToolsRestAPIResponseObject",
+    "MCPInfo",
+    "MCPServer",
+    "_McpDeniedDetail",
+    "_aggregate_server_key",
+    "_build_virtual_call_logging_obj",
+    "_check_byok_credential",
+    "_client_has_passthrough_authorization",
+    "_client_has_per_server_auth_header",
+    "_dispatch_virtual_mcp_tool",
+    "_fire_mcp_tool_call_logging",
+    "_get_allowed_mcp_servers",
+    "_get_allowed_mcp_servers_from_mcp_server_names",
+    "_get_byok_credential",
+    "_get_prompts_from_mcp_servers",
+    "_get_resource_templates_from_mcp_servers",
+    "_get_resources_from_mcp_servers",
+    "_get_standard_logging_mcp_tool_call",
+    "_get_tools_from_mcp_servers",
+    "_get_user_oauth_extra_headers_from_db",
+    "_handle_local_mcp_tool",
+    "_handle_managed_mcp_tool",
+    "_http_detail_message",
+    "_invalidate_byok_cred_cache",
+    "_list_mcp_prompts",
+    "_list_mcp_resource_templates",
+    "_list_mcp_resources",
+    "_list_mcp_tools",
+    "_list_tools_before_first_call",
+    "_mcp_session_id_from_headers",
+    "_merge_gateway_initialize_instructions",
+    "_prefetch_oauth_creds_for_user",
+    "_prepare_mcp_server_headers",
+    "_raise_if_initialize_grants_no_mcp_servers",
+    "_resolve_display_name_to_original",
+    "_run_post_mcp_call_guardrails",
+    "_server_answers_to",
+    "_tool_name_matches",
+    "apply_tool_overrides",
+    "call_mcp_tool",
+    "execute_mcp_tool",
+    "filter_tools_by_allowed_tools",
+    "filter_tools_by_key_team_permissions",
+    "fire_mcp_tool_call_failure_logging",
+    "mcp_get_prompt",
+    "mcp_read_resource",
+    "raise_denied_scoped_mcp_access",
+)
+
+
+async def _invalidate_byok_cred_cache(user_id: str, server_id: str) -> None:
+    """Drop a stored-or-deleted BYOK credential from this worker's cache and from every peer worker's."""
+    cache_key: Final = byok_credential_cache_key(user_id, server_id)
+    byok_credential_cache.delete_cache(cache_key)
+    await publish_auth_cache_invalidation(cache_key=cache_key)
+
+
+def _mcp_session_id_from_headers(
+    raw_headers: dict[str, str] | None,
+) -> str | None:
+    """The ``mcp-session-id`` of a stateful MCP session, read case-insensitively
+    from the request headers. ``None`` for stateless calls (no such header)."""
+    if not raw_headers:
+        return None
+    for key, value in raw_headers.items():
+        if isinstance(key, str) and key.lower() == "mcp-session-id":
+            return value or None
+    return None
+
+
+class ListMCPToolsRestAPIResponseObject(MCPTool):
+    """
+    Object returned by the /tools/list REST API route.
+    """
+
+    mcp_info: MCPInfo | None = Field(default=None, alias="mcp_info")
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+
+async def _build_virtual_call_logging_obj(
+    name: str,
+    arguments: dict[str, object],
+    user_api_key_auth: UserAPIKeyAuth,
+    raw_headers: Mapping[str, str] | None = None,
+    client_ip: str | None = None,
+) -> LiteLLMLoggingObj | None:
+    """Run the pre-call pipeline (guardrails + logging setup) for a virtual
+    mcp_tool_call so the SSE path spend-logs like the REST path."""
+    from litellm.proxy.common_request_processing import (
+        ProxyBaseLLMRequestProcessing,
+    )
+    from litellm.proxy.proxy_server import (
+        general_settings,
+        proxy_config,
+        proxy_logging_obj,
+    )
+
+    request: Final = build_synthetic_mcp_request(
+        path="/mcp/tools/call",
+        raw_headers=raw_headers,
+        client_ip=client_ip,
+    )
+    _, virtual_logging_obj = await ProxyBaseLLMRequestProcessing(
+        data={"name": name, "arguments": arguments}
+    ).common_processing_pre_call_logic(
+        request=request,
+        user_api_key_dict=user_api_key_auth,
+        proxy_config=proxy_config,
+        route_type=CallTypes.call_mcp_tool.value,
+        proxy_logging_obj=proxy_logging_obj,
+        general_settings=general_settings,
+    )
+    return virtual_logging_obj
+
+
+async def _dispatch_virtual_mcp_tool(
+    name: str,
+    arguments: dict[str, object] | None,
+    user_api_key_auth: UserAPIKeyAuth | None,
+    client_ip: str | None,
+    mcp_servers: list[str] | None = None,
+    mcp_auth_header: str | None = None,
+    mcp_server_auth_headers: dict[str, dict[str, str]] | None = None,
+    oauth2_headers: dict[str, str] | None = None,
+    raw_headers: dict[str, str] | None = None,
+    mcp_proxy_mode: bool = False,
+) -> CallToolResult | None:
+    """Handle the mcp_tool_search / mcp_tool_call virtual tools.
+
+    Returns a CallToolResult when ``name`` is a virtual tool, else ``None`` so
+    the caller falls through to normal tool routing.
+    """
+    from litellm.llms.litellm_proxy.skills.skill_search import DEFAULT_SKILL_SEARCH_TOP_K
+    from litellm.proxy._experimental.mcp_server.tool_search import (
+        AGENT_SEARCH_TOOL_NAME,
+        DEFAULT_AGENT_SEARCH_TOP_K,
+        MCP_PROXY_CALL_TOOL_NAME,
+        MCP_PROXY_TOOL_NAMES,
+        MCP_TOOL_SEARCH_TOOL_NAME,
+        SKILL_SEARCH_TOOL_NAME,
+        VIRTUAL_TOOL_NAMES,
+        coerce_top_k,
+        handle_agent_search,
+        handle_mcp_proxy_tool,
+        handle_mcp_tool_call,
+        handle_mcp_tool_search,
+        handle_skill_search,
+    )
+
+    if mcp_proxy_mode and name not in MCP_PROXY_TOOL_NAMES:
+        return CallToolResult(
+            content=[  # mutable-ok: MCP result content
+                TextContent(type="text", text=f"Tool {name} is unavailable on /mcp/proxy")
+            ],
+            is_error=True,
+        )
+
+    if mcp_proxy_mode and name in MCP_PROXY_TOOL_NAMES:
+        assert user_api_key_auth is not None
+        proxy_call_start: Final = datetime.now()  # noqa: DTZ005  # logging pipeline uses naive datetimes
+        proxy_logging_obj: Final = (
+            await _build_virtual_call_logging_obj(
+                name=name,
+                arguments=arguments or {},  # mutable-ok: logging pipeline payload
+                user_api_key_auth=user_api_key_auth,
+                raw_headers=raw_headers,
+                client_ip=client_ip,
+            )
+            if name == MCP_PROXY_CALL_TOOL_NAME
+            else None
+        )
+        try:
+            proxy_result: Final = await handle_mcp_proxy_tool(
+                name=name,
+                arguments=arguments or {},  # mutable-ok: proxy handler payload
+                user_api_key_dict=user_api_key_auth,
+                client_ip=client_ip,
+                mcp_servers=mcp_servers,
+                mcp_auth_header=mcp_auth_header,
+                mcp_server_auth_headers=mcp_server_auth_headers,
+                oauth2_headers=oauth2_headers,
+                raw_headers=raw_headers,
+                litellm_logging_obj=proxy_logging_obj,
+            )
+        except Exception as exc:
+            if proxy_logging_obj is not None:
+                from litellm.proxy.proxy_server import proxy_logging_obj as request_logging_obj
+
+                failure_end: Final = datetime.now()  # noqa: DTZ005  # matches the logging pipeline start time
+                failure_traceback: Final = traceback.format_exc(limit=MAXIMUM_TRACEBACK_LINES_TO_LOG)
+                try:
+                    proxy_logging_obj.failure_handler(exc, failure_traceback, proxy_call_start, failure_end)
+                    await proxy_logging_obj.async_failure_handler(exc, failure_traceback, proxy_call_start, failure_end)
+                    if not isinstance(exc, MCPUpstreamAuthError):
+                        await request_logging_obj.post_call_failure_hook(
+                            request_data={  # mutable-ok: failure hook mutates its request payload
+                                "name": name,
+                                "arguments": arguments,
+                                "litellm_logging_obj": proxy_logging_obj,
+                            },
+                            original_exception=exc,
+                            user_api_key_dict=user_api_key_auth,
+                            route="/mcp/call_tool",
+                            traceback_str=failure_traceback,
+                        )
+                except Exception:  # noqa: BLE001  # a failing failure hook must not mask the tool call's own error
+                    verbose_logger.exception("Error logging failed MCP proxy tool call")
+            raise
+        if proxy_logging_obj is not None:
+            return await _fire_mcp_tool_call_logging(
+                logging_obj=proxy_logging_obj,
+                result=proxy_result,
+                start_time=proxy_call_start,
+                end_time=datetime.now(),  # noqa: DTZ005  # matches the logging pipeline start time
+                user_api_key_auth=user_api_key_auth,
+                request_data=types.MappingProxyType({"name": name, "arguments": arguments}),
+            )
+        return proxy_result
+
+    if name not in VIRTUAL_TOOL_NAMES:
+        return None
+
+    if not getattr(
+        getattr(user_api_key_auth, "object_permission", None),
+        "mcp_tool_search_enabled",
+        False,
+    ):
+        return CallToolResult(
+            content=[
+                TextContent(
+                    type="text",
+                    text=f"Tool {name} requires mcp_tool_search_enabled on the key",
+                )
+            ],
+            is_error=True,
+        )
+
+    args: Final = arguments or {}
+    if name == MCP_TOOL_SEARCH_TOOL_NAME:
+        return await handle_mcp_tool_search(
+            query=TypeAdapter(str).validate_python(args.get("query", "")),
+            top_k=coerce_top_k(args.get("top_k", 5)),
+            user_api_key_dict=user_api_key_auth,
+            client_ip=client_ip,
+            mcp_servers=mcp_servers,
+            mcp_auth_header=mcp_auth_header,
+            mcp_server_auth_headers=mcp_server_auth_headers,
+            oauth2_headers=oauth2_headers,
+            raw_headers=raw_headers,
+        )
+
+    assert user_api_key_auth is not None  # guaranteed by the flag check above
+    if name == AGENT_SEARCH_TOOL_NAME:
+        return await handle_agent_search(
+            query=str(args.get("query", "")),
+            top_k=coerce_top_k(args.get("top_k", DEFAULT_AGENT_SEARCH_TOP_K), default=DEFAULT_AGENT_SEARCH_TOP_K),
+            user_api_key_dict=user_api_key_auth,
+        )
+    if name == SKILL_SEARCH_TOOL_NAME:
+        return await handle_skill_search(
+            query=str(args.get("query", "")),
+            top_k=coerce_top_k(args.get("top_k", DEFAULT_SKILL_SEARCH_TOP_K), default=DEFAULT_SKILL_SEARCH_TOP_K),
+            user_api_key_dict=user_api_key_auth,
+        )
+    virtual_logging_obj: Final = await _build_virtual_call_logging_obj(
+        name=name,
+        arguments=args,
+        user_api_key_auth=user_api_key_auth,
+        raw_headers=raw_headers,
+        client_ip=client_ip,
+    )
+    tool_request: Final = CallToolRequestParams.model_validate(
+        types.MappingProxyType({"name": args.get("tool_name", ""), "arguments": args.get("arguments") or {}})
+    )
+    return await handle_mcp_tool_call(
+        tool_name=tool_request.name,
+        arguments=tool_request.arguments or {},
+        user_api_key_dict=user_api_key_auth,
+        client_ip=client_ip,
+        mcp_servers=mcp_servers,
+        mcp_auth_header=mcp_auth_header,
+        mcp_server_auth_headers=mcp_server_auth_headers,
+        oauth2_headers=oauth2_headers,
+        raw_headers=raw_headers,
+        litellm_logging_obj=virtual_logging_obj,
+    )
+
+
+async def _get_allowed_mcp_servers_from_mcp_server_names(
+    mcp_servers: Sequence[str] | None,
+    allowed_mcp_servers: list[MCPServer],
+) -> list[MCPServer]:
+    """
+    Get the filtered MCP servers from the MCP server names.
+
+    Fails closed when ``mcp_servers`` is explicitly provided (path- or
+    header-derived) but none of the names resolve to a server alias or
+    access group the caller can access. The previous behavior returned
+    the full ``allowed_mcp_servers`` set, which silently widened scope
+    when a client targeted ``/mcp/<unknown>/`` and made URL/header
+    namespacing appear to work when it did not.
+    """
+
+    filtered_server: Final[dict[str, MCPServer]] = {}
+    # Filter servers based on mcp_servers parameter if provided
+    if mcp_servers is not None:
+        for server_or_group in mcp_servers:
+            server_name_matched = False
+
+            for server in allowed_mcp_servers:
+                if server and _server_answers_to(server, server_or_group):
+                    filtered_server[server.server_id] = server
+                    server_name_matched = True
+                    break
+
+            if not server_name_matched:
+                try:
+                    access_group_server_ids = await MCPRequestHandler._get_mcp_servers_from_access_groups(
+                        [server_or_group]
+                    )
+                    # Only include servers that the user has access to
+                    for server_id in access_group_server_ids:
+                        for server in allowed_mcp_servers:
+                            if server_id == server.server_id:
+                                filtered_server[server.server_id] = server
+                except Exception as e:
+                    verbose_logger.debug("Could not resolve '%s' as access group: %s", server_or_group, e)
+
+    if filtered_server:
+        return list(filtered_server.values())
+
+    if mcp_servers is not None:
+        # Caller asked for a specific scope but nothing resolved. Fail
+        # closed so URL/header namespacing cannot silently fall back to
+        # the caller's full allowed-server set.
+        verbose_logger.debug(
+            "MCP scope filter resolved to no servers for requested names %s; returning empty list (fail-closed).",
+            mcp_servers,
+        )
+        return []
+
+    return allowed_mcp_servers
+
+
+def _http_detail_message(detail: object) -> str:
+    return str(detail.get("error")) if isinstance(detail, dict) and detail.get("error") else str(detail)
+
+
+def _server_answers_to(server: MCPServer, name: str) -> bool:
+    requested: Final = name.lower()
+    return any(requested == known.lower() for known in iter_known_server_prefixes(server) if known)
+
+
+async def raise_denied_scoped_mcp_access(
+    requested_names: Sequence[str],
+    user_api_key_auth: UserAPIKeyAuth | None,
+    client_ip: str | None = None,
+) -> None:
+    """A scoped request (``/mcp/<name>`` path or ``x-mcp-servers`` header) resolved to zero
+    allowed servers, so the denial must be loud: a silent 200 with no tools reads as a healthy
+    server with no tools. Unknown, unauthorized, and access-group names all share one generic
+    error so scoping cannot probe which servers exist; the agent variant fires only when the
+    same request resolves once the agent binding is stripped, proving the binding caused the veto."""
+    agent_id: Final = user_api_key_auth.agent_id if user_api_key_auth else None
+    if user_api_key_auth is not None and agent_id:
+        resolved_without_agent: Final = await _get_allowed_mcp_servers(
+            user_api_key_auth=user_api_key_auth.model_copy(update=types.MappingProxyType({"agent_id": None})),
+            mcp_servers=requested_names,
+            client_ip=client_ip,
+        )
+
+        def _resolved_to_server(name: str) -> bool:
+            return any(_server_answers_to(server, name) for server in resolved_without_agent)
+
+        vetoed_server: Final = next((name for name in requested_names if _resolved_to_server(name)), None)
+        if vetoed_server is not None:
+            agent_denial: Final[_McpDeniedDetail] = {
+                "error": (
+                    f"MCP server '{vetoed_server}' is not available to this key: the key is bound to "
+                    f"agent '{agent_id}', whose MCP grants do not include this server. Add the server "
+                    f"to the agent's object_permission.mcp_servers (edit the agent in the Admin UI or "
+                    f"PATCH /v1/agents/{agent_id}), or use a key that is not bound to the agent."
+                )
+            }
+            raise HTTPException(status_code=403, detail=agent_denial)
+        vetoed_group: Final = next(
+            (
+                name
+                for name in requested_names
+                if not _resolved_to_server(name)
+                and any(name in (server.access_groups or ()) for server in resolved_without_agent)
+            ),
+            None,
+        )
+        if vetoed_group is not None:
+            group_denial: Final[_McpDeniedDetail] = {
+                "error": (
+                    f"MCP access group '{vetoed_group}' is not available to this key: the key is bound to "
+                    f"agent '{agent_id}', whose MCP grants do not include it. Add the group to the "
+                    f"agent's object_permission.mcp_access_groups (edit the agent in the Admin UI or "
+                    f"PATCH /v1/agents/{agent_id}), or use a key that is not bound to the agent."
+                )
+            }
+            raise HTTPException(status_code=403, detail=group_denial)
+    generic_denial: Final[_McpDeniedDetail] = {
+        "error": f"The key is not allowed to access the requested MCP servers: {', '.join(requested_names)}"
+    }
+    raise HTTPException(status_code=403, detail=generic_denial)
+
+
+def _tool_name_matches(tool_name: str, filter_list: list[str], mcp_server: MCPServer) -> bool:
+    """
+    Check if a tool name matches any name in the filter list.
+
+    Reads the same owner the server-level permission checks use, so discovery hides
+    exactly what dispatch refuses. ``mcp_server`` is required: guessing the boundary
+    at the first separator mismatches every tool on a server whose prefix contains
+    the separator.
+    """
+    bare_name: Final = strip_known_server_prefix(tool_name, mcp_server)
+    return match_known_tool_name(bare_name, mcp_server, filter_list) is not None
+
+
+def filter_tools_by_allowed_tools(
+    tools: list[MCPTool],
+    mcp_server: MCPServer,
+) -> list[MCPTool]:
+    """
+    Filter tools by allowed/disallowed tools configuration.
+
+    If allowed_tools is set, only tools in that list are returned.
+    If disallowed_tools is set, tools in that list are excluded.
+    Tool names are matched with and without server prefixes for flexibility.
+
+    Args:
+        tools: List of tools to filter
+        mcp_server: Server configuration with allowed_tools/disallowed_tools
+
+    Returns:
+        Filtered list of tools
+    """
+    from litellm.proxy._experimental.mcp_server.utils import (
+        server_applies_tool_allowlist,
+    )
+
+    tools_to_return = tools
+
+    # Filter by allowed_tools (whitelist)
+    if server_applies_tool_allowlist(mcp_server):
+        if not mcp_server.allowed_tools:
+            return []
+        tools_to_return = [
+            tool for tool in tools if _tool_name_matches(tool.name, mcp_server.allowed_tools, mcp_server)
+        ]
+
+    # Filter by disallowed_tools (blacklist)
+    if mcp_server.disallowed_tools:
+        tools_to_return = [
+            tool
+            for tool in tools_to_return
+            if not _tool_name_matches(tool.name, mcp_server.disallowed_tools, mcp_server)
+        ]
+
+    return tools_to_return
+
+
+def apply_tool_overrides(
+    tools: list[MCPTool],
+    mcp_server: MCPServer,
+) -> list[MCPTool]:
+    """Apply admin-configured display name/description overrides to tools.
+
+    Overrides are keyed by the unprefixed tool name, same convention as
+    allowed_tools configuration.
+    """
+    display_name_map: Final = mcp_server.tool_name_to_display_name or {}
+    description_map: Final = mcp_server.tool_name_to_description or {}
+    if not display_name_map and not description_map:
+        return tools
+
+    for tool in tools:
+        unprefixed = strip_known_server_prefix(tool.name, mcp_server)
+        lookup_key = unprefixed or tool.name
+        if lookup_key in display_name_map:
+            tool.name = display_name_map[lookup_key]
+        if lookup_key in description_map:
+            tool.description = description_map[lookup_key]
+    return tools
+
+
+async def _get_allowed_mcp_servers(
+    user_api_key_auth: UserAPIKeyAuth | None,
+    mcp_servers: Sequence[str] | None,
+    client_ip: str | None = None,
+) -> list[MCPServer]:
+    """Return allowed MCP servers for a request after applying filters.
+
+    Args:
+        user_api_key_auth: The authenticated user's API key info.
+        mcp_servers: Optional list of server names to filter to.
+        client_ip: Client IP for IP-based access control. If None, falls back to
+                  auth context. Pass explicitly from request handlers for safety.
+    Note: If client_ip is None and auth context is not set, IP filtering is skipped.
+          This is intentional for internal callers but may indicate a bug if called
+          from a request handler without proper context setup.
+    """
+    allowed_mcp_server_ids = await global_mcp_server_manager.get_allowed_mcp_servers(user_api_key_auth)
+    (
+        allowed_mcp_server_ids,
+        _ip_blocked,
+    ) = global_mcp_server_manager.filter_server_ids_by_ip_with_info(allowed_mcp_server_ids, client_ip)
+    verbose_logger.debug(
+        "MCP IP filter: client_ip=%s, allowed_server_ids=%s",
+        client_ip,
+        allowed_mcp_server_ids,
+    )
+    if _ip_blocked > 0:
+        verbose_logger.debug(
+            "MCP IP filtering: %d server(s) are not accessible from client IP %s "
+            "because they are restricted to internal networks. "
+            "No tools from those servers will be returned. "
+            "To expose a server externally, set 'available_on_public_internet: true' "
+            "in its configuration.",
+            _ip_blocked,
+            client_ip,
+        )
+    allowed_mcp_servers: list[MCPServer] = []
+    for allowed_mcp_server_id in allowed_mcp_server_ids:
+        mcp_server = global_mcp_server_manager.get_mcp_server_by_id(allowed_mcp_server_id)
+        if mcp_server is not None:
+            # Apply the request-time oauth2_flow backstop for legacy null rows.
+            mcp_server = MCPServerManager.resolve_oauth2_flow_for_request(mcp_server)
+            allowed_mcp_servers.append(mcp_server)
+
+    if mcp_servers is not None:
+        allowed_mcp_servers = await _get_allowed_mcp_servers_from_mcp_server_names(
+            mcp_servers=mcp_servers,
+            allowed_mcp_servers=allowed_mcp_servers,
+        )
+
+    return allowed_mcp_servers
+
+
+def _client_has_per_server_auth_header(
+    server: MCPServer,
+    mcp_server_auth_headers: dict[str, dict[str, str]] | None,
+) -> bool:
+    """True if the request carries a per-server ``x-mcp-{alias}-authorization``
+    header for this server. This is the multi-server binding: it names one
+    upstream, so it is unambiguously the caller's upstream token regardless of
+    auth mode (never the LiteLLM admission credential).
+
+    Resolves through the same ``lookup_mcp_server_auth_in_headers`` egress uses, so
+    the connect gate and egress agree on which per-server header names match: a
+    dashboard client sends ``x-mcp-{sanitize_mcp_alias_for_header(alias)}-authorization``,
+    and matching only the raw alias here would 401 a token egress would forward.
+    """
+    if not mcp_server_auth_headers:
+        return False
+    from litellm.proxy._experimental.mcp_server.utils import (
+        lookup_mcp_server_auth_in_headers,
+    )
+
+    server_headers: Final = lookup_mcp_server_auth_in_headers(
+        mcp_server_auth_headers,
+        alias=server.alias,
+        server_name=server.server_name,
+        access_groups=server.access_groups,
+    )
+    if isinstance(server_headers, str):
+        return bool(server_headers.strip())
+    if isinstance(server_headers, dict):
+        return any(isinstance(hk, str) and hk.lower() == "authorization" for hk in server_headers)
+    return False
+
+
+def _client_has_passthrough_authorization(
+    server: MCPServer,
+    oauth2_headers: dict[str, str] | None,
+    mcp_server_auth_headers: dict[str, dict[str, str]] | None,
+) -> bool:
+    """True if the incoming request already carries an ``Authorization``
+    header the gateway will forward to this pass-through server.
+
+    The client may supply the bearer as either the top-level
+    ``Authorization`` header (surfaced via ``oauth2_headers``) or a
+    per-server ``x-mcp-auth-<alias>`` style header (surfaced via
+    ``mcp_server_auth_headers``). Either form skips the pre-emptive 401.
+    """
+    if oauth2_headers:
+        for k in oauth2_headers:
+            if k.lower() == "authorization":
+                return True
+    return _client_has_per_server_auth_header(server, mcp_server_auth_headers)
+
+
+async def _get_user_oauth_extra_headers_from_db(
+    server: MCPServer,
+    user_api_key_auth: UserAPIKeyAuth | None,
+    prefetched_creds: 'Mapping[str, "OAuthCredentialPayload"] | None' = None,
+) -> dict[str, str] | None:
+    """Stored OAuth2 token for (user, server) as an ``Authorization: Bearer`` header, or None.
+
+    Thin wrapper over ``resolve_user_oauth_access_token`` (Redis cache, else DB + refresh);
+    ``prefetched_creds`` skips the per-server Redis/DB lookups for the batch path.
+    """
+    if server.auth_type != MCPAuth.oauth2 or user_api_key_auth is None:
+        return None
+    from litellm.proxy._experimental.mcp_server.db import (  # noqa: PLC0415
+        resolve_user_oauth_access_token,
+    )
+
+    token: Final = await resolve_user_oauth_access_token(
+        getattr(user_api_key_auth, "user_id", None), server, prefetched_creds
+    )
+    return {"Authorization": f"Bearer {token}"} if token else None
+
+
+async def _prefetch_oauth_creds_for_user(
+    user_api_key_auth: UserAPIKeyAuth | None,
+) -> dict[str, "OAuthCredentialPayload"]:
+    """Fetch all OAuth2 credentials for the user in one DB query.
+
+    Returns a dict keyed by server_id to avoid N+1 queries in asyncio.gather loops.
+    """
+    user_id: Final[str | None] = getattr(user_api_key_auth, "user_id", None) if user_api_key_auth else None
+    if not user_id:
+        return {}
+    try:
+        from litellm.proxy._experimental.mcp_server.db import (  # noqa: PLC0415
+            list_user_oauth_credentials,
+        )
+        from litellm.proxy.utils import get_prisma_client_or_throw  # noqa: PLC0415
+
+        prisma_client: Final = get_prisma_client_or_throw(
+            "Database not connected. Connect a database to use OAuth2 MCP tools."
+        )
+        creds: Final = await list_user_oauth_credentials(prisma_client, user_id)
+        return {c["server_id"]: c for c in creds if "server_id" in c}
+    except Exception as e:
+        verbose_logger.warning("_prefetch_oauth_creds_for_user: failed to prefetch for user=%s: %s", user_id, e)
+        return {}
+
+
+def _prepare_mcp_server_headers(
+    server: MCPServer,
+    mcp_server_auth_headers: dict[str, dict[str, str]] | None,
+    mcp_auth_header: str | None,
+    oauth2_headers: dict[str, str] | None,
+    raw_headers: dict[str, str] | None,
+    user_api_key_auth: UserAPIKeyAuth | None = None,
+    scope_servers: list[MCPServer] | None = None,
+) -> tuple[dict[str, str] | str | None, dict[str, str] | None]:
+    """Build auth and extra headers for a server.
+
+    ``scope_servers`` is the full server list a fan-out handler iterates. Passing it lets the
+    client-forwarded token modes withhold the caller's request-wide ``Authorization`` when
+    another server in the scope would also receive it (``_caller_authorization_fans_out``);
+    explicitly-addressed operations leave it None. Per-server ``x-mcp-{alias}-authorization``
+    headers are unaffected — they bind one token to one server and are the multi-server shape.
+    """
+    server_auth_header: dict[str, str] | str | None = None
+    if mcp_server_auth_headers:
+        from litellm.proxy._experimental.mcp_server.utils import (
+            lookup_mcp_server_auth_in_headers,
+        )
+
+        server_auth_header = lookup_mcp_server_auth_in_headers(
+            mcp_server_auth_headers,
+            alias=server.alias,
+            server_name=server.server_name,
+            access_groups=server.access_groups,
+        )
+
+    extra_headers: dict[str, str] | None = None
+    is_client_forwarded_mode: Final = server.is_client_forwarded_token
+    # In a multi-server listing scope the request-wide Authorization can only carry one token,
+    # so it is withheld from a client-forwarded server when another server in scope also consumes
+    # it (RFC 9700 cross-resource replay); such scopes must bind per-server via
+    # x-mcp-{alias}-authorization. The decision is computed once so BOTH the forwarding branch and
+    # the extra_headers copy loop below honor it — otherwise a server that lists Authorization in
+    # extra_headers would re-copy the withheld bearer from raw_headers and replay it anyway.
+    withhold_forwarded_authorization: Final = is_client_forwarded_mode and _caller_authorization_fans_out(
+        server, scope_servers
+    )
+    if server.auth_type == MCPAuth.oauth2:
+        # For OAuth2 M2M servers, upstream Authorization must come from
+        # client_credentials token fetch, never from caller headers.
+        if server.has_client_credentials:
+            extra_headers = None
+        else:
+            # Copy to avoid mutating the original dict (important for parallel fetching)
+            extra_headers = oauth2_headers.copy() if oauth2_headers else None
+            # Migrated authorization_code: the v2 resolver injects the stored per-user
+            # token, so drop the caller-forwarded Authorization (apply-if-absent would
+            # otherwise let it shadow the resolved token). Delegate keeps it. Centralized
+            # via _should_strip_caller_authorization to match _call_regular_mcp_tool.
+            if extra_headers and _should_strip_caller_authorization(
+                mcp_server=server,
+                raw_headers=raw_headers,
+                user_api_key_auth=user_api_key_auth,
+            ):
+                extra_headers = without_header(extra_headers, DEFAULT_CREDENTIAL_HEADER)
+    elif is_client_forwarded_mode:
+        if not withhold_forwarded_authorization:
+            extra_headers = _client_forwarded_authorization_headers(
+                mcp_server=server,
+                oauth2_headers=oauth2_headers,
+                raw_headers=raw_headers,
+                user_api_key_auth=user_api_key_auth,
+            )
+
+    if server.extra_headers and raw_headers:
+        if extra_headers is None:
+            extra_headers = {}
+
+        normalized_raw_headers: Final = {str(k).lower(): v for k, v in raw_headers.items() if isinstance(k, str)}
+
+        # Centralized strip decision shared with
+        # ``MCPServerManager._call_regular_mcp_tool`` so the two
+        # code paths cannot drift on this security-sensitive choice.
+        # See ``_should_strip_caller_authorization`` for the rules.
+        strip_caller_authorization: Final = _should_strip_caller_authorization(
+            mcp_server=server,
+            raw_headers=raw_headers,
+            user_api_key_auth=user_api_key_auth,
+        )
+
+        for header in server.extra_headers:
+            if not isinstance(header, str):
+                continue
+            if header.lower() == "authorization" and (strip_caller_authorization or withhold_forwarded_authorization):
+                continue
+            header_value = normalized_raw_headers.get(header.lower())
+            if header_value is None:
+                continue
+            extra_headers[header] = header_value
+
+    # Reset to None if no headers were actually added
+    if extra_headers is not None and len(extra_headers) == 0:
+        extra_headers = None
+
+    if server_auth_header is None:
+        server_auth_header = mcp_auth_header
+
+    return server_auth_header, extra_headers
+
+
+def _merge_gateway_initialize_instructions(
+    allowed_mcp_servers: list[MCPServer],
+) -> str | None:
+    """YAML/DB override, else upstream text (prefetch on init, or list_tools / health_check / call_tool cache)."""
+    if not allowed_mcp_servers:
+        return None
+
+    texts: Final[list[tuple[str, str]]] = []
+    for server in allowed_mcp_servers:
+        label = server.alias or server.server_name or server.name or server.server_id or "mcp"
+        if server.instructions and server.instructions.strip():
+            texts.append((label, server.instructions.strip()))
+            continue
+        if server.spec_path:
+            continue
+        cached = global_mcp_server_manager._upstream_initialize_instructions_by_server_id.get(server.server_id)
+        if cached and cached.strip():
+            texts.append((label, cached.strip()))
+
+    if not texts:
+        return None
+    if len(texts) == 1:
+        return texts[0][1]
+    return "\n\n---\n\n".join(f"[{lbl}]\n{txt}" for lbl, txt in texts)
+
+
+async def _raise_if_initialize_grants_no_mcp_servers(
+    allowed: Sequence[MCPServer],
+    user_api_key_auth: UserAPIKeyAuth | None,
+    mcp_servers: Sequence[str] | None,
+    client_ip: str | None,
+) -> None:
+    if allowed or user_api_key_auth is None or not user_api_key_auth.api_key:
+        return
+    if mcp_servers:
+        await raise_denied_scoped_mcp_access(
+            requested_names=mcp_servers,
+            user_api_key_auth=user_api_key_auth,
+            client_ip=client_ip,
+        )
+    no_servers_denial: Final[_McpDeniedDetail] = {
+        "error": (
+            "The key has no MCP servers granted, or none of its granted servers is loaded and allowed for "
+            "this client IP. Grant servers or access groups to the key, its team, or its organization "
+            "(object_permission.mcp_servers), check the server's allowed IPs, and reconnect."
+        )
+    }
+    raise HTTPException(status_code=403, detail=no_servers_denial)
+
+
+def _aggregate_server_key(server: MCPServer) -> str:
+    """The client-visible key for a server in listing outcomes and spend metadata: the same
+    display prefix (alias, or the short prefix when that mode is enabled) the caller already
+    sees on the tool names. Canonical internal server names never key a caller-readable
+    surface; when the display naming deliberately hides them, the outcome keys must too."""
+    return get_server_prefix(server) or "unknown"
+
+
+async def _get_tools_from_mcp_servers(
+    user_api_key_auth: UserAPIKeyAuth | None,
+    mcp_auth_header: str | None,
+    mcp_servers: list[str] | None,
+    mcp_server_auth_headers: dict[str, dict[str, str]] | None = None,
+    oauth2_headers: dict[str, str] | None = None,
+    raw_headers: dict[str, str] | None = None,
+    log_list_tools_to_spendlogs: bool = False,
+    list_tools_log_source: str | None = None,
+    litellm_trace_id: str | None = None,
+    request_tags: list[str] | None = None,
+    client_ip: str | None = None,
+    mcp_proxy_mode: bool = False,
+) -> AggregateToolListing:
+    """
+    Helper method to fetch tools from MCP servers based on server filtering criteria.
+
+    Args:
+        user_api_key_auth: User authentication info for access control
+        mcp_auth_header: Optional auth header for MCP server (deprecated)
+        mcp_servers: Optional list of server names/aliases to filter by
+        mcp_server_auth_headers: Optional dict of server-specific auth headers
+        oauth2_headers: Optional dict of oauth2 headers
+
+    Returns:
+        AggregateToolListing: Combined tools from filtered servers plus each server's
+        classified listing outcome
+    """
+
+    list_tools_start_time: Final = datetime.now()
+    litellm_logging_obj: LiteLLMLoggingObj | None = None
+    list_tools_request_data: dict[str, object] = {}
+
+    if log_list_tools_to_spendlogs:
+        # This is intentionally minimal: only async_success_handler / post_call_failure_hook
+        rules_obj: Final = Rules()
+        list_tools_call_id: Final = str(uuid.uuid4())
+        # Derive trace_id from raw_headers when not explicitly passed (same as A2A / MCP call_tool)
+        effective_litellm_trace_id: Final = litellm_trace_id or get_chain_id_from_headers(raw_headers)
+        spend_logs_metadata: Final[dict[str, object]] = {
+            "mcp_operation": "list_tools",
+        }
+        if isinstance(list_tools_log_source, str):
+            spend_logs_metadata["source"] = list_tools_log_source
+        if isinstance(mcp_servers, list):
+            spend_logs_metadata["requested_mcp_servers"] = mcp_servers
+
+        list_tools_request_data = {
+            "model": "MCP: list_tools",
+            "call_type": CallTypes.list_mcp_tools.value,
+            "litellm_call_id": list_tools_call_id,
+            "litellm_trace_id": effective_litellm_trace_id,
+            "metadata": {
+                "spend_logs_metadata": spend_logs_metadata,
+                "headers": logging_safe_mcp_headers(raw_headers),
+                **({"tags": request_tags} if request_tags else {}),
+            },
+            # Provide a small input payload for standard logging
+            "input": [
+                {
+                    "role": "system",
+                    "content": {
+                        "mcp_operation": "list_tools",
+                        "requested_mcp_servers": mcp_servers,
+                    },
+                }
+            ],
+        }
+
+        # Attach user identifiers using the standard helper
+        if user_api_key_auth is not None:
+            LiteLLMProxyRequestSetup.add_user_api_key_auth_to_request_metadata(
+                data=list_tools_request_data,
+                user_api_key_dict=user_api_key_auth,
+                _metadata_variable_name="metadata",
+            )
+
+            user_identifier: Final = getattr(user_api_key_auth, "end_user_id", None) or getattr(
+                user_api_key_auth, "user_id", None
+            )
+            if user_identifier:
+                list_tools_request_data["user"] = user_identifier
+
+        try:
+            litellm_logging_obj, _ = function_setup(
+                original_function="list_mcp_tools",
+                is_async_call=False,
+                rules_obj=rules_obj,
+                start_time=list_tools_start_time,
+                **list_tools_request_data,
+            )
+            if litellm_logging_obj:
+                litellm_logging_obj.call_type = CallTypes.list_mcp_tools.value
+                litellm_logging_obj.model = "MCP: list_tools"
+        except Exception as logging_error:
+            verbose_logger.debug("Failed to initialize logging for MCP list_tools: %s", logging_error)
+            litellm_logging_obj = None
+
+    try:
+        allowed_mcp_servers: Final = await _get_allowed_mcp_servers(
+            user_api_key_auth=user_api_key_auth,
+            mcp_servers=mcp_servers,
+            client_ip=client_ip,
+        )
+        if mcp_servers and not allowed_mcp_servers:
+            await raise_denied_scoped_mcp_access(
+                requested_names=mcp_servers,
+                user_api_key_auth=user_api_key_auth,
+                client_ip=client_ip,
+            )
+
+        # Pre-fetch OAuth credentials only when at least one server uses OAuth2,
+        # to avoid an unnecessary DB round-trip on requests with no OAuth2 MCP servers.
+        _has_oauth2_server = any(getattr(s, "auth_type", None) == MCPAuth.oauth2 for s in allowed_mcp_servers)
+        _prefetched_oauth_creds: Final = (
+            await _prefetch_oauth_creds_for_user(user_api_key_auth) if _has_oauth2_server else {}
+        )
+
+        async def _fetch_and_filter_server_tools(
+            server: MCPServer,
+        ) -> "tuple[list[MCPTool], ServerOutcome]":
+            """Fetch and filter tools from a single server, classifying any failure into that
+            server's outcome so the aggregate can keep serving the healthy subset without a
+            broken server masquerading as an empty one."""
+            if server is None:
+                return [], ServerListOk(tool_count=0)
+
+            server_auth_header, extra_headers = _prepare_mcp_server_headers(
+                server=server,
+                mcp_server_auth_headers=mcp_server_auth_headers,
+                mcp_auth_header=mcp_auth_header,
+                oauth2_headers=oauth2_headers,
+                raw_headers=raw_headers,
+                user_api_key_auth=user_api_key_auth,
+                scope_servers=allowed_mcp_servers,
+            )
+
+            # Prefer server-stored per-user OAuth when configured, so a stale
+            # Authorization header from the MCP client cannot override Redis/DB
+            # (same issue as call_tool in mcp_server_manager: VS Code caches tokens).
+            from litellm.proxy._experimental.mcp_server.outbound_credentials.adapter import (  # noqa: PLC0415
+                to_server_spec,
+            )
+
+            # A server migrated to the v2 resolver gets its token from the resolver at connect
+            # time; building it here would double-resolve and be shadowed by the v2 graft. The
+            # preemptive 401 already challenged a missing token, so one exists for the connect.
+            migrated_to_v2: Final = to_server_spec(server) is not None
+            if (
+                not migrated_to_v2
+                and server.auth_type == MCPAuth.oauth2
+                and getattr(server, "needs_user_oauth_token", False)
+                and user_api_key_auth is not None
+            ):
+                db_headers: Final = await _get_user_oauth_extra_headers_from_db(
+                    server,
+                    user_api_key_auth,
+                    prefetched_creds=_prefetched_oauth_creds,
+                )
+                if db_headers:
+                    extra_headers = db_headers
+
+            # If still no OAuth2 token, fall back to pre-fetched creds (non-stale-client path)
+            elif not migrated_to_v2 and extra_headers is None and server.auth_type == MCPAuth.oauth2:
+                extra_headers = await _get_user_oauth_extra_headers_from_db(
+                    server,
+                    user_api_key_auth,
+                    prefetched_creds=_prefetched_oauth_creds,
+                )
+
+            if server.is_byok and server.auth_type != MCPAuth.oauth2 and server_auth_header is None:
+                server_auth_header = await _get_byok_credential(server, user_api_key_auth)
+
+            try:
+                tools: Final = await global_mcp_server_manager._get_tools_from_server(
+                    server=server,
+                    mcp_auth_header=server_auth_header,
+                    extra_headers=extra_headers,
+                    add_prefix=True,  # Always add server prefix
+                    raw_headers=raw_headers,
+                    client_ip=client_ip,
+                    user_api_key_auth=user_api_key_auth,
+                    oauth2_headers=oauth2_headers,
+                )
+                filtered_tools = filter_tools_by_allowed_tools(tools, server)
+
+                filtered_tools = await filter_tools_by_key_team_permissions(
+                    tools=filtered_tools,
+                    server_id=server.server_id,
+                    user_api_key_auth=user_api_key_auth,
+                )
+
+                if mcp_proxy_mode:
+                    from litellm.proxy._experimental.mcp_server.tool_search import with_mcp_proxy_identity
+
+                    filtered_tools = [  # mutable-ok: MCP tool pipeline
+                        with_mcp_proxy_identity(tool, server.server_id) for tool in filtered_tools
+                    ]
+                else:
+                    filtered_tools = apply_tool_overrides(filtered_tools, server)
+
+                verbose_logger.debug(
+                    "Successfully fetched %s tools from server %s, %s after filtering",
+                    len(tools),
+                    server.name,
+                    len(filtered_tools),
+                )
+                return filtered_tools, ServerListOk(tool_count=len(filtered_tools))
+            except MCPUpstreamAuthError as e:
+                # Absorb so one unauthenticated server does not empty every other server's
+                # tools. Surfacing the upstream 401 to the client as a re-auth challenge is
+                # intentionally not done here: raising from this list handler cannot produce a
+                # 401 + WWW-Authenticate (the MCP session manager serializes it as a JSON-RPC
+                # error). Single-server routes surface it via the request-scope preemptive
+                # check in _raise_preemptive_401_for_unauthenticated_servers instead.
+                verbose_logger.debug("MCP list_tools: omitting %s; it needs upstream auth", server.name)
+                return [], classify_list_exception(e)
+            except Exception as e:
+                verbose_logger.exception("Error getting tools from server %s: %s", server.name, e)
+                return [], classify_list_exception(e)
+
+        # Fetch tools from all servers in parallel
+        tasks: Final = [_fetch_and_filter_server_tools(server) for server in allowed_mcp_servers]
+        results: Final = await asyncio.gather(*tasks)
+
+        # Flatten results into single list
+        all_tools: Final[list[MCPTool]] = [tool for tools, _ in results for tool in tools]
+        server_outcomes: Final[dict[str, ServerOutcome]] = {
+            _aggregate_server_key(server): outcome
+            for server, (_, outcome) in zip(allowed_mcp_servers, results)
+            if server is not None
+        }
+
+        # If logging is enabled, enrich spend_logs_metadata with counts
+        if litellm_logging_obj:
+            per_server_tool_counts: Final[dict[str, int]] = {
+                _aggregate_server_key(server): len(server_tools)
+                for server, (server_tools, _) in zip(allowed_mcp_servers, results)
+                if server is not None
+            }
+
+            metadata_dict: Final = litellm_logging_obj.model_call_details.get("metadata")
+            if isinstance(metadata_dict, dict):
+                spend_meta = metadata_dict.get("spend_logs_metadata")
+                if not isinstance(spend_meta, dict):
+                    spend_meta = {}
+                    metadata_dict["spend_logs_metadata"] = spend_meta
+                spend_meta["allowed_server_count"] = len(allowed_mcp_servers)
+                spend_meta["tool_count_total"] = len(all_tools)
+                spend_meta["per_server_tool_counts"] = per_server_tool_counts
+                spend_meta["per_server_list_outcomes"] = {
+                    key: outcome_wire_value(outcome) for key, outcome in server_outcomes.items()
+                }
+
+            end_time: Final = datetime.now()
+            try:
+                await litellm_logging_obj.async_success_handler(
+                    result=[tool.model_dump(mode="json") if isinstance(tool, MCPTool) else tool for tool in all_tools],
+                    start_time=list_tools_start_time,
+                    end_time=end_time,
+                )
+            except Exception as log_exc:
+                # list_tools responses must not be dropped due to non-blocking
+                # observability/serialization failures.
+                verbose_logger.warning(
+                    "MCP list_tools success logging failed (continuing): %s",
+                    log_exc,
+                )
+
+        verbose_logger.info("Successfully fetched %s tools total from all MCP servers", len(all_tools))
+
+        return AggregateToolListing(tools=all_tools, outcomes=server_outcomes)
+    except Exception as e:
+        # Only fire failure hook if logging was requested for this list-tools execution
+        if log_list_tools_to_spendlogs and user_api_key_auth is not None:
+            try:
+                from litellm.proxy.proxy_server import proxy_logging_obj
+
+                if proxy_logging_obj:
+                    traceback_str: Final = traceback.format_exc(limit=MAXIMUM_TRACEBACK_LINES_TO_LOG)
+                    await proxy_logging_obj.post_call_failure_hook(
+                        request_data=list_tools_request_data or {},
+                        original_exception=e,
+                        user_api_key_dict=user_api_key_auth,
+                        route="/mcp/list_tools",
+                        traceback_str=traceback_str,
+                    )
+            except Exception:
+                verbose_logger.debug("Failed to log MCP list_tools failure via post_call_failure_hook")
+        raise
+
+
+async def _get_prompts_from_mcp_servers(
+    user_api_key_auth: UserAPIKeyAuth | None,
+    mcp_auth_header: str | None,
+    mcp_servers: list[str] | None,
+    mcp_server_auth_headers: dict[str, dict[str, str]] | None = None,
+    oauth2_headers: dict[str, str] | None = None,
+    raw_headers: dict[str, str] | None = None,
+    client_ip: str | None = None,
+) -> list[Prompt]:
+    """
+    Helper method to fetch prompt from MCP servers based on server filtering criteria.
+
+    Args:
+        user_api_key_auth: User authentication info for access control
+        mcp_auth_header: Optional auth header for MCP server (deprecated)
+        mcp_servers: Optional list of server names/aliases to filter by
+        mcp_server_auth_headers: Optional dict of server-specific auth headers
+        oauth2_headers: Optional dict of oauth2 headers
+
+    Returns:
+        List[Prompt]: Combined list of prompts from filtered servers
+    """
+
+    allowed_mcp_servers: Final = await _get_allowed_mcp_servers(
+        user_api_key_auth=user_api_key_auth,
+        mcp_servers=mcp_servers,
+        client_ip=client_ip,
+    )
+
+    # Get prompts from each allowed server
+    all_prompts: Final = []
+    for server in allowed_mcp_servers:
+        if server is None:
+            continue
+
+        server_auth_header, extra_headers = _prepare_mcp_server_headers(
+            server=server,
+            mcp_server_auth_headers=mcp_server_auth_headers,
+            mcp_auth_header=mcp_auth_header,
+            oauth2_headers=oauth2_headers,
+            raw_headers=raw_headers,
+            user_api_key_auth=user_api_key_auth,
+            scope_servers=allowed_mcp_servers,
+        )
+
+        try:
+            prompts = await global_mcp_server_manager.get_prompts_from_server(
+                server=server,
+                user_api_key_auth=user_api_key_auth,
+                mcp_auth_header=server_auth_header,
+                extra_headers=extra_headers,
+                add_prefix=True,  # Always add server prefix
+                raw_headers=raw_headers,
+                client_ip=client_ip,
+            )
+
+            all_prompts.extend(prompts)
+
+            verbose_logger.debug("Successfully fetched %s prompts from server %s", len(prompts), server.name)
+        except Exception as e:
+            verbose_logger.exception("Error getting prompts from server %s: %s", server.name, e)
+            # Continue with other servers instead of failing completely
+
+    verbose_logger.info("Successfully fetched %s prompts total from all MCP servers", len(all_prompts))
+
+    return all_prompts
+
+
+async def _get_resources_from_mcp_servers(
+    user_api_key_auth: UserAPIKeyAuth | None,
+    mcp_auth_header: str | None,
+    mcp_servers: list[str] | None,
+    mcp_server_auth_headers: dict[str, dict[str, str]] | None = None,
+    oauth2_headers: dict[str, str] | None = None,
+    raw_headers: dict[str, str] | None = None,
+    client_ip: str | None = None,
+) -> list[Resource]:
+    """Fetch resources from allowed MCP servers."""
+
+    allowed_mcp_servers: Final = await _get_allowed_mcp_servers(
+        user_api_key_auth=user_api_key_auth,
+        mcp_servers=mcp_servers,
+        client_ip=client_ip,
+    )
+
+    all_resources: Final[list[Resource]] = []
+    for server in allowed_mcp_servers:
+        if server is None:
+            continue
+
+        server_auth_header, extra_headers = _prepare_mcp_server_headers(
+            server=server,
+            mcp_server_auth_headers=mcp_server_auth_headers,
+            mcp_auth_header=mcp_auth_header,
+            oauth2_headers=oauth2_headers,
+            raw_headers=raw_headers,
+            user_api_key_auth=user_api_key_auth,
+            scope_servers=allowed_mcp_servers,
+        )
+
+        try:
+            resources = await global_mcp_server_manager.get_resources_from_server(
+                server=server,
+                user_api_key_auth=user_api_key_auth,
+                mcp_auth_header=server_auth_header,
+                extra_headers=extra_headers,
+                add_prefix=True,  # Always add server prefix
+                raw_headers=raw_headers,
+                client_ip=client_ip,
+            )
+            all_resources.extend(resources)
+
+            verbose_logger.debug("Successfully fetched %s resources from server %s", len(resources), server.name)
+        except Exception as e:
+            verbose_logger.exception("Error getting resources from server %s: %s", server.name, e)
+
+    verbose_logger.info("Successfully fetched %s resources total from all MCP servers", len(all_resources))
+
+    return all_resources
+
+
+async def _get_resource_templates_from_mcp_servers(
+    user_api_key_auth: UserAPIKeyAuth | None,
+    mcp_auth_header: str | None,
+    mcp_servers: list[str] | None,
+    mcp_server_auth_headers: dict[str, dict[str, str]] | None = None,
+    oauth2_headers: dict[str, str] | None = None,
+    raw_headers: dict[str, str] | None = None,
+    client_ip: str | None = None,
+) -> list[ResourceTemplate]:
+    """Fetch resource templates from allowed MCP servers."""
+
+    allowed_mcp_servers: Final = await _get_allowed_mcp_servers(
+        user_api_key_auth=user_api_key_auth,
+        mcp_servers=mcp_servers,
+        client_ip=client_ip,
+    )
+
+    all_resource_templates: Final[list[ResourceTemplate]] = []
+    for server in allowed_mcp_servers:
+        if server is None:
+            continue
+
+        server_auth_header, extra_headers = _prepare_mcp_server_headers(
+            server=server,
+            mcp_server_auth_headers=mcp_server_auth_headers,
+            mcp_auth_header=mcp_auth_header,
+            oauth2_headers=oauth2_headers,
+            raw_headers=raw_headers,
+            user_api_key_auth=user_api_key_auth,
+            scope_servers=allowed_mcp_servers,
+        )
+
+        try:
+            resource_templates = await global_mcp_server_manager.get_resource_templates_from_server(
+                server=server,
+                user_api_key_auth=user_api_key_auth,
+                mcp_auth_header=server_auth_header,
+                extra_headers=extra_headers,
+                add_prefix=True,  # Always add server prefix
+                raw_headers=raw_headers,
+                client_ip=client_ip,
+            )
+            all_resource_templates.extend(resource_templates)
+            verbose_logger.debug(
+                "Successfully fetched %s resource templates from server %s",
+                len(resource_templates),
+                server.name,
+            )
+        except Exception as e:
+            verbose_logger.exception(
+                "Error getting resource templates from server %s: %s",
+                server.name,
+                str(e),
+            )
+
+    verbose_logger.info(
+        "Successfully fetched %s resource templates total from all MCP servers",
+        len(all_resource_templates),
+    )
+
+    return all_resource_templates
+
+
+async def filter_tools_by_key_team_permissions(
+    tools: list[MCPTool],
+    server_id: str,
+    user_api_key_auth: UserAPIKeyAuth | None,
+) -> list[MCPTool]:
+    """
+    Filter tools based on key/team mcp_tool_permissions.
+
+    Note: Tool names in the DB are stored without server prefixes,
+    but tool names from MCP servers are prefixed. We need to strip
+    the prefix before comparing.
+    """
+    # Filter by key/team tool-level permissions
+    allowed_tool_names: Final = await MCPRequestHandler.get_allowed_tools_for_server(
+        server_id=server_id,
+        user_api_key_auth=user_api_key_auth,
+    )
+
+    # Tools arrive prefixed with the server's own prefix; strip exactly that
+    # prefix (resolved from the server) rather than the first separator, so a
+    # prefix containing the separator still reduces to the stored bare name.
+    server: Final = global_mcp_server_manager.get_mcp_server_by_id(server_id)
+    return [
+        t
+        for t in tools
+        if MCPRequestHandler.tool_is_granted(strip_known_server_prefix(t.name, server), allowed_tool_names)
+    ]
+
+
+async def _list_mcp_tools(
+    user_api_key_auth: UserAPIKeyAuth | None = None,
+    mcp_auth_header: str | None = None,
+    mcp_servers: list[str] | None = None,
+    mcp_server_auth_headers: dict[str, dict[str, str]] | None = None,
+    oauth2_headers: dict[str, str] | None = None,
+    raw_headers: dict[str, str] | None = None,
+    log_list_tools_to_spendlogs: bool = False,
+    list_tools_log_source: str | None = None,
+    client_ip: str | None = None,
+    mcp_proxy_mode: bool = False,
+) -> AggregateToolListing:
+    """
+    List all available MCP tools.
+
+    Args:
+        user_api_key_auth: User authentication info for access control
+        mcp_auth_header: Optional auth header for MCP server (deprecated)
+        mcp_servers: Optional list of server names/aliases to filter by
+        mcp_server_auth_headers: Optional dict of server-specific auth headers {server_alias: auth_value}
+        client_ip: Client IP for IP-based server access control
+
+    Returns:
+        AggregateToolListing: Combined tools from all accessible servers plus each server's
+        classified listing outcome
+    """
+
+    try:
+        listing: Final = await _get_tools_from_mcp_servers(
+            user_api_key_auth=user_api_key_auth,
+            mcp_auth_header=mcp_auth_header,
+            mcp_servers=mcp_servers,
+            mcp_server_auth_headers=mcp_server_auth_headers,
+            oauth2_headers=oauth2_headers,
+            raw_headers=raw_headers,
+            log_list_tools_to_spendlogs=log_list_tools_to_spendlogs,
+            list_tools_log_source=list_tools_log_source,
+            client_ip=client_ip,
+            mcp_proxy_mode=mcp_proxy_mode,
+        )
+        verbose_logger.debug("Successfully fetched %s tools from managed MCP servers", len(listing.tools))
+        return listing
+    except HTTPException:
+        raise
+    except Exception as e:
+        verbose_logger.exception("Error getting tools from managed MCP servers: %s", e)
+        # Continue with an empty listing instead of failing completely
+        return AggregateToolListing(tools=[], outcomes={})
+
+
+async def _list_mcp_prompts(
+    user_api_key_auth: UserAPIKeyAuth | None = None,
+    mcp_auth_header: str | None = None,
+    mcp_servers: list[str] | None = None,
+    mcp_server_auth_headers: dict[str, dict[str, str]] | None = None,
+    oauth2_headers: dict[str, str] | None = None,
+    raw_headers: dict[str, str] | None = None,
+    client_ip: str | None = None,
+) -> list[Prompt]:
+    """
+    List all available MCP prompts.
+
+    Args:
+        user_api_key_auth: User authentication info for access control
+        mcp_auth_header: Optional auth header for MCP server (deprecated)
+        mcp_servers: Optional list of server names/aliases to filter by
+        mcp_server_auth_headers: Optional dict of server-specific auth headers {server_alias: auth_value}
+
+    Returns:
+        List[Prompt]: Combined list of tools from all accessible servers
+    """
+    # Get tools from managed MCP servers with error handling
+    managed_prompts = []
+    try:
+        managed_prompts = await _get_prompts_from_mcp_servers(
+            user_api_key_auth=user_api_key_auth,
+            mcp_auth_header=mcp_auth_header,
+            mcp_servers=mcp_servers,
+            mcp_server_auth_headers=mcp_server_auth_headers,
+            oauth2_headers=oauth2_headers,
+            raw_headers=raw_headers,
+            client_ip=client_ip,
+        )
+        verbose_logger.debug("Successfully fetched %s prompts from managed MCP servers", len(managed_prompts))
+    except Exception as e:
+        verbose_logger.exception("Error getting tools from managed MCP servers: %s", e)
+        # Continue with empty managed tools list instead of failing completely
+
+    return managed_prompts
+
+
+async def _list_mcp_resources(
+    user_api_key_auth: UserAPIKeyAuth | None = None,
+    mcp_auth_header: str | None = None,
+    mcp_servers: list[str] | None = None,
+    mcp_server_auth_headers: dict[str, dict[str, str]] | None = None,
+    oauth2_headers: dict[str, str] | None = None,
+    raw_headers: dict[str, str] | None = None,
+    client_ip: str | None = None,
+) -> list[Resource]:
+    """List all available MCP resources."""
+
+    managed_resources: list[Resource] = []
+    try:
+        managed_resources = await _get_resources_from_mcp_servers(
+            user_api_key_auth=user_api_key_auth,
+            mcp_auth_header=mcp_auth_header,
+            mcp_servers=mcp_servers,
+            mcp_server_auth_headers=mcp_server_auth_headers,
+            oauth2_headers=oauth2_headers,
+            raw_headers=raw_headers,
+            client_ip=client_ip,
+        )
+        verbose_logger.debug("Successfully fetched %s resources from managed MCP servers", len(managed_resources))
+    except Exception as e:
+        verbose_logger.exception("Error getting resources from managed MCP servers: %s", e)
+
+    return managed_resources
+
+
+async def _list_mcp_resource_templates(
+    user_api_key_auth: UserAPIKeyAuth | None = None,
+    mcp_auth_header: str | None = None,
+    mcp_servers: list[str] | None = None,
+    mcp_server_auth_headers: dict[str, dict[str, str]] | None = None,
+    oauth2_headers: dict[str, str] | None = None,
+    raw_headers: dict[str, str] | None = None,
+    client_ip: str | None = None,
+) -> list[ResourceTemplate]:
+    """List all available MCP resource templates."""
+
+    managed_resource_templates: list[ResourceTemplate] = []
+    try:
+        managed_resource_templates = await _get_resource_templates_from_mcp_servers(
+            user_api_key_auth=user_api_key_auth,
+            mcp_auth_header=mcp_auth_header,
+            mcp_servers=mcp_servers,
+            mcp_server_auth_headers=mcp_server_auth_headers,
+            oauth2_headers=oauth2_headers,
+            raw_headers=raw_headers,
+            client_ip=client_ip,
+        )
+        verbose_logger.debug(
+            "Successfully fetched %s resource templates from managed MCP servers",
+            len(managed_resource_templates),
+        )
+    except Exception as e:
+        verbose_logger.exception(
+            "Error getting resource templates from managed MCP servers: %s",
+            str(e),
+        )
+
+    return managed_resource_templates
+
+
+def _resolve_display_name_to_original(
+    name: str,
+    allowed_mcp_servers: list[MCPServer],
+) -> str:
+    """Translate a display-name override back to the original prefixed tool name.
+
+    When a client received a customised display name from tools/list (e.g.
+    "Get Pet") it will call tools/call with that same string.  We need to
+    reverse-map it to the original prefixed name (e.g.
+    "petstore_mcp-getPetById") before any routing or permission logic runs.
+    """
+    for server in allowed_mcp_servers:
+        display_map = server.tool_name_to_display_name or {}
+        for unprefixed_name, display_name in display_map.items():
+            if display_name == name:
+                return add_server_prefix_to_name(unprefixed_name, get_server_prefix(server))
+    return name
+
+
+async def _get_byok_credential(
+    mcp_server: MCPServer,
+    user_api_key_auth: UserAPIKeyAuth | None,
+) -> str | None:
+    """Retrieve the stored BYOK credential for a user+server pair, served from the worker cache within its TTL."""
+    if not mcp_server.is_byok:
+        return None
+    user_id: Final = (user_api_key_auth.user_id if user_api_key_auth else None) or ""
+    if not user_id:
+        return None
+
+    cached: Final = get_cached_byok_credential(user_id, mcp_server.server_id)
+    if cached is not None:
+        return cached.credential
+
+    from litellm.proxy._experimental.mcp_server.db import get_user_credential
+    from litellm.proxy.proxy_server import prisma_client
+
+    if prisma_client is None:
+        return None
+    credential: Final = await get_user_credential(
+        prisma_client=prisma_client,
+        user_id=user_id,
+        server_id=mcp_server.server_id,
+    )
+    cache_byok_credential(user_id, mcp_server.server_id, credential)
+    return credential
+
+
+async def _check_byok_credential(
+    mcp_server: MCPServer,
+    user_api_key_auth: UserAPIKeyAuth | None,
+) -> None:
+    """
+    If the MCP server is BYOK-enabled, verify that the requesting user has a
+    stored credential.  When no credential is found, raise an HTTP 401 with a
+    WWW-Authenticate header that points the MCP client to our OAuth metadata
+    endpoint so it can drive the authorization flow.
+    """
+    if not mcp_server.is_byok:
+        return
+
+    user_id: Final = (user_api_key_auth.user_id if user_api_key_auth else None) or ""
+    if not user_id:
+        raise HTTPException(
+            status_code=401,
+            detail={
+                "error": "byok_auth_required",
+                "server_id": mcp_server.server_id,
+                "server_name": mcp_server.server_name or mcp_server.name,
+                "message": "User identity is required for BYOK servers",
+            },
+            headers={"WWW-Authenticate": get_byok_www_authenticate()},
+        )
+
+    cached: Final = get_cached_byok_credential(user_id, mcp_server.server_id)
+    if cached is not None:
+        if cached.credential is None:
+            raise HTTPException(
+                status_code=401,
+                detail={
+                    "error": "byok_auth_required",
+                    "server_id": mcp_server.server_id,
+                    "server_name": mcp_server.server_name or mcp_server.name,
+                    "message": (
+                        "No stored credential found for this BYOK server. "
+                        "Complete the OAuth authorization flow to provide your API key."
+                    ),
+                },
+                headers={"WWW-Authenticate": get_byok_www_authenticate()},
+            )
+        return
+
+    from litellm.proxy._experimental.mcp_server.db import get_user_credential
+    from litellm.proxy.proxy_server import prisma_client
+
+    if prisma_client is None:
+        # Fail closed on DB unavailability: returning here previously
+        # bypassed the ownership check and let any proxy-authenticated
+        # caller invoke BYOK tools during outage windows.
+        raise HTTPException(
+            status_code=503,
+            detail={
+                "error": "byok_auth_unavailable",
+                "server_id": mcp_server.server_id,
+                "server_name": mcp_server.server_name or mcp_server.name,
+                "message": "BYOK credential check requires a database connection.",
+            },
+        )
+
+    credential: Final = await get_user_credential(
+        prisma_client=prisma_client,
+        user_id=user_id,
+        server_id=mcp_server.server_id,
+    )
+    cache_byok_credential(user_id, mcp_server.server_id, credential)
+    if credential is None:
+        raise HTTPException(
+            status_code=401,
+            detail={
+                "error": "byok_auth_required",
+                "server_id": mcp_server.server_id,
+                "server_name": mcp_server.server_name or mcp_server.name,
+                "message": (
+                    "No stored credential found for this BYOK server. "
+                    "Complete the OAuth authorization flow to provide your API key."
+                ),
+            },
+            headers={"WWW-Authenticate": get_byok_www_authenticate()},
+        )
+
+
+async def _list_tools_before_first_call(
+    server: MCPServer | None,
+    tool_name: str,
+    allowed_mcp_servers: list[MCPServer],
+    user_api_key_auth: UserAPIKeyAuth | None,
+    mcp_auth_header: str | None,
+    mcp_server_auth_headers: dict[str, dict[str, str]] | None,
+    oauth2_headers: dict[str, str] | None,
+    raw_headers: dict[str, str] | None,
+    client_ip: str | None = None,
+) -> None:
+    """List ``server`` with the caller's own credentials when it does not yet expose ``tool_name`` here.
+
+    The startup fill skips a server whose upstream wants the caller's token, and mcp 2 no
+    longer lists before an uncached tools/call, so a worker that has not served tools/list
+    for this caller would otherwise answer 404 for a tool the caller can see. Gating on the
+    requested tool, not on any prior listing, keeps callers with different upstream catalogs
+    from masking each other.
+    """
+    if server is None or global_mcp_server_manager.server_exposes_tool(server, tool_name):
+        return
+    if all(allowed.server_id != server.server_id for allowed in allowed_mcp_servers):
+        return
+    try:
+        await _get_tools_from_mcp_servers(
+            user_api_key_auth=user_api_key_auth,
+            mcp_auth_header=mcp_auth_header,
+            mcp_servers=[server.server_id],
+            mcp_server_auth_headers=mcp_server_auth_headers,
+            oauth2_headers=oauth2_headers,
+            raw_headers=raw_headers,
+            client_ip=client_ip,
+        )
+    except Exception as e:  # noqa: BLE001  # best effort: resolution below answers as it did before
+        verbose_logger.debug("MCP tools/call: listing %s before its first call failed: %s", server.name, e)
+
+
+async def execute_mcp_tool(
+    name: str,
+    arguments: dict[str, object],
+    allowed_mcp_servers: list[MCPServer],
+    start_time: datetime,
+    user_api_key_auth: UserAPIKeyAuth | None = None,
+    mcp_auth_header: str | None = None,
+    mcp_server_auth_headers: dict[str, dict[str, str]] | None = None,
+    oauth2_headers: dict[str, str] | None = None,
+    raw_headers: dict[str, str] | None = None,
+    host_progress_callback: ProgressCallback | None = None,
+    guardrail_context: Mapping[str, object] | None = None,
+    client_ip: str | None = None,
+    **kwargs: object,  # kwargs-ok: preserves the existing REST and decorated logging call contract
+) -> CallToolResult:
+    context: Final = prepare_context(
+        user_api_key_auth=user_api_key_auth,
+        mcp_auth_header=mcp_auth_header,
+        mcp_server_auth_headers=mcp_server_auth_headers,
+        oauth2_headers=oauth2_headers,
+        raw_headers=raw_headers,
+        client_ip=client_ip,
+    )
+    operation: Final = AuthorizedToolCall(
+        name=name,
+        arguments=arguments,
+        allowed_mcp_servers=tuple(allowed_mcp_servers),
+        start_time=start_time,
+        host_progress_callback=host_progress_callback,
+        guardrail_context=guardrail_context,
+        logging_data=types.MappingProxyType(kwargs),
+    )
+    return await GatewayOperations().execute(operation, context)
+
+
+async def _execute_mcp_tool(
+    name: str,
+    arguments: dict[str, object],
+    allowed_mcp_servers: list[MCPServer],
+    start_time: datetime,
+    user_api_key_auth: UserAPIKeyAuth | None = None,
+    mcp_auth_header: str | None = None,
+    mcp_server_auth_headers: dict[str, dict[str, str]] | None = None,
+    oauth2_headers: dict[str, str] | None = None,
+    raw_headers: dict[str, str] | None = None,
+    host_progress_callback: ProgressCallback | None = None,
+    guardrail_context: Mapping[str, object] | None = None,
+    client_ip: str | None = None,
+    **kwargs: Any,
+) -> CallToolResult:
+    """
+    Execute MCP tool.
+
+    This function assumes permission checks have already been performed.
+
+    Args:
+        name: Tool name (may include server prefix)
+        arguments: Tool arguments
+        allowed_mcp_servers: Pre-validated list of servers the user can access
+        start_time: Start time for logging
+        user_api_key_auth: Optional user API key auth for logging
+        mcp_auth_header: Optional MCP auth header
+        mcp_server_auth_headers: Optional server-specific auth headers
+        oauth2_headers: Optional OAuth2 headers
+        raw_headers: Optional raw HTTP headers
+        **kwargs: Additional arguments (e.g., litellm_logging_obj)
+
+    Returns:
+        CallToolResult: Tool execution result
+    """
+    # Track resolved MCP server for both permission checks and dispatch
+    mcp_server: MCPServer | None = None
+    requested_server_id: Final[str | None] = kwargs.get("requested_server_id")
+
+    # If the client called with a display-name override (e.g. "Get Pet"),
+    # translate it back to the original prefixed name before any routing.
+    name = _resolve_display_name_to_original(name, allowed_mcp_servers)
+
+    # Remove prefix from tool name for logging and processing
+    original_tool_name, server_name = split_server_prefix_from_name(name)
+
+    requested_server: MCPServer | None = None
+    if requested_server_id:
+        requested_server = next(
+            (s for s in allowed_mcp_servers if s.server_id == requested_server_id),
+            None,
+        )
+
+    name_is_prefixed = False
+    if requested_server is not None and MCP_TOOL_PREFIX_SEPARATOR in name:
+        all_registry_prefixes: Final[set[str]] = set()
+        for registry_server in global_mcp_server_manager.get_registry().values():
+            for known_prefix in iter_known_server_prefixes(registry_server):
+                all_registry_prefixes.add(normalize_server_name(known_prefix))
+        name_is_prefixed = is_tool_name_prefixed(name, known_server_prefixes=all_registry_prefixes)
+
+    first_call_target: Final = (
+        requested_server
+        if requested_server is not None and not name_is_prefixed
+        else global_mcp_server_manager.server_owning_tool_name_prefix(name)
+    )
+    first_call_tool_name: Final = (
+        name
+        if first_call_target is None or (requested_server is not None and not name_is_prefixed)
+        else strip_known_server_prefix(name, first_call_target)
+    )
+    await _list_tools_before_first_call(
+        server=first_call_target,
+        tool_name=first_call_tool_name,
+        allowed_mcp_servers=allowed_mcp_servers,
+        user_api_key_auth=user_api_key_auth,
+        mcp_auth_header=mcp_auth_header,
+        mcp_server_auth_headers=mcp_server_auth_headers,
+        oauth2_headers=oauth2_headers,
+        raw_headers=raw_headers,
+        client_ip=client_ip,
+    )
+
+    if requested_server is not None and not name_is_prefixed:
+        # REST callers may pass server_id with the upstream tool name (no
+        # LiteLLM prefix). The first segment is not a registered server
+        # prefix, so the whole string is the upstream tool name and may
+        # legitimately contain the separator (e.g. "text-to-speech").
+        # server_id is authoritative for routing and auth.
+        mcp_server = requested_server
+        server_name = requested_server.name
+        original_tool_name = name
+    else:
+        # Resolve from tool name (MCP JSON-RPC or prefixed REST tool names).
+        mcp_server = global_mcp_server_manager._get_mcp_server_from_tool_name(name)
+        if mcp_server is None and requested_server is not None:
+            for known_prefix in iter_known_server_prefixes(requested_server):
+                candidate = global_mcp_server_manager._get_mcp_server_from_tool_name(
+                    add_server_prefix_to_name(name, known_prefix)
+                )
+                if candidate is not None:
+                    mcp_server = candidate
+                    break
+        if mcp_server is not None:
+            server_name = mcp_server.name
+            original_tool_name = strip_known_server_prefix(name, mcp_server)
+
+        if requested_server is not None:
+            if mcp_server is not None and mcp_server.server_id != requested_server.server_id:
+                raise HTTPException(
+                    status_code=403,
+                    detail={
+                        "error": "tool_server_mismatch",
+                        "message": (
+                            f"Tool '{name}' belongs to MCP server "
+                            f"'{mcp_server.name}' but request specified "
+                            f"server_id for '{requested_server.name}'."
+                        ),
+                    },
+                )
+            if mcp_server is None:
+                mcp_server = requested_server
+                server_name = requested_server.name
+                original_tool_name = strip_known_server_prefix(name, requested_server)
+
+    # Only enforce server-level permissions when we can resolve a server
+    if server_name:
+        if not MCPRequestHandler.is_tool_allowed(
+            allowed_mcp_servers=[server.name for server in allowed_mcp_servers],
+            server_name=server_name,
+        ):
+            raise HTTPException(
+                status_code=403,
+                detail="User not allowed to call this tool.",
+            )
+
+    standard_logging_mcp_tool_call: Final[StandardLoggingMCPToolCall] = _get_standard_logging_mcp_tool_call(
+        name=original_tool_name,  # Use original name for logging
+        arguments=arguments,
+        server_name=server_name,
+        session_id=_mcp_session_id_from_headers(raw_headers),
+    )
+    litellm_logging_obj: Final[LiteLLMLoggingObj | None] = kwargs.get("litellm_logging_obj", None)
+    if litellm_logging_obj:
+        litellm_logging_obj.model_call_details["mcp_tool_call_metadata"] = standard_logging_mcp_tool_call
+        litellm_logging_obj.model = f"MCP: {name}"
+        litellm_logging_obj.model_call_details["model"] = f"MCP: {name}"
+    # Resolve the MCP server early so BYOK checks and credential injection
+    # apply to ALL dispatch paths (local tool registry AND managed MCP server).
+    if mcp_server is None:
+        mcp_server = global_mcp_server_manager._get_mcp_server_from_tool_name(name)
+
+    if mcp_server:
+        standard_logging_mcp_tool_call["mcp_server_cost_info"] = (mcp_server.mcp_info or {}).get("mcp_server_cost_info")
+        if litellm_logging_obj:
+            litellm_logging_obj.model_call_details["mcp_tool_call_metadata"] = standard_logging_mcp_tool_call
+
+        # BYOK: retrieve the stored per-user credential.  A single DB call
+        # both checks existence and fetches the value, avoiding a double query.
+        if mcp_server.is_byok and not mcp_auth_header:
+            byok_cred: Final = await _get_byok_credential(mcp_server, user_api_key_auth)
+            if byok_cred is None:
+                raise HTTPException(
+                    status_code=401,
+                    detail={
+                        "error": "byok_auth_required",
+                        "server_id": mcp_server.server_id,
+                        "server_name": mcp_server.server_name or mcp_server.name,
+                        "message": (
+                            "No stored credential found for this BYOK server. "
+                            "Complete the OAuth authorization flow to provide your API key."
+                        ),
+                    },
+                    headers={"WWW-Authenticate": get_byok_www_authenticate()},
+                )
+            mcp_auth_header = byok_cred
+        elif mcp_server.is_byok:
+            # External auth header supplied; still enforce user-identity check.
+            await _check_byok_credential(mcp_server, user_api_key_auth)
+
+    # Check if tool exists in local registry first (for OpenAPI-based tools)
+    # These tools are registered with their prefixed names
+    #########################################################
+    local_tool: Final = global_mcp_tool_registry.get_tool(name)
+    if local_tool:
+        # OpenAPI-backed tools used to bypass `pre_call_tool_check` —
+        # only the managed path ran allowed/banned-tool checks, key/team
+        # tool permissions, and parameter validation. Run the same checks
+        # before dispatching to the local registry. Refuse the call if
+        # we cannot resolve a server: tools registered via
+        # openapi_to_mcp_generator are always tied to a server, so a
+        # missing mcp_server here means the tool->server mapping has
+        # not finished initializing or the registry entry is orphaned.
+        # Skipping the check would re-open the same authorization gap.
+        if mcp_server is None:
+            raise HTTPException(
+                status_code=503,
+                detail=(
+                    f"MCP server for tool '{name}' is not available; "
+                    "refusing to dispatch without authorization checks. "
+                    "Retry once the server is registered."
+                ),
+            )
+
+        # `pre_call_tool_check` calls into `proxy_logging_obj` for the
+        # pre-call guardrail hooks, so source it from the canonical
+        # `proxy_server` module the same way `_handle_managed_mcp_tool`
+        # does. `kwargs.get("proxy_logging_obj")` is None on the MCP
+        # entry path and would crash with AttributeError after the
+        # security checks pass.
+        from litellm.proxy.proxy_server import proxy_logging_obj
+
+        hook_result = await global_mcp_server_manager.pre_call_tool_check(
+            name=original_tool_name,
+            arguments=arguments or {},
+            server_name=server_name or mcp_server.name,
+            user_api_key_auth=user_api_key_auth,
+            proxy_logging_obj=proxy_logging_obj,
+            server=mcp_server,
+            raw_headers=raw_headers,
+            litellm_logging_obj=litellm_logging_obj,
+            guardrail_context=guardrail_context,
+        )
+        # `pre_call_tool_check` may return guardrail-modified
+        # arguments; honor them on the local path too.
+        if isinstance(hook_result, dict) and "arguments" in hook_result:
+            arguments = hook_result["arguments"]
+
+        verbose_logger.debug("Executing local registry tool: %s", name)
+        # The credential rides ContextVars because the tool function has its
+        # headers baked into the closure at registration time.
+        auth_header_value, openapi_forwarded_headers, upstream_credential = _resolve_openapi_tool_auth(
+            mcp_server=mcp_server,
+            mcp_auth_header=mcp_auth_header,
+            mcp_server_auth_headers=mcp_server_auth_headers,
+            raw_headers=raw_headers,
+            user_api_key_auth=user_api_key_auth,
+        )
+        (
+            resolved_auth_headers,
+            forwarded_headers,
+        ) = await global_mcp_server_manager.resolve_openapi_upstream_auth(
+            mcp_server=mcp_server,
+            oauth2_headers=oauth2_headers,
+            raw_headers=raw_headers,
+            mcp_auth_header=upstream_credential,
+            user_api_key_auth=user_api_key_auth,
+            forwarded_headers=openapi_forwarded_headers,
+        )
+
+        _auth_token: Final = _request_auth_header.set(auth_header_value)
+        _extra_token: Final = _request_extra_headers.set(forwarded_headers)
+        _resolved_token: Final = _request_resolved_auth_headers.set(resolved_auth_headers)
+        try:
+            response = await _handle_local_mcp_tool(name, arguments)
+        finally:
+            _request_auth_header.reset(_auth_token)
+            _request_extra_headers.reset(_extra_token)
+            _request_resolved_auth_headers.reset(_resolved_token)
+
+    # Try managed MCP server tool (the name is bare; the prefix boundary was
+    # already resolved above against this server's registered prefixes)
+    # Primary and recommended way to use external MCP servers
+    #########################################################
+    elif mcp_server:
+        response = await _handle_managed_mcp_tool(
+            server_name=server_name,
+            name=original_tool_name,
+            arguments=arguments,
+            user_api_key_auth=user_api_key_auth,
+            mcp_auth_header=mcp_auth_header,
+            mcp_server_auth_headers=mcp_server_auth_headers,
+            oauth2_headers=oauth2_headers,
+            raw_headers=raw_headers,
+            client_ip=client_ip,
+            litellm_logging_obj=litellm_logging_obj,
+            guardrail_context=guardrail_context,
+            host_progress_callback=host_progress_callback,
+        )
+
+    # Fall back to local tool registry with original name (legacy support)
+    #########################################################
+    # Deprecated: Local MCP Server Tool
+    #########################################################
+    else:
+        # Gate only what can actually dispatch. When the unprefixed name is
+        # not in the registry either, `_handle_local_mcp_tool` below reports
+        # 404 and nothing runs, so demanding a server here would turn every
+        # unknown tool name into a misleading 503.
+        if global_mcp_tool_registry.get_tool(original_tool_name) is not None:
+            # `mcp_server` is None here because the tool name is not in the
+            # tool -> server mapping, but the name still carries a prefix
+            # that the server-level check above compared against the
+            # caller's `allowed_mcp_servers` by exact `name`. So the named
+            # server is in that list and can carry the tool-level checks,
+            # even with the mapping cold. Resolve it from
+            # `allowed_mcp_servers` rather than the registry: the registry
+            # would happily return a server the caller holds no grant for,
+            # and matching anything other than `name` would accept a server
+            # the check never validated.
+            prefix_server: Final = next(
+                (candidate for candidate in allowed_mcp_servers if candidate.name == server_name),
+                None,
+            )
+            if prefix_server is None:
+                # A non-empty prefix that passed the server-level check
+                # always matches here, so this arm only fires when the
+                # prefix was empty, which is exactly the case that check
+                # skips. Fail closed rather than dispatch with no server to
+                # evaluate a tool ceiling against.
+                raise HTTPException(
+                    status_code=503,
+                    detail=(
+                        f"MCP server for tool '{original_tool_name}' is not available; "
+                        "refusing to dispatch without authorization checks. "
+                        "Retry once the server is registered."
+                    ),
+                )
+
+            from litellm.proxy.proxy_server import proxy_logging_obj
+
+            hook_result = await global_mcp_server_manager.pre_call_tool_check(
+                name=original_tool_name,
+                arguments=arguments,
+                server_name=server_name,
+                user_api_key_auth=user_api_key_auth,
+                proxy_logging_obj=proxy_logging_obj,
+                server=prefix_server,
+                raw_headers=raw_headers,
+                litellm_logging_obj=litellm_logging_obj,
+                guardrail_context=guardrail_context,
+            )
+            if "arguments" in hook_result:
+                arguments = hook_result["arguments"]  # pyright: ignore[reportAny]  # hook returns untyped args
+
+        response = await _handle_local_mcp_tool(original_tool_name, arguments)
+
+    return await _run_post_mcp_call_guardrails(
+        result=response,
+        litellm_logging_obj=litellm_logging_obj,
+        user_api_key_auth=user_api_key_auth,
+        request_data=kwargs,
+    )
+
+
+async def _run_post_mcp_call_guardrails(
+    result: CallToolResult,
+    litellm_logging_obj: LiteLLMLoggingObj | None,
+    user_api_key_auth: UserAPIKeyAuth | None,
+    request_data: Mapping[str, object],
+) -> CallToolResult:
+    """Run ``post_mcp_call`` guardrails over an executed tool result.
+
+    Lives on ``execute_mcp_tool``'s return path rather than inside
+    ``_fire_mcp_tool_call_logging`` so enforcement never depends on logging
+    being configured, and so every dispatch route gets it: the MCP protocol
+    handler, the REST endpoint, and tool search all funnel through here.
+    A guardrail that rejects the result raises, matching ``pre_mcp_call``.
+    """
+    from litellm.proxy.proxy_server import proxy_logging_obj
+
+    if proxy_logging_obj is None:
+        return result
+    return await proxy_logging_obj.post_mcp_call_hook(
+        response=result,
+        request_data=(
+            litellm_logging_obj.model_call_details if litellm_logging_obj is not None else dict(request_data)
+        ),
+        user_api_key_dict=user_api_key_auth,
+    )
+
+
+async def _fire_mcp_tool_call_logging(
+    logging_obj: LiteLLMLoggingObj,
+    result: CallToolResult,
+    start_time: datetime,
+    end_time: datetime,
+    user_api_key_auth: UserAPIKeyAuth | None = None,
+    request_data: Mapping[str, object] | None = None,
+) -> CallToolResult:
+    """Fire post-call logging for an executed MCP tool call, returning the result to send.
+
+    The returned result is what the caller must forward to the client: a
+    ``post_mcp_call`` guardrail may rewrite the tool output (e.g. mask
+    sensitive values) or reject it, in which case its exception propagates.
+    Guardrails run before the success/failure logging so the masked text, not
+    the raw one, is what gets logged.
+
+    A result with ``is_error=True`` is logged as a failure (``status="failure"``
+    payload, so OTel marks the span ERROR) while the HTTP wire behavior stays
+    200 + ``isError: true`` per the MCP spec. The error check runs after
+    ``async_post_mcp_tool_call_hook`` because guardrails may flip the result
+    to ``is_error=True`` in that hook. Raised exceptions never reach here (the
+    ``@client`` wrapper and ``call_mcp_tool``'s except path log those), so
+    this cannot double-log a failure.
+
+    ``request_data`` may carry credential-bearing fields (the REST path puts
+    ``raw_headers``, ``mcp_auth_header``, ``mcp_server_auth_headers``, and
+    ``oauth2_headers`` at the top level of its data dict), so those are
+    stripped before the dict is handed to ``post_call_failure_hook``
+    callbacks.
+    """
+    from litellm.proxy.proxy_server import proxy_logging_obj
+
+    logging_obj.post_call(original_response=result)
+    await logging_obj.async_post_mcp_tool_call_hook(
+        kwargs=logging_obj.model_call_details,
+        response_obj=result,
+        start_time=start_time,
+        end_time=end_time,
+    )
+    logging_obj.call_type = CallTypes.call_mcp_tool.value
+    error_message: Final = extract_mcp_tool_result_error_message(result)
+    if error_message is None:
+        await logging_obj.async_success_handler(result=result, start_time=start_time, end_time=end_time)
+        return result
+
+    logging_obj.has_run_logging(event_type="sync_success")
+    logging_obj.has_run_logging(event_type="async_success")
+    tool_error: Final = MCPToolResultError(error_message)
+    logging_obj.failure_handler(tool_error, "", start_time, end_time)
+    await logging_obj.async_failure_handler(tool_error, "", start_time, end_time)
+
+    if user_api_key_auth is None:
+        return result
+
+    if proxy_logging_obj:
+        sanitized_request_data: Final = {
+            key: value for key, value in (request_data or {}).items() if key not in _MCP_CREDENTIAL_REQUEST_FIELDS
+        }
+        await proxy_logging_obj.post_call_failure_hook(
+            request_data=sanitized_request_data,
+            original_exception=tool_error,
+            user_api_key_dict=user_api_key_auth,
+            route="/mcp/call_tool",
+        )
+    return result
+
+
+async def fire_mcp_tool_call_failure_logging(
+    logging_obj: LiteLLMLoggingObj | None,
+    exception: Exception,
+    start_time: datetime,
+    user_api_key_auth: UserAPIKeyAuth | None,
+    request_data: Mapping[str, object],
+) -> None:
+    """Failure logging shared by the ``/mcp`` path and the REST endpoint. Call from
+    inside the ``except`` block so the traceback is still available.
+
+    The failure handlers run first because ``_ProxyDBLogger.async_post_call_failure_hook``
+    builds the failure spend-log row from the ``standard_logging_object`` they produce;
+    both gate on ``should_run_logging``, so the ``@client`` wrapper does not log twice.
+    A relayed upstream 401 (``MCPUpstreamAuthError``) is an expected caller-must-reauth
+    signal and skips ``post_call_failure_hook``, which fires the ``llm_exceptions`` alert.
+    """
+    from litellm.proxy.proxy_server import proxy_logging_obj
+
+    traceback_str: Final = traceback.format_exc(limit=MAXIMUM_TRACEBACK_LINES_TO_LOG)
+    if logging_obj is not None:
+        end_time: Final = datetime.now()  # noqa: DTZ005  # naive to match `start_time`, which it is subtracted from
+        logging_obj.failure_handler(exception, traceback_str, start_time, end_time)
+        await logging_obj.async_failure_handler(exception, traceback_str, start_time, end_time)
+
+    if isinstance(exception, MCPUpstreamAuthError) or not proxy_logging_obj or user_api_key_auth is None:
+        return
+    sanitized_request_data: Final = {
+        key: value for key, value in request_data.items() if key not in _MCP_CREDENTIAL_REQUEST_FIELDS
+    }
+    await proxy_logging_obj.post_call_failure_hook(
+        request_data=sanitized_request_data,
+        original_exception=exception,
+        user_api_key_dict=user_api_key_auth,
+        route="/mcp/call_tool",
+        traceback_str=traceback_str,
+    )
+
+
+@client
+async def call_mcp_tool(
+    name: str,
+    arguments: dict[str, object] | None = None,
+    user_api_key_auth: UserAPIKeyAuth | None = None,
+    mcp_auth_header: str | None = None,
+    mcp_servers: list[str] | None = None,
+    mcp_server_auth_headers: dict[str, dict[str, str]] | None = None,
+    oauth2_headers: dict[str, str] | None = None,
+    raw_headers: dict[str, str] | None = None,
+    client_ip: str | None = None,
+    **kwargs: Any,
+) -> CallToolResult:
+    """
+    Call a specific tool with the provided arguments (handles prefixed tool names).
+    """
+    start_time: Final = datetime.now()
+    litellm_logging_obj: Final[LiteLLMLoggingObj | None] = kwargs.get("litellm_logging_obj", None)
+
+    try:
+        if arguments is None:
+            raise HTTPException(status_code=400, detail="Request arguments are required")
+
+        ## CHECK IF USER IS ALLOWED TO CALL THIS TOOL
+        allowed_mcp_server_ids: Final = await global_mcp_server_manager.get_allowed_mcp_servers(
+            user_api_key_auth=user_api_key_auth,
+        )
+
+        allowed_mcp_servers: list[MCPServer] = []
+        for allowed_mcp_server_id in allowed_mcp_server_ids:
+            allowed_server = global_mcp_server_manager.get_mcp_server_by_id(allowed_mcp_server_id)
+            if allowed_server is not None:
+                # Same request-time oauth2_flow backstop the listing path applies,
+                # so a null-flow M2M-shape row is treated as M2M on tool calls too.
+                allowed_server = MCPServerManager.resolve_oauth2_flow_for_request(allowed_server)
+                allowed_mcp_servers.append(allowed_server)
+
+        allowed_mcp_servers = await _get_allowed_mcp_servers_from_mcp_server_names(
+            mcp_servers=mcp_servers,
+            allowed_mcp_servers=allowed_mcp_servers,
+        )
+        if mcp_servers and not allowed_mcp_servers:
+            await raise_denied_scoped_mcp_access(
+                requested_names=mcp_servers,
+                user_api_key_auth=user_api_key_auth,
+                client_ip=client_ip,
+            )
+        if not allowed_mcp_servers:
+            raise HTTPException(
+                status_code=403,
+                detail="User not allowed to call this tool.",
+            )
+
+        # Delegate to execute_mcp_tool for execution
+        response = await execute_mcp_tool(
+            name=name,
+            arguments=arguments,
+            allowed_mcp_servers=allowed_mcp_servers,
+            start_time=start_time,
+            user_api_key_auth=user_api_key_auth,
+            mcp_auth_header=mcp_auth_header,
+            mcp_server_auth_headers=mcp_server_auth_headers,
+            oauth2_headers=oauth2_headers,
+            raw_headers=raw_headers,
+            client_ip=client_ip,
+            **kwargs,
+        )
+    except Exception as e:
+        await fire_mcp_tool_call_failure_logging(litellm_logging_obj, e, start_time, user_api_key_auth, kwargs)
+        raise
+
+    if litellm_logging_obj:
+        response = await _fire_mcp_tool_call_logging(
+            logging_obj=litellm_logging_obj,
+            result=response,
+            start_time=start_time,
+            end_time=datetime.now(),
+            user_api_key_auth=user_api_key_auth,
+            request_data=kwargs,
+        )
+    return response
+
+
+async def mcp_get_prompt(
+    name: str,
+    arguments: dict[str, str] | None = None,
+    user_api_key_auth: UserAPIKeyAuth | None = None,
+    mcp_auth_header: str | None = None,
+    mcp_servers: list[str] | None = None,
+    mcp_server_auth_headers: dict[str, dict[str, str]] | None = None,
+    oauth2_headers: dict[str, str] | None = None,
+    raw_headers: dict[str, str] | None = None,
+    client_ip: str | None = None,
+) -> GetPromptResult:
+    """
+    Fetch a specific MCP prompt, handling both prefixed and unprefixed names.
+    """
+    allowed_mcp_servers: Final = await _get_allowed_mcp_servers(
+        user_api_key_auth=user_api_key_auth,
+        mcp_servers=mcp_servers,
+        client_ip=client_ip,
+    )
+
+    if not allowed_mcp_servers:
+        raise HTTPException(
+            status_code=403,
+            detail="User not allowed to get this prompt.",
+        )
+
+    # Extract server name from prefixed prompt name
+    original_prompt_name, server_name = split_server_prefix_from_name(name)
+
+    server: Final = next((s for s in allowed_mcp_servers if s.name == server_name), None)
+    if server is None:
+        raise HTTPException(
+            status_code=403,
+            detail="User not allowed to get this prompt.",
+        )
+
+    server_auth_header, extra_headers = _prepare_mcp_server_headers(
+        server=server,
+        mcp_server_auth_headers=mcp_server_auth_headers,
+        mcp_auth_header=mcp_auth_header,
+        oauth2_headers=oauth2_headers,
+        raw_headers=raw_headers,
+        user_api_key_auth=user_api_key_auth,
+    )
+
+    return await global_mcp_server_manager.get_prompt_from_server(
+        server=server,
+        user_api_key_auth=user_api_key_auth,
+        prompt_name=original_prompt_name,
+        arguments=arguments,
+        mcp_auth_header=server_auth_header,
+        extra_headers=extra_headers,
+        raw_headers=raw_headers,
+        client_ip=client_ip,
+    )
+
+
+async def mcp_read_resource(
+    url: AnyUrl,
+    user_api_key_auth: UserAPIKeyAuth | None = None,
+    mcp_auth_header: str | None = None,
+    mcp_servers: list[str] | None = None,
+    mcp_server_auth_headers: dict[str, dict[str, str]] | None = None,
+    oauth2_headers: dict[str, str] | None = None,
+    raw_headers: dict[str, str] | None = None,
+    client_ip: str | None = None,
+) -> ReadResourceResult:
+    """Read resource contents from upstream MCP servers."""
+
+    allowed_mcp_servers: Final = await _get_allowed_mcp_servers(
+        user_api_key_auth=user_api_key_auth,
+        mcp_servers=mcp_servers,
+        client_ip=client_ip,
+    )
+
+    if not allowed_mcp_servers:
+        raise HTTPException(
+            status_code=403,
+            detail="User not allowed to read this resource.",
+        )
+
+    if len(allowed_mcp_servers) != 1:
+        raise HTTPException(
+            status_code=400,
+            detail=("Multiple MCP servers configured; read_resource currently supports exactly one allowed server."),
+        )
+
+    server: Final = allowed_mcp_servers[0]
+
+    server_auth_header, extra_headers = _prepare_mcp_server_headers(
+        server=server,
+        mcp_server_auth_headers=mcp_server_auth_headers,
+        mcp_auth_header=mcp_auth_header,
+        oauth2_headers=oauth2_headers,
+        raw_headers=raw_headers,
+        user_api_key_auth=user_api_key_auth,
+    )
+
+    return await global_mcp_server_manager.read_resource_from_server(
+        server=server,
+        user_api_key_auth=user_api_key_auth,
+        url=url,
+        mcp_auth_header=server_auth_header,
+        extra_headers=extra_headers,
+        raw_headers=raw_headers,
+        client_ip=client_ip,
+    )
+
+
+def _get_standard_logging_mcp_tool_call(
+    name: str,
+    arguments: dict[str, object],
+    server_name: str | None,
+    session_id: str | None = None,
+) -> StandardLoggingMCPToolCall:
+    mcp_server: Final = global_mcp_server_manager._get_mcp_server_from_tool_name(
+        add_server_prefix_to_name(name, server_name) if server_name else name
+    )
+    namespaced_tool_name: Final = f"{server_name}/{name}" if server_name else name
+    if mcp_server:
+        mcp_info: Final = mcp_server.mcp_info or {}
+        return StandardLoggingMCPToolCall(
+            name=name,
+            arguments=arguments,
+            mcp_server_name=mcp_info.get("server_name"),
+            mcp_server_logo_url=mcp_info.get("logo_url"),
+            namespaced_tool_name=namespaced_tool_name,
+            mcp_session_id=session_id,
+            mcp_auth_mode=mcp_server.auth_type,
+            mcp_server_resource=_redact_mcp_resource_url(mcp_server.url),
+        )
+    else:
+        return StandardLoggingMCPToolCall(
+            name=name,
+            arguments=arguments,
+            namespaced_tool_name=namespaced_tool_name,
+            mcp_session_id=session_id,
+        )
+
+
+async def _handle_managed_mcp_tool(
+    server_name: str,
+    name: str,
+    arguments: dict[str, object],
+    user_api_key_auth: UserAPIKeyAuth | None = None,
+    mcp_auth_header: str | None = None,
+    mcp_server_auth_headers: dict[str, dict[str, str]] | None = None,
+    oauth2_headers: dict[str, str] | None = None,
+    raw_headers: dict[str, str] | None = None,
+    litellm_logging_obj: LiteLLMLoggingObj | None = None,
+    host_progress_callback: ProgressCallback | None = None,
+    guardrail_context: Mapping[str, object] | None = None,
+    client_ip: str | None = None,
+) -> CallToolResult:
+    """Handle tool execution for managed server tools"""
+    # Import here to avoid circular import
+    from litellm.proxy.proxy_server import proxy_logging_obj
+
+    call_tool_result: Final = await global_mcp_server_manager.call_tool(
+        server_name=server_name,
+        name=name,
+        arguments=arguments,
+        user_api_key_auth=user_api_key_auth,
+        mcp_auth_header=mcp_auth_header,
+        mcp_server_auth_headers=mcp_server_auth_headers,
+        oauth2_headers=oauth2_headers,
+        raw_headers=raw_headers,
+        client_ip=client_ip,
+        proxy_logging_obj=proxy_logging_obj,
+        host_progress_callback=host_progress_callback,
+        litellm_logging_obj=litellm_logging_obj,
+        guardrail_context=guardrail_context,
+    )
+    verbose_logger.debug("CALL TOOL RESULT: %s", call_tool_result)
+    return call_tool_result
+
+
+async def _handle_local_mcp_tool(name: str, arguments: dict[str, object]) -> CallToolResult:
+    """Execute a local-registry tool and report whether it succeeded.
+
+    Returns the result rather than bare content because the verdict is part of it: the content
+    alone cannot say whether the handler failed, so callers used to stamp is_error=False on every
+    outcome and an upstream rejection was served as tool output.
+
+    A failure is reported as ``is_error=True`` here rather than raised, because the REST surface
+    turns an unrecognized exception into a 500 and an upstream 403 or 429 is not a gateway crash.
+    ``MCPUpstreamAuthError`` is the exception: it propagates so the caller is told to
+    re-authenticate, which both renderers already know how to say.
+
+    Note: Local tools don't use prefixes, so we use the original name
+    """
+    import inspect
+
+    tool: Final = global_mcp_tool_registry.get_tool(name)
+    if not tool:
+        raise HTTPException(status_code=404, detail=f"Tool '{name}' not found")
+
+    try:
+        if inspect.iscoroutinefunction(tool.handler):
+            result = await tool.handler(**arguments)
+        else:
+            result = tool.handler(**arguments)
+    except MCPUpstreamAuthError:
+        raise
+    except Exception as e:
+        verbose_logger.exception("Error executing local tool %s: %s", name, e)
+        return CallToolResult(
+            content=[TextContent(text=f"Error: {e}", type="text")],  # mutable-ok: MCP result content
+            is_error=True,
+        )
+    return CallToolResult(
+        content=[TextContent(text=str(result), type="text")],  # mutable-ok: MCP result content
+        is_error=False,
+    )
+
+
+_MCP_CREDENTIAL_REQUEST_FIELDS: Final = frozenset(
+    {
+        "raw_headers",
+        "mcp_auth_header",
+        "mcp_server_auth_headers",
+        "oauth2_headers",
+        "user_api_key_auth",
+    }
+)
+
+
+class _McpDeniedDetail(TypedDict):
+    error: ReadOnly[str]
+
+
+async def _execute_handle_list_tools(
+    context: OperationContext, params: PaginatedRequestParams, host_progress_callback: ProgressCallback | None = None
+) -> ListToolsResult:
+    try:
+        (
+            user_api_key_auth,
+            mcp_auth_header,
+            mcp_servers,
+            mcp_server_auth_headers,
+            oauth2_headers,
+            raw_headers,
+            _client_ip,
+        ) = context.legacy_auth()
+        verbose_logger.debug("MCP list_tools - User API Key Auth from context: %s", user_api_key_auth)
+        verbose_logger.debug("MCP list_tools - MCP servers from context: %s", mcp_servers)
+        verbose_logger.debug(
+            "MCP list_tools - MCP server auth headers: %s",
+            list(mcp_server_auth_headers.keys()) if mcp_server_auth_headers else None,
+        )
+        from mcp.types import Tool
+
+        from litellm.proxy._experimental.mcp_server.tool_search import (
+            get_mcp_proxy_tool_definitions,
+            get_virtual_tool_definitions,
+        )
+
+        if context.mcp_proxy_mode:
+            return ListToolsResult(tools=[Tool.model_validate(d) for d in get_mcp_proxy_tool_definitions()])
+        if getattr(
+            getattr(user_api_key_auth, "object_permission", None),
+            "mcp_tool_search_enabled",
+            False,
+        ):
+            return ListToolsResult(tools=[Tool.model_validate(d) for d in get_virtual_tool_definitions()])
+
+        # Get mcp_servers from context variable
+        verbose_logger.debug("MCP list_tools - Calling _list_mcp_tools")
+        listing: Final = await _list_mcp_tools(
+            user_api_key_auth=user_api_key_auth,
+            mcp_auth_header=mcp_auth_header,
+            mcp_servers=mcp_servers,
+            mcp_server_auth_headers=mcp_server_auth_headers,
+            oauth2_headers=oauth2_headers,
+            raw_headers=raw_headers,
+            log_list_tools_to_spendlogs=True,
+            list_tools_log_source="mcp_protocol",
+            client_ip=_client_ip,
+        )
+        verbose_logger.info("MCP list_tools - Successfully returned %s tools", len(listing.tools))
+        if not listing.outcomes:
+            return ListToolsResult(tools=listing.tools)
+        outcome_meta: Final = {
+            SERVER_OUTCOMES_META_KEY: {key: outcome_wire_value(outcome) for key, outcome in listing.outcomes.items()}
+        }
+        return ListToolsResult.model_validate({"tools": listing.tools, "_meta": outcome_meta})
+    except HTTPException as e:
+        from mcp.shared.exceptions import MCPError
+        from mcp.types import INVALID_REQUEST
+
+        raise MCPError(code=INVALID_REQUEST, message=_http_detail_message(e.detail)) from e
+    except Exception as e:
+        verbose_logger.exception("Error in list_tools endpoint: %s", e)
+        # Return empty list instead of failing completely
+        # This prevents the HTTP stream from failing and allows the client to get a response
+        return ListToolsResult(tools=[])  # mutable-ok: MCP result payload
+
+
+async def _execute_mcp_server_tool_call(
+    context: OperationContext, params: CallToolRequestParams, host_progress_callback: ProgressCallback | None = None
+) -> CallToolResult:
+    from mcp.types import CallToolResult
+
+    from litellm.exceptions import BlockedPiiEntityError, GuardrailRaisedException
+    from litellm.proxy.litellm_pre_call_utils import add_litellm_data_to_request
+    from litellm.proxy.proxy_server import proxy_config
+
+    (
+        user_api_key_auth,
+        mcp_auth_header,
+        mcp_servers,
+        mcp_server_auth_headers,
+        oauth2_headers,
+        raw_headers,
+        _client_ip,
+    ) = context.legacy_auth()
+    verbose_logger.debug(
+        "MCP mcp_server_tool_call - user_api_key_auth=%s, user_role=%s",
+        user_api_key_auth,
+        getattr(user_api_key_auth, "user_role", "N/A"),
+    )
+
+    verbose_logger.debug("MCP mcp_server_tool_call - User API Key Auth from context: %s", user_api_key_auth)
+
+    try:
+        # Inside this try so virtual-tool errors convert to isError
+        # CallToolResult instead of raising out of the protocol handler.
+        virtual_tool_result: Final = await _dispatch_virtual_mcp_tool(
+            name=params.name,
+            arguments=params.arguments,
+            user_api_key_auth=user_api_key_auth,
+            client_ip=_client_ip,
+            mcp_servers=mcp_servers,
+            mcp_auth_header=mcp_auth_header,
+            mcp_server_auth_headers=mcp_server_auth_headers,
+            oauth2_headers=oauth2_headers,
+            raw_headers=raw_headers,
+            mcp_proxy_mode=context.mcp_proxy_mode,
+        )
+        if virtual_tool_result is not None:
+            return virtual_tool_result
+
+        # Create a body date for logging
+        body_data: Final = {"name": params.name, "arguments": params.arguments}  # mutable-ok: logging payload
+        # Set trace/session id from raw_headers so spend logs and logging_obj stay consistent (same as A2A)
+        chain_id: Final = get_chain_id_from_headers(raw_headers)
+        if chain_id:
+            body_data["litellm_trace_id"] = chain_id
+            body_data["litellm_session_id"] = chain_id
+
+        request: Final = build_synthetic_mcp_request(
+            path="/mcp/tools/call",
+            raw_headers=raw_headers,
+            client_ip=_client_ip,
+        )
+        if user_api_key_auth is not None:
+            data = await add_litellm_data_to_request(
+                data=body_data,
+                request=request,
+                # Bill a team-derived call to the team that granted it. A keyless admitted
+                # subject carries no team_id, so spend skipped team updates entirely and
+                # charged the user's PRIMARY org — the granting team's budget never
+                # accumulated (so it could never begin to block) and, cross-org, the wrong
+                # organization was charged. This is the ACCOUNTING half; the enforcement
+                # half (an already-over-budget team stops granting) lives in the source gate.
+                # Authorization is unaffected: it ran before this, and the union is resolved
+                # from the untouched auth object passed to call_mcp_tool below.
+                user_api_key_dict=await MCPRequestHandler.billing_auth_for_tool_call(
+                    user_api_key_auth, tool_name=params.name
+                ),
+                proxy_config=proxy_config,
+            )
+        else:
+            data = body_data
+
+        response: Final = await call_mcp_tool(
+            user_api_key_auth=user_api_key_auth,
+            mcp_auth_header=mcp_auth_header,
+            mcp_servers=mcp_servers,
+            mcp_server_auth_headers=mcp_server_auth_headers,
+            oauth2_headers=oauth2_headers,
+            raw_headers=raw_headers,
+            client_ip=_client_ip,
+            host_progress_callback=host_progress_callback,
+            **data,  # for logging
+        )
+    except MCPMissingUserEnvVarsError as e:
+        verbose_logger.info(
+            "MCP mcp_server_tool_call missing per-user env vars: server_id=%s missing=%s",
+            e.server_id,
+            e.missing,
+        )
+        return CallToolResult(
+            content=[TextContent(text=str(e), type="text")],
+            is_error=True,
+        )
+    except BlockedPiiEntityError as e:
+        verbose_logger.error("BlockedPiiEntityError in MCP tool call: %s", e)
+        return CallToolResult(
+            content=[
+                TextContent(
+                    text=f"Error: Blocked PII entity detected - {e}",
+                    type="text",
+                )
+            ],
+            is_error=True,
+        )
+    except GuardrailRaisedException as e:
+        verbose_logger.error("GuardrailRaisedException in MCP tool call: %s", e)
+        return CallToolResult(
+            content=[TextContent(text=f"Error: Guardrail violation - {e}", type="text")],
+            is_error=True,
+        )
+    except HTTPException as e:
+        verbose_logger.error("HTTPException in MCP tool call: %s", e)
+        return CallToolResult(
+            content=[TextContent(text=f"Error: {_http_detail_message(e.detail)}", type="text")],
+            is_error=True,
+        )
+    except MCPUpstreamAuthError as e:
+        # The MCP session manager serializes handler exceptions as JSON-RPC errors, so a
+        # mid-session tool call cannot emit a raw 401 + WWW-Authenticate the way the REST
+        # call path and the connect-time preemptive check do. Return an explicit isError
+        # naming the upstream status (at info level, not a traceback) so the client still
+        # learns it must re-authenticate upstream and expected pass-through 401s don't spam.
+        verbose_logger.info("Upstream auth failure calling MCP tool: HTTP %s", e.status_code)
+        return CallToolResult(
+            content=[
+                TextContent(
+                    text=f"Error: upstream authentication required (HTTP {e.status_code})",
+                    type="text",
+                )
+            ],
+            is_error=True,
+        )
+    except Exception as e:
+        verbose_logger.exception("MCP mcp_server_tool_call - error: %s", e)
+        return CallToolResult(
+            content=[TextContent(text=f"Error: {e}", type="text")],
+            is_error=True,
+        )
+
+    return response
+
+
+async def _execute_list_prompts(
+    context: OperationContext, params: PaginatedRequestParams, host_progress_callback: ProgressCallback | None = None
+) -> ListPromptsResult:
+    if context.mcp_proxy_mode:
+        _reject_mcp_proxy_operation()
+    try:
+        (
+            user_api_key_auth,
+            mcp_auth_header,
+            mcp_servers,
+            mcp_server_auth_headers,
+            oauth2_headers,
+            raw_headers,
+            _client_ip,
+        ) = context.legacy_auth()
+        verbose_logger.debug("MCP list_prompts - User API Key Auth from context: %s", user_api_key_auth)
+        verbose_logger.debug("MCP list_prompts - MCP servers from context: %s", mcp_servers)
+        verbose_logger.debug(
+            "MCP list_prompts - MCP server auth headers: %s",
+            list(mcp_server_auth_headers.keys()) if mcp_server_auth_headers else None,
+        )
+        # Get mcp_servers from context variable
+        verbose_logger.debug("MCP list_prompts - Calling _list_prompts")
+        prompts: Final = await _list_mcp_prompts(
+            user_api_key_auth=user_api_key_auth,
+            mcp_auth_header=mcp_auth_header,
+            mcp_servers=mcp_servers,
+            mcp_server_auth_headers=mcp_server_auth_headers,
+            oauth2_headers=oauth2_headers,
+            raw_headers=raw_headers,
+            client_ip=_client_ip,
+        )
+        verbose_logger.info("MCP list_prompts - Successfully returned %s prompts", len(prompts))
+        return ListPromptsResult(prompts=prompts)
+    except Exception as e:
+        verbose_logger.exception("Error in list_prompts endpoint: %s", e)
+        # Return empty list instead of failing completely
+        # This prevents the HTTP stream from failing and allows the client to get a response
+        return ListPromptsResult(prompts=[])  # mutable-ok: MCP result payload
+
+
+async def _execute_get_prompt(
+    context: OperationContext, params: GetPromptRequestParams, host_progress_callback: ProgressCallback | None = None
+) -> GetPromptResult:
+    if context.mcp_proxy_mode:
+        _reject_mcp_proxy_operation()
+    (
+        user_api_key_auth,
+        mcp_auth_header,
+        mcp_servers,
+        mcp_server_auth_headers,
+        oauth2_headers,
+        raw_headers,
+        _client_ip,
+    ) = context.legacy_auth()
+
+    verbose_logger.debug("MCP mcp_server_tool_call - User API Key Auth from context: %s", user_api_key_auth)
+    return await mcp_get_prompt(
+        name=params.name,
+        arguments=params.arguments,
+        user_api_key_auth=user_api_key_auth,
+        mcp_auth_header=mcp_auth_header,
+        mcp_servers=mcp_servers,
+        mcp_server_auth_headers=mcp_server_auth_headers,
+        oauth2_headers=oauth2_headers,
+        raw_headers=raw_headers,
+        client_ip=_client_ip,
+    )
+
+
+async def _execute_list_resources(
+    context: OperationContext, params: PaginatedRequestParams, host_progress_callback: ProgressCallback | None = None
+) -> ListResourcesResult:
+    if context.mcp_proxy_mode:
+        _reject_mcp_proxy_operation()
+    try:
+        (
+            user_api_key_auth,
+            mcp_auth_header,
+            mcp_servers,
+            mcp_server_auth_headers,
+            oauth2_headers,
+            raw_headers,
+            _client_ip,
+        ) = context.legacy_auth()
+        verbose_logger.debug("MCP list_resources - User API Key Auth from context: %s", user_api_key_auth)
+        verbose_logger.debug("MCP list_resources - MCP servers from context: %s", mcp_servers)
+        verbose_logger.debug(
+            "MCP list_resources - MCP server auth headers: %s",
+            list(mcp_server_auth_headers.keys()) if mcp_server_auth_headers else None,
+        )
+
+        resources: Final = await _list_mcp_resources(
+            user_api_key_auth=user_api_key_auth,
+            mcp_auth_header=mcp_auth_header,
+            mcp_servers=mcp_servers,
+            mcp_server_auth_headers=mcp_server_auth_headers,
+            oauth2_headers=oauth2_headers,
+            raw_headers=raw_headers,
+            client_ip=_client_ip,
+        )
+        verbose_logger.info("MCP list_resources - Successfully returned %s resources", len(resources))
+        return ListResourcesResult(resources=resources)
+    except Exception as e:
+        verbose_logger.exception("Error in list_resources endpoint: %s", e)
+        return ListResourcesResult(resources=[])  # mutable-ok: MCP result payload
+
+
+async def _execute_list_resource_templates(
+    context: OperationContext, params: PaginatedRequestParams, host_progress_callback: ProgressCallback | None = None
+) -> ListResourceTemplatesResult:
+    if context.mcp_proxy_mode:
+        _reject_mcp_proxy_operation()
+    try:
+        (
+            user_api_key_auth,
+            mcp_auth_header,
+            mcp_servers,
+            mcp_server_auth_headers,
+            oauth2_headers,
+            raw_headers,
+            _client_ip,
+        ) = context.legacy_auth()
+        verbose_logger.debug("MCP list_resource_templates - User API Key Auth from context: %s", user_api_key_auth)
+        verbose_logger.debug("MCP list_resource_templates - MCP servers from context: %s", mcp_servers)
+        verbose_logger.debug(
+            "MCP list_resource_templates - MCP server auth headers: %s",
+            list(mcp_server_auth_headers.keys()) if mcp_server_auth_headers else None,
+        )
+
+        resource_templates: Final = await _list_mcp_resource_templates(
+            user_api_key_auth=user_api_key_auth,
+            mcp_auth_header=mcp_auth_header,
+            mcp_servers=mcp_servers,
+            mcp_server_auth_headers=mcp_server_auth_headers,
+            oauth2_headers=oauth2_headers,
+            raw_headers=raw_headers,
+            client_ip=_client_ip,
+        )
+        verbose_logger.info(
+            "MCP list_resource_templates - Successfully returned %s resource templates", len(resource_templates)
+        )
+        return ListResourceTemplatesResult(resource_templates=resource_templates)
+    except Exception as e:
+        verbose_logger.exception("Error in list_resource_templates endpoint: %s", e)
+        return ListResourceTemplatesResult(resource_templates=[])  # mutable-ok: MCP result payload
+
+
+async def _execute_read_resource(
+    context: OperationContext, params: ReadResourceRequestParams, host_progress_callback: ProgressCallback | None = None
+) -> ReadResourceResult:
+    if context.mcp_proxy_mode:
+        _reject_mcp_proxy_operation()
+    (
+        user_api_key_auth,
+        mcp_auth_header,
+        mcp_servers,
+        mcp_server_auth_headers,
+        oauth2_headers,
+        raw_headers,
+        _client_ip,
+    ) = context.legacy_auth()
+
+    read_resource_result: Final = await mcp_read_resource(
+        url=params.uri,
+        user_api_key_auth=user_api_key_auth,
+        mcp_auth_header=mcp_auth_header,
+        mcp_servers=mcp_servers,
+        mcp_server_auth_headers=mcp_server_auth_headers,
+        oauth2_headers=oauth2_headers,
+        raw_headers=raw_headers,
+        client_ip=_client_ip,
+    )
+
+    return read_resource_result
+
+
+def _reject_mcp_proxy_operation() -> NoReturn:
+    from mcp.shared.exceptions import MCPError
+    from mcp.types import METHOD_NOT_FOUND
+
+    raise MCPError(code=METHOD_NOT_FOUND, message="Operation unavailable on /mcp/proxy")
+
+
+def prepare_context(
+    user_api_key_auth: UserAPIKeyAuth | None = None,
+    mcp_auth_header: str | None = None,
+    mcp_servers: Sequence[str] | None = None,
+    mcp_server_auth_headers: Mapping[str, Mapping[str, str]] | None = None,
+    oauth2_headers: Mapping[str, str] | None = None,
+    raw_headers: Mapping[str, str] | None = None,
+    client_ip: str | None = None,
+    mcp_proxy_mode: bool = False,
+) -> OperationContext:
+    return OperationContext(
+        _caller=user_api_key_auth,
+        mcp_auth_header=mcp_auth_header,
+        mcp_servers=tuple(mcp_servers) if mcp_servers is not None else None,
+        mcp_server_auth_headers=mcp_server_auth_headers,
+        oauth2_headers=oauth2_headers,
+        raw_headers=raw_headers,
+        client_ip=client_ip,
+        mcp_proxy_mode=mcp_proxy_mode,
+    )
+
+
+GatewayOperation: TypeAlias = (
+    AuthorizedToolCall
+    | ListToolsRequest
+    | CallToolRequest
+    | ListPromptsRequest
+    | GetPromptRequest
+    | ListResourcesRequest
+    | ListResourceTemplatesRequest
+    | ReadResourceRequest
+)
+GatewayResult: TypeAlias = (
+    ListToolsResult
+    | CallToolResult
+    | ListPromptsResult
+    | GetPromptResult
+    | ListResourcesResult
+    | ListResourceTemplatesResult
+    | ReadResourceResult
+)
+
+
+class GatewayOperations:
+    def __init__(self, host_progress_callback: ProgressCallback | None = None) -> None:
+        self._host_progress_callback = host_progress_callback
+
+    @overload
+    async def execute(self, operation: AuthorizedToolCall, context: OperationContext) -> CallToolResult: ...
+
+    @overload
+    async def execute(self, operation: ListToolsRequest, context: OperationContext) -> ListToolsResult: ...
+
+    @overload
+    async def execute(self, operation: CallToolRequest, context: OperationContext) -> CallToolResult: ...
+
+    @overload
+    async def execute(self, operation: ListPromptsRequest, context: OperationContext) -> ListPromptsResult: ...
+
+    @overload
+    async def execute(self, operation: GetPromptRequest, context: OperationContext) -> GetPromptResult: ...
+
+    @overload
+    async def execute(self, operation: ListResourcesRequest, context: OperationContext) -> ListResourcesResult: ...
+
+    @overload
+    async def execute(
+        self, operation: ListResourceTemplatesRequest, context: OperationContext
+    ) -> ListResourceTemplatesResult: ...
+
+    @overload
+    async def execute(self, operation: ReadResourceRequest, context: OperationContext) -> ReadResourceResult: ...
+
+    async def execute(self, operation: GatewayOperation, context: OperationContext) -> GatewayResult:
+        match operation:
+            case AuthorizedToolCall():
+                auth, token, _servers, server_headers, oauth_headers, headers, _client_ip = context.legacy_auth()
+                return await _execute_mcp_tool(
+                    name=operation.name,
+                    arguments=dict(operation.arguments),  # mutable-ok: existing tool hooks own mutable argument data
+                    allowed_mcp_servers=list(
+                        operation.allowed_mcp_servers
+                    ),  # mutable-ok: legacy dispatch list contract
+                    start_time=operation.start_time,
+                    user_api_key_auth=auth,
+                    mcp_auth_header=token,
+                    mcp_server_auth_headers=server_headers,
+                    oauth2_headers=oauth_headers,
+                    raw_headers=headers,
+                    client_ip=_client_ip,
+                    host_progress_callback=operation.host_progress_callback,
+                    guardrail_context=operation.guardrail_context,
+                    **operation.logging_data,
+                )
+            case ListToolsRequest(params=params):
+                return await _execute_handle_list_tools(
+                    context, params or PaginatedRequestParams(), self._host_progress_callback
+                )
+            case CallToolRequest(params=params):
+                return await _execute_mcp_server_tool_call(context, params, self._host_progress_callback)
+            case ListPromptsRequest(params=params):
+                return await _execute_list_prompts(
+                    context, params or PaginatedRequestParams(), self._host_progress_callback
+                )
+            case GetPromptRequest(params=params):
+                return await _execute_get_prompt(context, params, self._host_progress_callback)
+            case ListResourcesRequest(params=params):
+                return await _execute_list_resources(
+                    context, params or PaginatedRequestParams(), self._host_progress_callback
+                )
+            case ListResourceTemplatesRequest(params=params):
+                return await _execute_list_resource_templates(
+                    context, params or PaginatedRequestParams(), self._host_progress_callback
+                )
+            case ReadResourceRequest(params=params):
+                return await _execute_read_resource(context, params, self._host_progress_callback)
+            case _:
+                assert_never(operation)
diff --git a/litellm/proxy/_experimental/mcp_server/rest_endpoints.py b/litellm/proxy/_experimental/mcp_server/rest_endpoints.py
index 15f97a15b73..c2f7bf7d531 100644
--- a/litellm/proxy/_experimental/mcp_server/rest_endpoints.py
+++ b/litellm/proxy/_experimental/mcp_server/rest_endpoints.py
@@ -203,17 +203,19 @@ if MCP_AVAILABLE:
     from litellm.proxy._experimental.mcp_server.oauth_utils import (
         get_request_base_url,
     )
-    from litellm.proxy._experimental.mcp_server.server import (
+    from litellm.proxy._experimental.mcp_server.operations import (
         ListMCPToolsRestAPIResponseObject,
         MCPInfo,
         MCPServer,
-        _aggregate_server_key,  # pyright: ignore[reportPrivateUsage]  # same per-server key as the tools/list _meta outcomes
-        _apply_toolset_scope,
+        _aggregate_server_key,
         _fire_mcp_tool_call_logging,
         execute_mcp_tool,
         filter_tools_by_allowed_tools,
         filter_tools_by_key_team_permissions,
         fire_mcp_tool_call_failure_logging,
+    )
+    from litellm.proxy._experimental.mcp_server.server import (
+        _apply_toolset_scope,
         reject_disallowed_mcp_client,
     )
 
@@ -670,6 +672,7 @@ if MCP_AVAILABLE:
         user_api_key_auth: UserAPIKeyAuth | None = None,
         extra_headers: dict[str, str] | None = None,
         apply_tool_filters: bool = True,
+        client_ip: str | None = None,
     ):
         """Helper function to get tools for a single server.
 
@@ -684,6 +687,7 @@ if MCP_AVAILABLE:
             extra_headers=extra_headers,
             add_prefix=False,
             raw_headers=raw_headers,
+            client_ip=client_ip,
             user_api_key_auth=user_api_key_auth,
         )
 
@@ -797,6 +801,7 @@ if MCP_AVAILABLE:
                 user_api_key_dict,
                 extra_headers=user_oauth_extra_headers,
                 apply_tool_filters=apply_tool_filters,
+                client_ip=rest_client_ip,
             )
         except MCPUpstreamAuthError:
             # Surface the upstream 401/403 to the caller so it can emit the
@@ -1016,6 +1021,7 @@ if MCP_AVAILABLE:
                             user_api_key_dict,
                             extra_headers=user_oauth_extra_headers,
                             apply_tool_filters=apply_tool_filters,
+                            client_ip=_rest_client_ip,
                         )
                     except Exception as e:
                         verbose_logger.warning(
@@ -1193,6 +1199,7 @@ if MCP_AVAILABLE:
                     mcp_server_auth_headers=data.get("mcp_server_auth_headers"),
                     oauth2_headers=user_oauth_extra_headers or data.get("oauth2_headers"),
                     raw_headers=data.get("raw_headers"),
+                    client_ip=IPAddressUtils.get_mcp_client_ip(request),
                     litellm_logging_obj=data.get("litellm_logging_obj"),
                     guardrail_context=MCPRequestContext.resolve_guardrail_context(data),
                     requested_server_id=canonical_server_id,
diff --git a/litellm/proxy/_experimental/mcp_server/server.py b/litellm/proxy/_experimental/mcp_server/server.py
index 3a9bca926b0..33978bb9182 100644
--- a/litellm/proxy/_experimental/mcp_server/server.py
+++ b/litellm/proxy/_experimental/mcp_server/server.py
@@ -11,28 +11,22 @@ import hashlib
 import json
 import os
 import time
-import traceback
 import types
-import uuid
 from collections import Counter
-from collections.abc import AsyncIterator, Callable, Iterable, Mapping, Sequence
-from datetime import datetime
-from typing import TYPE_CHECKING, Any, Final, NoReturn, Protocol
+from collections.abc import AsyncGenerator, AsyncIterator, Callable, Iterable, Mapping, Sequence
+from typing import TYPE_CHECKING, Final, NoReturn, Protocol
 
 import httpx
 from fastapi import FastAPI, HTTPException
-from pydantic import AnyUrl, ConfigDict, Field, TypeAdapter, ValidationError
+from pydantic import ConfigDict, TypeAdapter, ValidationError
 from starlette.requests import Request as StarletteRequest
 from starlette.responses import JSONResponse
 from starlette.types import Message, Receive, Scope, Send
-from typing_extensions import ReadOnly, TypedDict
 
 from litellm._logging import verbose_logger
 from litellm.constants import (
-    MAXIMUM_TRACEBACK_LINES_TO_LOG,
     MCP_GATEWAY_SESSION_ID_PREFIX_LENGTH,
 )
-from litellm.litellm_core_utils.litellm_logging import Logging as LiteLLMLoggingObj
 from litellm.llms.custom_httpx.http_handler import (
     get_async_httpx_client,
     httpxSpecialProvider,
@@ -41,12 +35,6 @@ from litellm.proxy._experimental.mcp_server.auth.user_api_key_auth_mcp import (
     MCPRequestHandler,
     _is_mcp_admitted_user_subject,
 )
-from litellm.proxy._experimental.mcp_server.byok_credential_cache import (
-    byok_credential_cache,
-    byok_credential_cache_key,
-    cache_byok_credential,
-    get_cached_byok_credential,
-)
 from litellm.proxy._experimental.mcp_server.client_allowlist import (
     MCPClientAllowlist,
     check_mcp_client_allowed,
@@ -56,7 +44,6 @@ from litellm.proxy._experimental.mcp_server.discoverable_endpoints import (
     get_request_base_url,
 )
 from litellm.proxy._experimental.mcp_server.exceptions import (
-    MCPToolResultError,
     MCPUpstreamAuthError,
 )
 from litellm.proxy._experimental.mcp_server.mcp_context import (
@@ -74,7 +61,6 @@ from litellm.proxy._experimental.mcp_server.mcp_debug import (
 )
 from litellm.proxy._experimental.mcp_server.oauth_utils import (
     _redact_mcp_resource_url,
-    get_byok_www_authenticate,
     get_passthrough_www_authenticate,
     get_route_relative_request_path,
     well_known_root_suffix,
@@ -84,14 +70,6 @@ from litellm.proxy._experimental.mcp_server.utils import (
     LITELLM_MCP_SERVER_DESCRIPTION,
     LITELLM_MCP_SERVER_NAME,
     LITELLM_MCP_SERVER_VERSION,
-    MCPMissingUserEnvVarsError,
-    add_server_prefix_to_name,
-    build_synthetic_mcp_request,
-    extract_mcp_tool_result_error_message,
-    get_server_prefix,
-    iter_known_server_prefixes,
-    logging_safe_mcp_headers,
-    match_known_tool_name,
 )
 from litellm.proxy._types import (
     ProxyException,
@@ -99,13 +77,6 @@ from litellm.proxy._types import (
     UserAPIKeyAuth,
 )
 from litellm.proxy.auth.ip_address_utils import IPAddressUtils
-from litellm.proxy.common_utils.auth_cache_invalidation_pubsub import (
-    publish_auth_cache_invalidation,
-)
-from litellm.proxy.litellm_pre_call_utils import (
-    LiteLLMProxyRequestSetup,
-    get_chain_id_from_headers,
-)
 from litellm.types.mcp import (
     MCPAuth,
     MCPGatewaySession,
@@ -114,14 +85,11 @@ from litellm.types.mcp import (
     MCPGatewaySessionsTerminateResponse,
     MCPSpecVersion,
 )
-from litellm.types.mcp_server.mcp_server_manager import MCPInfo, MCPServer
-from litellm.types.utils import CallTypes, StandardLoggingMCPToolCall
-from litellm.utils import Rules, client, function_setup
+from litellm.types.mcp_server.mcp_server_manager import MCPServer
 
 if TYPE_CHECKING:
     from mcp.server.session import ServerSession as _McpServerSession
 
-    from litellm.proxy._experimental.mcp_server.db import OAuthCredentialPayload
 
 _STATEFUL_SESSION_IDLE_TIMEOUT_SECONDS: Final = 30 * 60
 # Upper bound on concurrent stateful sessions a single caller may hold. Each
@@ -159,13 +127,6 @@ def unsupported_protocol_version(scope: Scope) -> str | None:
     return None
 
 
-async def _invalidate_byok_cred_cache(user_id: str, server_id: str) -> None:
-    """Drop a stored-or-deleted BYOK credential from this worker's cache and from every peer worker's."""
-    cache_key: Final = byok_credential_cache_key(user_id, server_id)
-    byok_credential_cache.delete_cache(cache_key)
-    await publish_auth_cache_invalidation(cache_key=cache_key)
-
-
 # Check if MCP is available
 # "mcp" requires python 3.10 or higher, but several litellm users use python 3.8
 # We're making this conditional import to avoid breaking users who use python 3.8.
@@ -210,19 +171,6 @@ _SESSION_MANAGERS_INITIALIZED = False
 _INITIALIZATION_LOCK: Final = asyncio.Lock()
 
 
-def _mcp_session_id_from_headers(
-    raw_headers: dict[str, str] | None,
-) -> str | None:
-    """The ``mcp-session-id`` of a stateful MCP session, read case-insensitively
-    from the request headers. ``None`` for stateless calls (no such header)."""
-    if not raw_headers:
-        return None
-    for key, value in raw_headers.items():
-        if isinstance(key, str) and key.lower() == "mcp-session-id":
-            return value or None
-    return None
-
-
 def _jsonrpc_text_has_top_level_method(text: str) -> bool:
     """Whether a (possibly truncated) JSON-RPC envelope has a ``method`` key at
     the root object's top level.
@@ -466,6 +414,56 @@ def _proxy_exception_to_http_exception(exc: ProxyException) -> HTTPException:
 
 
 if MCP_AVAILABLE:
+    __all__ = (
+        "_MCP_CREDENTIAL_REQUEST_FIELDS",
+        "ListMCPToolsRestAPIResponseObject",
+        "_McpDeniedDetail",
+        "_aggregate_server_key",
+        "_build_virtual_call_logging_obj",
+        "_check_byok_credential",
+        "_client_has_passthrough_authorization",
+        "_client_has_per_server_auth_header",
+        "_dispatch_virtual_mcp_tool",
+        "_fire_mcp_tool_call_logging",
+        "_get_allowed_mcp_servers",
+        "_get_allowed_mcp_servers_from_mcp_server_names",
+        "_get_byok_credential",
+        "_get_prompts_from_mcp_servers",
+        "_get_resource_templates_from_mcp_servers",
+        "_get_resources_from_mcp_servers",
+        "_get_standard_logging_mcp_tool_call",
+        "_get_tools_from_mcp_servers",
+        "_get_user_oauth_extra_headers_from_db",
+        "_handle_local_mcp_tool",
+        "_handle_managed_mcp_tool",
+        "_http_detail_message",
+        "_invalidate_byok_cred_cache",
+        "_list_mcp_prompts",
+        "_list_mcp_resource_templates",
+        "_list_mcp_resources",
+        "_list_mcp_tools",
+        "_list_tools_before_first_call",
+        "_mcp_session_id_from_headers",
+        "_merge_gateway_initialize_instructions",
+        "_prefetch_oauth_creds_for_user",
+        "_prepare_mcp_server_headers",
+        "_raise_if_initialize_grants_no_mcp_servers",
+        "_redact_mcp_resource_url",
+        "_resolve_display_name_to_original",
+        "_run_post_mcp_call_guardrails",
+        "_server_answers_to",
+        "_tool_name_matches",
+        "apply_tool_overrides",
+        "call_mcp_tool",
+        "execute_mcp_tool",
+        "filter_tools_by_allowed_tools",
+        "filter_tools_by_key_team_permissions",
+        "fire_mcp_tool_call_failure_logging",
+        "global_mcp_server_manager",
+        "mcp_get_prompt",
+        "mcp_read_resource",
+        "raise_denied_scoped_mcp_access",
+    )
     from mcp.server import Server
 
     # Import auth context variables and middleware
@@ -476,6 +474,23 @@ if MCP_AVAILABLE:
     from mcp.server.context import ServerRequestContext
     from mcp.server.lowlevel.server import NotificationOptions
     from mcp.server.models import InitializationOptions
+    from mcp.shared.exceptions import MCPError
+    from mcp.types import (
+        CallToolRequest,
+        GetPromptRequest,
+        ListPromptsRequest,
+        ListResourcesRequest,
+        ListResourceTemplatesRequest,
+        ListToolsRequest,
+        ReadResourceRequest,
+    )
+
+    from litellm.proxy._experimental.mcp_server import operations
+    from litellm.proxy._experimental.mcp_server.contracts import OperationContext
+    from litellm.proxy._experimental.mcp_server.operations import (
+        _invalidate_byok_cred_cache,
+        _mcp_session_id_from_headers,
+    )
 
     try:
         from mcp.server.streamable_http_manager import StreamableHTTPSessionManager
@@ -493,62 +508,27 @@ if MCP_AVAILABLE:
         ListResourceTemplatesResult,
         ListToolsResult,
         PaginatedRequestParams,
-        Prompt,
         ReadResourceRequestParams,
-        TextContent,
     )
-    from mcp.types import Tool as MCPTool
     from mcp_types.version import HANDSHAKE_PROTOCOL_VERSIONS
 
     from litellm.proxy._experimental.mcp_server.auth.litellm_auth_handler import (
         MCPAuthenticatedUser,
     )
-    from litellm.proxy._experimental.mcp_server.faults.list_outcomes import (
-        SERVER_OUTCOMES_META_KEY,
-        AggregateToolListing,
-        ServerListOk,
-        ServerOutcome,
-        classify_list_exception,
-        outcome_wire_value,
-    )
     from litellm.proxy._experimental.mcp_server.mcp_server_manager import (
         MCPServerManager,
-        _caller_authorization_fans_out,
-        _client_forwarded_authorization_headers,
-        _resolve_openapi_tool_auth,
-        _should_strip_caller_authorization,
         global_mcp_server_manager,
     )
-    from litellm.proxy._experimental.mcp_server.openapi_to_mcp_generator import (
-        _request_auth_header,
-        _request_extra_headers,
-        _request_resolved_auth_headers,
-    )
-    from litellm.proxy._experimental.mcp_server.sse_transport import SseServerTransport
-    from litellm.proxy._experimental.mcp_server.tool_registry import (
-        global_mcp_tool_registry,
-    )
-    from litellm.proxy._experimental.mcp_server.utils import (
-        MCP_TOOL_PREFIX_SEPARATOR,
-        is_tool_name_prefixed,
-        normalize_server_name,
-        split_server_prefix_from_name,
-        strip_known_server_prefix,
-    )
-    from litellm.types.mcp import DEFAULT_CREDENTIAL_HEADER, without_header
 
     ######################################################
     ############ MCP Tools List REST API Response Object #
     # Defined here because we don't want to add `mcp` as a
     # required dependency for `litellm` pip package
     ######################################################
-    class ListMCPToolsRestAPIResponseObject(MCPTool):
-        """
-        Object returned by the /tools/list REST API route.
-        """
-
-        mcp_info: MCPInfo | None = Field(default=None, alias="mcp_info")
-        model_config = ConfigDict(arbitrary_types_allowed=True)
+    from litellm.proxy._experimental.mcp_server.operations import (
+        ListMCPToolsRestAPIResponseObject,
+    )
+    from litellm.proxy._experimental.mcp_server.sse_transport import SseServerTransport
 
     def _gateway_create_initialization_options(
         self,
@@ -818,94 +798,45 @@ if MCP_AVAILABLE:
     ############### MCP Server Routes #######################
     ########################################################
 
-    async def handle_list_tools(ctx: ServerRequestContext, params: PaginatedRequestParams) -> ListToolsResult:
-        """
-        List all available tools, with each server's listing outcome attached to the result's
-        ``_meta`` (SERVER_OUTCOMES_META_KEY) so a broken upstream is distinguishable from a healthy
-        server with no tools. Returning a ListToolsResult (rather than a bare list) makes the MCP SDK
-        pass the result through unwrapped, which is what lets the ``_meta`` survive to the client.
-        Also captures the active session for propagation to callbacks.
-        """
-        req_ctx: Final = ctx
-        _ctx_reset_token: Final = active_mcp_request_ctx_var.set(ctx)
-        _session_reset_token: Final = active_mcp_session_var.set(ctx.session)
-        _trace_token = None
-        _transport_token = None
-        _destinations_token = None
-
-        try:
-            _trace_token = _otel_set_mcp_trace_carrier(_mcp_meta_trace_carrier(req_ctx))
-            _transport_token = _otel_set_mcp_transport_span(_otel_transport_span_from_message(req_ctx))
-            _destinations_token = _otel_set_mcp_request_destinations(req_ctx)
-            # Get user authentication from context variable
+    @contextlib.asynccontextmanager
+    async def _legacy_operation_context(ctx: ServerRequestContext, *, trace: bool) -> AsyncGenerator[OperationContext]:
+        with contextlib.ExitStack() as cleanup:
+            cleanup.callback(active_mcp_request_ctx_var.reset, active_mcp_request_ctx_var.set(ctx))
+            cleanup.callback(active_mcp_session_var.reset, active_mcp_session_var.set(ctx.session))
+            if trace:
+                cleanup.callback(
+                    _otel_reset_mcp_trace_carrier, _otel_set_mcp_trace_carrier(_mcp_meta_trace_carrier(ctx))
+                )
+                cleanup.callback(
+                    _otel_reset_mcp_transport_span, _otel_set_mcp_transport_span(_otel_transport_span_from_message(ctx))
+                )
+                cleanup.callback(_otel_reset_mcp_request_destinations, _otel_set_mcp_request_destinations(ctx))
             (
-                user_api_key_auth,
-                mcp_auth_header,
-                mcp_servers,
-                mcp_server_auth_headers,
-                oauth2_headers,
-                raw_headers,
-                _client_ip,
+                auth,
+                token,
+                servers,
+                server_headers,
+                oauth_headers,
+                headers,
+                client_ip,
             ) = await get_or_extract_auth_context()
-            verbose_logger.debug("MCP list_tools - User API Key Auth from context: %s", user_api_key_auth)
-            verbose_logger.debug("MCP list_tools - MCP servers from context: %s", mcp_servers)
-            verbose_logger.debug(
-                "MCP list_tools - MCP server auth headers: %s",
-                list(mcp_server_auth_headers.keys()) if mcp_server_auth_headers else None,
-            )
-            from mcp.types import Tool
-
-            from litellm.proxy._experimental.mcp_server.tool_search import (
-                get_mcp_proxy_tool_definitions,
-                get_virtual_tool_definitions,
+            yield operations.prepare_context(
+                auth, token, servers, server_headers, oauth_headers, headers, client_ip, _mcp_proxy_mode.get()
             )
 
-            if _mcp_proxy_mode.get():
-                return ListToolsResult(tools=[Tool.model_validate(d) for d in get_mcp_proxy_tool_definitions()])
-            if getattr(
-                getattr(user_api_key_auth, "object_permission", None),
-                "mcp_tool_search_enabled",
-                False,
-            ):
-                return ListToolsResult(tools=[Tool.model_validate(d) for d in get_virtual_tool_definitions()])
-
-            # Get mcp_servers from context variable
-            verbose_logger.debug("MCP list_tools - Calling _list_mcp_tools")
-            listing: Final = await _list_mcp_tools(
-                user_api_key_auth=user_api_key_auth,
-                mcp_auth_header=mcp_auth_header,
-                mcp_servers=mcp_servers,
-                mcp_server_auth_headers=mcp_server_auth_headers,
-                oauth2_headers=oauth2_headers,
-                raw_headers=raw_headers,
-                log_list_tools_to_spendlogs=True,
-                list_tools_log_source="mcp_protocol",
-            )
-            verbose_logger.info("MCP list_tools - Successfully returned %s tools", len(listing.tools))
-            if not listing.outcomes:
-                return ListToolsResult(tools=listing.tools)
-            outcome_meta: Final = {
-                SERVER_OUTCOMES_META_KEY: {
-                    key: outcome_wire_value(outcome) for key, outcome in listing.outcomes.items()
-                }
-            }
-            return ListToolsResult.model_validate({"tools": listing.tools, "_meta": outcome_meta})
-        except HTTPException as e:
-            from mcp.shared.exceptions import MCPError
-            from mcp.types import INVALID_REQUEST
-
-            raise MCPError(code=INVALID_REQUEST, message=_http_detail_message(e.detail)) from e
-        except Exception as e:
-            verbose_logger.exception("Error in list_tools endpoint: %s", e)
-            # Return empty list instead of failing completely
-            # This prevents the HTTP stream from failing and allows the client to get a response
-            return ListToolsResult(tools=[])  # mutable-ok: MCP result payload
-        finally:
-            _otel_reset_mcp_request_destinations(_destinations_token)
-            _otel_reset_mcp_transport_span(_transport_token)
-            _otel_reset_mcp_trace_carrier(_trace_token)
-            active_mcp_session_var.reset(_session_reset_token)
-            active_mcp_request_ctx_var.reset(_ctx_reset_token)
+    async def handle_list_tools(ctx: ServerRequestContext, params: PaginatedRequestParams) -> ListToolsResult:
+        try:
+            async with _legacy_operation_context(ctx, trace=True) as context:
+                return await operations.GatewayOperations(_capture_host_progress_callback(ctx)).execute(
+                    ListToolsRequest(params=params), context
+                )
+        except MCPError:
+            raise
+        except HTTPException as exc:
+            raise MCPError(code=INVALID_REQUEST, message=operations._http_detail_message(exc.detail)) from exc
+        except Exception as exc:  # noqa: BLE001  # preserve native listing fallback for ingress failures
+            verbose_logger.exception("Error in list_tools endpoint: %s", exc)
+            return ListToolsResult(tools=[])
 
     def _capture_host_progress_callback(ctx: ServerRequestContext) -> Callable | None:
         """Return a progress-forwarding callback bound to the host MCP session.
@@ -942,581 +873,71 @@ if MCP_AVAILABLE:
 
         raise MCPError(code=METHOD_NOT_FOUND, message="Operation unavailable on /mcp/proxy")
 
-    async def _build_virtual_call_logging_obj(
-        name: str,
-        arguments: dict[str, object],
-        user_api_key_auth: UserAPIKeyAuth,
-        raw_headers: Mapping[str, str] | None = None,
-        client_ip: str | None = None,
-    ) -> LiteLLMLoggingObj | None:
-        """Run the pre-call pipeline (guardrails + logging setup) for a virtual
-        mcp_tool_call so the SSE path spend-logs like the REST path."""
-        from litellm.proxy.common_request_processing import (
-            ProxyBaseLLMRequestProcessing,
-        )
-        from litellm.proxy.proxy_server import (
-            general_settings,
-            proxy_config,
-            proxy_logging_obj,
-        )
-
-        request: Final = build_synthetic_mcp_request(
-            path="/mcp/tools/call",
-            raw_headers=raw_headers,
-            client_ip=client_ip,
-        )
-        _, virtual_logging_obj = await ProxyBaseLLMRequestProcessing(
-            data={"name": name, "arguments": arguments}
-        ).common_processing_pre_call_logic(
-            request=request,
-            user_api_key_dict=user_api_key_auth,
-            proxy_config=proxy_config,
-            route_type=CallTypes.call_mcp_tool.value,
-            proxy_logging_obj=proxy_logging_obj,
-            general_settings=general_settings,
-        )
-        return virtual_logging_obj
-
-    async def _dispatch_virtual_mcp_tool(
-        name: str,
-        arguments: dict[str, object] | None,
-        user_api_key_auth: UserAPIKeyAuth | None,
-        client_ip: str | None,
-        mcp_servers: list[str] | None = None,
-        mcp_auth_header: str | None = None,
-        mcp_server_auth_headers: dict[str, dict[str, str]] | None = None,
-        oauth2_headers: dict[str, str] | None = None,
-        raw_headers: dict[str, str] | None = None,
-    ) -> CallToolResult | None:
-        """Handle the mcp_tool_search / mcp_tool_call virtual tools.
-
-        Returns a CallToolResult when ``name`` is a virtual tool, else ``None`` so
-        the caller falls through to normal tool routing.
-        """
-        from litellm.llms.litellm_proxy.skills.skill_search import DEFAULT_SKILL_SEARCH_TOP_K
-        from litellm.proxy._experimental.mcp_server.tool_search import (
-            AGENT_SEARCH_TOOL_NAME,
-            DEFAULT_AGENT_SEARCH_TOP_K,
-            MCP_PROXY_CALL_TOOL_NAME,
-            MCP_PROXY_TOOL_NAMES,
-            MCP_TOOL_SEARCH_TOOL_NAME,
-            SKILL_SEARCH_TOOL_NAME,
-            VIRTUAL_TOOL_NAMES,
-            coerce_top_k,
-            handle_agent_search,
-            handle_mcp_proxy_tool,
-            handle_mcp_tool_call,
-            handle_mcp_tool_search,
-            handle_skill_search,
-        )
-
-        if _mcp_proxy_mode.get() and name not in MCP_PROXY_TOOL_NAMES:
-            return CallToolResult(
-                content=[  # mutable-ok: MCP result content
-                    TextContent(type="text", text=f"Tool {name} is unavailable on /mcp/proxy")
-                ],
-                is_error=True,
-            )
-
-        if _mcp_proxy_mode.get() and name in MCP_PROXY_TOOL_NAMES:
-            assert user_api_key_auth is not None
-            proxy_call_start: Final = datetime.now()  # noqa: DTZ005  # logging pipeline uses naive datetimes
-            proxy_logging_obj: Final = (
-                await _build_virtual_call_logging_obj(
-                    name=name,
-                    arguments=arguments or {},  # mutable-ok: logging pipeline payload
-                    user_api_key_auth=user_api_key_auth,
-                    raw_headers=raw_headers,
-                    client_ip=client_ip,
-                )
-                if name == MCP_PROXY_CALL_TOOL_NAME
-                else None
-            )
-            try:
-                proxy_result: Final = await handle_mcp_proxy_tool(
-                    name=name,
-                    arguments=arguments or {},  # mutable-ok: proxy handler payload
-                    user_api_key_dict=user_api_key_auth,
-                    client_ip=client_ip,
-                    mcp_servers=mcp_servers,
-                    mcp_auth_header=mcp_auth_header,
-                    mcp_server_auth_headers=mcp_server_auth_headers,
-                    oauth2_headers=oauth2_headers,
-                    raw_headers=raw_headers,
-                    litellm_logging_obj=proxy_logging_obj,
-                )
-            except Exception as exc:
-                if proxy_logging_obj is not None:
-                    from litellm.proxy.proxy_server import proxy_logging_obj as request_logging_obj
-
-                    failure_end: Final = datetime.now()  # noqa: DTZ005  # matches the logging pipeline start time
-                    failure_traceback: Final = traceback.format_exc(limit=MAXIMUM_TRACEBACK_LINES_TO_LOG)
-                    try:
-                        proxy_logging_obj.failure_handler(exc, failure_traceback, proxy_call_start, failure_end)
-                        await proxy_logging_obj.async_failure_handler(
-                            exc, failure_traceback, proxy_call_start, failure_end
-                        )
-                        if not isinstance(exc, MCPUpstreamAuthError):
-                            await request_logging_obj.post_call_failure_hook(
-                                request_data={  # mutable-ok: failure hook mutates its request payload
-                                    "name": name,
-                                    "arguments": arguments,
-                                    "litellm_logging_obj": proxy_logging_obj,
-                                },
-                                original_exception=exc,
-                                user_api_key_dict=user_api_key_auth,
-                                route="/mcp/call_tool",
-                                traceback_str=failure_traceback,
-                            )
-                    except Exception:  # noqa: BLE001  # a failing failure hook must not mask the tool call's own error
-                        verbose_logger.exception("Error logging failed MCP proxy tool call")
-                raise
-            if proxy_logging_obj is not None:
-                return await _fire_mcp_tool_call_logging(
-                    logging_obj=proxy_logging_obj,
-                    result=proxy_result,
-                    start_time=proxy_call_start,
-                    end_time=datetime.now(),  # noqa: DTZ005  # matches the logging pipeline start time
-                    user_api_key_auth=user_api_key_auth,
-                    request_data=types.MappingProxyType({"name": name, "arguments": arguments}),
-                )
-            return proxy_result
-
-        if name not in VIRTUAL_TOOL_NAMES:
-            return None
-
-        if not getattr(
-            getattr(user_api_key_auth, "object_permission", None),
-            "mcp_tool_search_enabled",
-            False,
-        ):
-            return CallToolResult(
-                content=[
-                    TextContent(
-                        type="text",
-                        text=f"Tool {name} requires mcp_tool_search_enabled on the key",
-                    )
-                ],
-                is_error=True,
-            )
-
-        args: Final = arguments or {}
-        if name == MCP_TOOL_SEARCH_TOOL_NAME:
-            return await handle_mcp_tool_search(
-                query=args.get("query", ""),
-                top_k=coerce_top_k(args.get("top_k", 5)),
-                user_api_key_dict=user_api_key_auth,
-                client_ip=client_ip,
-                mcp_servers=mcp_servers,
-                mcp_auth_header=mcp_auth_header,
-                mcp_server_auth_headers=mcp_server_auth_headers,
-                oauth2_headers=oauth2_headers,
-                raw_headers=raw_headers,
-            )
-
-        assert user_api_key_auth is not None  # guaranteed by the flag check above
-        if name == AGENT_SEARCH_TOOL_NAME:
-            return await handle_agent_search(
-                query=str(args.get("query", "")),
-                top_k=coerce_top_k(args.get("top_k", DEFAULT_AGENT_SEARCH_TOP_K), default=DEFAULT_AGENT_SEARCH_TOP_K),
-                user_api_key_dict=user_api_key_auth,
-            )
-        if name == SKILL_SEARCH_TOOL_NAME:
-            return await handle_skill_search(
-                query=str(args.get("query", "")),
-                top_k=coerce_top_k(args.get("top_k", DEFAULT_SKILL_SEARCH_TOP_K), default=DEFAULT_SKILL_SEARCH_TOP_K),
-                user_api_key_dict=user_api_key_auth,
-            )
-        virtual_logging_obj: Final = await _build_virtual_call_logging_obj(
-            name=name,
-            arguments=args,
-            user_api_key_auth=user_api_key_auth,
-            raw_headers=raw_headers,
-            client_ip=client_ip,
-        )
-        return await handle_mcp_tool_call(
-            tool_name=args.get("tool_name", ""),
-            arguments=args.get("arguments") or {},
-            user_api_key_dict=user_api_key_auth,
-            client_ip=client_ip,
-            mcp_servers=mcp_servers,
-            mcp_auth_header=mcp_auth_header,
-            mcp_server_auth_headers=mcp_server_auth_headers,
-            oauth2_headers=oauth2_headers,
-            raw_headers=raw_headers,
-            litellm_logging_obj=virtual_logging_obj,
-        )
+    from litellm.proxy._experimental.mcp_server.operations import (
+        _build_virtual_call_logging_obj,
+        _dispatch_virtual_mcp_tool,
+    )
 
     async def mcp_server_tool_call(ctx: ServerRequestContext, params: CallToolRequestParams) -> CallToolResult:
-        """
-        Call a specific tool with the provided arguments
-        Args:
-            ctx: SDK request context carrying the client session and HTTP request
-            params (CallToolRequestParams): Tool name and arguments
-        Returns:
-            CallToolResult: Tool execution results
-        """
-        from mcp.types import CallToolResult
-
-        from litellm.exceptions import BlockedPiiEntityError, GuardrailRaisedException
-        from litellm.proxy.litellm_pre_call_utils import add_litellm_data_to_request
-        from litellm.proxy.proxy_server import proxy_config
-
-        req_ctx: Final = ctx
-        _ctx_reset_token: Final = active_mcp_request_ctx_var.set(ctx)
-        _session_reset_token: Final = active_mcp_session_var.set(ctx.session)
-        _trace_token = None
-        _transport_token = None
-        _destinations_token = None
-
-        try:
-            _trace_token = _otel_set_mcp_trace_carrier(_mcp_meta_trace_carrier(req_ctx))
-            _transport_token = _otel_set_mcp_transport_span(_otel_transport_span_from_message(req_ctx))
-            _destinations_token = _otel_set_mcp_request_destinations(req_ctx)
-            # Validate arguments
-            (
-                user_api_key_auth,
-                mcp_auth_header,
-                mcp_servers,
-                mcp_server_auth_headers,
-                oauth2_headers,
-                raw_headers,
-                _client_ip,
-            ) = await get_or_extract_auth_context()
-            verbose_logger.debug(
-                "MCP mcp_server_tool_call - user_api_key_auth=%s, user_role=%s",
-                user_api_key_auth,
-                getattr(user_api_key_auth, "user_role", "N/A"),
+        async with _legacy_operation_context(ctx, trace=True) as context:
+            return await operations.GatewayOperations(_capture_host_progress_callback(ctx)).execute(
+                CallToolRequest(params=params), context
             )
 
-            verbose_logger.debug("MCP mcp_server_tool_call - User API Key Auth from context: %s", user_api_key_auth)
-
-            try:
-                # Inside this try so virtual-tool errors convert to isError
-                # CallToolResult instead of raising out of the protocol handler.
-                virtual_tool_result: Final = await _dispatch_virtual_mcp_tool(
-                    name=params.name,
-                    arguments=params.arguments,
-                    user_api_key_auth=user_api_key_auth,
-                    client_ip=_client_ip,
-                    mcp_servers=mcp_servers,
-                    mcp_auth_header=mcp_auth_header,
-                    mcp_server_auth_headers=mcp_server_auth_headers,
-                    oauth2_headers=oauth2_headers,
-                    raw_headers=raw_headers,
-                )
-                if virtual_tool_result is not None:
-                    return virtual_tool_result
-
-                host_progress_callback: Final = _capture_host_progress_callback(ctx)
-                # Create a body date for logging
-                body_data: Final = {"name": params.name, "arguments": params.arguments}  # mutable-ok: logging payload
-                # Set trace/session id from raw_headers so spend logs and logging_obj stay consistent (same as A2A)
-                chain_id: Final = get_chain_id_from_headers(raw_headers)
-                if chain_id:
-                    body_data["litellm_trace_id"] = chain_id
-                    body_data["litellm_session_id"] = chain_id
-
-                request: Final = build_synthetic_mcp_request(
-                    path="/mcp/tools/call",
-                    raw_headers=raw_headers,
-                    client_ip=_client_ip,
-                )
-                if user_api_key_auth is not None:
-                    data = await add_litellm_data_to_request(
-                        data=body_data,
-                        request=request,
-                        # Bill a team-derived call to the team that granted it. A keyless admitted
-                        # subject carries no team_id, so spend skipped team updates entirely and
-                        # charged the user's PRIMARY org — the granting team's budget never
-                        # accumulated (so it could never begin to block) and, cross-org, the wrong
-                        # organization was charged. This is the ACCOUNTING half; the enforcement
-                        # half (an already-over-budget team stops granting) lives in the source gate.
-                        # Authorization is unaffected: it ran before this, and the union is resolved
-                        # from the untouched auth object passed to call_mcp_tool below.
-                        user_api_key_dict=await MCPRequestHandler.billing_auth_for_tool_call(
-                            user_api_key_auth, tool_name=params.name
-                        ),
-                        proxy_config=proxy_config,
-                    )
-                else:
-                    data = body_data
-
-                response: Final = await call_mcp_tool(
-                    user_api_key_auth=user_api_key_auth,
-                    mcp_auth_header=mcp_auth_header,
-                    mcp_servers=mcp_servers,
-                    mcp_server_auth_headers=mcp_server_auth_headers,
-                    oauth2_headers=oauth2_headers,
-                    raw_headers=raw_headers,
-                    client_ip=_client_ip,
-                    host_progress_callback=host_progress_callback,
-                    **data,  # for logging
-                )
-            except MCPMissingUserEnvVarsError as e:
-                verbose_logger.info(
-                    "MCP mcp_server_tool_call missing per-user env vars: server_id=%s missing=%s",
-                    e.server_id,
-                    e.missing,
-                )
-                return CallToolResult(
-                    content=[TextContent(text=str(e), type="text")],
-                    is_error=True,
-                )
-            except BlockedPiiEntityError as e:
-                verbose_logger.error("BlockedPiiEntityError in MCP tool call: %s", e)
-                return CallToolResult(
-                    content=[
-                        TextContent(
-                            text=f"Error: Blocked PII entity detected - {e}",
-                            type="text",
-                        )
-                    ],
-                    is_error=True,
-                )
-            except GuardrailRaisedException as e:
-                verbose_logger.error("GuardrailRaisedException in MCP tool call: %s", e)
-                return CallToolResult(
-                    content=[TextContent(text=f"Error: Guardrail violation - {e}", type="text")],
-                    is_error=True,
-                )
-            except HTTPException as e:
-                verbose_logger.error("HTTPException in MCP tool call: %s", e)
-                return CallToolResult(
-                    content=[TextContent(text=f"Error: {_http_detail_message(e.detail)}", type="text")],
-                    is_error=True,
-                )
-            except MCPUpstreamAuthError as e:
-                # The MCP session manager serializes handler exceptions as JSON-RPC errors, so a
-                # mid-session tool call cannot emit a raw 401 + WWW-Authenticate the way the REST
-                # call path and the connect-time preemptive check do. Return an explicit isError
-                # naming the upstream status (at info level, not a traceback) so the client still
-                # learns it must re-authenticate upstream and expected pass-through 401s don't spam.
-                verbose_logger.info("Upstream auth failure calling MCP tool: HTTP %s", e.status_code)
-                return CallToolResult(
-                    content=[
-                        TextContent(
-                            text=f"Error: upstream authentication required (HTTP {e.status_code})",
-                            type="text",
-                        )
-                    ],
-                    is_error=True,
-                )
-            except Exception as e:
-                verbose_logger.exception("MCP mcp_server_tool_call - error: %s", e)
-                return CallToolResult(
-                    content=[TextContent(text=f"Error: {e}", type="text")],
-                    is_error=True,
-                )
-
-            return response
-        finally:
-            _otel_reset_mcp_request_destinations(_destinations_token)
-            _otel_reset_mcp_transport_span(_transport_token)
-            _otel_reset_mcp_trace_carrier(_trace_token)
-            active_mcp_session_var.reset(_session_reset_token)
-            active_mcp_request_ctx_var.reset(_ctx_reset_token)
-
     async def list_prompts(ctx: ServerRequestContext, params: PaginatedRequestParams) -> ListPromptsResult:
-        """
-        List all available prompts
-        """
         if _mcp_proxy_mode.get():
             _reject_mcp_proxy_operation()
-        _ctx_reset_token: Final = active_mcp_request_ctx_var.set(ctx)
-        _session_reset_token: Final = active_mcp_session_var.set(ctx.session)
-
         try:
-            # Get user authentication from context variable
-            (
-                user_api_key_auth,
-                mcp_auth_header,
-                mcp_servers,
-                mcp_server_auth_headers,
-                oauth2_headers,
-                raw_headers,
-                _client_ip,
-            ) = await get_or_extract_auth_context()
-            verbose_logger.debug("MCP list_prompts - User API Key Auth from context: %s", user_api_key_auth)
-            verbose_logger.debug("MCP list_prompts - MCP servers from context: %s", mcp_servers)
-            verbose_logger.debug(
-                "MCP list_prompts - MCP server auth headers: %s",
-                list(mcp_server_auth_headers.keys()) if mcp_server_auth_headers else None,
-            )
-            # Get mcp_servers from context variable
-            verbose_logger.debug("MCP list_prompts - Calling _list_prompts")
-            prompts: Final = await _list_mcp_prompts(
-                user_api_key_auth=user_api_key_auth,
-                mcp_auth_header=mcp_auth_header,
-                mcp_servers=mcp_servers,
-                mcp_server_auth_headers=mcp_server_auth_headers,
-                oauth2_headers=oauth2_headers,
-                raw_headers=raw_headers,
-            )
-            verbose_logger.info("MCP list_prompts - Successfully returned %s prompts", len(prompts))
-            return ListPromptsResult(prompts=prompts)
-        except Exception as e:
-            verbose_logger.exception("Error in list_prompts endpoint: %s", e)
-            # Return empty list instead of failing completely
-            # This prevents the HTTP stream from failing and allows the client to get a response
-            return ListPromptsResult(prompts=[])  # mutable-ok: MCP result payload
-        finally:
-            active_mcp_session_var.reset(_session_reset_token)
-            active_mcp_request_ctx_var.reset(_ctx_reset_token)
+            async with _legacy_operation_context(ctx, trace=False) as context:
+                return await operations.GatewayOperations(_capture_host_progress_callback(ctx)).execute(
+                    ListPromptsRequest(params=params), context
+                )
+        except Exception as exc:  # noqa: BLE001  # preserve native listing fallback for ingress failures
+            verbose_logger.exception("Error in list_prompts endpoint: %s", exc)
+            return ListPromptsResult(prompts=[])
 
     async def get_prompt(ctx: ServerRequestContext, params: GetPromptRequestParams) -> GetPromptResult:
-        """
-        Get a specific prompt with the provided arguments
-        """
         if _mcp_proxy_mode.get():
             _reject_mcp_proxy_operation()
-        _ctx_reset_token: Final = active_mcp_request_ctx_var.set(ctx)
-        _session_reset_token: Final = active_mcp_session_var.set(ctx.session)
-
-        try:
-            (
-                user_api_key_auth,
-                mcp_auth_header,
-                mcp_servers,
-                mcp_server_auth_headers,
-                oauth2_headers,
-                raw_headers,
-                _client_ip,
-            ) = await get_or_extract_auth_context()
-
-            verbose_logger.debug("MCP mcp_server_tool_call - User API Key Auth from context: %s", user_api_key_auth)
-            return await mcp_get_prompt(
-                name=params.name,
-                arguments=params.arguments,
-                user_api_key_auth=user_api_key_auth,
-                mcp_auth_header=mcp_auth_header,
-                mcp_servers=mcp_servers,
-                mcp_server_auth_headers=mcp_server_auth_headers,
-                oauth2_headers=oauth2_headers,
-                raw_headers=raw_headers,
+        async with _legacy_operation_context(ctx, trace=False) as context:
+            return await operations.GatewayOperations(_capture_host_progress_callback(ctx)).execute(
+                GetPromptRequest(params=params), context
             )
-        finally:
-            active_mcp_session_var.reset(_session_reset_token)
-            active_mcp_request_ctx_var.reset(_ctx_reset_token)
 
     async def list_resources(ctx: ServerRequestContext, params: PaginatedRequestParams) -> ListResourcesResult:
-        """List all available resources."""
         if _mcp_proxy_mode.get():
             _reject_mcp_proxy_operation()
-        _ctx_reset_token: Final = active_mcp_request_ctx_var.set(ctx)
-        _session_reset_token: Final = active_mcp_session_var.set(ctx.session)
-
         try:
-            (
-                user_api_key_auth,
-                mcp_auth_header,
-                mcp_servers,
-                mcp_server_auth_headers,
-                oauth2_headers,
-                raw_headers,
-                _client_ip,
-            ) = await get_or_extract_auth_context()
-            verbose_logger.debug("MCP list_resources - User API Key Auth from context: %s", user_api_key_auth)
-            verbose_logger.debug("MCP list_resources - MCP servers from context: %s", mcp_servers)
-            verbose_logger.debug(
-                "MCP list_resources - MCP server auth headers: %s",
-                list(mcp_server_auth_headers.keys()) if mcp_server_auth_headers else None,
-            )
-
-            resources: Final = await _list_mcp_resources(
-                user_api_key_auth=user_api_key_auth,
-                mcp_auth_header=mcp_auth_header,
-                mcp_servers=mcp_servers,
-                mcp_server_auth_headers=mcp_server_auth_headers,
-                oauth2_headers=oauth2_headers,
-                raw_headers=raw_headers,
-            )
-            verbose_logger.info("MCP list_resources - Successfully returned %s resources", len(resources))
-            return ListResourcesResult(resources=resources)
-        except Exception as e:
-            verbose_logger.exception("Error in list_resources endpoint: %s", e)
-            return ListResourcesResult(resources=[])  # mutable-ok: MCP result payload
-        finally:
-            active_mcp_session_var.reset(_session_reset_token)
-            active_mcp_request_ctx_var.reset(_ctx_reset_token)
+            async with _legacy_operation_context(ctx, trace=False) as context:
+                return await operations.GatewayOperations(_capture_host_progress_callback(ctx)).execute(
+                    ListResourcesRequest(params=params), context
+                )
+        except Exception as exc:  # noqa: BLE001  # preserve native listing fallback for ingress failures
+            verbose_logger.exception("Error in list_resources endpoint: %s", exc)
+            return ListResourcesResult(resources=[])
 
     async def list_resource_templates(
         ctx: ServerRequestContext, params: PaginatedRequestParams
     ) -> ListResourceTemplatesResult:
-        """List all available resource templates."""
         if _mcp_proxy_mode.get():
             _reject_mcp_proxy_operation()
-        _ctx_reset_token: Final = active_mcp_request_ctx_var.set(ctx)
-        _session_reset_token: Final = active_mcp_session_var.set(ctx.session)
-
         try:
-            (
-                user_api_key_auth,
-                mcp_auth_header,
-                mcp_servers,
-                mcp_server_auth_headers,
-                oauth2_headers,
-                raw_headers,
-                _client_ip,
-            ) = await get_or_extract_auth_context()
-            verbose_logger.debug("MCP list_resource_templates - User API Key Auth from context: %s", user_api_key_auth)
-            verbose_logger.debug("MCP list_resource_templates - MCP servers from context: %s", mcp_servers)
-            verbose_logger.debug(
-                "MCP list_resource_templates - MCP server auth headers: %s",
-                list(mcp_server_auth_headers.keys()) if mcp_server_auth_headers else None,
-            )
-
-            resource_templates: Final = await _list_mcp_resource_templates(
-                user_api_key_auth=user_api_key_auth,
-                mcp_auth_header=mcp_auth_header,
-                mcp_servers=mcp_servers,
-                mcp_server_auth_headers=mcp_server_auth_headers,
-                oauth2_headers=oauth2_headers,
-                raw_headers=raw_headers,
-            )
-            verbose_logger.info(
-                "MCP list_resource_templates - Successfully returned %s resource templates", len(resource_templates)
-            )
-            return ListResourceTemplatesResult(resource_templates=resource_templates)
-        except Exception as e:
-            verbose_logger.exception("Error in list_resource_templates endpoint: %s", e)
-            return ListResourceTemplatesResult(resource_templates=[])  # mutable-ok: MCP result payload
-        finally:
-            active_mcp_session_var.reset(_session_reset_token)
-            active_mcp_request_ctx_var.reset(_ctx_reset_token)
+            async with _legacy_operation_context(ctx, trace=False) as context:
+                return await operations.GatewayOperations(_capture_host_progress_callback(ctx)).execute(
+                    ListResourceTemplatesRequest(params=params), context
+                )
+        except Exception as exc:  # noqa: BLE001  # preserve native listing fallback for ingress failures
+            verbose_logger.exception("Error in list_resource_templates endpoint: %s", exc)
+            return ListResourceTemplatesResult(resource_templates=[])
 
     async def read_resource(ctx: ServerRequestContext, params: ReadResourceRequestParams) -> ReadResourceResult:
         if _mcp_proxy_mode.get():
             _reject_mcp_proxy_operation()
-        _ctx_reset_token: Final = active_mcp_request_ctx_var.set(ctx)
-        _session_reset_token: Final = active_mcp_session_var.set(ctx.session)
-
-        try:
-            (
-                user_api_key_auth,
-                mcp_auth_header,
-                mcp_servers,
-                mcp_server_auth_headers,
-                oauth2_headers,
-                raw_headers,
-                _client_ip,
-            ) = await get_or_extract_auth_context()
-
-            read_resource_result: Final = await mcp_read_resource(
-                url=params.uri,
-                user_api_key_auth=user_api_key_auth,
-                mcp_auth_header=mcp_auth_header,
-                mcp_servers=mcp_servers,
-                mcp_server_auth_headers=mcp_server_auth_headers,
-                oauth2_headers=oauth2_headers,
-                raw_headers=raw_headers,
+        async with _legacy_operation_context(ctx, trace=False) as context:
+            return await operations.GatewayOperations(_capture_host_progress_callback(ctx)).execute(
+                ReadResourceRequest(params=params), context
             )
 
-            return read_resource_result
-        finally:
-            active_mcp_session_var.reset(_session_reset_token)
-            active_mcp_request_ctx_var.reset(_ctx_reset_token)
-
     server.add_request_handler("tools/list", PaginatedRequestParams, handle_list_tools)
     server.add_request_handler("tools/call", CallToolRequestParams, mcp_server_tool_call)
     server.add_request_handler("prompts/list", PaginatedRequestParams, list_prompts)
@@ -1533,527 +954,24 @@ if MCP_AVAILABLE:
     ############ Helper Functions ##########################
     ########################################################
 
-    async def _get_allowed_mcp_servers_from_mcp_server_names(
-        mcp_servers: Sequence[str] | None,
-        allowed_mcp_servers: list[MCPServer],
-    ) -> list[MCPServer]:
-        """
-        Get the filtered MCP servers from the MCP server names.
-
-        Fails closed when ``mcp_servers`` is explicitly provided (path- or
-        header-derived) but none of the names resolve to a server alias or
-        access group the caller can access. The previous behavior returned
-        the full ``allowed_mcp_servers`` set, which silently widened scope
-        when a client targeted ``/mcp/<unknown>/`` and made URL/header
-        namespacing appear to work when it did not.
-        """
-
-        filtered_server: Final[dict[str, MCPServer]] = {}
-        # Filter servers based on mcp_servers parameter if provided
-        if mcp_servers is not None:
-            for server_or_group in mcp_servers:
-                server_name_matched = False
-
-                for server in allowed_mcp_servers:
-                    if server and _server_answers_to(server, server_or_group):
-                        filtered_server[server.server_id] = server
-                        server_name_matched = True
-                        break
-
-                if not server_name_matched:
-                    try:
-                        access_group_server_ids = await MCPRequestHandler._get_mcp_servers_from_access_groups(
-                            [server_or_group]
-                        )
-                        # Only include servers that the user has access to
-                        for server_id in access_group_server_ids:
-                            for server in allowed_mcp_servers:
-                                if server_id == server.server_id:
-                                    filtered_server[server.server_id] = server
-                    except Exception as e:
-                        verbose_logger.debug("Could not resolve '%s' as access group: %s", server_or_group, e)
-
-        if filtered_server:
-            return list(filtered_server.values())
-
-        if mcp_servers is not None:
-            # Caller asked for a specific scope but nothing resolved. Fail
-            # closed so URL/header namespacing cannot silently fall back to
-            # the caller's full allowed-server set.
-            verbose_logger.debug(
-                "MCP scope filter resolved to no servers for requested names %s; returning empty list (fail-closed).",
-                mcp_servers,
-            )
-            return []
-
-        return allowed_mcp_servers
-
-    def _http_detail_message(detail: object) -> str:
-        return str(detail.get("error")) if isinstance(detail, dict) and detail.get("error") else str(detail)
-
-    def _server_answers_to(server: MCPServer, name: str) -> bool:
-        requested: Final = name.lower()
-        return any(requested == known.lower() for known in iter_known_server_prefixes(server) if known)
-
-    class _McpDeniedDetail(TypedDict):
-        error: ReadOnly[str]
-
-    async def raise_denied_scoped_mcp_access(
-        requested_names: Sequence[str],
-        user_api_key_auth: UserAPIKeyAuth | None,
-        client_ip: str | None = None,
-    ) -> None:
-        """A scoped request (``/mcp/<name>`` path or ``x-mcp-servers`` header) resolved to zero
-        allowed servers, so the denial must be loud: a silent 200 with no tools reads as a healthy
-        server with no tools. Unknown, unauthorized, and access-group names all share one generic
-        error so scoping cannot probe which servers exist; the agent variant fires only when the
-        same request resolves once the agent binding is stripped, proving the binding caused the veto."""
-        agent_id: Final = user_api_key_auth.agent_id if user_api_key_auth else None
-        if user_api_key_auth is not None and agent_id:
-            resolved_without_agent: Final = await _get_allowed_mcp_servers(
-                user_api_key_auth=user_api_key_auth.model_copy(update=types.MappingProxyType({"agent_id": None})),
-                mcp_servers=requested_names,
-                client_ip=client_ip,
-            )
-
-            def _resolved_to_server(name: str) -> bool:
-                return any(_server_answers_to(server, name) for server in resolved_without_agent)
-
-            vetoed_server: Final = next((name for name in requested_names if _resolved_to_server(name)), None)
-            if vetoed_server is not None:
-                agent_denial: Final[_McpDeniedDetail] = {
-                    "error": (
-                        f"MCP server '{vetoed_server}' is not available to this key: the key is bound to "
-                        f"agent '{agent_id}', whose MCP grants do not include this server. Add the server "
-                        f"to the agent's object_permission.mcp_servers (edit the agent in the Admin UI or "
-                        f"PATCH /v1/agents/{agent_id}), or use a key that is not bound to the agent."
-                    )
-                }
-                raise HTTPException(status_code=403, detail=agent_denial)
-            vetoed_group: Final = next(
-                (
-                    name
-                    for name in requested_names
-                    if not _resolved_to_server(name)
-                    and any(name in (server.access_groups or ()) for server in resolved_without_agent)
-                ),
-                None,
-            )
-            if vetoed_group is not None:
-                group_denial: Final[_McpDeniedDetail] = {
-                    "error": (
-                        f"MCP access group '{vetoed_group}' is not available to this key: the key is bound to "
-                        f"agent '{agent_id}', whose MCP grants do not include it. Add the group to the "
-                        f"agent's object_permission.mcp_access_groups (edit the agent in the Admin UI or "
-                        f"PATCH /v1/agents/{agent_id}), or use a key that is not bound to the agent."
-                    )
-                }
-                raise HTTPException(status_code=403, detail=group_denial)
-        generic_denial: Final[_McpDeniedDetail] = {
-            "error": f"The key is not allowed to access the requested MCP servers: {', '.join(requested_names)}"
-        }
-        raise HTTPException(status_code=403, detail=generic_denial)
-
-    def _tool_name_matches(tool_name: str, filter_list: list[str], mcp_server: MCPServer) -> bool:
-        """
-        Check if a tool name matches any name in the filter list.
-
-        Reads the same owner the server-level permission checks use, so discovery hides
-        exactly what dispatch refuses. ``mcp_server`` is required: guessing the boundary
-        at the first separator mismatches every tool on a server whose prefix contains
-        the separator.
-        """
-        bare_name: Final = strip_known_server_prefix(tool_name, mcp_server)
-        return match_known_tool_name(bare_name, mcp_server, filter_list) is not None
-
-    def filter_tools_by_allowed_tools(
-        tools: list[MCPTool],
-        mcp_server: MCPServer,
-    ) -> list[MCPTool]:
-        """
-        Filter tools by allowed/disallowed tools configuration.
-
-        If allowed_tools is set, only tools in that list are returned.
-        If disallowed_tools is set, tools in that list are excluded.
-        Tool names are matched with and without server prefixes for flexibility.
-
-        Args:
-            tools: List of tools to filter
-            mcp_server: Server configuration with allowed_tools/disallowed_tools
-
-        Returns:
-            Filtered list of tools
-        """
-        from litellm.proxy._experimental.mcp_server.utils import (
-            server_applies_tool_allowlist,
-        )
-
-        tools_to_return = tools
-
-        # Filter by allowed_tools (whitelist)
-        if server_applies_tool_allowlist(mcp_server):
-            if not mcp_server.allowed_tools:
-                return []
-            tools_to_return = [
-                tool for tool in tools if _tool_name_matches(tool.name, mcp_server.allowed_tools, mcp_server)
-            ]
-
-        # Filter by disallowed_tools (blacklist)
-        if mcp_server.disallowed_tools:
-            tools_to_return = [
-                tool
-                for tool in tools_to_return
-                if not _tool_name_matches(tool.name, mcp_server.disallowed_tools, mcp_server)
-            ]
-
-        return tools_to_return
-
-    def apply_tool_overrides(
-        tools: list[MCPTool],
-        mcp_server: MCPServer,
-    ) -> list[MCPTool]:
-        """Apply admin-configured display name/description overrides to tools.
-
-        Overrides are keyed by the unprefixed tool name, same convention as
-        allowed_tools configuration.
-        """
-        display_name_map: Final = mcp_server.tool_name_to_display_name or {}
-        description_map: Final = mcp_server.tool_name_to_description or {}
-        if not display_name_map and not description_map:
-            return tools
-
-        for tool in tools:
-            unprefixed = strip_known_server_prefix(tool.name, mcp_server)
-            lookup_key = unprefixed or tool.name
-            if lookup_key in display_name_map:
-                tool.name = display_name_map[lookup_key]
-            if lookup_key in description_map:
-                tool.description = description_map[lookup_key]
-        return tools
-
-    def _get_client_ip_from_context() -> str | None:
-        """
-        Extract client_ip from auth context.
-        Returns None if context not set (caller should handle this as "no IP filtering").
-        """
-        try:
-            auth_user: Final = auth_context_var.get()
-            if auth_user and isinstance(auth_user, MCPAuthenticatedUser):
-                return auth_user.client_ip
-        except Exception:
-            pass
-        return None
-
-    async def _get_allowed_mcp_servers(
-        user_api_key_auth: UserAPIKeyAuth | None,
-        mcp_servers: Sequence[str] | None,
-        client_ip: str | None = None,
-    ) -> list[MCPServer]:
-        """Return allowed MCP servers for a request after applying filters.
-
-        Args:
-            user_api_key_auth: The authenticated user's API key info.
-            mcp_servers: Optional list of server names to filter to.
-            client_ip: Client IP for IP-based access control. If None, falls back to
-                      auth context. Pass explicitly from request handlers for safety.
-        Note: If client_ip is None and auth context is not set, IP filtering is skipped.
-              This is intentional for internal callers but may indicate a bug if called
-              from a request handler without proper context setup.
-        """
-        # Use explicit client_ip if provided, otherwise try auth context
-        if client_ip is None:
-            client_ip = _get_client_ip_from_context()
-            if client_ip is None:
-                verbose_logger.debug(
-                    "MCP _get_allowed_mcp_servers called without client_ip and no auth context. "
-                    "IP filtering will be skipped. This is expected for internal calls."
-                )
-
-        allowed_mcp_server_ids = await global_mcp_server_manager.get_allowed_mcp_servers(user_api_key_auth)
-        (
-            allowed_mcp_server_ids,
-            _ip_blocked,
-        ) = global_mcp_server_manager.filter_server_ids_by_ip_with_info(allowed_mcp_server_ids, client_ip)
-        verbose_logger.debug(
-            "MCP IP filter: client_ip=%s, allowed_server_ids=%s",
-            client_ip,
-            allowed_mcp_server_ids,
-        )
-        if _ip_blocked > 0:
-            verbose_logger.debug(
-                "MCP IP filtering: %d server(s) are not accessible from client IP %s "
-                "because they are restricted to internal networks. "
-                "No tools from those servers will be returned. "
-                "To expose a server externally, set 'available_on_public_internet: true' "
-                "in its configuration.",
-                _ip_blocked,
-                client_ip,
-            )
-        allowed_mcp_servers: list[MCPServer] = []
-        for allowed_mcp_server_id in allowed_mcp_server_ids:
-            mcp_server = global_mcp_server_manager.get_mcp_server_by_id(allowed_mcp_server_id)
-            if mcp_server is not None:
-                # Apply the request-time oauth2_flow backstop for legacy null rows.
-                mcp_server = MCPServerManager.resolve_oauth2_flow_for_request(mcp_server)
-                allowed_mcp_servers.append(mcp_server)
-
-        if mcp_servers is not None:
-            allowed_mcp_servers = await _get_allowed_mcp_servers_from_mcp_server_names(
-                mcp_servers=mcp_servers,
-                allowed_mcp_servers=allowed_mcp_servers,
-            )
-
-        return allowed_mcp_servers
-
-    def _client_has_per_server_auth_header(
-        server: MCPServer,
-        mcp_server_auth_headers: dict[str, dict[str, str]] | None,
-    ) -> bool:
-        """True if the request carries a per-server ``x-mcp-{alias}-authorization``
-        header for this server. This is the multi-server binding: it names one
-        upstream, so it is unambiguously the caller's upstream token regardless of
-        auth mode (never the LiteLLM admission credential).
-
-        Resolves through the same ``lookup_mcp_server_auth_in_headers`` egress uses, so
-        the connect gate and egress agree on which per-server header names match: a
-        dashboard client sends ``x-mcp-{sanitize_mcp_alias_for_header(alias)}-authorization``,
-        and matching only the raw alias here would 401 a token egress would forward.
-        """
-        if not mcp_server_auth_headers:
-            return False
-        from litellm.proxy._experimental.mcp_server.utils import (
-            lookup_mcp_server_auth_in_headers,
-        )
-
-        server_headers: Final = lookup_mcp_server_auth_in_headers(
-            mcp_server_auth_headers,
-            alias=server.alias,
-            server_name=server.server_name,
-            access_groups=server.access_groups,
-        )
-        if isinstance(server_headers, str):
-            return bool(server_headers.strip())
-        if isinstance(server_headers, dict):
-            return any(isinstance(hk, str) and hk.lower() == "authorization" for hk in server_headers)
-        return False
-
-    def _client_has_passthrough_authorization(
-        server: MCPServer,
-        oauth2_headers: dict[str, str] | None,
-        mcp_server_auth_headers: dict[str, dict[str, str]] | None,
-    ) -> bool:
-        """True if the incoming request already carries an ``Authorization``
-        header the gateway will forward to this pass-through server.
-
-        The client may supply the bearer as either the top-level
-        ``Authorization`` header (surfaced via ``oauth2_headers``) or a
-        per-server ``x-mcp-auth-<alias>`` style header (surfaced via
-        ``mcp_server_auth_headers``). Either form skips the pre-emptive 401.
-        """
-        if oauth2_headers:
-            for k in oauth2_headers:
-                if k.lower() == "authorization":
-                    return True
-        return _client_has_per_server_auth_header(server, mcp_server_auth_headers)
-
-    async def _get_user_oauth_extra_headers_from_db(
-        server: MCPServer,
-        user_api_key_auth: UserAPIKeyAuth | None,
-        prefetched_creds: 'Mapping[str, "OAuthCredentialPayload"] | None' = None,
-    ) -> dict[str, str] | None:
-        """Stored OAuth2 token for (user, server) as an ``Authorization: Bearer`` header, or None.
-
-        Thin wrapper over ``resolve_user_oauth_access_token`` (Redis cache, else DB + refresh);
-        ``prefetched_creds`` skips the per-server Redis/DB lookups for the batch path.
-        """
-        if server.auth_type != MCPAuth.oauth2 or user_api_key_auth is None:
-            return None
-        from litellm.proxy._experimental.mcp_server.db import (  # noqa: PLC0415
-            resolve_user_oauth_access_token,
-        )
-
-        token: Final = await resolve_user_oauth_access_token(
-            getattr(user_api_key_auth, "user_id", None), server, prefetched_creds
-        )
-        return {"Authorization": f"Bearer {token}"} if token else None
-
-    async def _prefetch_oauth_creds_for_user(
-        user_api_key_auth: UserAPIKeyAuth | None,
-    ) -> dict[str, "OAuthCredentialPayload"]:
-        """Fetch all OAuth2 credentials for the user in one DB query.
-
-        Returns a dict keyed by server_id to avoid N+1 queries in asyncio.gather loops.
-        """
-        user_id: Final[str | None] = getattr(user_api_key_auth, "user_id", None) if user_api_key_auth else None
-        if not user_id:
-            return {}
-        try:
-            from litellm.proxy._experimental.mcp_server.db import (  # noqa: PLC0415
-                list_user_oauth_credentials,
-            )
-            from litellm.proxy.utils import get_prisma_client_or_throw  # noqa: PLC0415
-
-            prisma_client: Final = get_prisma_client_or_throw(
-                "Database not connected. Connect a database to use OAuth2 MCP tools."
-            )
-            creds: Final = await list_user_oauth_credentials(prisma_client, user_id)
-            return {c["server_id"]: c for c in creds if "server_id" in c}
-        except Exception as e:
-            verbose_logger.warning("_prefetch_oauth_creds_for_user: failed to prefetch for user=%s: %s", user_id, e)
-            return {}
-
-    def _prepare_mcp_server_headers(
-        server: MCPServer,
-        mcp_server_auth_headers: dict[str, dict[str, str]] | None,
-        mcp_auth_header: str | None,
-        oauth2_headers: dict[str, str] | None,
-        raw_headers: dict[str, str] | None,
-        user_api_key_auth: UserAPIKeyAuth | None = None,
-        scope_servers: list[MCPServer] | None = None,
-    ) -> tuple[dict[str, str] | str | None, dict[str, str] | None]:
-        """Build auth and extra headers for a server.
-
-        ``scope_servers`` is the full server list a fan-out handler iterates. Passing it lets the
-        client-forwarded token modes withhold the caller's request-wide ``Authorization`` when
-        another server in the scope would also receive it (``_caller_authorization_fans_out``);
-        explicitly-addressed operations leave it None. Per-server ``x-mcp-{alias}-authorization``
-        headers are unaffected — they bind one token to one server and are the multi-server shape.
-        """
-        server_auth_header: dict[str, str] | str | None = None
-        if mcp_server_auth_headers:
-            from litellm.proxy._experimental.mcp_server.utils import (
-                lookup_mcp_server_auth_in_headers,
-            )
-
-            server_auth_header = lookup_mcp_server_auth_in_headers(
-                mcp_server_auth_headers,
-                alias=server.alias,
-                server_name=server.server_name,
-                access_groups=server.access_groups,
-            )
-
-        extra_headers: dict[str, str] | None = None
-        is_client_forwarded_mode: Final = server.is_client_forwarded_token
-        # In a multi-server listing scope the request-wide Authorization can only carry one token,
-        # so it is withheld from a client-forwarded server when another server in scope also consumes
-        # it (RFC 9700 cross-resource replay); such scopes must bind per-server via
-        # x-mcp-{alias}-authorization. The decision is computed once so BOTH the forwarding branch and
-        # the extra_headers copy loop below honor it — otherwise a server that lists Authorization in
-        # extra_headers would re-copy the withheld bearer from raw_headers and replay it anyway.
-        withhold_forwarded_authorization: Final = is_client_forwarded_mode and _caller_authorization_fans_out(
-            server, scope_servers
-        )
-        if server.auth_type == MCPAuth.oauth2:
-            # For OAuth2 M2M servers, upstream Authorization must come from
-            # client_credentials token fetch, never from caller headers.
-            if server.has_client_credentials:
-                extra_headers = None
-            else:
-                # Copy to avoid mutating the original dict (important for parallel fetching)
-                extra_headers = oauth2_headers.copy() if oauth2_headers else None
-                # Migrated authorization_code: the v2 resolver injects the stored per-user
-                # token, so drop the caller-forwarded Authorization (apply-if-absent would
-                # otherwise let it shadow the resolved token). Delegate keeps it. Centralized
-                # via _should_strip_caller_authorization to match _call_regular_mcp_tool.
-                if extra_headers and _should_strip_caller_authorization(
-                    mcp_server=server,
-                    raw_headers=raw_headers,
-                    user_api_key_auth=user_api_key_auth,
-                ):
-                    extra_headers = without_header(extra_headers, DEFAULT_CREDENTIAL_HEADER)
-        elif is_client_forwarded_mode:
-            if not withhold_forwarded_authorization:
-                extra_headers = _client_forwarded_authorization_headers(
-                    mcp_server=server,
-                    oauth2_headers=oauth2_headers,
-                    raw_headers=raw_headers,
-                    user_api_key_auth=user_api_key_auth,
-                )
-
-        if server.extra_headers and raw_headers:
-            if extra_headers is None:
-                extra_headers = {}
-
-            normalized_raw_headers: Final = {str(k).lower(): v for k, v in raw_headers.items() if isinstance(k, str)}
-
-            # Centralized strip decision shared with
-            # ``MCPServerManager._call_regular_mcp_tool`` so the two
-            # code paths cannot drift on this security-sensitive choice.
-            # See ``_should_strip_caller_authorization`` for the rules.
-            strip_caller_authorization: Final = _should_strip_caller_authorization(
-                mcp_server=server,
-                raw_headers=raw_headers,
-                user_api_key_auth=user_api_key_auth,
-            )
-
-            for header in server.extra_headers:
-                if not isinstance(header, str):
-                    continue
-                if header.lower() == "authorization" and (
-                    strip_caller_authorization or withhold_forwarded_authorization
-                ):
-                    continue
-                header_value = normalized_raw_headers.get(header.lower())
-                if header_value is None:
-                    continue
-                extra_headers[header] = header_value
-
-        # Reset to None if no headers were actually added
-        if extra_headers is not None and len(extra_headers) == 0:
-            extra_headers = None
-
-        if server_auth_header is None:
-            server_auth_header = mcp_auth_header
-
-        return server_auth_header, extra_headers
-
-    def _merge_gateway_initialize_instructions(
-        allowed_mcp_servers: list[MCPServer],
-    ) -> str | None:
-        """YAML/DB override, else upstream text (prefetch on init, or list_tools / health_check / call_tool cache)."""
-        if not allowed_mcp_servers:
-            return None
-
-        texts: Final[list[tuple[str, str]]] = []
-        for server in allowed_mcp_servers:
-            label = server.alias or server.server_name or server.name or server.server_id or "mcp"
-            if server.instructions and server.instructions.strip():
-                texts.append((label, server.instructions.strip()))
-                continue
-            if server.spec_path:
-                continue
-            cached = global_mcp_server_manager._upstream_initialize_instructions_by_server_id.get(server.server_id)
-            if cached and cached.strip():
-                texts.append((label, cached.strip()))
-
-        if not texts:
-            return None
-        if len(texts) == 1:
-            return texts[0][1]
-        return "\n\n---\n\n".join(f"[{lbl}]\n{txt}" for lbl, txt in texts)
-
-    async def _raise_if_initialize_grants_no_mcp_servers(
-        allowed: Sequence[MCPServer],
-        user_api_key_auth: UserAPIKeyAuth | None,
-        mcp_servers: Sequence[str] | None,
-        client_ip: str | None,
-    ) -> None:
-        if allowed or user_api_key_auth is None or not user_api_key_auth.api_key:
-            return
-        if mcp_servers:
-            await raise_denied_scoped_mcp_access(
-                requested_names=mcp_servers,
-                user_api_key_auth=user_api_key_auth,
-                client_ip=client_ip,
-            )
-        no_servers_denial: Final[_McpDeniedDetail] = {
-            "error": (
-                "The key has no MCP servers granted, or none of its granted servers is loaded and allowed for "
-                "this client IP. Grant servers or access groups to the key, its team, or its organization "
-                "(object_permission.mcp_servers), check the server's allowed IPs, and reconnect."
-            )
-        }
-        raise HTTPException(status_code=403, detail=no_servers_denial)
+    from litellm.proxy._experimental.mcp_server.operations import (
+        _client_has_passthrough_authorization,
+        _client_has_per_server_auth_header,
+        _get_allowed_mcp_servers,
+        _get_allowed_mcp_servers_from_mcp_server_names,
+        _get_user_oauth_extra_headers_from_db,
+        _http_detail_message,
+        _McpDeniedDetail,
+        _merge_gateway_initialize_instructions,
+        _prefetch_oauth_creds_for_user,
+        _prepare_mcp_server_headers,
+        _raise_if_initialize_grants_no_mcp_servers,
+        _server_answers_to,
+        _tool_name_matches,
+        apply_tool_overrides,
+        filter_tools_by_allowed_tools,
+        raise_denied_scoped_mcp_access,
+    )
 
     @contextlib.asynccontextmanager
     async def _gateway_initialize_instructions_request_scope(
@@ -2063,26 +981,28 @@ if MCP_AVAILABLE:
         scoped_server_endpoint: bool = False,
         is_initialize: bool = False,
     ) -> AsyncIterator[None]:
-        allowed: Final = await _get_allowed_mcp_servers(
+        allowed: Final = await operations._get_allowed_mcp_servers(
             user_api_key_auth=user_api_key_auth,
             mcp_servers=mcp_servers,
             client_ip=client_ip,
         )
         if is_initialize:
-            await _raise_if_initialize_grants_no_mcp_servers(allowed, user_api_key_auth, mcp_servers, client_ip)
+            await operations._raise_if_initialize_grants_no_mcp_servers(
+                allowed, user_api_key_auth, mcp_servers, client_ip
+            )
         if allowed:
             # return_exceptions=True: a per-server probe failure (incl. CancelledError
             # bubbled from anyio task group teardown on connection refused) must not
             # cancel sibling probes or 500 the gateway initialize request.
             await asyncio.gather(
                 *[
-                    global_mcp_server_manager._ensure_upstream_initialize_instructions_cached(s)
+                    operations.global_mcp_server_manager._ensure_upstream_initialize_instructions_cached(s)
                     for s in allowed
                     if s is not None
                 ],
                 return_exceptions=True,
             )
-        merged: Final = _merge_gateway_initialize_instructions(allowed_mcp_servers=allowed)
+        merged: Final = operations._merge_gateway_initialize_instructions(allowed_mcp_servers=allowed)
         scoped_server_name = None
         if scoped_server_endpoint and len(allowed) == 1:
             scoped_server: Final = allowed[0]
@@ -2097,1599 +1017,34 @@ if MCP_AVAILABLE:
             _mcp_gateway_initialize_instructions.reset(instructions_token)
             _mcp_gateway_server_name.reset(server_name_token)
 
-    def _aggregate_server_key(server: MCPServer) -> str:
-        """The client-visible key for a server in listing outcomes and spend metadata: the same
-        display prefix (alias, or the short prefix when that mode is enabled) the caller already
-        sees on the tool names. Canonical internal server names never key a caller-readable
-        surface; when the display naming deliberately hides them, the outcome keys must too."""
-        return get_server_prefix(server) or "unknown"
-
-    async def _get_tools_from_mcp_servers(
-        user_api_key_auth: UserAPIKeyAuth | None,
-        mcp_auth_header: str | None,
-        mcp_servers: list[str] | None,
-        mcp_server_auth_headers: dict[str, dict[str, str]] | None = None,
-        oauth2_headers: dict[str, str] | None = None,
-        raw_headers: dict[str, str] | None = None,
-        log_list_tools_to_spendlogs: bool = False,
-        list_tools_log_source: str | None = None,
-        litellm_trace_id: str | None = None,
-        request_tags: list[str] | None = None,
-        client_ip: str | None = None,
-        mcp_proxy_mode: bool = False,
-    ) -> AggregateToolListing:
-        """
-        Helper method to fetch tools from MCP servers based on server filtering criteria.
-
-        Args:
-            user_api_key_auth: User authentication info for access control
-            mcp_auth_header: Optional auth header for MCP server (deprecated)
-            mcp_servers: Optional list of server names/aliases to filter by
-            mcp_server_auth_headers: Optional dict of server-specific auth headers
-            oauth2_headers: Optional dict of oauth2 headers
-
-        Returns:
-            AggregateToolListing: Combined tools from filtered servers plus each server's
-            classified listing outcome
-        """
-        if not MCP_AVAILABLE:
-            return AggregateToolListing(tools=[], outcomes={})
-
-        list_tools_start_time: Final = datetime.now()
-        litellm_logging_obj: LiteLLMLoggingObj | None = None
-        list_tools_request_data: dict[str, object] = {}
-
-        if log_list_tools_to_spendlogs:
-            # This is intentionally minimal: only async_success_handler / post_call_failure_hook
-            rules_obj: Final = Rules()
-            list_tools_call_id: Final = str(uuid.uuid4())
-            # Derive trace_id from raw_headers when not explicitly passed (same as A2A / MCP call_tool)
-            effective_litellm_trace_id: Final = litellm_trace_id or get_chain_id_from_headers(raw_headers)
-            spend_logs_metadata: Final[dict[str, object]] = {
-                "mcp_operation": "list_tools",
-            }
-            if isinstance(list_tools_log_source, str):
-                spend_logs_metadata["source"] = list_tools_log_source
-            if isinstance(mcp_servers, list):
-                spend_logs_metadata["requested_mcp_servers"] = mcp_servers
-
-            list_tools_request_data = {
-                "model": "MCP: list_tools",
-                "call_type": CallTypes.list_mcp_tools.value,
-                "litellm_call_id": list_tools_call_id,
-                "litellm_trace_id": effective_litellm_trace_id,
-                "metadata": {
-                    "spend_logs_metadata": spend_logs_metadata,
-                    "headers": logging_safe_mcp_headers(raw_headers),
-                    **({"tags": request_tags} if request_tags else {}),
-                },
-                # Provide a small input payload for standard logging
-                "input": [
-                    {
-                        "role": "system",
-                        "content": {
-                            "mcp_operation": "list_tools",
-                            "requested_mcp_servers": mcp_servers,
-                        },
-                    }
-                ],
-            }
-
-            # Attach user identifiers using the standard helper
-            if user_api_key_auth is not None:
-                LiteLLMProxyRequestSetup.add_user_api_key_auth_to_request_metadata(
-                    data=list_tools_request_data,
-                    user_api_key_dict=user_api_key_auth,
-                    _metadata_variable_name="metadata",
-                )
-
-                user_identifier: Final = getattr(user_api_key_auth, "end_user_id", None) or getattr(
-                    user_api_key_auth, "user_id", None
-                )
-                if user_identifier:
-                    list_tools_request_data["user"] = user_identifier
-
-            try:
-                litellm_logging_obj, _ = function_setup(
-                    original_function="list_mcp_tools",
-                    rules_obj=rules_obj,
-                    start_time=list_tools_start_time,
-                    **list_tools_request_data,
-                )
-                if litellm_logging_obj:
-                    litellm_logging_obj.call_type = CallTypes.list_mcp_tools.value
-                    litellm_logging_obj.model = "MCP: list_tools"
-            except Exception as logging_error:
-                verbose_logger.debug("Failed to initialize logging for MCP list_tools: %s", logging_error)
-                litellm_logging_obj = None
-
-        try:
-            allowed_mcp_servers: Final = await _get_allowed_mcp_servers(
-                user_api_key_auth=user_api_key_auth,
-                mcp_servers=mcp_servers,
-                client_ip=client_ip,
-            )
-            if mcp_servers and not allowed_mcp_servers:
-                await raise_denied_scoped_mcp_access(
-                    requested_names=mcp_servers,
-                    user_api_key_auth=user_api_key_auth,
-                    client_ip=client_ip,
-                )
-
-            # Pre-fetch OAuth credentials only when at least one server uses OAuth2,
-            # to avoid an unnecessary DB round-trip on requests with no OAuth2 MCP servers.
-            _has_oauth2_server = any(getattr(s, "auth_type", None) == MCPAuth.oauth2 for s in allowed_mcp_servers)
-            _prefetched_oauth_creds: Final = (
-                await _prefetch_oauth_creds_for_user(user_api_key_auth) if _has_oauth2_server else {}
-            )
-
-            async def _fetch_and_filter_server_tools(
-                server: MCPServer,
-            ) -> "tuple[list[MCPTool], ServerOutcome]":
-                """Fetch and filter tools from a single server, classifying any failure into that
-                server's outcome so the aggregate can keep serving the healthy subset without a
-                broken server masquerading as an empty one."""
-                if server is None:
-                    return [], ServerListOk(tool_count=0)
-
-                server_auth_header, extra_headers = _prepare_mcp_server_headers(
-                    server=server,
-                    mcp_server_auth_headers=mcp_server_auth_headers,
-                    mcp_auth_header=mcp_auth_header,
-                    oauth2_headers=oauth2_headers,
-                    raw_headers=raw_headers,
-                    user_api_key_auth=user_api_key_auth,
-                    scope_servers=allowed_mcp_servers,
-                )
-
-                # Prefer server-stored per-user OAuth when configured, so a stale
-                # Authorization header from the MCP client cannot override Redis/DB
-                # (same issue as call_tool in mcp_server_manager: VS Code caches tokens).
-                from litellm.proxy._experimental.mcp_server.outbound_credentials.adapter import (  # noqa: PLC0415
-                    to_server_spec,
-                )
-
-                # A server migrated to the v2 resolver gets its token from the resolver at connect
-                # time; building it here would double-resolve and be shadowed by the v2 graft. The
-                # preemptive 401 already challenged a missing token, so one exists for the connect.
-                migrated_to_v2: Final = to_server_spec(server) is not None
-                if (
-                    not migrated_to_v2
-                    and server.auth_type == MCPAuth.oauth2
-                    and getattr(server, "needs_user_oauth_token", False)
-                    and user_api_key_auth is not None
-                ):
-                    db_headers: Final = await _get_user_oauth_extra_headers_from_db(
-                        server,
-                        user_api_key_auth,
-                        prefetched_creds=_prefetched_oauth_creds,
-                    )
-                    if db_headers:
-                        extra_headers = db_headers
-
-                # If still no OAuth2 token, fall back to pre-fetched creds (non-stale-client path)
-                elif not migrated_to_v2 and extra_headers is None and server.auth_type == MCPAuth.oauth2:
-                    extra_headers = await _get_user_oauth_extra_headers_from_db(
-                        server,
-                        user_api_key_auth,
-                        prefetched_creds=_prefetched_oauth_creds,
-                    )
-
-                if server.is_byok and server.auth_type != MCPAuth.oauth2 and server_auth_header is None:
-                    server_auth_header = await _get_byok_credential(server, user_api_key_auth)
-
-                try:
-                    tools: Final = await global_mcp_server_manager._get_tools_from_server(
-                        server=server,
-                        mcp_auth_header=server_auth_header,
-                        extra_headers=extra_headers,
-                        add_prefix=True,  # Always add server prefix
-                        raw_headers=raw_headers,
-                        user_api_key_auth=user_api_key_auth,
-                        oauth2_headers=oauth2_headers,
-                    )
-                    filtered_tools = filter_tools_by_allowed_tools(tools, server)
-
-                    filtered_tools = await filter_tools_by_key_team_permissions(
-                        tools=filtered_tools,
-                        server_id=server.server_id,
-                        user_api_key_auth=user_api_key_auth,
-                    )
-
-                    if mcp_proxy_mode:
-                        from litellm.proxy._experimental.mcp_server.tool_search import with_mcp_proxy_identity
-
-                        filtered_tools = [  # mutable-ok: MCP tool pipeline
-                            with_mcp_proxy_identity(tool, server.server_id) for tool in filtered_tools
-                        ]
-                    else:
-                        filtered_tools = apply_tool_overrides(filtered_tools, server)
-
-                    verbose_logger.debug(
-                        "Successfully fetched %s tools from server %s, %s after filtering",
-                        len(tools),
-                        server.name,
-                        len(filtered_tools),
-                    )
-                    return filtered_tools, ServerListOk(tool_count=len(filtered_tools))
-                except MCPUpstreamAuthError as e:
-                    # Absorb so one unauthenticated server does not empty every other server's
-                    # tools. Surfacing the upstream 401 to the client as a re-auth challenge is
-                    # intentionally not done here: raising from this list handler cannot produce a
-                    # 401 + WWW-Authenticate (the MCP session manager serializes it as a JSON-RPC
-                    # error). Single-server routes surface it via the request-scope preemptive
-                    # check in _raise_preemptive_401_for_unauthenticated_servers instead.
-                    verbose_logger.debug("MCP list_tools: omitting %s; it needs upstream auth", server.name)
-                    return [], classify_list_exception(e)
-                except Exception as e:
-                    verbose_logger.exception("Error getting tools from server %s: %s", server.name, e)
-                    return [], classify_list_exception(e)
-
-            # Fetch tools from all servers in parallel
-            tasks: Final = [_fetch_and_filter_server_tools(server) for server in allowed_mcp_servers]
-            results: Final = await asyncio.gather(*tasks)
-
-            # Flatten results into single list
-            all_tools: Final[list[MCPTool]] = [tool for tools, _ in results for tool in tools]
-            server_outcomes: Final[dict[str, ServerOutcome]] = {
-                _aggregate_server_key(server): outcome
-                for server, (_, outcome) in zip(allowed_mcp_servers, results)
-                if server is not None
-            }
-
-            # If logging is enabled, enrich spend_logs_metadata with counts
-            if litellm_logging_obj:
-                per_server_tool_counts: Final[dict[str, int]] = {
-                    _aggregate_server_key(server): len(server_tools)
-                    for server, (server_tools, _) in zip(allowed_mcp_servers, results)
-                    if server is not None
-                }
-
-                metadata_dict: Final = litellm_logging_obj.model_call_details.get("metadata")
-                if isinstance(metadata_dict, dict):
-                    spend_meta = metadata_dict.get("spend_logs_metadata")
-                    if not isinstance(spend_meta, dict):
-                        spend_meta = {}
-                        metadata_dict["spend_logs_metadata"] = spend_meta
-                    spend_meta["allowed_server_count"] = len(allowed_mcp_servers)
-                    spend_meta["tool_count_total"] = len(all_tools)
-                    spend_meta["per_server_tool_counts"] = per_server_tool_counts
-                    spend_meta["per_server_list_outcomes"] = {
-                        key: outcome_wire_value(outcome) for key, outcome in server_outcomes.items()
-                    }
-
-                end_time: Final = datetime.now()
-                try:
-                    await litellm_logging_obj.async_success_handler(
-                        result=[
-                            tool.model_dump(mode="json") if isinstance(tool, MCPTool) else tool for tool in all_tools
-                        ],
-                        start_time=list_tools_start_time,
-                        end_time=end_time,
-                    )
-                except Exception as log_exc:
-                    # list_tools responses must not be dropped due to non-blocking
-                    # observability/serialization failures.
-                    verbose_logger.warning(
-                        "MCP list_tools success logging failed (continuing): %s",
-                        log_exc,
-                    )
-
-            verbose_logger.info("Successfully fetched %s tools total from all MCP servers", len(all_tools))
-
-            return AggregateToolListing(tools=all_tools, outcomes=server_outcomes)
-        except Exception as e:
-            # Only fire failure hook if logging was requested for this list-tools execution
-            if log_list_tools_to_spendlogs and user_api_key_auth is not None:
-                try:
-                    from litellm.proxy.proxy_server import proxy_logging_obj
-
-                    if proxy_logging_obj:
-                        traceback_str: Final = traceback.format_exc(limit=MAXIMUM_TRACEBACK_LINES_TO_LOG)
-                        await proxy_logging_obj.post_call_failure_hook(
-                            request_data=list_tools_request_data or {},
-                            original_exception=e,
-                            user_api_key_dict=user_api_key_auth,
-                            route="/mcp/list_tools",
-                            traceback_str=traceback_str,
-                        )
-                except Exception:
-                    verbose_logger.debug("Failed to log MCP list_tools failure via post_call_failure_hook")
-            raise
-
-    async def _get_prompts_from_mcp_servers(
-        user_api_key_auth: UserAPIKeyAuth | None,
-        mcp_auth_header: str | None,
-        mcp_servers: list[str] | None,
-        mcp_server_auth_headers: dict[str, dict[str, str]] | None = None,
-        oauth2_headers: dict[str, str] | None = None,
-        raw_headers: dict[str, str] | None = None,
-    ) -> list[Prompt]:
-        """
-        Helper method to fetch prompt from MCP servers based on server filtering criteria.
-
-        Args:
-            user_api_key_auth: User authentication info for access control
-            mcp_auth_header: Optional auth header for MCP server (deprecated)
-            mcp_servers: Optional list of server names/aliases to filter by
-            mcp_server_auth_headers: Optional dict of server-specific auth headers
-            oauth2_headers: Optional dict of oauth2 headers
-
-        Returns:
-            List[Prompt]: Combined list of prompts from filtered servers
-        """
-        if not MCP_AVAILABLE:
-            return []
-
-        allowed_mcp_servers: Final = await _get_allowed_mcp_servers(
-            user_api_key_auth=user_api_key_auth,
-            mcp_servers=mcp_servers,
-        )
-
-        # Get prompts from each allowed server
-        all_prompts: Final = []
-        for server in allowed_mcp_servers:
-            if server is None:
-                continue
-
-            server_auth_header, extra_headers = _prepare_mcp_server_headers(
-                server=server,
-                mcp_server_auth_headers=mcp_server_auth_headers,
-                mcp_auth_header=mcp_auth_header,
-                oauth2_headers=oauth2_headers,
-                raw_headers=raw_headers,
-                user_api_key_auth=user_api_key_auth,
-                scope_servers=allowed_mcp_servers,
-            )
-
-            try:
-                prompts = await global_mcp_server_manager.get_prompts_from_server(
-                    server=server,
-                    user_api_key_auth=user_api_key_auth,
-                    mcp_auth_header=server_auth_header,
-                    extra_headers=extra_headers,
-                    add_prefix=True,  # Always add server prefix
-                    raw_headers=raw_headers,
-                )
-
-                all_prompts.extend(prompts)
-
-                verbose_logger.debug("Successfully fetched %s prompts from server %s", len(prompts), server.name)
-            except Exception as e:
-                verbose_logger.exception("Error getting prompts from server %s: %s", server.name, e)
-                # Continue with other servers instead of failing completely
-
-        verbose_logger.info("Successfully fetched %s prompts total from all MCP servers", len(all_prompts))
-
-        return all_prompts
-
-    async def _get_resources_from_mcp_servers(
-        user_api_key_auth: UserAPIKeyAuth | None,
-        mcp_auth_header: str | None,
-        mcp_servers: list[str] | None,
-        mcp_server_auth_headers: dict[str, dict[str, str]] | None = None,
-        oauth2_headers: dict[str, str] | None = None,
-        raw_headers: dict[str, str] | None = None,
-    ) -> list[Resource]:
-        """Fetch resources from allowed MCP servers."""
-
-        if not MCP_AVAILABLE:
-            return []
-
-        allowed_mcp_servers: Final = await _get_allowed_mcp_servers(
-            user_api_key_auth=user_api_key_auth,
-            mcp_servers=mcp_servers,
-        )
-
-        all_resources: Final[list[Resource]] = []
-        for server in allowed_mcp_servers:
-            if server is None:
-                continue
-
-            server_auth_header, extra_headers = _prepare_mcp_server_headers(
-                server=server,
-                mcp_server_auth_headers=mcp_server_auth_headers,
-                mcp_auth_header=mcp_auth_header,
-                oauth2_headers=oauth2_headers,
-                raw_headers=raw_headers,
-                user_api_key_auth=user_api_key_auth,
-                scope_servers=allowed_mcp_servers,
-            )
-
-            try:
-                resources = await global_mcp_server_manager.get_resources_from_server(
-                    server=server,
-                    user_api_key_auth=user_api_key_auth,
-                    mcp_auth_header=server_auth_header,
-                    extra_headers=extra_headers,
-                    add_prefix=True,  # Always add server prefix
-                    raw_headers=raw_headers,
-                )
-                all_resources.extend(resources)
-
-                verbose_logger.debug("Successfully fetched %s resources from server %s", len(resources), server.name)
-            except Exception as e:
-                verbose_logger.exception("Error getting resources from server %s: %s", server.name, e)
-
-        verbose_logger.info("Successfully fetched %s resources total from all MCP servers", len(all_resources))
-
-        return all_resources
-
-    async def _get_resource_templates_from_mcp_servers(
-        user_api_key_auth: UserAPIKeyAuth | None,
-        mcp_auth_header: str | None,
-        mcp_servers: list[str] | None,
-        mcp_server_auth_headers: dict[str, dict[str, str]] | None = None,
-        oauth2_headers: dict[str, str] | None = None,
-        raw_headers: dict[str, str] | None = None,
-    ) -> list[ResourceTemplate]:
-        """Fetch resource templates from allowed MCP servers."""
-
-        if not MCP_AVAILABLE:
-            return []
-
-        allowed_mcp_servers: Final = await _get_allowed_mcp_servers(
-            user_api_key_auth=user_api_key_auth,
-            mcp_servers=mcp_servers,
-        )
-
-        all_resource_templates: Final[list[ResourceTemplate]] = []
-        for server in allowed_mcp_servers:
-            if server is None:
-                continue
-
-            server_auth_header, extra_headers = _prepare_mcp_server_headers(
-                server=server,
-                mcp_server_auth_headers=mcp_server_auth_headers,
-                mcp_auth_header=mcp_auth_header,
-                oauth2_headers=oauth2_headers,
-                raw_headers=raw_headers,
-                user_api_key_auth=user_api_key_auth,
-                scope_servers=allowed_mcp_servers,
-            )
-
-            try:
-                resource_templates = await global_mcp_server_manager.get_resource_templates_from_server(
-                    server=server,
-                    user_api_key_auth=user_api_key_auth,
-                    mcp_auth_header=server_auth_header,
-                    extra_headers=extra_headers,
-                    add_prefix=True,  # Always add server prefix
-                    raw_headers=raw_headers,
-                )
-                all_resource_templates.extend(resource_templates)
-                verbose_logger.debug(
-                    "Successfully fetched %s resource templates from server %s",
-                    len(resource_templates),
-                    server.name,
-                )
-            except Exception as e:
-                verbose_logger.exception(
-                    "Error getting resource templates from server %s: %s",
-                    server.name,
-                    str(e),
-                )
-
-        verbose_logger.info(
-            "Successfully fetched %s resource templates total from all MCP servers",
-            len(all_resource_templates),
-        )
-
-        return all_resource_templates
-
-    async def filter_tools_by_key_team_permissions(
-        tools: list[MCPTool],
-        server_id: str,
-        user_api_key_auth: UserAPIKeyAuth | None,
-    ) -> list[MCPTool]:
-        """
-        Filter tools based on key/team mcp_tool_permissions.
-
-        Note: Tool names in the DB are stored without server prefixes,
-        but tool names from MCP servers are prefixed. We need to strip
-        the prefix before comparing.
-        """
-        # Filter by key/team tool-level permissions
-        allowed_tool_names: Final = await MCPRequestHandler.get_allowed_tools_for_server(
-            server_id=server_id,
-            user_api_key_auth=user_api_key_auth,
-        )
-
-        # Tools arrive prefixed with the server's own prefix; strip exactly that
-        # prefix (resolved from the server) rather than the first separator, so a
-        # prefix containing the separator still reduces to the stored bare name.
-        server: Final = global_mcp_server_manager.get_mcp_server_by_id(server_id)
-        return [
-            t
-            for t in tools
-            if MCPRequestHandler.tool_is_granted(strip_known_server_prefix(t.name, server), allowed_tool_names)
-        ]
-
-    async def _list_mcp_tools(
-        user_api_key_auth: UserAPIKeyAuth | None = None,
-        mcp_auth_header: str | None = None,
-        mcp_servers: list[str] | None = None,
-        mcp_server_auth_headers: dict[str, dict[str, str]] | None = None,
-        oauth2_headers: dict[str, str] | None = None,
-        raw_headers: dict[str, str] | None = None,
-        log_list_tools_to_spendlogs: bool = False,
-        list_tools_log_source: str | None = None,
-        client_ip: str | None = None,
-        mcp_proxy_mode: bool = False,
-    ) -> AggregateToolListing:
-        """
-        List all available MCP tools.
-
-        Args:
-            user_api_key_auth: User authentication info for access control
-            mcp_auth_header: Optional auth header for MCP server (deprecated)
-            mcp_servers: Optional list of server names/aliases to filter by
-            mcp_server_auth_headers: Optional dict of server-specific auth headers {server_alias: auth_value}
-            client_ip: Client IP for IP-based server access control
-
-        Returns:
-            AggregateToolListing: Combined tools from all accessible servers plus each server's
-            classified listing outcome
-        """
-        if not MCP_AVAILABLE:
-            return AggregateToolListing(tools=[], outcomes={})
-
-        try:
-            listing: Final = await _get_tools_from_mcp_servers(
-                user_api_key_auth=user_api_key_auth,
-                mcp_auth_header=mcp_auth_header,
-                mcp_servers=mcp_servers,
-                mcp_server_auth_headers=mcp_server_auth_headers,
-                oauth2_headers=oauth2_headers,
-                raw_headers=raw_headers,
-                log_list_tools_to_spendlogs=log_list_tools_to_spendlogs,
-                list_tools_log_source=list_tools_log_source,
-                client_ip=client_ip,
-                mcp_proxy_mode=mcp_proxy_mode,
-            )
-            verbose_logger.debug("Successfully fetched %s tools from managed MCP servers", len(listing.tools))
-            return listing
-        except HTTPException:
-            raise
-        except Exception as e:
-            verbose_logger.exception("Error getting tools from managed MCP servers: %s", e)
-            # Continue with an empty listing instead of failing completely
-            return AggregateToolListing(tools=[], outcomes={})
-
-    async def _list_mcp_prompts(
-        user_api_key_auth: UserAPIKeyAuth | None = None,
-        mcp_auth_header: str | None = None,
-        mcp_servers: list[str] | None = None,
-        mcp_server_auth_headers: dict[str, dict[str, str]] | None = None,
-        oauth2_headers: dict[str, str] | None = None,
-        raw_headers: dict[str, str] | None = None,
-    ) -> list[Prompt]:
-        """
-        List all available MCP prompts.
-
-        Args:
-            user_api_key_auth: User authentication info for access control
-            mcp_auth_header: Optional auth header for MCP server (deprecated)
-            mcp_servers: Optional list of server names/aliases to filter by
-            mcp_server_auth_headers: Optional dict of server-specific auth headers {server_alias: auth_value}
-
-        Returns:
-            List[Prompt]: Combined list of tools from all accessible servers
-        """
-        if not MCP_AVAILABLE:
-            return []
-        # Get tools from managed MCP servers with error handling
-        managed_prompts = []
-        try:
-            managed_prompts = await _get_prompts_from_mcp_servers(
-                user_api_key_auth=user_api_key_auth,
-                mcp_auth_header=mcp_auth_header,
-                mcp_servers=mcp_servers,
-                mcp_server_auth_headers=mcp_server_auth_headers,
-                oauth2_headers=oauth2_headers,
-                raw_headers=raw_headers,
-            )
-            verbose_logger.debug("Successfully fetched %s prompts from managed MCP servers", len(managed_prompts))
-        except Exception as e:
-            verbose_logger.exception("Error getting tools from managed MCP servers: %s", e)
-            # Continue with empty managed tools list instead of failing completely
-
-        return managed_prompts
-
-    async def _list_mcp_resources(
-        user_api_key_auth: UserAPIKeyAuth | None = None,
-        mcp_auth_header: str | None = None,
-        mcp_servers: list[str] | None = None,
-        mcp_server_auth_headers: dict[str, dict[str, str]] | None = None,
-        oauth2_headers: dict[str, str] | None = None,
-        raw_headers: dict[str, str] | None = None,
-    ) -> list[Resource]:
-        """List all available MCP resources."""
-
-        if not MCP_AVAILABLE:
-            return []
-
-        managed_resources: list[Resource] = []
-        try:
-            managed_resources = await _get_resources_from_mcp_servers(
-                user_api_key_auth=user_api_key_auth,
-                mcp_auth_header=mcp_auth_header,
-                mcp_servers=mcp_servers,
-                mcp_server_auth_headers=mcp_server_auth_headers,
-                oauth2_headers=oauth2_headers,
-                raw_headers=raw_headers,
-            )
-            verbose_logger.debug("Successfully fetched %s resources from managed MCP servers", len(managed_resources))
-        except Exception as e:
-            verbose_logger.exception("Error getting resources from managed MCP servers: %s", e)
-
-        return managed_resources
-
-    async def _list_mcp_resource_templates(
-        user_api_key_auth: UserAPIKeyAuth | None = None,
-        mcp_auth_header: str | None = None,
-        mcp_servers: list[str] | None = None,
-        mcp_server_auth_headers: dict[str, dict[str, str]] | None = None,
-        oauth2_headers: dict[str, str] | None = None,
-        raw_headers: dict[str, str] | None = None,
-    ) -> list[ResourceTemplate]:
-        """List all available MCP resource templates."""
-
-        if not MCP_AVAILABLE:
-            return []
-
-        managed_resource_templates: list[ResourceTemplate] = []
-        try:
-            managed_resource_templates = await _get_resource_templates_from_mcp_servers(
-                user_api_key_auth=user_api_key_auth,
-                mcp_auth_header=mcp_auth_header,
-                mcp_servers=mcp_servers,
-                mcp_server_auth_headers=mcp_server_auth_headers,
-                oauth2_headers=oauth2_headers,
-                raw_headers=raw_headers,
-            )
-            verbose_logger.debug(
-                "Successfully fetched %s resource templates from managed MCP servers",
-                len(managed_resource_templates),
-            )
-        except Exception as e:
-            verbose_logger.exception(
-                "Error getting resource templates from managed MCP servers: %s",
-                str(e),
-            )
-
-        return managed_resource_templates
-
-    def _resolve_display_name_to_original(
-        name: str,
-        allowed_mcp_servers: list[MCPServer],
-    ) -> str:
-        """Translate a display-name override back to the original prefixed tool name.
-
-        When a client received a customised display name from tools/list (e.g.
-        "Get Pet") it will call tools/call with that same string.  We need to
-        reverse-map it to the original prefixed name (e.g.
-        "petstore_mcp-getPetById") before any routing or permission logic runs.
-        """
-        for server in allowed_mcp_servers:
-            display_map = server.tool_name_to_display_name or {}
-            for unprefixed_name, display_name in display_map.items():
-                if display_name == name:
-                    return add_server_prefix_to_name(unprefixed_name, get_server_prefix(server))
-        return name
-
-    async def _get_byok_credential(
-        mcp_server: MCPServer,
-        user_api_key_auth: UserAPIKeyAuth | None,
-    ) -> str | None:
-        """Retrieve the stored BYOK credential for a user+server pair, served from the worker cache within its TTL."""
-        if not mcp_server.is_byok:
-            return None
-        user_id: Final = (user_api_key_auth.user_id if user_api_key_auth else None) or ""
-        if not user_id:
-            return None
-
-        cached: Final = get_cached_byok_credential(user_id, mcp_server.server_id)
-        if cached is not None:
-            return cached.credential
-
-        from litellm.proxy._experimental.mcp_server.db import get_user_credential
-        from litellm.proxy.proxy_server import prisma_client
-
-        if prisma_client is None:
-            return None
-        credential: Final = await get_user_credential(
-            prisma_client=prisma_client,
-            user_id=user_id,
-            server_id=mcp_server.server_id,
-        )
-        cache_byok_credential(user_id, mcp_server.server_id, credential)
-        return credential
-
-    async def _check_byok_credential(
-        mcp_server: MCPServer,
-        user_api_key_auth: UserAPIKeyAuth | None,
-    ) -> None:
-        """
-        If the MCP server is BYOK-enabled, verify that the requesting user has a
-        stored credential.  When no credential is found, raise an HTTP 401 with a
-        WWW-Authenticate header that points the MCP client to our OAuth metadata
-        endpoint so it can drive the authorization flow.
-        """
-        if not mcp_server.is_byok:
-            return
-
-        user_id: Final = (user_api_key_auth.user_id if user_api_key_auth else None) or ""
-        if not user_id:
-            raise HTTPException(
-                status_code=401,
-                detail={
-                    "error": "byok_auth_required",
-                    "server_id": mcp_server.server_id,
-                    "server_name": mcp_server.server_name or mcp_server.name,
-                    "message": "User identity is required for BYOK servers",
-                },
-                headers={"WWW-Authenticate": get_byok_www_authenticate()},
-            )
-
-        cached: Final = get_cached_byok_credential(user_id, mcp_server.server_id)
-        if cached is not None:
-            if cached.credential is None:
-                raise HTTPException(
-                    status_code=401,
-                    detail={
-                        "error": "byok_auth_required",
-                        "server_id": mcp_server.server_id,
-                        "server_name": mcp_server.server_name or mcp_server.name,
-                        "message": (
-                            "No stored credential found for this BYOK server. "
-                            "Complete the OAuth authorization flow to provide your API key."
-                        ),
-                    },
-                    headers={"WWW-Authenticate": get_byok_www_authenticate()},
-                )
-            return
-
-        from litellm.proxy._experimental.mcp_server.db import get_user_credential
-        from litellm.proxy.proxy_server import prisma_client
-
-        if prisma_client is None:
-            # Fail closed on DB unavailability: returning here previously
-            # bypassed the ownership check and let any proxy-authenticated
-            # caller invoke BYOK tools during outage windows.
-            raise HTTPException(
-                status_code=503,
-                detail={
-                    "error": "byok_auth_unavailable",
-                    "server_id": mcp_server.server_id,
-                    "server_name": mcp_server.server_name or mcp_server.name,
-                    "message": "BYOK credential check requires a database connection.",
-                },
-            )
-
-        credential: Final = await get_user_credential(
-            prisma_client=prisma_client,
-            user_id=user_id,
-            server_id=mcp_server.server_id,
-        )
-        cache_byok_credential(user_id, mcp_server.server_id, credential)
-        if credential is None:
-            raise HTTPException(
-                status_code=401,
-                detail={
-                    "error": "byok_auth_required",
-                    "server_id": mcp_server.server_id,
-                    "server_name": mcp_server.server_name or mcp_server.name,
-                    "message": (
-                        "No stored credential found for this BYOK server. "
-                        "Complete the OAuth authorization flow to provide your API key."
-                    ),
-                },
-                headers={"WWW-Authenticate": get_byok_www_authenticate()},
-            )
-
-    async def _list_tools_before_first_call(
-        server: MCPServer | None,
-        tool_name: str,
-        allowed_mcp_servers: list[MCPServer],
-        user_api_key_auth: UserAPIKeyAuth | None,
-        mcp_auth_header: str | None,
-        mcp_server_auth_headers: dict[str, dict[str, str]] | None,
-        oauth2_headers: dict[str, str] | None,
-        raw_headers: dict[str, str] | None,
-    ) -> None:
-        """List ``server`` with the caller's own credentials when it does not yet expose ``tool_name`` here.
-
-        The startup fill skips a server whose upstream wants the caller's token, and mcp 2 no
-        longer lists before an uncached tools/call, so a worker that has not served tools/list
-        for this caller would otherwise answer 404 for a tool the caller can see. Gating on the
-        requested tool, not on any prior listing, keeps callers with different upstream catalogs
-        from masking each other.
-        """
-        if server is None or global_mcp_server_manager.server_exposes_tool(server, tool_name):
-            return
-        if all(allowed.server_id != server.server_id for allowed in allowed_mcp_servers):
-            return
-        try:
-            await _get_tools_from_mcp_servers(
-                user_api_key_auth=user_api_key_auth,
-                mcp_auth_header=mcp_auth_header,
-                mcp_servers=[server.server_id],
-                mcp_server_auth_headers=mcp_server_auth_headers,
-                oauth2_headers=oauth2_headers,
-                raw_headers=raw_headers,
-            )
-        except Exception as e:  # noqa: BLE001  # best effort: resolution below answers as it did before
-            verbose_logger.debug("MCP tools/call: listing %s before its first call failed: %s", server.name, e)
-
-    async def execute_mcp_tool(
-        name: str,
-        arguments: dict[str, object],
-        allowed_mcp_servers: list[MCPServer],
-        start_time: datetime,
-        user_api_key_auth: UserAPIKeyAuth | None = None,
-        mcp_auth_header: str | None = None,
-        mcp_server_auth_headers: dict[str, dict[str, str]] | None = None,
-        oauth2_headers: dict[str, str] | None = None,
-        raw_headers: dict[str, str] | None = None,
-        host_progress_callback: Callable | None = None,
-        guardrail_context: Mapping[str, object] | None = None,
-        **kwargs: Any,
-    ) -> CallToolResult:
-        """
-        Execute MCP tool.
-
-        This function assumes permission checks have already been performed.
-
-        Args:
-            name: Tool name (may include server prefix)
-            arguments: Tool arguments
-            allowed_mcp_servers: Pre-validated list of servers the user can access
-            start_time: Start time for logging
-            user_api_key_auth: Optional user API key auth for logging
-            mcp_auth_header: Optional MCP auth header
-            mcp_server_auth_headers: Optional server-specific auth headers
-            oauth2_headers: Optional OAuth2 headers
-            raw_headers: Optional raw HTTP headers
-            **kwargs: Additional arguments (e.g., litellm_logging_obj)
-
-        Returns:
-            CallToolResult: Tool execution result
-        """
-        # Track resolved MCP server for both permission checks and dispatch
-        mcp_server: MCPServer | None = None
-        requested_server_id: Final[str | None] = kwargs.get("requested_server_id")
-
-        # If the client called with a display-name override (e.g. "Get Pet"),
-        # translate it back to the original prefixed name before any routing.
-        name = _resolve_display_name_to_original(name, allowed_mcp_servers)
-
-        # Remove prefix from tool name for logging and processing
-        original_tool_name, server_name = split_server_prefix_from_name(name)
-
-        requested_server: MCPServer | None = None
-        if requested_server_id:
-            requested_server = next(
-                (s for s in allowed_mcp_servers if s.server_id == requested_server_id),
-                None,
-            )
-
-        name_is_prefixed = False
-        if requested_server is not None and MCP_TOOL_PREFIX_SEPARATOR in name:
-            all_registry_prefixes: Final[set[str]] = set()
-            for registry_server in global_mcp_server_manager.get_registry().values():
-                for known_prefix in iter_known_server_prefixes(registry_server):
-                    all_registry_prefixes.add(normalize_server_name(known_prefix))
-            name_is_prefixed = is_tool_name_prefixed(name, known_server_prefixes=all_registry_prefixes)
-
-        first_call_target: Final = (
-            requested_server
-            if requested_server is not None and not name_is_prefixed
-            else global_mcp_server_manager.server_owning_tool_name_prefix(name)
-        )
-        first_call_tool_name: Final = (
-            name
-            if first_call_target is None or (requested_server is not None and not name_is_prefixed)
-            else strip_known_server_prefix(name, first_call_target)
-        )
-        await _list_tools_before_first_call(
-            server=first_call_target,
-            tool_name=first_call_tool_name,
-            allowed_mcp_servers=allowed_mcp_servers,
-            user_api_key_auth=user_api_key_auth,
-            mcp_auth_header=mcp_auth_header,
-            mcp_server_auth_headers=mcp_server_auth_headers,
-            oauth2_headers=oauth2_headers,
-            raw_headers=raw_headers,
-        )
-
-        if requested_server is not None and not name_is_prefixed:
-            # REST callers may pass server_id with the upstream tool name (no
-            # LiteLLM prefix). The first segment is not a registered server
-            # prefix, so the whole string is the upstream tool name and may
-            # legitimately contain the separator (e.g. "text-to-speech").
-            # server_id is authoritative for routing and auth.
-            mcp_server = requested_server
-            server_name = requested_server.name
-            original_tool_name = name
-        else:
-            # Resolve from tool name (MCP JSON-RPC or prefixed REST tool names).
-            mcp_server = global_mcp_server_manager._get_mcp_server_from_tool_name(name)
-            if mcp_server is None and requested_server is not None:
-                for known_prefix in iter_known_server_prefixes(requested_server):
-                    candidate = global_mcp_server_manager._get_mcp_server_from_tool_name(
-                        add_server_prefix_to_name(name, known_prefix)
-                    )
-                    if candidate is not None:
-                        mcp_server = candidate
-                        break
-            if mcp_server is not None:
-                server_name = mcp_server.name
-                original_tool_name = strip_known_server_prefix(name, mcp_server)
-
-            if requested_server is not None:
-                if mcp_server is not None and mcp_server.server_id != requested_server.server_id:
-                    raise HTTPException(
-                        status_code=403,
-                        detail={
-                            "error": "tool_server_mismatch",
-                            "message": (
-                                f"Tool '{name}' belongs to MCP server "
-                                f"'{mcp_server.name}' but request specified "
-                                f"server_id for '{requested_server.name}'."
-                            ),
-                        },
-                    )
-                if mcp_server is None:
-                    mcp_server = requested_server
-                    server_name = requested_server.name
-                    original_tool_name = strip_known_server_prefix(name, requested_server)
-
-        # Only enforce server-level permissions when we can resolve a server
-        if server_name:
-            if not MCPRequestHandler.is_tool_allowed(
-                allowed_mcp_servers=[server.name for server in allowed_mcp_servers],
-                server_name=server_name,
-            ):
-                raise HTTPException(
-                    status_code=403,
-                    detail="User not allowed to call this tool.",
-                )
-
-        standard_logging_mcp_tool_call: Final[StandardLoggingMCPToolCall] = _get_standard_logging_mcp_tool_call(
-            name=original_tool_name,  # Use original name for logging
-            arguments=arguments,
-            server_name=server_name,
-            session_id=_mcp_session_id_from_headers(raw_headers),
-        )
-        litellm_logging_obj: Final[LiteLLMLoggingObj | None] = kwargs.get("litellm_logging_obj", None)
-        if litellm_logging_obj:
-            litellm_logging_obj.model_call_details["mcp_tool_call_metadata"] = standard_logging_mcp_tool_call
-            litellm_logging_obj.model = f"MCP: {name}"
-            litellm_logging_obj.model_call_details["model"] = f"MCP: {name}"
-        # Resolve the MCP server early so BYOK checks and credential injection
-        # apply to ALL dispatch paths (local tool registry AND managed MCP server).
-        if mcp_server is None:
-            mcp_server = global_mcp_server_manager._get_mcp_server_from_tool_name(name)
-
-        if mcp_server:
-            standard_logging_mcp_tool_call["mcp_server_cost_info"] = (mcp_server.mcp_info or {}).get(
-                "mcp_server_cost_info"
-            )
-            if litellm_logging_obj:
-                litellm_logging_obj.model_call_details["mcp_tool_call_metadata"] = standard_logging_mcp_tool_call
-
-            # BYOK: retrieve the stored per-user credential.  A single DB call
-            # both checks existence and fetches the value, avoiding a double query.
-            if mcp_server.is_byok and not mcp_auth_header:
-                byok_cred: Final = await _get_byok_credential(mcp_server, user_api_key_auth)
-                if byok_cred is None:
-                    raise HTTPException(
-                        status_code=401,
-                        detail={
-                            "error": "byok_auth_required",
-                            "server_id": mcp_server.server_id,
-                            "server_name": mcp_server.server_name or mcp_server.name,
-                            "message": (
-                                "No stored credential found for this BYOK server. "
-                                "Complete the OAuth authorization flow to provide your API key."
-                            ),
-                        },
-                        headers={"WWW-Authenticate": get_byok_www_authenticate()},
-                    )
-                mcp_auth_header = byok_cred
-            elif mcp_server.is_byok:
-                # External auth header supplied; still enforce user-identity check.
-                await _check_byok_credential(mcp_server, user_api_key_auth)
-
-        # Check if tool exists in local registry first (for OpenAPI-based tools)
-        # These tools are registered with their prefixed names
-        #########################################################
-        local_tool: Final = global_mcp_tool_registry.get_tool(name)
-        if local_tool:
-            # OpenAPI-backed tools used to bypass `pre_call_tool_check` —
-            # only the managed path ran allowed/banned-tool checks, key/team
-            # tool permissions, and parameter validation. Run the same checks
-            # before dispatching to the local registry. Refuse the call if
-            # we cannot resolve a server: tools registered via
-            # openapi_to_mcp_generator are always tied to a server, so a
-            # missing mcp_server here means the tool->server mapping has
-            # not finished initializing or the registry entry is orphaned.
-            # Skipping the check would re-open the same authorization gap.
-            if mcp_server is None:
-                raise HTTPException(
-                    status_code=503,
-                    detail=(
-                        f"MCP server for tool '{name}' is not available; "
-                        "refusing to dispatch without authorization checks. "
-                        "Retry once the server is registered."
-                    ),
-                )
-
-            # `pre_call_tool_check` calls into `proxy_logging_obj` for the
-            # pre-call guardrail hooks, so source it from the canonical
-            # `proxy_server` module the same way `_handle_managed_mcp_tool`
-            # does. `kwargs.get("proxy_logging_obj")` is None on the MCP
-            # entry path and would crash with AttributeError after the
-            # security checks pass.
-            from litellm.proxy.proxy_server import proxy_logging_obj
-
-            hook_result = await global_mcp_server_manager.pre_call_tool_check(
-                name=original_tool_name,
-                arguments=arguments or {},
-                server_name=server_name or mcp_server.name,
-                user_api_key_auth=user_api_key_auth,
-                proxy_logging_obj=proxy_logging_obj,
-                server=mcp_server,
-                raw_headers=raw_headers,
-                litellm_logging_obj=litellm_logging_obj,
-                guardrail_context=guardrail_context,
-            )
-            # `pre_call_tool_check` may return guardrail-modified
-            # arguments; honor them on the local path too.
-            if isinstance(hook_result, dict) and "arguments" in hook_result:
-                arguments = hook_result["arguments"]
-
-            verbose_logger.debug("Executing local registry tool: %s", name)
-            # The credential rides ContextVars because the tool function has its
-            # headers baked into the closure at registration time.
-            auth_header_value, openapi_forwarded_headers, upstream_credential = _resolve_openapi_tool_auth(
-                mcp_server=mcp_server,
-                mcp_auth_header=mcp_auth_header,
-                mcp_server_auth_headers=mcp_server_auth_headers,
-                raw_headers=raw_headers,
-                user_api_key_auth=user_api_key_auth,
-            )
-            (
-                resolved_auth_headers,
-                forwarded_headers,
-            ) = await global_mcp_server_manager.resolve_openapi_upstream_auth(
-                mcp_server=mcp_server,
-                oauth2_headers=oauth2_headers,
-                raw_headers=raw_headers,
-                mcp_auth_header=upstream_credential,
-                user_api_key_auth=user_api_key_auth,
-                forwarded_headers=openapi_forwarded_headers,
-            )
-
-            _auth_token: Final = _request_auth_header.set(auth_header_value)
-            _extra_token: Final = _request_extra_headers.set(forwarded_headers)
-            _resolved_token: Final = _request_resolved_auth_headers.set(resolved_auth_headers)
-            try:
-                response = await _handle_local_mcp_tool(name, arguments)
-            finally:
-                _request_auth_header.reset(_auth_token)
-                _request_extra_headers.reset(_extra_token)
-                _request_resolved_auth_headers.reset(_resolved_token)
-
-        # Try managed MCP server tool (the name is bare; the prefix boundary was
-        # already resolved above against this server's registered prefixes)
-        # Primary and recommended way to use external MCP servers
-        #########################################################
-        elif mcp_server:
-            response = await _handle_managed_mcp_tool(
-                server_name=server_name,
-                name=original_tool_name,
-                arguments=arguments,
-                user_api_key_auth=user_api_key_auth,
-                mcp_auth_header=mcp_auth_header,
-                mcp_server_auth_headers=mcp_server_auth_headers,
-                oauth2_headers=oauth2_headers,
-                raw_headers=raw_headers,
-                litellm_logging_obj=litellm_logging_obj,
-                guardrail_context=guardrail_context,
-                host_progress_callback=host_progress_callback,
-            )
-
-        # Fall back to local tool registry with original name (legacy support)
-        #########################################################
-        # Deprecated: Local MCP Server Tool
-        #########################################################
-        else:
-            # Gate only what can actually dispatch. When the unprefixed name is
-            # not in the registry either, `_handle_local_mcp_tool` below reports
-            # 404 and nothing runs, so demanding a server here would turn every
-            # unknown tool name into a misleading 503.
-            if global_mcp_tool_registry.get_tool(original_tool_name) is not None:
-                # `mcp_server` is None here because the tool name is not in the
-                # tool -> server mapping, but the name still carries a prefix
-                # that the server-level check above compared against the
-                # caller's `allowed_mcp_servers` by exact `name`. So the named
-                # server is in that list and can carry the tool-level checks,
-                # even with the mapping cold. Resolve it from
-                # `allowed_mcp_servers` rather than the registry: the registry
-                # would happily return a server the caller holds no grant for,
-                # and matching anything other than `name` would accept a server
-                # the check never validated.
-                prefix_server: Final = next(
-                    (candidate for candidate in allowed_mcp_servers if candidate.name == server_name),
-                    None,
-                )
-                if prefix_server is None:
-                    # A non-empty prefix that passed the server-level check
-                    # always matches here, so this arm only fires when the
-                    # prefix was empty, which is exactly the case that check
-                    # skips. Fail closed rather than dispatch with no server to
-                    # evaluate a tool ceiling against.
-                    raise HTTPException(
-                        status_code=503,
-                        detail=(
-                            f"MCP server for tool '{original_tool_name}' is not available; "
-                            "refusing to dispatch without authorization checks. "
-                            "Retry once the server is registered."
-                        ),
-                    )
-
-                from litellm.proxy.proxy_server import proxy_logging_obj
-
-                hook_result = await global_mcp_server_manager.pre_call_tool_check(
-                    name=original_tool_name,
-                    arguments=arguments,
-                    server_name=server_name,
-                    user_api_key_auth=user_api_key_auth,
-                    proxy_logging_obj=proxy_logging_obj,
-                    server=prefix_server,
-                    raw_headers=raw_headers,
-                    litellm_logging_obj=litellm_logging_obj,
-                    guardrail_context=guardrail_context,
-                )
-                if "arguments" in hook_result:
-                    arguments = hook_result["arguments"]  # pyright: ignore[reportAny]  # hook returns untyped args
-
-            response = await _handle_local_mcp_tool(original_tool_name, arguments)
-
-        return await _run_post_mcp_call_guardrails(
-            result=response,
-            litellm_logging_obj=litellm_logging_obj,
-            user_api_key_auth=user_api_key_auth,
-            request_data=kwargs,
-        )
-
-    async def _run_post_mcp_call_guardrails(
-        result: CallToolResult,
-        litellm_logging_obj: LiteLLMLoggingObj | None,
-        user_api_key_auth: UserAPIKeyAuth | None,
-        request_data: Mapping[str, object],
-    ) -> CallToolResult:
-        """Run ``post_mcp_call`` guardrails over an executed tool result.
-
-        Lives on ``execute_mcp_tool``'s return path rather than inside
-        ``_fire_mcp_tool_call_logging`` so enforcement never depends on logging
-        being configured, and so every dispatch route gets it: the MCP protocol
-        handler, the REST endpoint, and tool search all funnel through here.
-        A guardrail that rejects the result raises, matching ``pre_mcp_call``.
-        """
-        from litellm.proxy.proxy_server import proxy_logging_obj
-
-        if proxy_logging_obj is None:
-            return result
-        return await proxy_logging_obj.post_mcp_call_hook(
-            response=result,
-            request_data=(
-                litellm_logging_obj.model_call_details if litellm_logging_obj is not None else dict(request_data)
-            ),
-            user_api_key_dict=user_api_key_auth,
-        )
-
-    _MCP_CREDENTIAL_REQUEST_FIELDS: Final = frozenset(
-        {
-            "raw_headers",
-            "mcp_auth_header",
-            "mcp_server_auth_headers",
-            "oauth2_headers",
-            "user_api_key_auth",
-        }
+    from litellm.proxy._experimental.mcp_server.operations import (
+        _MCP_CREDENTIAL_REQUEST_FIELDS,
+        _aggregate_server_key,
+        _check_byok_credential,
+        _fire_mcp_tool_call_logging,
+        _get_byok_credential,
+        _get_prompts_from_mcp_servers,
+        _get_resource_templates_from_mcp_servers,
+        _get_resources_from_mcp_servers,
+        _get_standard_logging_mcp_tool_call,
+        _get_tools_from_mcp_servers,
+        _handle_local_mcp_tool,
+        _handle_managed_mcp_tool,
+        _list_mcp_prompts,
+        _list_mcp_resource_templates,
+        _list_mcp_resources,
+        _list_mcp_tools,
+        _list_tools_before_first_call,
+        _resolve_display_name_to_original,
+        _run_post_mcp_call_guardrails,
+        call_mcp_tool,
+        execute_mcp_tool,
+        filter_tools_by_key_team_permissions,
+        fire_mcp_tool_call_failure_logging,
+        mcp_get_prompt,
+        mcp_read_resource,
     )
 
-    async def _fire_mcp_tool_call_logging(
-        logging_obj: LiteLLMLoggingObj,
-        result: CallToolResult,
-        start_time: datetime,
-        end_time: datetime,
-        user_api_key_auth: UserAPIKeyAuth | None = None,
-        request_data: Mapping[str, object] | None = None,
-    ) -> CallToolResult:
-        """Fire post-call logging for an executed MCP tool call, returning the result to send.
-
-        The returned result is what the caller must forward to the client: a
-        ``post_mcp_call`` guardrail may rewrite the tool output (e.g. mask
-        sensitive values) or reject it, in which case its exception propagates.
-        Guardrails run before the success/failure logging so the masked text, not
-        the raw one, is what gets logged.
-
-        A result with ``is_error=True`` is logged as a failure (``status="failure"``
-        payload, so OTel marks the span ERROR) while the HTTP wire behavior stays
-        200 + ``isError: true`` per the MCP spec. The error check runs after
-        ``async_post_mcp_tool_call_hook`` because guardrails may flip the result
-        to ``is_error=True`` in that hook. Raised exceptions never reach here (the
-        ``@client`` wrapper and ``call_mcp_tool``'s except path log those), so
-        this cannot double-log a failure.
-
-        ``request_data`` may carry credential-bearing fields (the REST path puts
-        ``raw_headers``, ``mcp_auth_header``, ``mcp_server_auth_headers``, and
-        ``oauth2_headers`` at the top level of its data dict), so those are
-        stripped before the dict is handed to ``post_call_failure_hook``
-        callbacks.
-        """
-        from litellm.proxy.proxy_server import proxy_logging_obj
-
-        logging_obj.post_call(original_response=result)
-        await logging_obj.async_post_mcp_tool_call_hook(
-            kwargs=logging_obj.model_call_details,
-            response_obj=result,
-            start_time=start_time,
-            end_time=end_time,
-        )
-        logging_obj.call_type = CallTypes.call_mcp_tool.value
-        error_message: Final = extract_mcp_tool_result_error_message(result)
-        if error_message is None:
-            await logging_obj.async_success_handler(result=result, start_time=start_time, end_time=end_time)
-            return result
-
-        logging_obj.has_run_logging(event_type="sync_success")
-        logging_obj.has_run_logging(event_type="async_success")
-        tool_error: Final = MCPToolResultError(error_message)
-        logging_obj.failure_handler(tool_error, "", start_time, end_time)
-        await logging_obj.async_failure_handler(tool_error, "", start_time, end_time)
-
-        if user_api_key_auth is None:
-            return result
-
-        if proxy_logging_obj:
-            sanitized_request_data: Final = {
-                key: value for key, value in (request_data or {}).items() if key not in _MCP_CREDENTIAL_REQUEST_FIELDS
-            }
-            await proxy_logging_obj.post_call_failure_hook(
-                request_data=sanitized_request_data,
-                original_exception=tool_error,
-                user_api_key_dict=user_api_key_auth,
-                route="/mcp/call_tool",
-            )
-        return result
-
-    async def fire_mcp_tool_call_failure_logging(
-        logging_obj: LiteLLMLoggingObj | None,
-        exception: Exception,
-        start_time: datetime,
-        user_api_key_auth: UserAPIKeyAuth | None,
-        request_data: Mapping[str, object],
-    ) -> None:
-        """Failure logging shared by the ``/mcp`` path and the REST endpoint. Call from
-        inside the ``except`` block so the traceback is still available.
-
-        The failure handlers run first because ``_ProxyDBLogger.async_post_call_failure_hook``
-        builds the failure spend-log row from the ``standard_logging_object`` they produce;
-        both gate on ``should_run_logging``, so the ``@client`` wrapper does not log twice.
-        A relayed upstream 401 (``MCPUpstreamAuthError``) is an expected caller-must-reauth
-        signal and skips ``post_call_failure_hook``, which fires the ``llm_exceptions`` alert.
-        """
-        from litellm.proxy.proxy_server import proxy_logging_obj
-
-        traceback_str: Final = traceback.format_exc(limit=MAXIMUM_TRACEBACK_LINES_TO_LOG)
-        if logging_obj is not None:
-            end_time: Final = datetime.now()  # noqa: DTZ005  # naive to match `start_time`, which it is subtracted from
-            logging_obj.failure_handler(exception, traceback_str, start_time, end_time)
-            await logging_obj.async_failure_handler(exception, traceback_str, start_time, end_time)
-
-        if isinstance(exception, MCPUpstreamAuthError) or not proxy_logging_obj or user_api_key_auth is None:
-            return
-        sanitized_request_data: Final = {
-            key: value for key, value in request_data.items() if key not in _MCP_CREDENTIAL_REQUEST_FIELDS
-        }
-        await proxy_logging_obj.post_call_failure_hook(
-            request_data=sanitized_request_data,
-            original_exception=exception,
-            user_api_key_dict=user_api_key_auth,
-            route="/mcp/call_tool",
-            traceback_str=traceback_str,
-        )
-
-    @client
-    async def call_mcp_tool(
-        name: str,
-        arguments: dict[str, object] | None = None,
-        user_api_key_auth: UserAPIKeyAuth | None = None,
-        mcp_auth_header: str | None = None,
-        mcp_servers: list[str] | None = None,
-        mcp_server_auth_headers: dict[str, dict[str, str]] | None = None,
-        oauth2_headers: dict[str, str] | None = None,
-        raw_headers: dict[str, str] | None = None,
-        client_ip: str | None = None,
-        **kwargs: Any,
-    ) -> CallToolResult:
-        """
-        Call a specific tool with the provided arguments (handles prefixed tool names).
-        """
-        start_time: Final = datetime.now()
-        litellm_logging_obj: Final[LiteLLMLoggingObj | None] = kwargs.get("litellm_logging_obj", None)
-
-        try:
-            if arguments is None:
-                raise HTTPException(status_code=400, detail="Request arguments are required")
-
-            ## CHECK IF USER IS ALLOWED TO CALL THIS TOOL
-            allowed_mcp_server_ids: Final = await global_mcp_server_manager.get_allowed_mcp_servers(
-                user_api_key_auth=user_api_key_auth,
-            )
-
-            allowed_mcp_servers: list[MCPServer] = []
-            for allowed_mcp_server_id in allowed_mcp_server_ids:
-                allowed_server = global_mcp_server_manager.get_mcp_server_by_id(allowed_mcp_server_id)
-                if allowed_server is not None:
-                    # Same request-time oauth2_flow backstop the listing path applies,
-                    # so a null-flow M2M-shape row is treated as M2M on tool calls too.
-                    allowed_server = MCPServerManager.resolve_oauth2_flow_for_request(allowed_server)
-                    allowed_mcp_servers.append(allowed_server)
-
-            allowed_mcp_servers = await _get_allowed_mcp_servers_from_mcp_server_names(
-                mcp_servers=mcp_servers,
-                allowed_mcp_servers=allowed_mcp_servers,
-            )
-            if mcp_servers and not allowed_mcp_servers:
-                await raise_denied_scoped_mcp_access(
-                    requested_names=mcp_servers,
-                    user_api_key_auth=user_api_key_auth,
-                    client_ip=client_ip,
-                )
-            if not allowed_mcp_servers:
-                raise HTTPException(
-                    status_code=403,
-                    detail="User not allowed to call this tool.",
-                )
-
-            # Delegate to execute_mcp_tool for execution
-            response = await execute_mcp_tool(
-                name=name,
-                arguments=arguments,
-                allowed_mcp_servers=allowed_mcp_servers,
-                start_time=start_time,
-                user_api_key_auth=user_api_key_auth,
-                mcp_auth_header=mcp_auth_header,
-                mcp_server_auth_headers=mcp_server_auth_headers,
-                oauth2_headers=oauth2_headers,
-                raw_headers=raw_headers,
-                **kwargs,
-            )
-        except Exception as e:
-            await fire_mcp_tool_call_failure_logging(litellm_logging_obj, e, start_time, user_api_key_auth, kwargs)
-            raise
-
-        if litellm_logging_obj:
-            response = await _fire_mcp_tool_call_logging(
-                logging_obj=litellm_logging_obj,
-                result=response,
-                start_time=start_time,
-                end_time=datetime.now(),
-                user_api_key_auth=user_api_key_auth,
-                request_data=kwargs,
-            )
-        return response
-
-    async def mcp_get_prompt(
-        name: str,
-        arguments: dict[str, object] | None = None,
-        user_api_key_auth: UserAPIKeyAuth | None = None,
-        mcp_auth_header: str | None = None,
-        mcp_servers: list[str] | None = None,
-        mcp_server_auth_headers: dict[str, dict[str, str]] | None = None,
-        oauth2_headers: dict[str, str] | None = None,
-        raw_headers: dict[str, str] | None = None,
-    ) -> GetPromptResult:
-        """
-        Fetch a specific MCP prompt, handling both prefixed and unprefixed names.
-        """
-        allowed_mcp_servers: Final = await _get_allowed_mcp_servers(
-            user_api_key_auth=user_api_key_auth,
-            mcp_servers=mcp_servers,
-        )
-
-        if not allowed_mcp_servers:
-            raise HTTPException(
-                status_code=403,
-                detail="User not allowed to get this prompt.",
-            )
-
-        # Extract server name from prefixed prompt name
-        original_prompt_name, server_name = split_server_prefix_from_name(name)
-
-        server: Final = next((s for s in allowed_mcp_servers if s.name == server_name), None)
-        if server is None:
-            raise HTTPException(
-                status_code=403,
-                detail="User not allowed to get this prompt.",
-            )
-
-        server_auth_header, extra_headers = _prepare_mcp_server_headers(
-            server=server,
-            mcp_server_auth_headers=mcp_server_auth_headers,
-            mcp_auth_header=mcp_auth_header,
-            oauth2_headers=oauth2_headers,
-            raw_headers=raw_headers,
-            user_api_key_auth=user_api_key_auth,
-        )
-
-        return await global_mcp_server_manager.get_prompt_from_server(
-            server=server,
-            user_api_key_auth=user_api_key_auth,
-            prompt_name=original_prompt_name,
-            arguments=arguments,
-            mcp_auth_header=server_auth_header,
-            extra_headers=extra_headers,
-            raw_headers=raw_headers,
-        )
-
-    async def mcp_read_resource(
-        url: AnyUrl,
-        user_api_key_auth: UserAPIKeyAuth | None = None,
-        mcp_auth_header: str | None = None,
-        mcp_servers: list[str] | None = None,
-        mcp_server_auth_headers: dict[str, dict[str, str]] | None = None,
-        oauth2_headers: dict[str, str] | None = None,
-        raw_headers: dict[str, str] | None = None,
-    ) -> ReadResourceResult:
-        """Read resource contents from upstream MCP servers."""
-
-        allowed_mcp_servers: Final = await _get_allowed_mcp_servers(
-            user_api_key_auth=user_api_key_auth,
-            mcp_servers=mcp_servers,
-        )
-
-        if not allowed_mcp_servers:
-            raise HTTPException(
-                status_code=403,
-                detail="User not allowed to read this resource.",
-            )
-
-        if len(allowed_mcp_servers) != 1:
-            raise HTTPException(
-                status_code=400,
-                detail=(
-                    "Multiple MCP servers configured; read_resource currently supports exactly one allowed server."
-                ),
-            )
-
-        server: Final = allowed_mcp_servers[0]
-
-        server_auth_header, extra_headers = _prepare_mcp_server_headers(
-            server=server,
-            mcp_server_auth_headers=mcp_server_auth_headers,
-            mcp_auth_header=mcp_auth_header,
-            oauth2_headers=oauth2_headers,
-            raw_headers=raw_headers,
-            user_api_key_auth=user_api_key_auth,
-        )
-
-        return await global_mcp_server_manager.read_resource_from_server(
-            server=server,
-            user_api_key_auth=user_api_key_auth,
-            url=url,
-            mcp_auth_header=server_auth_header,
-            extra_headers=extra_headers,
-            raw_headers=raw_headers,
-        )
-
-    def _get_standard_logging_mcp_tool_call(
-        name: str,
-        arguments: dict[str, object],
-        server_name: str | None,
-        session_id: str | None = None,
-    ) -> StandardLoggingMCPToolCall:
-        mcp_server: Final = global_mcp_server_manager._get_mcp_server_from_tool_name(
-            add_server_prefix_to_name(name, server_name) if server_name else name
-        )
-        namespaced_tool_name: Final = f"{server_name}/{name}" if server_name else name
-        if mcp_server:
-            mcp_info: Final = mcp_server.mcp_info or {}
-            return StandardLoggingMCPToolCall(
-                name=name,
-                arguments=arguments,
-                mcp_server_name=mcp_info.get("server_name"),
-                mcp_server_logo_url=mcp_info.get("logo_url"),
-                namespaced_tool_name=namespaced_tool_name,
-                mcp_session_id=session_id,
-                mcp_auth_mode=mcp_server.auth_type,
-                mcp_server_resource=_redact_mcp_resource_url(mcp_server.url),
-            )
-        else:
-            return StandardLoggingMCPToolCall(
-                name=name,
-                arguments=arguments,
-                namespaced_tool_name=namespaced_tool_name,
-                mcp_session_id=session_id,
-            )
-
-    async def _handle_managed_mcp_tool(
-        server_name: str,
-        name: str,
-        arguments: dict[str, object],
-        user_api_key_auth: UserAPIKeyAuth | None = None,
-        mcp_auth_header: str | None = None,
-        mcp_server_auth_headers: dict[str, dict[str, str]] | None = None,
-        oauth2_headers: dict[str, str] | None = None,
-        raw_headers: dict[str, str] | None = None,
-        litellm_logging_obj: LiteLLMLoggingObj | None = None,
-        host_progress_callback: Callable | None = None,
-        guardrail_context: Mapping[str, object] | None = None,
-    ) -> CallToolResult:
-        """Handle tool execution for managed server tools"""
-        # Import here to avoid circular import
-        from litellm.proxy.proxy_server import proxy_logging_obj
-
-        call_tool_result: Final = await global_mcp_server_manager.call_tool(
-            server_name=server_name,
-            name=name,
-            arguments=arguments,
-            user_api_key_auth=user_api_key_auth,
-            mcp_auth_header=mcp_auth_header,
-            mcp_server_auth_headers=mcp_server_auth_headers,
-            oauth2_headers=oauth2_headers,
-            raw_headers=raw_headers,
-            proxy_logging_obj=proxy_logging_obj,
-            host_progress_callback=host_progress_callback,
-            litellm_logging_obj=litellm_logging_obj,
-            guardrail_context=guardrail_context,
-        )
-        verbose_logger.debug("CALL TOOL RESULT: %s", call_tool_result)
-        return call_tool_result
-
-    async def _handle_local_mcp_tool(name: str, arguments: dict[str, object]) -> CallToolResult:
-        """Execute a local-registry tool and report whether it succeeded.
-
-        Returns the result rather than bare content because the verdict is part of it: the content
-        alone cannot say whether the handler failed, so callers used to stamp is_error=False on every
-        outcome and an upstream rejection was served as tool output.
-
-        A failure is reported as ``is_error=True`` here rather than raised, because the REST surface
-        turns an unrecognized exception into a 500 and an upstream 403 or 429 is not a gateway crash.
-        ``MCPUpstreamAuthError`` is the exception: it propagates so the caller is told to
-        re-authenticate, which both renderers already know how to say.
-
-        Note: Local tools don't use prefixes, so we use the original name
-        """
-        import inspect
-
-        tool: Final = global_mcp_tool_registry.get_tool(name)
-        if not tool:
-            raise HTTPException(status_code=404, detail=f"Tool '{name}' not found")
-
-        try:
-            if inspect.iscoroutinefunction(tool.handler):
-                result = await tool.handler(**arguments)
-            else:
-                result = tool.handler(**arguments)
-        except MCPUpstreamAuthError:
-            raise
-        except Exception as e:
-            verbose_logger.exception("Error executing local tool %s: %s", name, e)
-            return CallToolResult(
-                content=[TextContent(text=f"Error: {e}", type="text")],  # mutable-ok: MCP result content
-                is_error=True,
-            )
-        return CallToolResult(
-            content=[TextContent(text=str(result), type="text")],  # mutable-ok: MCP result content
-            is_error=False,
-        )
-
     def _get_mcp_servers_in_path(path: str) -> list[str] | None:
         """
         Get the MCP servers from the path
@@ -4178,7 +1533,9 @@ if MCP_AVAILABLE:
                     detail=f"API key does not have access to toolset '{toolset_id}'.",
                 )
 
-        tool_permissions = await global_mcp_server_manager.resolve_toolset_tool_permissions(toolset_ids=[toolset_id])
+        tool_permissions = await operations.global_mcp_server_manager.resolve_toolset_tool_permissions(
+            toolset_ids=[toolset_id]
+        )
         server_ids: Final = list(tool_permissions.keys())
         existing_op: Final = user_api_key_auth.object_permission
         if existing_op is not None:
@@ -4197,7 +1554,7 @@ if MCP_AVAILABLE:
                 mcp_servers=server_ids,
                 mcp_tool_permissions=tool_permissions,
             )
-        return user_api_key_auth.model_copy(update={"object_permission": updated_op})
+        return user_api_key_auth.model_copy(update={"object_permission": updated_op, "mcp_toolset_id": toolset_id})
 
     async def _raise_preemptive_401_for_unauthenticated_servers(
         scope: Scope,
@@ -4221,7 +1578,7 @@ if MCP_AVAILABLE:
         a server it will be 403'd on immediately after authentication.
         """
         for server_name in mcp_servers or []:
-            server = global_mcp_server_manager.get_mcp_server_by_name(server_name, client_ip=client_ip)
+            server = operations.global_mcp_server_manager.get_mcp_server_by_name(server_name, client_ip=client_ip)
             if server is not None and allowed_server_ids is not None and server.server_id not in allowed_server_ids:
                 # Caller's narrowed scope excludes this server — skip the
                 # preemptive challenge and let downstream authorization
@@ -4234,7 +1591,7 @@ if MCP_AVAILABLE:
                 # authorization_url/token_url can change their inferred flow.
                 continue
             if server is not None:
-                server = await global_mcp_server_manager.ensure_oauth_metadata_discovered(server)
+                server = await operations.global_mcp_server_manager.ensure_oauth_metadata_discovered(server)
             if server and server.auth_type == MCPAuth.oauth2:
                 # The challenge decision is per oauth2 sub-mode, not per header:
                 # gateway-managed modes (M2M and interactive authorization_code)
@@ -4262,7 +1619,7 @@ if MCP_AVAILABLE:
                     # authorization server is the gateway itself, vaulting via the
                     # authorize interlude); the per-server relay advertised below
                     # cannot vault without a litellm key on its token request.
-                    if await global_mcp_server_manager.has_user_oauth_token(server, user_api_key_auth):
+                    if await operations.global_mcp_server_manager.has_user_oauth_token(server, user_api_key_auth):
                         continue
 
                     if _is_mcp_admitted_user_subject(user_api_key_auth):
@@ -4345,12 +1702,12 @@ if MCP_AVAILABLE:
                 and server.server_id
                 in frozenset(
                     allowed.server_id
-                    for allowed in await _get_allowed_mcp_servers(
+                    for allowed in await operations._get_allowed_mcp_servers(
                         user_api_key_auth=user_api_key_auth, mcp_servers=mcp_servers, client_ip=client_ip
                     )
                 )
             ):
-                await global_mcp_server_manager.preflight_token_exchange(
+                await operations.global_mcp_server_manager.preflight_token_exchange(
                     server=server,
                     oauth2_headers=oauth2_headers,
                     user_api_key_auth=user_api_key_auth,
@@ -4366,7 +1723,9 @@ if MCP_AVAILABLE:
             if (
                 server
                 and server.is_oauth_passthrough
-                and not _client_has_passthrough_authorization(server, oauth2_headers, mcp_server_auth_headers)
+                and not operations._client_has_passthrough_authorization(
+                    server, oauth2_headers, mcp_server_auth_headers
+                )
             ):
                 www_authenticate = get_passthrough_www_authenticate(
                     scope=scope,
@@ -4383,7 +1742,7 @@ if MCP_AVAILABLE:
                 and server.is_oauth_delegate
                 and len(mcp_servers or []) == 1
                 and _get_forwarded_auth_from_scope(scope) is None
-                and not _client_has_per_server_auth_header(server, mcp_server_auth_headers)
+                and not operations._client_has_per_server_auth_header(server, mcp_server_auth_headers)
             ):
                 www_authenticate = get_passthrough_www_authenticate(
                     scope=scope,
@@ -4400,7 +1759,7 @@ if MCP_AVAILABLE:
                 and server.is_true_passthrough
                 and len(mcp_servers or []) == 1
                 and not _scope_has_authorization_header(scope)
-                and not _client_has_per_server_auth_header(server, mcp_server_auth_headers)
+                and not operations._client_has_per_server_auth_header(server, mcp_server_auth_headers)
             ):
                 if server.is_dcr_bridge:
                     raise HTTPException(
@@ -4528,7 +1887,7 @@ if MCP_AVAILABLE:
 
         # Use the authorized server set, not the raw user-supplied names, so that
         # a caller cannot force a probe to a server their key is not allowed to use.
-        allowed_servers: Final = await _get_allowed_mcp_servers(
+        allowed_servers: Final = await operations._get_allowed_mcp_servers(
             user_api_key_auth=user_api_key_auth,
             mcp_servers=mcp_servers,
             client_ip=client_ip,
diff --git a/litellm/proxy/_experimental/mcp_server/tool_search.py b/litellm/proxy/_experimental/mcp_server/tool_search.py
index a482d02c31d..3650c722103 100644
--- a/litellm/proxy/_experimental/mcp_server/tool_search.py
+++ b/litellm/proxy/_experimental/mcp_server/tool_search.py
@@ -463,8 +463,8 @@ async def handle_mcp_tool_search(
     oauth2_headers: dict[str, str] | None = None,
     raw_headers: dict[str, str] | None = None,
 ) -> CallToolResult:
-    from litellm.proxy._experimental.mcp_server.server import (
-        _list_mcp_tools,  # pyright: ignore[reportPrivateUsage]  # shared catalog owner
+    from litellm.proxy._experimental.mcp_server.operations import (
+        _list_mcp_tools,
     )
     from litellm.proxy.proxy_server import llm_router, proxy_logging_obj
 
@@ -519,8 +519,8 @@ async def handle_mcp_proxy_tool(
     from jsonschema import validate
 
     from litellm.proxy import proxy_server
-    from litellm.proxy._experimental.mcp_server.server import (  # pyright: ignore[reportPrivateUsage]  # shared catalog owner
-        _list_mcp_tools,  # pyright: ignore[reportPrivateUsage]  # shared catalog owner
+    from litellm.proxy._experimental.mcp_server.operations import (
+        _list_mcp_tools,
     )
 
     listing: Final = await _list_mcp_tools(
@@ -607,7 +607,7 @@ async def handle_mcp_tool_call(
     requested_server_id: str | None = None,
     guardrail_context: Mapping[str, object] | None = None,
 ) -> CallToolResult:
-    from litellm.proxy._experimental.mcp_server.server import (
+    from litellm.proxy._experimental.mcp_server.operations import (
         _get_allowed_mcp_servers,
         execute_mcp_tool,
         raise_denied_scoped_mcp_access,
@@ -643,6 +643,7 @@ async def handle_mcp_tool_call(
         mcp_server_auth_headers=mcp_server_auth_headers,
         oauth2_headers=oauth2_headers,
         raw_headers=raw_headers,
+        client_ip=client_ip,
         litellm_logging_obj=litellm_logging_obj,
         requested_server_id=requested_server_id,
         guardrail_context=guardrail_context,
diff --git a/litellm/proxy/_types.py b/litellm/proxy/_types.py
index 3b34440d0bf..07338bcff52 100644
--- a/litellm/proxy/_types.py
+++ b/litellm/proxy/_types.py
@@ -3238,6 +3238,7 @@ class UserAPIKeyAuth(LiteLLM_VerificationTokenView):  # the expected response ob
     # above; a forged value could at most narrow, but the stripping keeps the field's provenance
     # single-owner so its meaning stays trustworthy.
     mcp_session_resource_server_id: str | None = Field(default=None, exclude=True)
+    mcp_toolset_id: str | None = Field(default=None, exclude=True)
     via_virtual_key: bool = Field(
         default=False,
         exclude=True,
@@ -3279,6 +3280,7 @@ class UserAPIKeyAuth(LiteLLM_VerificationTokenView):  # the expected response ob
         values.pop("mcp_admitted_user_subject", None)
         values.pop("mcp_source_team_rpm_limits", None)
         values.pop("mcp_session_resource_server_id", None)
+        values.pop("mcp_toolset_id", None)
         values.pop("via_virtual_key", None)
         if values.get("api_key") is not None:
             values.update({"token": cls._safe_hash_litellm_api_key(values.get("api_key"))})
diff --git a/scripts/check_mcp_operation_boundary.py b/scripts/check_mcp_operation_boundary.py
new file mode 100644
index 00000000000..b6c9dcefabf
--- /dev/null
+++ b/scripts/check_mcp_operation_boundary.py
@@ -0,0 +1,65 @@
+import ast
+import sys
+from pathlib import Path
+from typing import Final
+
+PACKAGE: Final = Path("litellm/proxy/_experimental/mcp_server")
+LEGACY_ADAPTERS: Final = frozenset({"server.py", "legacy_callbacks.py", "mcp_context.py", "mcp_debug.py"})
+CONFINED_NAMES: Final = frozenset(
+    {
+        "auth_context_var",
+        "active_mcp_session_var",
+        "active_mcp_request_ctx_var",
+        "get_active_auth_context",
+        "get_active_mcp_session",
+        "get_active_mcp_request_ctx",
+        "get_or_extract_auth_context",
+        "_session_obj_auth_storage",
+        "WeakKeyDictionary",
+        "_mcp_active_toolset_id",
+        "_mcp_gateway_initialize_instructions",
+        "_mcp_gateway_server_name",
+        "_mcp_proxy_mode",
+    }
+)
+
+
+def is_confined(name: str) -> bool:
+    return name in CONFINED_NAMES or name.startswith("_stateful_session_")
+
+
+def violations(path: Path, source: str) -> tuple[str, ...]:
+    if path.name in LEGACY_ADAPTERS:
+        return ()
+    tree: Final = ast.parse(source, filename=str(path))
+    return tuple(
+        f"{path}:{node.lineno}: MCP request/session state belongs in a legacy adapter"
+        for node in ast.walk(tree)
+        if (
+            isinstance(node, ast.ImportFrom)
+            and (
+                (node.module or "").endswith(".mcp_context")
+                or any(is_confined(alias.name) for alias in node.names)
+                or (path.name in {"operations.py", "contracts.py"} and (node.module or "").endswith(".server"))
+            )
+            or isinstance(node, ast.Name)
+            and is_confined(node.id)
+            or isinstance(node, ast.Attribute)
+            and is_confined(node.attr)
+        )
+    )
+
+
+def main() -> int:
+    findings: Final = tuple(
+        finding for path in sorted(PACKAGE.rglob("*.py")) for finding in violations(path, path.read_text())
+    )
+    if findings:
+        print("\n".join(findings), file=sys.stderr)
+        return 1
+    print("MCP operation boundary: passed")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())
diff --git a/scripts/pre_commit_lint.sh b/scripts/pre_commit_lint.sh
index 1abd415d237..22cc38f841c 100755
--- a/scripts/pre_commit_lint.sh
+++ b/scripts/pre_commit_lint.sh
@@ -102,6 +102,9 @@ ui_prettier_pattern='^ui/litellm-dashboard/.*\.(js|jsx|ts|tsx|mjs|cjs|json|css|s
 ui_eslint_pattern='^ui/litellm-dashboard/.*\.(js|jsx|ts|tsx|mjs|cjs)$'
 
 litellm_py_files=$(scope_match "$litellm_py_pattern")
+if [ -n "$(scope_match '^(litellm/proxy/_experimental/mcp_server/|scripts/check_mcp_operation_boundary\.py)')" ]; then
+    uv run --no-sync python scripts/check_mcp_operation_boundary.py || exit 1
+fi
 e2e_py_files=$(scope_match "$e2e_py_pattern")
 test_tree_files=$(scope_match "$test_tree_pattern")
 # ruff format (and CI's format step) skip enterprise; the rest of make lint covers it.
diff --git a/tests/test_litellm/proxy/_experimental/mcp_server/test_byok_oauth_endpoints.py b/tests/test_litellm/proxy/_experimental/mcp_server/test_byok_oauth_endpoints.py
index 87e23893616..a77b4c8d565 100644
--- a/tests/test_litellm/proxy/_experimental/mcp_server/test_byok_oauth_endpoints.py
+++ b/tests/test_litellm/proxy/_experimental/mcp_server/test_byok_oauth_endpoints.py
@@ -1,3 +1,4 @@
+from litellm.proxy._experimental.mcp_server import operations as mcp_operations
 """
 Unit tests for the BYOK OAuth 2.1 authorization server endpoints.
 
@@ -592,7 +593,7 @@ async def test_check_byok_credential_missing_credential(monkeypatch):
 
     monkeypatch.delenv("PROXY_BASE_URL", raising=False)
     monkeypatch.delenv("SERVER_ROOT_PATH", raising=False)
-    server_module.byok_credential_cache.flush_cache()
+    mcp_operations.byok_credential_cache.flush_cache()
     mock_prisma = MagicMock()
 
     with (
@@ -628,13 +629,13 @@ async def test_execute_byok_tool_missing_credential_advertises_api_key_flow(monk
     from litellm.types.mcp_server.mcp_server_manager import MCPServer
 
     monkeypatch.setenv("PROXY_BASE_URL", "https://gateway.example.com/proxy")
-    mcp_module.byok_credential_cache.flush_cache()
+    mcp_operations.byok_credential_cache.flush_cache()
     server = MCPServer(server_id="byok-discovery", name="byok-discovery", transport=MCPTransport.http, is_byok=True)
     prisma = MagicMock()
     prisma.db.litellm_mcpusercredentials.find_unique = AsyncMock(return_value=None)
     monkeypatch.setattr(proxy_server, "prisma_client", prisma)
     with pytest.raises(HTTPException) as exc_info:
-        await mcp_module.execute_mcp_tool(
+        await mcp_operations.execute_mcp_tool(
             name="list_regions",
             arguments={},
             allowed_mcp_servers=[server],
@@ -687,7 +688,7 @@ async def test_invalidate_byok_cred_cache_evicts_locally_and_broadcasts_the_same
 
     server = MCPServer(server_id="byok-revoke", name="byok-server", transport=MCPTransport.http, is_byok=True)
     user_auth = UserAPIKeyAuth(user_id="mallory", api_key="sk-test")
-    server_module.byok_credential_cache.flush_cache()
+    mcp_operations.byok_credential_cache.flush_cache()
     db_lookup = AsyncMock(side_effect=["sk-before-revoke", None])
     publish = AsyncMock()
 
@@ -699,13 +700,13 @@ async def test_invalidate_byok_cred_cache_evicts_locally_and_broadcasts_the_same
             "litellm.proxy.proxy_server.prisma_client", MagicMock()
         ),
         patch.object(  # test-quality-ok: the redis publisher is module-level; asserting the broadcast without a redis
-            server_module, "publish_auth_cache_invalidation", new=publish
+            mcp_operations, "publish_auth_cache_invalidation", new=publish
         ),
     ):
-        assert await server_module._get_byok_credential(server, user_auth) == "sk-before-revoke"
-        assert await server_module._get_byok_credential(server, user_auth) == "sk-before-revoke"
-        await server_module._invalidate_byok_cred_cache("mallory", "byok-revoke")
-        assert await server_module._get_byok_credential(server, user_auth) is None
+        assert await mcp_operations._get_byok_credential(server, user_auth) == "sk-before-revoke"
+        assert await mcp_operations._get_byok_credential(server, user_auth) == "sk-before-revoke"
+        await mcp_operations._invalidate_byok_cred_cache("mallory", "byok-revoke")
+        assert await mcp_operations._get_byok_credential(server, user_auth) is None
 
     assert db_lookup.await_count == 2
     publish.assert_awaited_once_with(cache_key=byok_credential_cache_key("mallory", "byok-revoke"))
diff --git a/tests/test_litellm/proxy/_experimental/mcp_server/test_contracts.py b/tests/test_litellm/proxy/_experimental/mcp_server/test_contracts.py
new file mode 100644
index 00000000000..e13ecdfcce9
--- /dev/null
+++ b/tests/test_litellm/proxy/_experimental/mcp_server/test_contracts.py
@@ -0,0 +1,60 @@
+from dataclasses import FrozenInstanceError
+
+import pytest
+
+from litellm.proxy._experimental.mcp_server.operations import prepare_context
+from litellm.proxy._types import UserAPIKeyAuth
+
+
+def test_operation_context_isolates_nested_headers_and_caller_permissions():
+    caller = UserAPIKeyAuth(user_id="alpha", models=["allowed"])
+    caller.mcp_admitted_user_subject = True
+    caller.mcp_session_resource_server_id = "alpha-server"
+    caller.mcp_toolset_id = "toolset-alpha"
+    caller.mcp_source_team_rpm_limits = {"team": {"alpha-server": 2}}
+    headers = {"x-caller": "alpha"}
+    server_headers = {"alpha-server": {"authorization": "alpha-token"}}
+    context = prepare_context(caller, raw_headers=headers, mcp_server_auth_headers=server_headers)
+
+    caller.models.append("forbidden")
+    caller.mcp_source_team_rpm_limits["team"]["alpha-server"] = 999
+    headers["x-caller"] = "bravo"
+    server_headers["alpha-server"]["authorization"] = "bravo-token"
+    captured = context.user_api_key_auth
+    assert captured is not None
+    assert captured.models == ["allowed"]
+    assert captured.mcp_admitted_user_subject is True
+    assert captured.mcp_session_resource_server_id == "alpha-server"
+    assert captured.mcp_toolset_id == "toolset-alpha"
+    assert captured.mcp_source_team_rpm_limits == {"team": {"alpha-server": 2}}
+    captured.models.append("also-forbidden")
+    assert context.user_api_key_auth.models == ["allowed"]
+    assert context.raw_headers == {"x-caller": "alpha"}
+    assert context.mcp_server_auth_headers == {"alpha-server": {"authorization": "alpha-token"}}
+    with pytest.raises(TypeError):
+        context.raw_headers["x-caller"] = "changed"
+    with pytest.raises(TypeError):
+        context.mcp_server_auth_headers["alpha-server"]["authorization"] = "changed"
+    with pytest.raises(FrozenInstanceError):
+        context.client_ip = "untrusted"
+
+
+def test_operation_context_preserves_missing_and_empty_inputs():
+    missing = prepare_context()
+    empty = prepare_context(mcp_servers=[], raw_headers={}, oauth2_headers={}, mcp_server_auth_headers={})
+    assert missing.user_api_key_auth is None
+    assert missing.mcp_servers is None
+    assert missing.raw_headers is None
+    assert missing.oauth2_headers is None
+    assert missing.mcp_server_auth_headers is None
+    assert empty.mcp_servers == ()
+    assert empty.raw_headers == {}
+    assert empty.oauth2_headers == {}
+    assert empty.mcp_server_auth_headers == {}
+
+
+def test_toolset_request_marker_cannot_be_supplied_by_caller_or_serialized():
+    auth = UserAPIKeyAuth.model_validate({"user_id": "alpha", "mcp_toolset_id": "forged"})
+    assert auth.mcp_toolset_id is None
+    auth.mcp_toolset_id = "server-resolved"
+    assert "mcp_toolset_id" not in auth.model_dump()
diff --git a/tests/test_litellm/proxy/_experimental/mcp_server/test_mcp_block_recording.py b/tests/test_litellm/proxy/_experimental/mcp_server/test_mcp_block_recording.py
index 64d926bc5e3..b8aadef430f 100644
--- a/tests/test_litellm/proxy/_experimental/mcp_server/test_mcp_block_recording.py
+++ b/tests/test_litellm/proxy/_experimental/mcp_server/test_mcp_block_recording.py
@@ -1,5 +1,6 @@
+from litellm.proxy._experimental.mcp_server import operations as mcp_operations
 """Tests for guardrail-block recording in
-``litellm.proxy._experimental.mcp_server.server.call_mcp_tool``.
+``litellm.proxy._experimental.mcp_server.operations.call_mcp_tool``.
 
 A pre-call MCP guardrail block *raises* into ``call_mcp_tool``'s
 ``except Exception``. The failure spend-log row that the Guardrails Monitor's
@@ -70,7 +71,7 @@ async def _call_block(logging_obj, order: list, *, user_api_key_auth=mock.sentin
 
     with mock.patch.dict(sys.modules, {"litellm.proxy.proxy_server": fake_proxy_server}):
         with contextlib.suppress(HTTPException):
-            await server.call_mcp_tool.__wrapped__(
+            await mcp_operations.call_mcp_tool.__wrapped__(
                 name="t",
                 arguments=None,
                 user_api_key_auth=user_api_key_auth,
diff --git a/tests/test_litellm/proxy/_experimental/mcp_server/test_mcp_hook_extra_headers.py b/tests/test_litellm/proxy/_experimental/mcp_server/test_mcp_hook_extra_headers.py
index 28faf375ab8..9659eb1cbc2 100644
--- a/tests/test_litellm/proxy/_experimental/mcp_server/test_mcp_hook_extra_headers.py
+++ b/tests/test_litellm/proxy/_experimental/mcp_server/test_mcp_hook_extra_headers.py
@@ -1229,7 +1229,7 @@ class TestResolveByokMcpAuthHeader:
         user_auth = UserAPIKeyAuth(user_id="user-1", api_key="sk-dashboard")
 
         with patch(
-            "litellm.proxy._experimental.mcp_server.server._get_byok_credential",
+            "litellm.proxy._experimental.mcp_server.operations._get_byok_credential",
             new=AsyncMock(return_value="stored-cred"),
         ):
             result = await _resolve_byok_mcp_auth_header(server, user_auth, None)
@@ -1249,7 +1249,7 @@ class TestResolveByokMcpAuthHeader:
         user_auth = UserAPIKeyAuth(user_id="user-1", api_key="sk-dashboard")
 
         with patch(
-            "litellm.proxy._experimental.mcp_server.server._get_byok_credential",
+            "litellm.proxy._experimental.mcp_server.operations._get_byok_credential",
             new=AsyncMock(return_value=None),
         ):
             with pytest.raises(HTTPException) as exc_info:
@@ -1272,7 +1272,7 @@ class TestResolveByokMcpAuthHeader:
         check_mock = AsyncMock(return_value=None)
 
         with patch(
-            "litellm.proxy._experimental.mcp_server.server._check_byok_credential",
+            "litellm.proxy._experimental.mcp_server.operations._check_byok_credential",
             new=check_mock,
         ):
             result = await _resolve_byok_mcp_auth_header(server, user_auth, "caller-header")
diff --git a/tests/test_litellm/proxy/_experimental/mcp_server/test_mcp_oauth_passthrough_tools.py b/tests/test_litellm/proxy/_experimental/mcp_server/test_mcp_oauth_passthrough_tools.py
index 3f5d4ad83ea..1909e3306a2 100644
--- a/tests/test_litellm/proxy/_experimental/mcp_server/test_mcp_oauth_passthrough_tools.py
+++ b/tests/test_litellm/proxy/_experimental/mcp_server/test_mcp_oauth_passthrough_tools.py
@@ -1,3 +1,4 @@
+from litellm.proxy._experimental.mcp_server import operations as mcp_operations
 """Unit tests for MCP OAuth passthrough tool-fetch behavior."""
 
 import logging
@@ -339,16 +340,16 @@ async def test_aggregate_list_tools_absorbs_one_unauthenticated_server():
             raise MCPUpstreamAuthError(status_code=401, www_authenticate=None, server_name=server.name)
         return [good_tool]
 
-    with patch.object(mcp_server, "_get_allowed_mcp_servers", AsyncMock(return_value=[delegate, working])), patch.object(
-        mcp_server, "_prefetch_oauth_creds_for_user", AsyncMock(return_value={})
-    ), patch.object(mcp_server, "_prepare_mcp_server_headers", MagicMock(return_value=(None, None))), patch.object(
-        mcp_server, "_get_user_oauth_extra_headers_from_db", AsyncMock(return_value=None)
+    with patch.object(mcp_operations, "_get_allowed_mcp_servers", AsyncMock(return_value=[delegate, working])), patch.object(
+        mcp_operations, "_prefetch_oauth_creds_for_user", AsyncMock(return_value={})
+    ), patch.object(mcp_operations, "_prepare_mcp_server_headers", MagicMock(return_value=(None, None))), patch.object(
+        mcp_operations, "_get_user_oauth_extra_headers_from_db", AsyncMock(return_value=None)
     ), patch.object(
-        mcp_server, "filter_tools_by_key_team_permissions", AsyncMock(side_effect=lambda tools, **k: tools)
+        mcp_operations, "filter_tools_by_key_team_permissions", AsyncMock(side_effect=lambda tools, **k: tools)
     ), patch.object(
-        mcp_server.global_mcp_server_manager, "_get_tools_from_server", AsyncMock(side_effect=fake_get_tools)
+        mcp_operations.global_mcp_server_manager, "_get_tools_from_server", AsyncMock(side_effect=fake_get_tools)
     ):
-        listing = await mcp_server._get_tools_from_mcp_servers(
+        listing = await mcp_operations._get_tools_from_mcp_servers(
             user_api_key_auth=UserAPIKeyAuth(token="h", user_id="u1"),
             mcp_auth_header=None,
             mcp_servers=None,
@@ -382,14 +383,14 @@ async def test_single_server_route_also_absorbs_upstream_auth_error():
     # /<server>/mcp sets the path-derived single-server scope; absorption must hold even then.
     token = _mcp_gateway_server_name.set("delegate_docs")
     try:
-        with patch.object(mcp_server, "_get_allowed_mcp_servers", AsyncMock(return_value=[delegate])), patch.object(
-            mcp_server, "_prefetch_oauth_creds_for_user", AsyncMock(return_value={})
-        ), patch.object(mcp_server, "_prepare_mcp_server_headers", MagicMock(return_value=(None, None))), patch.object(
-            mcp_server, "_get_user_oauth_extra_headers_from_db", AsyncMock(return_value=None)
+        with patch.object(mcp_operations, "_get_allowed_mcp_servers", AsyncMock(return_value=[delegate])), patch.object(
+            mcp_operations, "_prefetch_oauth_creds_for_user", AsyncMock(return_value={})
+        ), patch.object(mcp_operations, "_prepare_mcp_server_headers", MagicMock(return_value=(None, None))), patch.object(
+            mcp_operations, "_get_user_oauth_extra_headers_from_db", AsyncMock(return_value=None)
         ), patch.object(
-            mcp_server.global_mcp_server_manager, "_get_tools_from_server", AsyncMock(side_effect=fake_get_tools)
+            mcp_operations.global_mcp_server_manager, "_get_tools_from_server", AsyncMock(side_effect=fake_get_tools)
         ):
-            listing = await mcp_server._get_tools_from_mcp_servers(
+            listing = await mcp_operations._get_tools_from_mcp_servers(
                 user_api_key_auth=UserAPIKeyAuth(token="h", user_id="u1"),
                 mcp_auth_header=None,
                 mcp_servers=["delegate_docs"],
@@ -419,15 +420,15 @@ async def test_aggregate_with_single_accessible_server_still_absorbs():
     async def fake_get_tools(server, **kwargs):
         raise MCPUpstreamAuthError(status_code=401, www_authenticate=None, server_name=server.name)
 
-    with patch.object(mcp_server, "_get_allowed_mcp_servers", AsyncMock(return_value=[delegate])), patch.object(
-        mcp_server, "_prefetch_oauth_creds_for_user", AsyncMock(return_value={})
-    ), patch.object(mcp_server, "_prepare_mcp_server_headers", MagicMock(return_value=(None, None))), patch.object(
-        mcp_server, "_get_user_oauth_extra_headers_from_db", AsyncMock(return_value=None)
+    with patch.object(mcp_operations, "_get_allowed_mcp_servers", AsyncMock(return_value=[delegate])), patch.object(
+        mcp_operations, "_prefetch_oauth_creds_for_user", AsyncMock(return_value={})
+    ), patch.object(mcp_operations, "_prepare_mcp_server_headers", MagicMock(return_value=(None, None))), patch.object(
+        mcp_operations, "_get_user_oauth_extra_headers_from_db", AsyncMock(return_value=None)
     ), patch.object(
-        mcp_server.global_mcp_server_manager, "_get_tools_from_server", AsyncMock(side_effect=fake_get_tools)
+        mcp_operations.global_mcp_server_manager, "_get_tools_from_server", AsyncMock(side_effect=fake_get_tools)
     ):
         # Aggregate route: no explicit server filter, even though only one server is accessible.
-        listing = await mcp_server._get_tools_from_mcp_servers(
+        listing = await mcp_operations._get_tools_from_mcp_servers(
             user_api_key_auth=UserAPIKeyAuth(token="h", user_id="u1"),
             mcp_auth_header=None,
             mcp_servers=None,
@@ -475,3 +476,25 @@ async def test_client_creation_failure_logs_sanitized_exchange(monkeypatch, capl
             await manager._get_tools_from_server(server)
     assert "POST https://upstream/ -> HTTP 500" in caplog.text
     assert "missing_scope" in caplog.text and "query-secret" not in caplog.text
+
+
+@pytest.mark.parametrize(
+    "oauth_headers,server_headers,authorized",
+    [
+        ({"Authorization": "Bearer upstream"}, None, True),
+        ({"AUTHORIZATION": "Bearer upstream"}, None, True),
+        ({"x-unrelated": "present"}, None, False),
+        (None, {"catalog": {"Authorization": "Bearer scoped"}}, True),
+        (None, {"other-server": {"Authorization": "Bearer unrelated"}}, False),
+        (None, {"catalog": {"x-unrelated": "present"}}, False),
+        (None, {"catalog": "Bearer legacy"}, True),
+        (None, {"catalog": "   "}, False),
+    ],
+)
+def test_passthrough_admission_recognizes_only_matching_authorization(oauth_headers, server_headers, authorized):
+    from litellm.proxy._experimental.mcp_server.operations import _client_has_passthrough_authorization
+    from litellm.types.mcp import MCPTransport
+    from litellm.types.mcp_server.mcp_server_manager import MCPServer
+
+    server = MCPServer(server_id="catalog", name="catalog", alias="catalog", transport=MCPTransport.http)
+    assert _client_has_passthrough_authorization(server, oauth_headers, server_headers) is authorized
diff --git a/tests/test_litellm/proxy/_experimental/mcp_server/test_mcp_proxy_mode.py b/tests/test_litellm/proxy/_experimental/mcp_server/test_mcp_proxy_mode.py
index 84d4f1fd083..ed5d67164bd 100644
--- a/tests/test_litellm/proxy/_experimental/mcp_server/test_mcp_proxy_mode.py
+++ b/tests/test_litellm/proxy/_experimental/mcp_server/test_mcp_proxy_mode.py
@@ -1,3 +1,4 @@
+from litellm.proxy._experimental.mcp_server import operations as mcp_operations
 import json
 from datetime import datetime
 
@@ -27,8 +28,8 @@ def proxy_mode():
 @pytest.mark.asyncio
 @pytest.mark.usefixtures("proxy_mode")
 async def test_proxy_call_rejects_non_proxy_tool_names() -> None:
-    result = await server._dispatch_virtual_mcp_tool(
-        name="math_stdio-add", arguments={"a": 1, "b": 2}, user_api_key_auth=AUTH, client_ip=None
+    result = await mcp_operations._dispatch_virtual_mcp_tool(
+        name="math_stdio-add", arguments={"a": 1, "b": 2}, user_api_key_auth=AUTH, client_ip=None, mcp_proxy_mode=True
     )
 
     assert result is not None
@@ -105,12 +106,13 @@ async def test_proxy_scope_exception_emits_failure_log(monkeypatch: pytest.Monke
     arguments = {"tool_id": "denied-scope", "arguments": {}}
 
     with pytest.raises(HTTPException) as denied:
-        await server._dispatch_virtual_mcp_tool(
+        await mcp_operations._dispatch_virtual_mcp_tool(
             name="call_tool",
             arguments=arguments,
             user_api_key_auth=auth,
             client_ip=None,
             mcp_servers=["ungranted"],
+            mcp_proxy_mode=True,
             raw_headers={"authorization": "Bearer raw-scope-secret", "x-litellm-call-id": "scope-denial"},
         )
 
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 3668a06203c..169de9095cf 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
@@ -1,3 +1,4 @@
+from litellm.proxy._experimental.mcp_server import operations as mcp_operations
 import asyncio
 import contextlib
 import contextvars
@@ -138,7 +139,7 @@ async def test_mcp_server_tool_call_body_contains_request_data(_mcp_request_ctx)
         mock_add_litellm_data_to_request,
     ):
         with patch(
-            "litellm.proxy._experimental.mcp_server.server.call_mcp_tool",
+            "litellm.proxy._experimental.mcp_server.operations.call_mcp_tool",
             mock_call_mcp_tool,
         ):
             with patch(
@@ -194,7 +195,7 @@ async def test_mcp_server_tool_call_forwards_client_headers_to_logging(_mcp_requ
         mock_add_litellm_data_to_request,
     ):
         with patch(
-            "litellm.proxy._experimental.mcp_server.server.call_mcp_tool",
+            "litellm.proxy._experimental.mcp_server.operations.call_mcp_tool",
             mock_call_mcp_tool,
         ):
             with patch("litellm.proxy.proxy_server.proxy_config", MagicMock()):
@@ -241,7 +242,7 @@ async def test_mcp_server_tool_call_strips_custom_litellm_key_header(_mcp_reques
         capturing_add_litellm_data_to_request,
     ):
         with patch(
-            "litellm.proxy._experimental.mcp_server.server.call_mcp_tool",
+            "litellm.proxy._experimental.mcp_server.operations.call_mcp_tool",
             mock_call_mcp_tool,
         ):
             with patch("litellm.proxy.proxy_server.proxy_config", MagicMock()):
@@ -287,11 +288,11 @@ async def test_mcp_server_tool_call_relays_upstream_auth_error_as_iserror(_mcp_r
         mock_add_litellm_data_to_request,
     ):
         with patch(
-            "litellm.proxy._experimental.mcp_server.server.call_mcp_tool",
+            "litellm.proxy._experimental.mcp_server.operations.call_mcp_tool",
             mock_call_mcp_tool,
         ):
             with patch("litellm.proxy.proxy_server.proxy_config", MagicMock()):
-                with patch("litellm.proxy._experimental.mcp_server.server.verbose_logger", mock_logger):
+                with patch("litellm.proxy._experimental.mcp_server.operations.verbose_logger", mock_logger):
                     result = await mcp_server_tool_call(_mcp_request_ctx(), _call_tool_params("test_tool", {"param": "value"}))
 
     assert result.is_error is True
@@ -867,15 +868,15 @@ async def test_get_prompts_from_mcp_servers_success():
 
     with (
         patch(
-            "litellm.proxy._experimental.mcp_server.server._get_allowed_mcp_servers",
+            "litellm.proxy._experimental.mcp_server.operations._get_allowed_mcp_servers",
             AsyncMock(return_value=[server_a, server_b]),
         ) as mock_allowed,
         patch(
-            "litellm.proxy._experimental.mcp_server.server._prepare_mcp_server_headers",
+            "litellm.proxy._experimental.mcp_server.operations._prepare_mcp_server_headers",
             return_value=(None, None),
         ) as mock_headers,
         patch(
-            "litellm.proxy._experimental.mcp_server.server.global_mcp_server_manager",
+            "litellm.proxy._experimental.mcp_server.operations.global_mcp_server_manager",
         ) as mock_manager,
     ):
         mock_manager.get_prompts_from_server = AsyncMock(
@@ -927,15 +928,15 @@ async def test_get_resources_from_mcp_servers_success():
 
     with (
         patch(
-            "litellm.proxy._experimental.mcp_server.server._get_allowed_mcp_servers",
+            "litellm.proxy._experimental.mcp_server.operations._get_allowed_mcp_servers",
             AsyncMock(return_value=[server_a, server_b]),
         ) as mock_allowed,
         patch(
-            "litellm.proxy._experimental.mcp_server.server._prepare_mcp_server_headers",
+            "litellm.proxy._experimental.mcp_server.operations._prepare_mcp_server_headers",
             return_value=(None, None),
         ) as mock_headers,
         patch(
-            "litellm.proxy._experimental.mcp_server.server.global_mcp_server_manager",
+            "litellm.proxy._experimental.mcp_server.operations.global_mcp_server_manager",
         ) as mock_manager,
     ):
         mock_manager.get_resources_from_server = AsyncMock(
@@ -992,15 +993,15 @@ async def test_get_resource_templates_from_mcp_servers_success():
 
     with (
         patch(
-            "litellm.proxy._experimental.mcp_server.server._get_allowed_mcp_servers",
+            "litellm.proxy._experimental.mcp_server.operations._get_allowed_mcp_servers",
             AsyncMock(return_value=[server]),
         ) as mock_allowed,
         patch(
-            "litellm.proxy._experimental.mcp_server.server._prepare_mcp_server_headers",
+            "litellm.proxy._experimental.mcp_server.operations._prepare_mcp_server_headers",
             return_value=(None, None),
         ) as mock_headers,
         patch(
-            "litellm.proxy._experimental.mcp_server.server.global_mcp_server_manager",
+            "litellm.proxy._experimental.mcp_server.operations.global_mcp_server_manager",
         ) as mock_manager,
     ):
         mock_manager.get_resource_templates_from_server = AsyncMock(
@@ -1042,15 +1043,15 @@ async def test_mcp_get_prompt_success():
 
     with (
         patch(
-            "litellm.proxy._experimental.mcp_server.server._get_allowed_mcp_servers",
+            "litellm.proxy._experimental.mcp_server.operations._get_allowed_mcp_servers",
             AsyncMock(return_value=[server]),
         ) as mock_allowed,
         patch(
-            "litellm.proxy._experimental.mcp_server.server._prepare_mcp_server_headers",
+            "litellm.proxy._experimental.mcp_server.operations._prepare_mcp_server_headers",
             return_value=({"Authorization": "token"}, {"X-Test": "1"}),
         ) as mock_headers,
         patch(
-            "litellm.proxy._experimental.mcp_server.server.global_mcp_server_manager",
+            "litellm.proxy._experimental.mcp_server.operations.global_mcp_server_manager",
         ) as mock_manager,
     ):
         mock_manager.get_prompt_from_server = AsyncMock(return_value=prompt_result)
@@ -1078,6 +1079,7 @@ async def test_mcp_get_prompt_success():
         mcp_auth_header={"Authorization": "token"},
         extra_headers={"X-Test": "1"},
         raw_headers=None,
+        client_ip=None,
     )
     assert result is prompt_result
 
@@ -1106,15 +1108,15 @@ async def test_mcp_read_resource_success():
 
     with (
         patch(
-            "litellm.proxy._experimental.mcp_server.server._get_allowed_mcp_servers",
+            "litellm.proxy._experimental.mcp_server.operations._get_allowed_mcp_servers",
             AsyncMock(return_value=[server]),
         ) as mock_allowed,
         patch(
-            "litellm.proxy._experimental.mcp_server.server._prepare_mcp_server_headers",
+            "litellm.proxy._experimental.mcp_server.operations._prepare_mcp_server_headers",
             return_value=({"Authorization": "token"}, {"X-Test": "1"}),
         ) as mock_headers,
         patch(
-            "litellm.proxy._experimental.mcp_server.server.global_mcp_server_manager",
+            "litellm.proxy._experimental.mcp_server.operations.global_mcp_server_manager",
         ) as mock_manager,
     ):
         mock_manager.read_resource_from_server = AsyncMock(return_value=read_result)
@@ -1140,6 +1142,7 @@ async def test_mcp_read_resource_success():
         mcp_auth_header={"Authorization": "token"},
         extra_headers={"X-Test": "1"},
         raw_headers=None,
+        client_ip=None,
     )
     assert result is read_result
 
@@ -1264,7 +1267,7 @@ async def test_mcp_read_resource_multiple_servers_error():
     server_b.name = "server_b"
 
     with patch(
-        "litellm.proxy._experimental.mcp_server.server._get_allowed_mcp_servers",
+        "litellm.proxy._experimental.mcp_server.operations._get_allowed_mcp_servers",
         AsyncMock(return_value=[server_a, server_b]),
     ) as mock_allowed:
         with pytest.raises(HTTPException) as exc_info:
@@ -1354,11 +1357,11 @@ async def test_get_tools_from_mcp_servers_continues_when_one_server_fails():
     mock_manager._get_tools_from_server = mock_get_tools_from_server
 
     with patch(
-        "litellm.proxy._experimental.mcp_server.server.global_mcp_server_manager",
+        "litellm.proxy._experimental.mcp_server.operations.global_mcp_server_manager",
         mock_manager,
     ):
         with patch(
-            "litellm.proxy._experimental.mcp_server.server.verbose_logger",
+            "litellm.proxy._experimental.mcp_server.operations.verbose_logger",
         ) as mock_logger:
             # Test with server-specific auth headers
             mcp_server_auth_headers = {
@@ -1450,11 +1453,11 @@ async def test_get_tools_from_mcp_servers_handles_all_servers_failing():
     mock_manager._get_tools_from_server = mock_get_tools_from_server
 
     with patch(
-        "litellm.proxy._experimental.mcp_server.server.global_mcp_server_manager",
+        "litellm.proxy._experimental.mcp_server.operations.global_mcp_server_manager",
         mock_manager,
     ):
         with patch(
-            "litellm.proxy._experimental.mcp_server.server.verbose_logger",
+            "litellm.proxy._experimental.mcp_server.operations.verbose_logger",
         ) as mock_logger:
             # Test with server-specific auth headers
             mcp_server_auth_headers = {
@@ -1524,11 +1527,11 @@ async def _denied_scoped_list(
 
     with (
         patch(  # test-quality-ok: the permission resolver is a module-level function; the suite's only seam
-            "litellm.proxy._experimental.mcp_server.server._get_allowed_mcp_servers",
+            "litellm.proxy._experimental.mcp_server.operations._get_allowed_mcp_servers",
             resolver,
         ),
         patch(  # test-quality-ok: the server registry is a module-level singleton; the suite's only seam
-            "litellm.proxy._experimental.mcp_server.server.global_mcp_server_manager",
+            "litellm.proxy._experimental.mcp_server.operations.global_mcp_server_manager",
             mock_manager,
         ),
     ):
@@ -1575,11 +1578,11 @@ async def test_empty_scope_lists_nothing_instead_of_raising_a_nameless_denial():
 
     with (
         patch(  # test-quality-ok: the permission resolver is a module-level function; the suite's only seam
-            "litellm.proxy._experimental.mcp_server.server._get_allowed_mcp_servers",
+            "litellm.proxy._experimental.mcp_server.operations._get_allowed_mcp_servers",
             resolver,
         ),
         patch(  # test-quality-ok: the server registry is a module-level singleton; the suite's only seam
-            "litellm.proxy._experimental.mcp_server.server.global_mcp_server_manager",
+            "litellm.proxy._experimental.mcp_server.operations.global_mcp_server_manager",
             _denied_scope_manager({"github": "srv-github"}),
         ),
     ):
@@ -1721,7 +1724,8 @@ async def test_scoped_list_agent_veto_attributed_for_differently_cased_server_na
 
 
 @pytest.mark.asyncio
-async def test_handle_list_tools_converts_permission_httpexception_to_mcp_error(_mcp_request_ctx):
+@pytest.mark.parametrize("denial_at_auth", [False, True])
+async def test_handle_list_tools_converts_permission_httpexception_to_mcp_error(_mcp_request_ctx, denial_at_auth):
     """The MCP protocol handler surfaces a permission HTTPException as a clean JSON-RPC error
     (MCPError, INVALID_REQUEST) carrying the denial message, instead of a raw 500."""
     try:
@@ -1738,10 +1742,10 @@ async def test_handle_list_tools_converts_permission_httpexception_to_mcp_error(
     with (
         patch(  # test-quality-ok: the protocol handler reads auth from module context; no injection seam
             "litellm.proxy._experimental.mcp_server.server.get_or_extract_auth_context",
-            new=AsyncMock(return_value=(None, None, None, None, None, None, None)),
+            new=AsyncMock(return_value=(None, None, None, None, None, None, None), side_effect=denial if denial_at_auth else None),
         ),
         patch(  # test-quality-ok: the listing helper is the handler's only collaborator; the suite's seam
-            "litellm.proxy._experimental.mcp_server.server._list_mcp_tools",
+            "litellm.proxy._experimental.mcp_server.operations._list_mcp_tools",
             new=AsyncMock(side_effect=denial),
         ),
     ):
@@ -1768,7 +1772,7 @@ async def test_mcp_server_tool_call_renders_denial_message_not_detail_dict(_mcp_
             new=AsyncMock(return_value=(None, None, None, None, None, None, None)),
         ),
         patch(  # test-quality-ok: the tool-call helper is the handler's only collaborator; the suite's seam
-            "litellm.proxy._experimental.mcp_server.server.call_mcp_tool",
+            "litellm.proxy._experimental.mcp_server.operations.call_mcp_tool",
             new=AsyncMock(side_effect=denial),
         ),
     ):
@@ -1819,7 +1823,7 @@ async def test_mcp_server_tool_call_body_with_none_arguments(_mcp_request_ctx):
         mock_add_litellm_data_to_request,
     ):
         with patch(
-            "litellm.proxy._experimental.mcp_server.server.call_mcp_tool",
+            "litellm.proxy._experimental.mcp_server.operations.call_mcp_tool",
             mock_call_mcp_tool,
         ):
             with patch(
@@ -1893,7 +1897,7 @@ async def test_concurrent_initialize_session_managers():
                 "run",
                 return_value=mock_cm_sse,
             ) as mock_sse_run,
-            patch("litellm.proxy._experimental.mcp_server.server.verbose_logger"),
+            patch("litellm.proxy._experimental.mcp_server.operations.verbose_logger"),
         ):
             # Create multiple concurrent tasks that call initialize_session_managers
             async def init_task():
@@ -2333,7 +2337,7 @@ async def test_mcp_routing_chunked_initialize_to_stateful():
             "litellm.proxy._experimental.mcp_server.server.set_auth_context",
         ),
         patch(  # test-quality-ok: registry is empty in unit tests; key owns one server
-            "litellm.proxy._experimental.mcp_server.server._get_allowed_mcp_servers",
+            "litellm.proxy._experimental.mcp_server.operations._get_allowed_mcp_servers",
             new_callable=AsyncMock,
             return_value=[MagicMock()],
         ),
@@ -2823,7 +2827,7 @@ async def test_initialize_request_tracks_active_session_after_response_header():
                 return_value=(owner_auth, None, None, None, None, None),
             ),
             patch(  # test-quality-ok: registry is empty in unit tests; key owns one server
-                "litellm.proxy._experimental.mcp_server.server._get_allowed_mcp_servers",
+                "litellm.proxy._experimental.mcp_server.operations._get_allowed_mcp_servers",
                 new_callable=AsyncMock,
                 return_value=[MagicMock()],
             ),
@@ -2976,7 +2980,7 @@ async def test_initialize_request_records_client_name_in_gateway_sessions_report
                 return_value=(owner_auth, None, None, None, None, None),
             ),
             patch(  # test-quality-ok: registry is empty in unit tests; key owns one server
-                "litellm.proxy._experimental.mcp_server.server._get_allowed_mcp_servers",
+                "litellm.proxy._experimental.mcp_server.operations._get_allowed_mcp_servers",
                 new_callable=AsyncMock,
                 return_value=[MagicMock()],
             ),
@@ -3451,7 +3455,7 @@ async def test_initialize_request_with_existing_session_tracks_new_session():
                 ),
             ),
             patch(  # test-quality-ok: registry is empty in unit tests; key owns one server
-                "litellm.proxy._experimental.mcp_server.server._get_allowed_mcp_servers",
+                "litellm.proxy._experimental.mcp_server.operations._get_allowed_mcp_servers",
                 new_callable=AsyncMock,
                 return_value=[MagicMock()],
             ),
@@ -4164,7 +4168,7 @@ async def test_mcp_routing_with_conflicting_alias_and_group_name():
 
     with (
         patch(
-            "litellm.proxy._experimental.mcp_server.server.global_mcp_server_manager.get_allowed_mcp_servers",
+            "litellm.proxy._experimental.mcp_server.operations.global_mcp_server_manager.get_allowed_mcp_servers",
             mock_get_allowed,
         ),
         patch(
@@ -4172,7 +4176,7 @@ async def test_mcp_routing_with_conflicting_alias_and_group_name():
             mock_db_lookup,
         ),
         patch(
-            "litellm.proxy._experimental.mcp_server.server.global_mcp_server_manager._get_tools_from_server",
+            "litellm.proxy._experimental.mcp_server.operations.global_mcp_server_manager._get_tools_from_server",
             mock_get_tools_spy,
         ),
     ):
@@ -4281,16 +4285,16 @@ async def test_oauth2_caller_headers_not_forwarded_for_migrated_server():
             side_effect=mock_fetch_tools_with_timeout,
         ),
         patch(
-            "litellm.proxy._experimental.mcp_server.server._get_allowed_mcp_servers",
+            "litellm.proxy._experimental.mcp_server.operations._get_allowed_mcp_servers",
             AsyncMock(return_value=[oauth2_server]),
         ),
         patch(
-            "litellm.proxy._experimental.mcp_server.server._prefetch_oauth_creds_for_user",
+            "litellm.proxy._experimental.mcp_server.operations._prefetch_oauth_creds_for_user",
             new_callable=AsyncMock,
             return_value={},
         ),
         patch(
-            "litellm.proxy._experimental.mcp_server.server._get_user_oauth_extra_headers_from_db",
+            "litellm.proxy._experimental.mcp_server.operations._get_user_oauth_extra_headers_from_db",
             new_callable=AsyncMock,
             return_value=None,
         ),
@@ -4372,7 +4376,7 @@ async def test_list_tools_single_server_unprefixed_names():
     mock_manager._get_tools_from_server = mock_get_tools_from_server
 
     with patch(
-        "litellm.proxy._experimental.mcp_server.server.global_mcp_server_manager",
+        "litellm.proxy._experimental.mcp_server.operations.global_mcp_server_manager",
         mock_manager,
     ):
         listing = await _get_tools_from_mcp_servers(
@@ -4451,7 +4455,7 @@ async def test_list_tools_multiple_servers_prefixed_names():
     mock_manager._get_tools_from_server = mock_get_tools_from_server
 
     with patch(
-        "litellm.proxy._experimental.mcp_server.server.global_mcp_server_manager",
+        "litellm.proxy._experimental.mcp_server.operations.global_mcp_server_manager",
         mock_manager,
     ):
         listing = await _get_tools_from_mcp_servers(
@@ -4631,7 +4635,7 @@ async def test_call_mcp_tool_user_unauthorized_access():
             AsyncMock(return_value=["allowed_server", "another_server"]),
         ),
         patch(
-            "litellm.proxy._experimental.mcp_server.server.global_mcp_server_manager.get_mcp_server_by_id",
+            "litellm.proxy._experimental.mcp_server.operations.global_mcp_server_manager.get_mcp_server_by_id",
             side_effect=mock_get_server_by_id,
         ),
     ):
@@ -4661,11 +4665,11 @@ async def test_call_mcp_tool_scoped_denial_names_the_binding_agent():
 
     with (
         patch(  # test-quality-ok: the server registry is a module-level singleton; the suite's only seam
-            "litellm.proxy._experimental.mcp_server.server.global_mcp_server_manager.get_allowed_mcp_servers",
+            "litellm.proxy._experimental.mcp_server.operations.global_mcp_server_manager.get_allowed_mcp_servers",
             AsyncMock(return_value=[]),
         ),
         patch(  # test-quality-ok: the permission resolver is a module-level function; the suite's only seam
-            "litellm.proxy._experimental.mcp_server.server._get_allowed_mcp_servers",
+            "litellm.proxy._experimental.mcp_server.operations._get_allowed_mcp_servers",
             _scope_resolver({"github": "srv-github"}),
         ),
     ):
@@ -4737,7 +4741,7 @@ async def test_call_mcp_tool_unauthorized_403_does_not_leak_server_credentials()
             AsyncMock(return_value=["allowed_server"]),
         ),
         patch(
-            "litellm.proxy._experimental.mcp_server.server.global_mcp_server_manager.get_mcp_server_by_id",
+            "litellm.proxy._experimental.mcp_server.operations.global_mcp_server_manager.get_mcp_server_by_id",
             side_effect=mock_get_server_by_id,
         ),
     ):
@@ -4880,7 +4884,7 @@ async def test_list_tools_filters_by_key_team_permissions():
     mock_manager._get_tools_from_server = mock_get_tools_from_server
 
     with patch(
-        "litellm.proxy._experimental.mcp_server.server.global_mcp_server_manager",
+        "litellm.proxy._experimental.mcp_server.operations.global_mcp_server_manager",
         mock_manager,
     ):
         listing = await _get_tools_from_mcp_servers(
@@ -4991,7 +4995,7 @@ async def test_list_tools_with_team_tool_permissions_inheritance():
     mock_manager._get_tools_from_server = mock_get_tools_from_server
 
     with patch(
-        "litellm.proxy._experimental.mcp_server.server.global_mcp_server_manager",
+        "litellm.proxy._experimental.mcp_server.operations.global_mcp_server_manager",
         mock_manager,
     ):
         # Mock the team object permission retrieval
@@ -5083,7 +5087,7 @@ async def test_list_tools_with_no_tool_permissions_shows_all():
     mock_manager._get_tools_from_server = mock_get_tools_from_server
 
     with patch(
-        "litellm.proxy._experimental.mcp_server.server.global_mcp_server_manager",
+        "litellm.proxy._experimental.mcp_server.operations.global_mcp_server_manager",
         mock_manager,
     ):
         listing = await _get_tools_from_mcp_servers(
@@ -5189,7 +5193,7 @@ async def test_list_tools_strips_prefix_when_matching_permissions():
     mock_manager._get_tools_from_server = mock_get_tools_from_server
 
     with patch(
-        "litellm.proxy._experimental.mcp_server.server.global_mcp_server_manager",
+        "litellm.proxy._experimental.mcp_server.operations.global_mcp_server_manager",
         mock_manager,
     ):
         listing = await _get_tools_from_mcp_servers(
@@ -5631,12 +5635,12 @@ async def test_call_mcp_tool_logs_failure_via_post_call_failure_hook():
             return_value=mock_server,
         ),
         patch(
-            "litellm.proxy._experimental.mcp_server.server._get_allowed_mcp_servers_from_mcp_server_names",
+            "litellm.proxy._experimental.mcp_server.operations._get_allowed_mcp_servers_from_mcp_server_names",
             new_callable=AsyncMock,
             return_value=[mock_server],
         ),
         patch(
-            "litellm.proxy._experimental.mcp_server.server.execute_mcp_tool",
+            "litellm.proxy._experimental.mcp_server.operations.execute_mcp_tool",
             new_callable=AsyncMock,
             side_effect=Exception("boom"),
         ),
@@ -5700,26 +5704,26 @@ async def test_get_tools_from_mcp_servers_logs_list_tools_to_spendlogs_when_enab
 
     with (
         patch(
-            "litellm.proxy._experimental.mcp_server.server._get_allowed_mcp_servers",
+            "litellm.proxy._experimental.mcp_server.operations._get_allowed_mcp_servers",
             new=AsyncMock(return_value=[server_a]),
         ),
         patch(
-            "litellm.proxy._experimental.mcp_server.server._prepare_mcp_server_headers",
+            "litellm.proxy._experimental.mcp_server.operations._prepare_mcp_server_headers",
             return_value=(None, None),
         ),
         patch(
-            "litellm.proxy._experimental.mcp_server.server.global_mcp_server_manager",
+            "litellm.proxy._experimental.mcp_server.operations.global_mcp_server_manager",
         ) as mock_manager,
         patch(
-            "litellm.proxy._experimental.mcp_server.server.filter_tools_by_allowed_tools",
+            "litellm.proxy._experimental.mcp_server.operations.filter_tools_by_allowed_tools",
             side_effect=lambda tools, _server: tools,
         ),
         patch(
-            "litellm.proxy._experimental.mcp_server.server.filter_tools_by_key_team_permissions",
+            "litellm.proxy._experimental.mcp_server.operations.filter_tools_by_key_team_permissions",
             new=AsyncMock(side_effect=lambda tools, **_: tools),
         ),
         patch(
-            "litellm.proxy._experimental.mcp_server.server.function_setup",
+            "litellm.proxy._experimental.mcp_server.operations.function_setup",
             side_effect=_capture_function_setup,
         ),
     ):
@@ -5782,26 +5786,26 @@ async def test_get_tools_from_mcp_servers_returns_tools_when_success_logging_fai
 
     with (
         patch(
-            "litellm.proxy._experimental.mcp_server.server._get_allowed_mcp_servers",
+            "litellm.proxy._experimental.mcp_server.operations._get_allowed_mcp_servers",
             new=AsyncMock(return_value=[server_a]),
         ),
         patch(
-            "litellm.proxy._experimental.mcp_server.server._prepare_mcp_server_headers",
+            "litellm.proxy._experimental.mcp_server.operations._prepare_mcp_server_headers",
             return_value=(None, None),
         ),
         patch(
-            "litellm.proxy._experimental.mcp_server.server.global_mcp_server_manager",
+            "litellm.proxy._experimental.mcp_server.operations.global_mcp_server_manager",
         ) as mock_manager,
         patch(
-            "litellm.proxy._experimental.mcp_server.server.filter_tools_by_allowed_tools",
+            "litellm.proxy._experimental.mcp_server.operations.filter_tools_by_allowed_tools",
             side_effect=lambda tools, _server: tools,
         ),
         patch(
-            "litellm.proxy._experimental.mcp_server.server.filter_tools_by_key_team_permissions",
+            "litellm.proxy._experimental.mcp_server.operations.filter_tools_by_key_team_permissions",
             new=AsyncMock(side_effect=lambda tools, **_: tools),
         ),
         patch(
-            "litellm.proxy._experimental.mcp_server.server.function_setup",
+            "litellm.proxy._experimental.mcp_server.operations.function_setup",
             return_value=(dummy_logging_obj, None),
         ),
     ):
@@ -6102,23 +6106,23 @@ async def test_get_tools_from_mcp_servers_injects_stored_oauth2_token():
 
     with (
         patch(
-            "litellm.proxy._experimental.mcp_server.server._get_allowed_mcp_servers",
+            "litellm.proxy._experimental.mcp_server.operations._get_allowed_mcp_servers",
             new=AsyncMock(return_value=[oauth2_server]),
         ),
         patch(
             # Patch the bulk prefetch so no real DB connection is needed
-            "litellm.proxy._experimental.mcp_server.server._prefetch_oauth_creds_for_user",
+            "litellm.proxy._experimental.mcp_server.operations._prefetch_oauth_creds_for_user",
             new=AsyncMock(return_value=prefetched_creds),
         ) as mock_prefetch,
         patch(
-            "litellm.proxy._experimental.mcp_server.server.global_mcp_server_manager",
+            "litellm.proxy._experimental.mcp_server.operations.global_mcp_server_manager",
         ) as mock_manager,
         patch(
-            "litellm.proxy._experimental.mcp_server.server.filter_tools_by_allowed_tools",
+            "litellm.proxy._experimental.mcp_server.operations.filter_tools_by_allowed_tools",
             side_effect=lambda tools, _server: tools,
         ),
         patch(
-            "litellm.proxy._experimental.mcp_server.server.filter_tools_by_key_team_permissions",
+            "litellm.proxy._experimental.mcp_server.operations.filter_tools_by_key_team_permissions",
             new=AsyncMock(side_effect=lambda tools, **_: tools),
         ),
     ):
@@ -6450,7 +6454,7 @@ class TestGatewayCreateInitializationOptions:
 
         with (
             patch(
-                "litellm.proxy._experimental.mcp_server.server._get_allowed_mcp_servers",
+                "litellm.proxy._experimental.mcp_server.operations._get_allowed_mcp_servers",
                 new_callable=AsyncMock,
                 return_value=[scoped_server],
             ),
@@ -6480,7 +6484,7 @@ class TestGatewayCreateInitializationOptions:
         from litellm.proxy._types import UserAPIKeyAuth
 
         with patch(  # test-quality-ok: grant resolution is the input under test
-            "litellm.proxy._experimental.mcp_server.server._get_allowed_mcp_servers",
+            "litellm.proxy._experimental.mcp_server.operations._get_allowed_mcp_servers",
             new_callable=AsyncMock,
             return_value=[],
         ):
@@ -6506,7 +6510,7 @@ class TestGatewayCreateInitializationOptions:
         from litellm.proxy._types import UserAPIKeyAuth
 
         with patch(  # test-quality-ok: grant resolution is the input under test
-            "litellm.proxy._experimental.mcp_server.server._get_allowed_mcp_servers",
+            "litellm.proxy._experimental.mcp_server.operations._get_allowed_mcp_servers",
             new_callable=AsyncMock,
             return_value=[],
         ):
@@ -6531,7 +6535,7 @@ class TestGatewayCreateInitializationOptions:
         from litellm.proxy._types import UserAPIKeyAuth
 
         with patch(  # test-quality-ok: grant resolution is the input under test
-            "litellm.proxy._experimental.mcp_server.server._get_allowed_mcp_servers",
+            "litellm.proxy._experimental.mcp_server.operations._get_allowed_mcp_servers",
             new_callable=AsyncMock,
             return_value=[],
         ):
@@ -6587,7 +6591,7 @@ class TestGatewayCreateInitializationOptions:
                 ),
             ),
             patch(
-                "litellm.proxy._experimental.mcp_server.server._get_allowed_mcp_servers",
+                "litellm.proxy._experimental.mcp_server.operations._get_allowed_mcp_servers",
                 new_callable=AsyncMock,
                 return_value=[scoped_server],
             ),
@@ -6722,14 +6726,14 @@ async def test_list_tools_with_legacy_db_m2m_server_resolves_oauth2_flow():
 
     with (
         patch(
-            "litellm.proxy._experimental.mcp_server.server.global_mcp_server_manager",
+            "litellm.proxy._experimental.mcp_server.operations.global_mcp_server_manager",
         ) as mock_manager,
         patch(
-            "litellm.proxy._experimental.mcp_server.server.filter_tools_by_allowed_tools",
+            "litellm.proxy._experimental.mcp_server.operations.filter_tools_by_allowed_tools",
             side_effect=lambda tools, _server: tools,
         ),
         patch(
-            "litellm.proxy._experimental.mcp_server.server.filter_tools_by_key_team_permissions",
+            "litellm.proxy._experimental.mcp_server.operations.filter_tools_by_key_team_permissions",
             new=AsyncMock(side_effect=lambda tools, **_: tools),
         ),
     ):
@@ -6992,7 +6996,7 @@ def _patch_delegate_resolver(server: MCPServer, *resolvable_names: str):
         return server if name in resolvable_names else None
 
     return patch(
-        "litellm.proxy._experimental.mcp_server.server.global_mcp_server_manager.get_mcp_server_by_name",
+        "litellm.proxy._experimental.mcp_server.operations.global_mcp_server_manager.get_mcp_server_by_name",
         side_effect=_resolve,
     )
 
@@ -7011,7 +7015,7 @@ async def test_legacy_delegate_bare_token_is_not_probed_upstream():  # test-qual
     with (
         _patch_delegate_resolver(server, "delegate_test"),
         patch(
-            "litellm.proxy._experimental.mcp_server.server._get_allowed_mcp_servers",
+            "litellm.proxy._experimental.mcp_server.operations._get_allowed_mcp_servers",
             new=AsyncMock(return_value=[server]),
         ),
         patch(
@@ -7047,7 +7051,7 @@ async def test_legacy_delegate_dual_credentials_are_not_probed_upstream():  # te
 
     with (
         patch(  # test-quality-ok: isolate authorized-server resolution so this test targets the preflight boundary
-            "litellm.proxy._experimental.mcp_server.server._get_allowed_mcp_servers",
+            "litellm.proxy._experimental.mcp_server.operations._get_allowed_mcp_servers",
             new=AsyncMock(return_value=[server]),
         ),
         patch(  # test-quality-ok: the removed probe call is the security regression under test
@@ -7094,7 +7098,7 @@ async def test_oauth_passthrough_preflight_preserves_status_contract(probe_statu
 
     with (
         patch(  # test-quality-ok: isolate authorized-server resolution so this test exercises the preflight contract
-            "litellm.proxy._experimental.mcp_server.server._get_allowed_mcp_servers",
+            "litellm.proxy._experimental.mcp_server.operations._get_allowed_mcp_servers",
             new=AsyncMock(return_value=[server]),
         ),
         patch(  # test-quality-ok: the upstream transport boundary is the behavior being mapped to an HTTP response
@@ -7140,7 +7144,7 @@ async def test_delegate_tokenless_request_not_probed():
     with (
         _patch_delegate_resolver(server, "delegate_test"),
         patch(
-            "litellm.proxy._experimental.mcp_server.server._get_allowed_mcp_servers",
+            "litellm.proxy._experimental.mcp_server.operations._get_allowed_mcp_servers",
             new=AsyncMock(return_value=[server]),
         ),
         patch(
@@ -7173,7 +7177,7 @@ async def test_delegate_preflight_skipped_on_multi_server_routes():
     with (
         _patch_delegate_resolver(servers[0], "delegate_test", "other_server"),
         patch(
-            "litellm.proxy._experimental.mcp_server.server._get_allowed_mcp_servers",
+            "litellm.proxy._experimental.mcp_server.operations._get_allowed_mcp_servers",
             new=AsyncMock(return_value=servers),
         ),
         patch(
@@ -7216,7 +7220,7 @@ async def test_bare_authorization_never_probes_passthrough_servers():
     with (
         _patch_delegate_resolver(passthrough_server, "pt_server"),
         patch(
-            "litellm.proxy._experimental.mcp_server.server._get_allowed_mcp_servers",
+            "litellm.proxy._experimental.mcp_server.operations._get_allowed_mcp_servers",
             new=AsyncMock(return_value=[passthrough_server]),
         ),
         patch(
@@ -7262,7 +7266,7 @@ async def test_delegate_not_probed_when_named_only_via_server_id():
     with (
         _patch_delegate_resolver(server, "delegate_test"),
         patch(
-            "litellm.proxy._experimental.mcp_server.server._get_allowed_mcp_servers",
+            "litellm.proxy._experimental.mcp_server.operations._get_allowed_mcp_servers",
             new=AsyncMock(return_value=[server]),
         ),
         patch(
@@ -7295,7 +7299,7 @@ async def test_delegate_probe_not_fanned_out_to_access_group_members():
     with (
         _patch_delegate_resolver(group_member, "delegate_test"),
         patch(
-            "litellm.proxy._experimental.mcp_server.server._get_allowed_mcp_servers",
+            "litellm.proxy._experimental.mcp_server.operations._get_allowed_mcp_servers",
             new=AsyncMock(return_value=[group_member]),
         ),
         patch(
@@ -7391,11 +7395,11 @@ async def test_execute_mcp_tool_rest_server_id_authoritative_for_unprefixed_tool
 
     with (
         patch.dict(
-            mcp_module.global_mcp_server_manager.tool_name_to_mcp_server_name_mapping,
+            mcp_operations.global_mcp_server_manager.tool_name_to_mcp_server_name_mapping,
             {"echo": oauth_server.name},
         ),
         patch.object(
-            mcp_module.global_mcp_server_manager,
+            mcp_operations.global_mcp_server_manager,
             "get_registry",
             return_value={
                 api_key_server.server_id: api_key_server,
@@ -7403,13 +7407,12 @@ async def test_execute_mcp_tool_rest_server_id_authoritative_for_unprefixed_tool
             },
         ),
         patch.object(
-            mcp_module.global_mcp_server_manager,
+            mcp_operations.global_mcp_server_manager,
             "_get_mcp_server_from_tool_name",
             return_value=oauth_server,
         ),
         patch.object(
-            mcp_module,
-            "_handle_managed_mcp_tool",
+            mcp_operations, "_handle_managed_mcp_tool",
             new=fake_handle_managed_mcp_tool,
         ),
         patch.object(
@@ -7418,12 +7421,12 @@ async def test_execute_mcp_tool_rest_server_id_authoritative_for_unprefixed_tool
             return_value=True,
         ),
         patch.object(
-            mcp_module.global_mcp_tool_registry,
+            mcp_operations.global_mcp_tool_registry,
             "get_tool",
             return_value=None,
         ),
     ):
-        await mcp_module.execute_mcp_tool(
+        await mcp_operations.execute_mcp_tool(
             name="echo",
             arguments={"message": "hello"},
             allowed_mcp_servers=[api_key_server, oauth_server],
@@ -7456,7 +7459,7 @@ def _worker_that_never_listed(server: MCPServer, upstream_tools: tuple[str, ...]
 
     from litellm.proxy._experimental.mcp_server import server as mcp_module
 
-    mcp_module.global_mcp_server_manager.registry[server.server_id] = server
+    mcp_operations.global_mcp_server_manager.registry[server.server_id] = server
     dispatched: dict[str, object] = {}
 
     async def fake_handle_managed_mcp_tool(**kwargs):
@@ -7468,17 +7471,17 @@ def _worker_that_never_listed(server: MCPServer, upstream_tools: tuple[str, ...]
 
     with (
         patch.object(  # test-quality-ok: the upstream MCP session is the boundary; a real one needs an initialize handshake over a live server
-            mcp_module.global_mcp_server_manager,
+            mcp_operations.global_mcp_server_manager,
             "_create_mcp_client",
             new=AsyncMock(return_value=MagicMock()),
         ) as create_client,
         patch.object(  # test-quality-ok: same boundary, this is the tools/list answer the upstream would give
-            mcp_module.global_mcp_server_manager,
+            mcp_operations.global_mcp_server_manager,
             "_fetch_tools_with_timeout",
             side_effect=fake_fetch_tools,
         ) as fetch_tools,
         patch.object(  # test-quality-ok: records the resolved server and bare name the managed call would forward upstream
-            mcp_module, "_handle_managed_mcp_tool", new=fake_handle_managed_mcp_tool
+            mcp_operations, "_handle_managed_mcp_tool", new=fake_handle_managed_mcp_tool
         ),
     ):
         yield SimpleNamespace(create_client=create_client, fetch_tools=fetch_tools, dispatched=dispatched)
@@ -7492,7 +7495,7 @@ async def test_execute_mcp_tool_lists_never_listed_passthrough_server_with_calle
 
     server = _never_listed_passthrough_server()
     with _worker_that_never_listed(server, upstream_tools=("add",)) as worker:
-        await mcp_module.execute_mcp_tool(
+        await mcp_operations.execute_mcp_tool(
             name="lazy_map-add",
             arguments={"a": 1, "b": 2},
             allowed_mcp_servers=[server],
@@ -7513,7 +7516,7 @@ async def test_execute_mcp_tool_rest_server_id_lists_never_listed_server_first()
 
     server = _never_listed_passthrough_server()
     with _worker_that_never_listed(server, upstream_tools=("add",)) as worker:
-        await mcp_module.execute_mcp_tool(
+        await mcp_operations.execute_mcp_tool(
             name="add",
             arguments={"a": 1, "b": 2},
             allowed_mcp_servers=[server],
@@ -7536,7 +7539,7 @@ async def test_execute_mcp_tool_unknown_tool_on_never_listed_server_lists_once_t
         _worker_that_never_listed(server, upstream_tools=("add",)) as worker,
         pytest.raises(HTTPException) as exc_info,
     ):
-        await mcp_module.execute_mcp_tool(
+        await mcp_operations.execute_mcp_tool(
             name="lazy_map-nope",
             arguments={},
             allowed_mcp_servers=[server],
@@ -7557,8 +7560,8 @@ async def test_execute_mcp_tool_does_not_relist_a_server_this_worker_already_lis
 
     server = _never_listed_passthrough_server()
     with _worker_that_never_listed(server, upstream_tools=("add",)) as worker:
-        mcp_module.global_mcp_server_manager._create_prefixed_tools([MCPTool(name="add", inputSchema={})], server)
-        await mcp_module.execute_mcp_tool(
+        mcp_operations.global_mcp_server_manager._create_prefixed_tools([MCPTool(name="add", inputSchema={})], server)
+        await mcp_operations.execute_mcp_tool(
             name="lazy_map-add",
             arguments={"a": 1, "b": 2},
             allowed_mcp_servers=[server],
@@ -7580,8 +7583,8 @@ async def test_execute_mcp_tool_lists_a_tool_this_worker_has_not_yet_seen_on_a_l
 
     server = _never_listed_passthrough_server()
     with _worker_that_never_listed(server, upstream_tools=("add", "multiply")) as worker:
-        mcp_module.global_mcp_server_manager._create_prefixed_tools([MCPTool(name="add", inputSchema={})], server)
-        await mcp_module.execute_mcp_tool(
+        mcp_operations.global_mcp_server_manager._create_prefixed_tools([MCPTool(name="add", inputSchema={})], server)
+        await mcp_operations.execute_mcp_tool(
             name="lazy_map-multiply",
             arguments={"a": 1, "b": 2},
             allowed_mcp_servers=[server],
@@ -7604,7 +7607,7 @@ async def test_execute_mcp_tool_never_lists_a_server_the_caller_cannot_access():
         _worker_that_never_listed(server, upstream_tools=("add",)) as worker,
         pytest.raises(HTTPException) as exc_info,
     ):
-        await mcp_module.execute_mcp_tool(
+        await mcp_operations.execute_mcp_tool(
             name="lazy_map-add",
             arguments={"a": 1, "b": 2},
             allowed_mcp_servers=[other_server],
@@ -7650,13 +7653,12 @@ async def test_execute_mcp_tool_strips_a_prefix_that_contains_the_separator():
 
     with (
         patch.object(
-            mcp_module.global_mcp_server_manager,
+            mcp_operations.global_mcp_server_manager,
             "_get_mcp_server_from_tool_name",
             return_value=alias_less_server,
         ),
         patch.object(
-            mcp_module,
-            "_handle_managed_mcp_tool",
+            mcp_operations, "_handle_managed_mcp_tool",
             new=fake_handle_managed_mcp_tool,
         ),
         patch.object(
@@ -7665,12 +7667,12 @@ async def test_execute_mcp_tool_strips_a_prefix_that_contains_the_separator():
             return_value=True,
         ),
         patch.object(
-            mcp_module.global_mcp_tool_registry,
+            mcp_operations.global_mcp_tool_registry,
             "get_tool",
             return_value=None,
         ),
     ):
-        await mcp_module.execute_mcp_tool(
+        await mcp_operations.execute_mcp_tool(
             name=f"{server_id}-read_wiki_contents",
             arguments={"repoName": "acme/wiki"},
             allowed_mcp_servers=[alias_less_server],
@@ -7724,11 +7726,11 @@ async def test_execute_mcp_tool_rest_server_id_injects_requested_server_credenti
 
     with (
         patch.dict(
-            mcp_module.global_mcp_server_manager.tool_name_to_mcp_server_name_mapping,
+            mcp_operations.global_mcp_server_manager.tool_name_to_mcp_server_name_mapping,
             {"echo": collision_server.name, "echo_requested-echo": requested_server.name},
         ),
         patch.object(
-            mcp_module.global_mcp_server_manager,
+            mcp_operations.global_mcp_server_manager,
             "get_registry",
             return_value={
                 requested_server.server_id: requested_server,
@@ -7736,7 +7738,7 @@ async def test_execute_mcp_tool_rest_server_id_injects_requested_server_credenti
             },
         ),
         patch.object(
-            mcp_module.global_mcp_server_manager,
+            mcp_operations.global_mcp_server_manager,
             "_create_mcp_client",
             new=fake_create_mcp_client,
         ),
@@ -7746,13 +7748,13 @@ async def test_execute_mcp_tool_rest_server_id_injects_requested_server_credenti
             return_value=True,
         ),
         patch.object(
-            mcp_module.global_mcp_tool_registry,
+            mcp_operations.global_mcp_tool_registry,
             "get_tool",
             return_value=None,
         ),
         patch("litellm.proxy.proxy_server.proxy_logging_obj", None),
     ):
-        await mcp_module.execute_mcp_tool(
+        await mcp_operations.execute_mcp_tool(
             name="echo",
             arguments={"message": "hello"},
             allowed_mcp_servers=[requested_server, collision_server],
@@ -7795,7 +7797,7 @@ async def test_execute_mcp_tool_rest_prefixed_tool_still_validates_server_id():
 
     with (
         patch.object(
-            mcp_module.global_mcp_server_manager,
+            mcp_operations.global_mcp_server_manager,
             "get_registry",
             return_value={
                 api_key_server.server_id: api_key_server,
@@ -7803,7 +7805,7 @@ async def test_execute_mcp_tool_rest_prefixed_tool_still_validates_server_id():
             },
         ),
         patch.object(
-            mcp_module.global_mcp_server_manager,
+            mcp_operations.global_mcp_server_manager,
             "_get_mcp_server_from_tool_name",
             return_value=oauth_server,
         ),
@@ -7813,13 +7815,13 @@ async def test_execute_mcp_tool_rest_prefixed_tool_still_validates_server_id():
             return_value=True,
         ),
         patch.object(
-            mcp_module.global_mcp_tool_registry,
+            mcp_operations.global_mcp_tool_registry,
             "get_tool",
             return_value=None,
         ),
         pytest.raises(HTTPException) as exc_info,
     ):
-        await mcp_module.execute_mcp_tool(
+        await mcp_operations.execute_mcp_tool(
             name="echo_oauth_m2m-echo",
             arguments={"message": "hello"},
             allowed_mcp_servers=[api_key_server, oauth_server],
@@ -7857,7 +7859,7 @@ async def test_execute_mcp_tool_rest_unauthorized_prefix_still_mismatches():
 
     with (
         patch.object(
-            mcp_module.global_mcp_server_manager,
+            mcp_operations.global_mcp_server_manager,
             "get_registry",
             return_value={
                 api_key_server.server_id: api_key_server,
@@ -7865,7 +7867,7 @@ async def test_execute_mcp_tool_rest_unauthorized_prefix_still_mismatches():
             },
         ),
         patch.object(
-            mcp_module.global_mcp_server_manager,
+            mcp_operations.global_mcp_server_manager,
             "_get_mcp_server_from_tool_name",
             return_value=restricted_server,
         ),
@@ -7875,13 +7877,13 @@ async def test_execute_mcp_tool_rest_unauthorized_prefix_still_mismatches():
             return_value=True,
         ),
         patch.object(
-            mcp_module.global_mcp_tool_registry,
+            mcp_operations.global_mcp_tool_registry,
             "get_tool",
             return_value=None,
         ),
         pytest.raises(HTTPException) as exc_info,
     ):
-        await mcp_module.execute_mcp_tool(
+        await mcp_operations.execute_mcp_tool(
             name="restricted_server-echo",
             arguments={"message": "hello"},
             allowed_mcp_servers=[api_key_server],
@@ -7921,18 +7923,17 @@ async def test_execute_mcp_tool_rest_hyphenated_upstream_tool_name_routes_to_req
 
     with (
         patch.object(
-            mcp_module.global_mcp_server_manager,
+            mcp_operations.global_mcp_server_manager,
             "get_registry",
             return_value={api_key_server.server_id: api_key_server},
         ),
         patch.object(
-            mcp_module.global_mcp_server_manager,
+            mcp_operations.global_mcp_server_manager,
             "_get_mcp_server_from_tool_name",
             return_value=None,
         ),
         patch.object(
-            mcp_module,
-            "_handle_managed_mcp_tool",
+            mcp_operations, "_handle_managed_mcp_tool",
             new=fake_handle_managed_mcp_tool,
         ),
         patch.object(
@@ -7941,12 +7942,12 @@ async def test_execute_mcp_tool_rest_hyphenated_upstream_tool_name_routes_to_req
             return_value=True,
         ),
         patch.object(
-            mcp_module.global_mcp_tool_registry,
+            mcp_operations.global_mcp_tool_registry,
             "get_tool",
             return_value=None,
         ),
     ):
-        await mcp_module.execute_mcp_tool(
+        await mcp_operations.execute_mcp_tool(
             name="text-to-speech",
             arguments={"message": "hello"},
             allowed_mcp_servers=[api_key_server],
@@ -8005,22 +8006,22 @@ async def test_execute_mcp_tool_sets_model_in_model_call_details():
 
     with (
         patch.object(
-            mcp_module.global_mcp_server_manager,
+            mcp_operations.global_mcp_server_manager,
             "_get_mcp_server_from_tool_name",
             return_value=fake_server,
         ),
         patch.object(
-            mcp_module.global_mcp_server_manager,
+            mcp_operations.global_mcp_server_manager,
             "pre_call_tool_check",
             new=AsyncMock(return_value={}),
         ),
         patch.object(
-            mcp_module.global_mcp_tool_registry,
+            mcp_operations.global_mcp_tool_registry,
             "get_tool",
             return_value=fake_tool,
         ),
         patch(
-            "litellm.proxy._experimental.mcp_server.server._handle_local_mcp_tool",
+            "litellm.proxy._experimental.mcp_server.operations._handle_local_mcp_tool",
             new=AsyncMock(return_value=[]),
         ),
         patch(
@@ -8028,7 +8029,7 @@ async def test_execute_mcp_tool_sets_model_in_model_call_details():
             return_value=True,
         ),
     ):
-        await mcp_module.execute_mcp_tool(
+        await mcp_operations.execute_mcp_tool(
             name="list_pets",
             arguments={"limit": 10},
             allowed_mcp_servers=[fake_server],
@@ -8084,7 +8085,7 @@ async def test_execute_mcp_tool_rest_unresolved_prefixed_name_routes_to_requeste
 
     with (
         patch.object(
-            mcp_module.global_mcp_server_manager,
+            mcp_operations.global_mcp_server_manager,
             "get_registry",
             return_value={
                 requested_server.server_id: requested_server,
@@ -8092,13 +8093,12 @@ async def test_execute_mcp_tool_rest_unresolved_prefixed_name_routes_to_requeste
             },
         ),
         patch.object(
-            mcp_module.global_mcp_server_manager,
+            mcp_operations.global_mcp_server_manager,
             "_get_mcp_server_from_tool_name",
             return_value=None,
         ),
         patch.object(
-            mcp_module,
-            "_handle_managed_mcp_tool",
+            mcp_operations, "_handle_managed_mcp_tool",
             new=fake_handle_managed_mcp_tool,
         ),
         patch.object(
@@ -8107,12 +8107,12 @@ async def test_execute_mcp_tool_rest_unresolved_prefixed_name_routes_to_requeste
             return_value=True,
         ),
         patch.object(
-            mcp_module.global_mcp_tool_registry,
+            mcp_operations.global_mcp_tool_registry,
             "get_tool",
             return_value=None,
         ),
     ):
-        await mcp_module.execute_mcp_tool(
+        await mcp_operations.execute_mcp_tool(
             name="known_prefix-list_things",
             arguments={"message": "hello"},
             allowed_mcp_servers=[requested_server, prefix_owner],
@@ -8164,7 +8164,7 @@ async def test_execute_mcp_tool_rest_prefix_retry_resolution_still_enforces_serv
 
     with (
         patch.object(
-            mcp_module.global_mcp_server_manager,
+            mcp_operations.global_mcp_server_manager,
             "get_registry",
             return_value={
                 requested_server.server_id: requested_server,
@@ -8172,7 +8172,7 @@ async def test_execute_mcp_tool_rest_prefix_retry_resolution_still_enforces_serv
             },
         ),
         patch.object(
-            mcp_module.global_mcp_server_manager,
+            mcp_operations.global_mcp_server_manager,
             "_get_mcp_server_from_tool_name",
             side_effect=resolve_only_when_requested_prefix_added,
         ),
@@ -8182,13 +8182,13 @@ async def test_execute_mcp_tool_rest_prefix_retry_resolution_still_enforces_serv
             return_value=True,
         ),
         patch.object(
-            mcp_module.global_mcp_tool_registry,
+            mcp_operations.global_mcp_tool_registry,
             "get_tool",
             return_value=None,
         ),
         pytest.raises(HTTPException) as exc_info,
     ):
-        await mcp_module.execute_mcp_tool(
+        await mcp_operations.execute_mcp_tool(
             name="known_prefix-echo",
             arguments={"message": "hello"},
             allowed_mcp_servers=[requested_server, prefix_owner],
@@ -9091,14 +9091,14 @@ async def test_call_tool_with_legacy_db_m2m_server_resolves_oauth2_flow():
 
     with (
         patch(
-            "litellm.proxy._experimental.mcp_server.server.global_mcp_server_manager",
+            "litellm.proxy._experimental.mcp_server.operations.global_mcp_server_manager",
         ) as mock_manager,
         patch(
-            "litellm.proxy._experimental.mcp_server.server.execute_mcp_tool",
+            "litellm.proxy._experimental.mcp_server.operations.execute_mcp_tool",
             side_effect=capture_execute,
         ),
         patch(
-            "litellm.proxy._experimental.mcp_server.server._get_allowed_mcp_servers_from_mcp_server_names",
+            "litellm.proxy._experimental.mcp_server.operations._get_allowed_mcp_servers_from_mcp_server_names",
             new=AsyncMock(side_effect=lambda mcp_servers, allowed_mcp_servers: allowed_mcp_servers),
         ),
     ):
@@ -9176,12 +9176,12 @@ async def test_call_mcp_tool_skips_failure_hook_for_upstream_auth_error():
         ),
         patch.object(global_mcp_server_manager, "get_mcp_server_by_id", return_value=mock_server),
         patch(
-            "litellm.proxy._experimental.mcp_server.server._get_allowed_mcp_servers_from_mcp_server_names",
+            "litellm.proxy._experimental.mcp_server.operations._get_allowed_mcp_servers_from_mcp_server_names",
             new_callable=AsyncMock,
             return_value=[mock_server],
         ),
         patch(
-            "litellm.proxy._experimental.mcp_server.server.execute_mcp_tool",
+            "litellm.proxy._experimental.mcp_server.operations.execute_mcp_tool",
             new_callable=AsyncMock,
             side_effect=MCPUpstreamAuthError(status_code=401, www_authenticate="Bearer", server_name="test_server"),
         ),
@@ -9261,7 +9261,7 @@ async def test_aggregate_listing_reports_per_server_outcomes():
     mock_manager._get_tools_from_server = mock_get_tools_from_server
 
     with patch(
-        "litellm.proxy._experimental.mcp_server.server.global_mcp_server_manager",
+        "litellm.proxy._experimental.mcp_server.operations.global_mcp_server_manager",
         mock_manager,
     ):
         listing = await _get_tools_from_mcp_servers(
@@ -9335,7 +9335,7 @@ async def test_handle_list_tools_attaches_outcome_meta(_mcp_request_ctx):
             new=AsyncMock(return_value=(None, None, None, None, None, None, None)),
         ),
         patch(
-            "litellm.proxy._experimental.mcp_server.server._list_mcp_tools",
+            "litellm.proxy._experimental.mcp_server.operations._list_mcp_tools",
             new=AsyncMock(return_value=listing),
         ),
     ):
@@ -9401,12 +9401,12 @@ class TestPreemptive401ModeAware:
 
         with (
             patch.object(
-                server_module.global_mcp_server_manager,
+                mcp_operations.global_mcp_server_manager,
                 "get_mcp_server_by_name",
                 return_value=server,
             ),
             patch.object(
-                server_module.global_mcp_server_manager,
+                mcp_operations.global_mcp_server_manager,
                 "has_user_oauth_token",
                 new_callable=AsyncMock,
                 return_value=has_stored_token,
@@ -9425,7 +9425,7 @@ class TestPreemptive401ModeAware:
     async def test_deferred_discovery_runs_before_delegate_challenge(self):
         from litellm.proxy._experimental.mcp_server import server as server_module
 
-        manager = server_module.global_mcp_server_manager
+        manager = mcp_operations.global_mcp_server_manager
         server = _make_oauth2_server(
             "lazy_delegate",
             oauth2_flow="authorization_code",
@@ -9457,7 +9457,7 @@ class TestPreemptive401ModeAware:
     async def test_stamped_m2m_challenge_skips_deferred_discovery(self):
         from litellm.proxy._experimental.mcp_server import server as server_module
 
-        manager = server_module.global_mcp_server_manager
+        manager = mcp_operations.global_mcp_server_manager
         server = _make_oauth2_server("stamped_m2m", oauth2_flow="client_credentials")
 
         with patch.object(
@@ -9500,12 +9500,12 @@ class TestPreemptive401ModeAware:
         with (
             patch.dict(os.environ, {"SERVER_ROOT_PATH": "/litellm"}),
             patch.object(
-                server_module.global_mcp_server_manager,
+                mcp_operations.global_mcp_server_manager,
                 "get_mcp_server_by_name",
                 return_value=server,
             ),
             patch.object(
-                server_module.global_mcp_server_manager,
+                mcp_operations.global_mcp_server_manager,
                 "has_user_oauth_token",
                 new_callable=AsyncMock,
                 return_value=False,
@@ -9607,17 +9607,17 @@ class TestSingleServerPreflightReachesIdJag:
 
         with (
             patch.object(  # test-quality-ok: route wiring must use the manager's configured server
-                server_module.global_mcp_server_manager,
+                mcp_operations.global_mcp_server_manager,
                 "get_mcp_server_by_name",
                 return_value=server,
             ),
             patch.object(  # test-quality-ok: route wiring must invoke the manager preflight
-                server_module.global_mcp_server_manager,
+                mcp_operations.global_mcp_server_manager,
                 "preflight_token_exchange",
                 preflight,
             ),
             patch.object(  # test-quality-ok: allowed-set resolution needs the DB; the test controls its answer
-                server_module, "_get_allowed_mcp_servers", AsyncMock(return_value=[server])
+                mcp_operations, "_get_allowed_mcp_servers", AsyncMock(return_value=[server])
             ),
         ):
             await server_module._raise_preemptive_401_for_unauthenticated_servers(
@@ -9667,12 +9667,12 @@ class TestSingleServerPreflightReachesIdJag:
 
         with (
             patch.object(  # test-quality-ok: route wiring must use the manager's configured server
-                server_module.global_mcp_server_manager,
+                mcp_operations.global_mcp_server_manager,
                 "get_mcp_server_by_name",
                 return_value=token_exchange,
             ),
             patch.object(  # test-quality-ok: route wiring must invoke the manager preflight
-                server_module.global_mcp_server_manager,
+                mcp_operations.global_mcp_server_manager,
                 "preflight_token_exchange",
                 preflight,
             ),
@@ -9733,13 +9733,13 @@ class TestOboPreflightScopedToAllowedServers:
         preflight = AsyncMock()
         with (
             patch.object(  # test-quality-ok: route handler reads the module-level manager, no injection seam
-                server_module.global_mcp_server_manager, "get_mcp_server_by_name", return_value=requested
+                mcp_operations.global_mcp_server_manager, "get_mcp_server_by_name", return_value=requested
             ),
             patch.object(  # test-quality-ok: the exchanger is the observable; a real one would call an IdP
-                server_module.global_mcp_server_manager, "preflight_token_exchange", preflight
+                mcp_operations.global_mcp_server_manager, "preflight_token_exchange", preflight
             ),
             patch.object(  # test-quality-ok: allowed-set resolution needs the DB; the test controls its answer
-                server_module, "_get_allowed_mcp_servers", allowed_lookup
+                mcp_operations, "_get_allowed_mcp_servers", allowed_lookup
             ),
         ):
             await server_module._raise_preemptive_401_for_unauthenticated_servers(
@@ -10048,7 +10048,7 @@ class TestListFiltersHonorThePrefixBoundary:
 
         with (
             patch.object(MCPRequestHandler, "get_allowed_tools_for_server", AsyncMock(return_value=grants)),
-            patch("litellm.proxy._experimental.mcp_server.server.global_mcp_server_manager") as mock_manager,
+            patch("litellm.proxy._experimental.mcp_server.operations.global_mcp_server_manager") as mock_manager,
         ):
             mock_manager.get_mcp_server_by_id.return_value = server
 
@@ -10111,11 +10111,11 @@ async def test_list_tools_injects_byok_credential_for_non_oauth2_auth_types(auth
 
     with (
         patch(
-            "litellm.proxy._experimental.mcp_server.server.global_mcp_server_manager",
+            "litellm.proxy._experimental.mcp_server.operations.global_mcp_server_manager",
             mock_manager,
         ),
         patch(
-            "litellm.proxy._experimental.mcp_server.server._get_byok_credential",
+            "litellm.proxy._experimental.mcp_server.operations._get_byok_credential",
             AsyncMock(return_value="personal-api-key"),
         ),
     ):
@@ -10208,3 +10208,44 @@ async def test_streamable_http_rejects_modern_protocol_version(header_value: str
     assert header_value in body["error"]["message"]
     for version in body["error"]["message"].split("supported: ")[1].split(", "):
         assert version in HANDSHAKE_PROTOCOL_VERSIONS
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("handler_name,field", [
+    ("handle_list_tools", "tools"),
+    ("list_prompts", "prompts"),
+    ("list_resources", "resources"),
+    ("list_resource_templates", "resource_templates"),
+])
+async def test_native_listing_preserves_empty_result_on_auth_failure(_mcp_request_ctx, handler_name, field):
+    from litellm.proxy._experimental.mcp_server import server
+
+    with patch.object(server, "get_or_extract_auth_context", AsyncMock(side_effect=RuntimeError("auth failure"))):
+        result = await getattr(server, handler_name)(_mcp_request_ctx(), _paged_params())
+    assert getattr(result, field) == []
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("failure_hook_raises", [False, True])
+async def test_tool_listing_preserves_permission_denial_when_failure_logging_fails(failure_hook_raises):
+    from litellm.proxy._experimental.mcp_server import operations
+    from litellm.proxy import proxy_server
+
+    auth = UserAPIKeyAuth(user_id="denied-caller")
+    denial = HTTPException(status_code=403, detail="scope denied")
+    logger = MagicMock()
+    logger.post_call_failure_hook = AsyncMock(side_effect=RuntimeError("log unavailable") if failure_hook_raises else None)
+    upstream = AsyncMock()
+    with (
+        patch.object(operations, "_get_allowed_mcp_servers", AsyncMock(side_effect=denial)),
+        patch.object(operations, "function_setup", return_value=(None, None)),
+        patch.object(proxy_server, "proxy_logging_obj", logger),
+        patch.object(operations.global_mcp_server_manager, "_get_tools_from_server", upstream),
+    ):
+        with pytest.raises(HTTPException) as rejected:
+            await operations._get_tools_from_mcp_servers(user_api_key_auth=auth, mcp_auth_header=None, mcp_servers=["catalog"], log_list_tools_to_spendlogs=True)
+    assert rejected.value is denial
+    upstream.assert_not_awaited()
+    logger.post_call_failure_hook.assert_awaited_once()
+    assert logger.post_call_failure_hook.await_args.kwargs["original_exception"] is denial
+    assert logger.post_call_failure_hook.await_args.kwargs["user_api_key_dict"] == auth
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 9140ac61f1a..7be79f9b514 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
@@ -71,6 +71,135 @@ from litellm.proxy.utils import ProxyLogging
 from litellm.types.guardrails import GuardrailEventHooks
 
 
+@pytest.mark.asyncio
+async def test_manager_sampling_preserves_explicit_headers_without_ambient_context():
+    from litellm.proxy._experimental.mcp_server import server as legacy_server
+
+    caller = UserAPIKeyAuth(user_id="sampling-caller")
+    upstream = MCPServer(
+        server_id="sampling-context",
+        name="sampling_context",
+        url="https://example.invalid/mcp",
+        transport=MCPTransport.http,
+        allow_sampling=True,
+    )
+    sampling = AsyncMock()
+    client = MagicMock()
+    client.call_tool = AsyncMock(return_value=CallToolResult(content=[]))
+    assert legacy_server.get_active_auth_context() is None
+    with (
+        patch("litellm.proxy._experimental.mcp_server.mcp_server_manager.MCPClient", return_value=client) as factory,
+        patch("litellm.proxy._experimental.mcp_server.sampling_handler.handle_sampling_create_message", sampling),
+    ):
+        await MCPServerManager()._call_regular_mcp_tool(
+            mcp_server=upstream,
+            original_tool_name="probe",
+            arguments={},
+            tasks=[],
+            mcp_auth_header=None,
+            mcp_server_auth_headers=None,
+            oauth2_headers=None,
+            raw_headers={"x-test-caller": "sampling-caller"},
+            proxy_logging_obj=None,
+            user_api_key_auth=caller,
+        )
+        callback = factory.call_args.kwargs["sampling_callback"]
+        await callback(None, None)
+    assert sampling.await_args.kwargs["user_api_key_auth"].user_id == "sampling-caller"
+    assert sampling.await_args.kwargs["raw_headers"] == {"x-test-caller": "sampling-caller"}
+
+
+
+@pytest.mark.asyncio
+async def test_sampling_callback_keeps_creation_context_after_caller_switch():
+    from mcp.server.auth.middleware.auth_context import auth_context_var
+
+    from litellm.proxy._experimental.mcp_server import server as legacy_server
+    from litellm.proxy._experimental.mcp_server.mcp_server_manager import _create_sampling_callback
+
+    token = auth_context_var.set(None)
+    recorder = AsyncMock()
+    try:
+        original = UserAPIKeyAuth(user_id="alpha", models=["alpha-model"])
+        original.mcp_admitted_user_subject = True
+        headers = {"x-caller": "alpha"}
+        legacy_server.set_auth_context(original, raw_headers=headers, client_ip="192.0.2.1")
+        callback = _create_sampling_callback()
+        original.models.append("bravo-model")
+        headers["x-caller"] = "bravo"
+        legacy_server.set_auth_context(UserAPIKeyAuth(user_id="bravo"), raw_headers={"x-caller": "bravo"})
+        with patch("litellm.proxy._experimental.mcp_server.sampling_handler.handle_sampling_create_message", recorder):
+            await callback(None, None)
+        observed = recorder.await_args.kwargs
+        assert observed["user_api_key_auth"].user_id == "alpha"
+        assert observed["user_api_key_auth"].models == ["alpha-model"]
+        assert observed["user_api_key_auth"].mcp_admitted_user_subject is True
+        assert observed["raw_headers"] == {"x-caller": "alpha"}
+        assert observed["client_ip"] == "192.0.2.1"
+    finally:
+        auth_context_var.reset(token)
+
+
+@pytest.mark.asyncio
+async def test_elicitation_callback_keeps_initiating_session():
+    from litellm.proxy._experimental.mcp_server import server as legacy_server
+    from litellm.proxy._experimental.mcp_server.mcp_server_manager import _create_elicitation_callback
+
+    initiating = MagicMock()
+    replacement = MagicMock()
+    recorder = AsyncMock()
+    token = legacy_server.active_mcp_session_var.set(initiating)
+    try:
+        callback = _create_elicitation_callback()
+        legacy_server.active_mcp_session_var.set(replacement)
+        with patch("litellm.proxy._experimental.mcp_server.elicitation_handler.handle_elicitation_request", recorder):
+            await callback(None, None)
+        assert recorder.await_args.kwargs["downstream_session"] is initiating
+        assert recorder.await_args.kwargs["downstream_capabilities"] is initiating.capabilities
+    finally:
+        legacy_server.active_mcp_session_var.reset(token)
+
+
+@pytest.mark.asyncio
+async def test_sampling_callbacks_isolate_callers_and_cancellation():
+    from mcp.types import ErrorData
+
+    from litellm.proxy._experimental.mcp_server.mcp_server_manager import _create_sampling_callback
+
+    started = asyncio.Event()
+    cancelled = asyncio.Event()
+    observed = {}
+
+    async def record_sampling(*, user_api_key_auth, raw_headers, **kwargs):
+        label = user_api_key_auth.user_id
+        if label == "cancelled":
+            started.set()
+            try:
+                await asyncio.Event().wait()
+            except asyncio.CancelledError:
+                cancelled.set()
+                raise
+        await asyncio.sleep(0)
+        observed[label] = raw_headers["x-caller"]
+        return ErrorData(code=-1, message=label)
+
+    callbacks = tuple(
+        _create_sampling_callback(UserAPIKeyAuth(user_id=label), raw_headers={"x-caller": label})
+        for label in ("alpha", "bravo", "cancelled")
+    )
+    with patch(
+        "litellm.proxy._experimental.mcp_server.sampling_handler.handle_sampling_create_message", record_sampling
+    ):
+        tasks = tuple(asyncio.create_task(callback(None, None)) for callback in callbacks)
+        await asyncio.wait_for(started.wait(), timeout=2)
+        tasks[2].cancel()
+        results = await asyncio.gather(*tasks, return_exceptions=True)
+    assert observed == {"alpha": "alpha", "bravo": "bravo"}
+    assert [result.message for result in results[:2]] == ["alpha", "bravo"]
+    assert isinstance(results[2], asyncio.CancelledError)
+    assert cancelled.is_set()
+
+
 def _reload_mcp_manager_module():
     utils_module = sys.modules["litellm.proxy._experimental.mcp_server.utils"]
     manager_module = sys.modules["litellm.proxy._experimental.mcp_server.mcp_server_manager"]
@@ -82,6 +211,9 @@ def _reload_mcp_manager_module():
     server_module = sys.modules.get("litellm.proxy._experimental.mcp_server.server")
     if server_module is not None and hasattr(server_module, "global_mcp_server_manager"):
         server_module.global_mcp_server_manager = reloaded.global_mcp_server_manager
+    operations_module = sys.modules.get("litellm.proxy._experimental.mcp_server.operations")
+    if operations_module is not None:
+        operations_module.global_mcp_server_manager = reloaded.global_mcp_server_manager
     return reloaded
 
 
@@ -3921,6 +4053,7 @@ class TestMCPServerManager:
             result = await manager.get_resource_templates_from_server(
                 server=server,
                 user_api_key_auth=None,
+                raw_headers=None,
                 mcp_auth_header="auth",
                 extra_headers=None,
                 add_prefix=False,
@@ -3933,6 +4066,8 @@ class TestMCPServerManager:
             stdio_env=None,
             subject_token=None,
             user_api_key_auth=None,
+            raw_headers=None,
+            client_ip=None,
         )
         mock_client.list_resource_templates.assert_awaited_once()
         assert result == expected_templates
@@ -5847,7 +5982,7 @@ class TestMCPServerManager:
         stored = {"Authorization": "Bearer stored-user-token"}
 
         with patch(
-            "litellm.proxy._experimental.mcp_server.server._get_user_oauth_extra_headers_from_db",
+            "litellm.proxy._experimental.mcp_server.operations._get_user_oauth_extra_headers_from_db",
             new=AsyncMock(return_value=stored),
         ) as mock_lookup:
             result = await manager._resolve_oauth2_headers_for_tool_call(
@@ -5874,7 +6009,7 @@ class TestMCPServerManager:
         user_auth = UserAPIKeyAuth(api_key="sk-test", user_id="alice")
 
         with patch(
-            "litellm.proxy._experimental.mcp_server.server._get_user_oauth_extra_headers_from_db",
+            "litellm.proxy._experimental.mcp_server.operations._get_user_oauth_extra_headers_from_db",
             new=AsyncMock(return_value={"Authorization": "Bearer should-not-be-used"}),
         ) as mock_lookup:
             result = await manager._resolve_oauth2_headers_for_tool_call(
@@ -5900,7 +6035,7 @@ class TestMCPServerManager:
         user_auth = UserAPIKeyAuth(api_key="sk-test", user_id="alice")
 
         with patch(
-            "litellm.proxy._experimental.mcp_server.server._get_user_oauth_extra_headers_from_db",
+            "litellm.proxy._experimental.mcp_server.operations._get_user_oauth_extra_headers_from_db",
             new=AsyncMock(side_effect=RuntimeError("redis down")),
         ):
             result = await manager._resolve_oauth2_headers_for_tool_call(
@@ -6056,7 +6191,7 @@ class TestMCPServerManager:
         user_auth = UserAPIKeyAuth(api_key="sk-test")
 
         with patch(
-            "litellm.proxy._experimental.mcp_server.server._get_user_oauth_extra_headers_from_db",
+            "litellm.proxy._experimental.mcp_server.operations._get_user_oauth_extra_headers_from_db",
             new=AsyncMock(return_value={"Authorization": "Bearer x"}),
         ) as mock_lookup:
             result = await manager._resolve_oauth2_headers_for_tool_call(
@@ -6860,7 +6995,8 @@ class TestMCPServerManager:
         }
         user_api_key_auth = UserAPIKeyAuth(api_key="sk-test", user_id="user-123")
 
-        token = _mcp_active_toolset_id.set("toolset-abc")
+        user_api_key_auth.mcp_toolset_id = "toolset-abc"
+        token = _mcp_active_toolset_id.set("unrelated-ambient-toolset")
         try:
             with (
                 patch.object(proxy_server_module, "user_api_key_cache", cache),
@@ -14075,3 +14211,31 @@ async def test_request_selected_during_guardrail_runs_concurrently_with_tool(mon
     assert guardrail_started.is_set() is selected
     assert result.is_error is False
     assert result.content[0].text == "executed"
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("with_caller", [True, False])
+async def test_client_sampling_does_not_fill_explicit_context_from_another_ambient_caller(with_caller):
+    from mcp.server.auth.middleware.auth_context import auth_context_var
+    from litellm.proxy._experimental.mcp_server import server as legacy_server
+
+    upstream = MCPServer(server_id="explicit-empty", name="explicit_empty", url="https://example.invalid/mcp", transport=MCPTransport.http, allow_sampling=True)
+    token = auth_context_var.set(None)
+    sampling = AsyncMock()
+    try:
+        legacy_server.set_auth_context(UserAPIKeyAuth(user_id="unrelated"), raw_headers={"authorization": "unrelated-credential"}, client_ip="192.0.2.99")
+        with (
+            patch("litellm.proxy._experimental.mcp_server.mcp_server_manager.MCPClient") as factory,
+            patch("litellm.proxy._experimental.mcp_server.sampling_handler.handle_sampling_create_message", sampling),
+        ):
+            await MCPServerManager()._create_mcp_client(upstream, user_api_key_auth=UserAPIKeyAuth(user_id="explicit") if with_caller else None)
+            await factory.call_args.kwargs["sampling_callback"](None, None)
+        captured = sampling.await_args.kwargs
+        if with_caller:
+            assert captured["user_api_key_auth"].user_id == "explicit"
+        else:
+            assert captured["user_api_key_auth"] is None
+        assert captured["raw_headers"] is None
+        assert captured["client_ip"] is None
+    finally:
+        auth_context_var.reset(token)
diff --git a/tests/test_litellm/proxy/_experimental/mcp_server/test_mcp_stale_session.py b/tests/test_litellm/proxy/_experimental/mcp_server/test_mcp_stale_session.py
index 9420eecd222..ec6fdef69ee 100644
--- a/tests/test_litellm/proxy/_experimental/mcp_server/test_mcp_stale_session.py
+++ b/tests/test_litellm/proxy/_experimental/mcp_server/test_mcp_stale_session.py
@@ -639,12 +639,12 @@ async def test_per_user_oauth_missing_stored_token_returns_preemptive_401():
             return_value=False,
         ),
         patch(
-            "litellm.proxy._experimental.mcp_server.server.global_mcp_server_manager.has_user_oauth_token",
+            "litellm.proxy._experimental.mcp_server.operations.global_mcp_server_manager.has_user_oauth_token",
             new_callable=AsyncMock,
             return_value=False,
         ) as mock_has_token,
         patch(
-            "litellm.proxy._experimental.mcp_server.server.global_mcp_server_manager.get_mcp_server_by_name",
+            "litellm.proxy._experimental.mcp_server.operations.global_mcp_server_manager.get_mcp_server_by_name",
             return_value=oauth_server,
         ),
         patch.object(
@@ -727,12 +727,12 @@ async def test_admitted_subject_missing_stored_token_challenged_with_resource_me
             return_value=False,
         ),
         patch(
-            "litellm.proxy._experimental.mcp_server.server.global_mcp_server_manager.has_user_oauth_token",
+            "litellm.proxy._experimental.mcp_server.operations.global_mcp_server_manager.has_user_oauth_token",
             new_callable=AsyncMock,
             return_value=False,
         ) as mock_has_token,
         patch(
-            "litellm.proxy._experimental.mcp_server.server.global_mcp_server_manager.get_mcp_server_by_name",
+            "litellm.proxy._experimental.mcp_server.operations.global_mcp_server_manager.get_mcp_server_by_name",
             return_value=oauth_server,
         ),
         patch.object(
@@ -833,11 +833,11 @@ async def test_client_credentials_server_is_not_preemptively_challenged(m2m_fiel
             return_value=False,
         ),
         patch(
-            "litellm.proxy._experimental.mcp_server.server.global_mcp_server_manager.has_user_oauth_token",
+            "litellm.proxy._experimental.mcp_server.operations.global_mcp_server_manager.has_user_oauth_token",
             new_callable=AsyncMock,
         ) as mock_has_token,
         patch(
-            "litellm.proxy._experimental.mcp_server.server.global_mcp_server_manager.get_mcp_server_by_name",
+            "litellm.proxy._experimental.mcp_server.operations.global_mcp_server_manager.get_mcp_server_by_name",
             return_value=m2m_server,
         ),
         patch.object(session_manager_stateless, "handle_request", new_callable=AsyncMock) as mock_handle_request,
@@ -929,16 +929,16 @@ async def test_handle_streamable_http_mcp_delegated_server_surfaces_upstream_cha
             return_value=False,
         ),
         patch(
-            "litellm.proxy._experimental.mcp_server.server._get_user_oauth_extra_headers_from_db",
+            "litellm.proxy._experimental.mcp_server.operations._get_user_oauth_extra_headers_from_db",
             new_callable=AsyncMock,
             return_value=None,
         ),
         patch(
-            "litellm.proxy._experimental.mcp_server.server.global_mcp_server_manager.get_mcp_server_by_name",
+            "litellm.proxy._experimental.mcp_server.operations.global_mcp_server_manager.get_mcp_server_by_name",
             return_value=delegated_server,
         ),
         patch(  # test-quality-ok: registry is empty in unit tests; key owns the delegated server
-            "litellm.proxy._experimental.mcp_server.server._get_allowed_mcp_servers",
+            "litellm.proxy._experimental.mcp_server.operations._get_allowed_mcp_servers",
             new_callable=AsyncMock,
             return_value=[delegated_server],
         ),
@@ -1022,12 +1022,12 @@ async def test_per_user_oauth_with_stored_token_skips_preemptive_401():
             return_value=False,
         ),
         patch(
-            "litellm.proxy._experimental.mcp_server.server.global_mcp_server_manager.has_user_oauth_token",
+            "litellm.proxy._experimental.mcp_server.operations.global_mcp_server_manager.has_user_oauth_token",
             new_callable=AsyncMock,
             return_value=True,
         ) as mock_has_token,
         patch(
-            "litellm.proxy._experimental.mcp_server.server.global_mcp_server_manager.get_mcp_server_by_name",
+            "litellm.proxy._experimental.mcp_server.operations.global_mcp_server_manager.get_mcp_server_by_name",
             return_value=oauth_server,
         ),
         patch.object(
@@ -1126,11 +1126,11 @@ async def test_handle_streamable_http_mcp_delegated_server_without_token_returns
             return_value=False,
         ),
         patch(
-            "litellm.proxy._experimental.mcp_server.server.global_mcp_server_manager.has_user_oauth_token",
+            "litellm.proxy._experimental.mcp_server.operations.global_mcp_server_manager.has_user_oauth_token",
             new_callable=AsyncMock,
         ) as mock_has_token,
         patch(
-            "litellm.proxy._experimental.mcp_server.server.global_mcp_server_manager.get_mcp_server_by_name",
+            "litellm.proxy._experimental.mcp_server.operations.global_mcp_server_manager.get_mcp_server_by_name",
             return_value=delegated_server,
         ),
         patch.object(
@@ -1218,7 +1218,7 @@ async def test_handle_streamable_http_mcp_token_exchange_without_subject_returns
             return_value=False,
         ),
         patch(
-            "litellm.proxy._experimental.mcp_server.server.global_mcp_server_manager.get_mcp_server_by_name",
+            "litellm.proxy._experimental.mcp_server.operations.global_mcp_server_manager.get_mcp_server_by_name",
             return_value=obo_server,
         ),
         patch.object(
@@ -1317,7 +1317,7 @@ async def test_handle_streamable_http_mcp_oauth_delegate_without_token_returns_g
             True,
         ),
         patch(
-            "litellm.proxy._experimental.mcp_server.server.global_mcp_server_manager.get_mcp_server_by_name",
+            "litellm.proxy._experimental.mcp_server.operations.global_mcp_server_manager.get_mcp_server_by_name",
             return_value=od_server,
         ),
         patch.object(
@@ -1391,7 +1391,7 @@ async def test_handle_streamable_http_mcp_oauth_delegate_with_forwarded_token_sk
             new_callable=AsyncMock,
         ),
         patch(
-            "litellm.proxy._experimental.mcp_server.server.global_mcp_server_manager.get_mcp_server_by_name",
+            "litellm.proxy._experimental.mcp_server.operations.global_mcp_server_manager.get_mcp_server_by_name",
             return_value=od_server,
         ),
         patch.object(
@@ -1453,7 +1453,7 @@ async def _run_passthrough_connect(
             new_callable=AsyncMock,
         ),
         patch(
-            "litellm.proxy._experimental.mcp_server.server.global_mcp_server_manager.get_mcp_server_by_name",
+            "litellm.proxy._experimental.mcp_server.operations.global_mcp_server_manager.get_mcp_server_by_name",
             return_value=server,
         ),
         patch.object(session_manager_stateless, "handle_request", new_callable=AsyncMock) as mock_handle_request,
@@ -1574,7 +1574,7 @@ async def test_handle_streamable_http_mcp_true_passthrough_without_token_surface
             return_value=probe_client,
         ),
         patch(
-            "litellm.proxy._experimental.mcp_server.server.global_mcp_server_manager.get_mcp_server_by_name",
+            "litellm.proxy._experimental.mcp_server.operations.global_mcp_server_manager.get_mcp_server_by_name",
             return_value=tp_server,
         ),
         patch.object(
@@ -1642,7 +1642,7 @@ async def test_handle_streamable_http_mcp_true_passthrough_dcr_bridge_challenges
             return_value=probe_client,
         ),
         patch(
-            "litellm.proxy._experimental.mcp_server.server.global_mcp_server_manager.get_mcp_server_by_name",
+            "litellm.proxy._experimental.mcp_server.operations.global_mcp_server_manager.get_mcp_server_by_name",
             return_value=bridge_server,
         ),
         patch.object(
@@ -1720,7 +1720,7 @@ async def test_handle_streamable_http_mcp_true_passthrough_with_token_skips_prob
             return_value=probe_client,
         ),
         patch(
-            "litellm.proxy._experimental.mcp_server.server.global_mcp_server_manager.get_mcp_server_by_name",
+            "litellm.proxy._experimental.mcp_server.operations.global_mcp_server_manager.get_mcp_server_by_name",
             return_value=tp_server,
         ),
         patch.object(
diff --git a/tests/test_litellm/proxy/_experimental/mcp_server/test_mcp_tool_search.py b/tests/test_litellm/proxy/_experimental/mcp_server/test_mcp_tool_search.py
index cb43d2c2592..4575741aa8b 100644
--- a/tests/test_litellm/proxy/_experimental/mcp_server/test_mcp_tool_search.py
+++ b/tests/test_litellm/proxy/_experimental/mcp_server/test_mcp_tool_search.py
@@ -1,3 +1,4 @@
+from litellm.proxy._experimental.mcp_server import operations as mcp_operations
 """
 Tests for MCP tool search feature.
 
@@ -572,7 +573,7 @@ class TestCallToolRestApiVirtualTools:
         mock_tool.input_schema = {"type": "object", "properties": {}}
 
         with patch(
-            "litellm.proxy._experimental.mcp_server.server._list_mcp_tools",
+            "litellm.proxy._experimental.mcp_server.operations._list_mcp_tools",
             new_callable=AsyncMock,
             return_value=AggregateToolListing(tools=[mock_tool], outcomes={}),
         ):
@@ -616,12 +617,12 @@ class TestCallToolRestApiVirtualTools:
 
         with (
             patch(
-                "litellm.proxy._experimental.mcp_server.server._get_allowed_mcp_servers",
+                "litellm.proxy._experimental.mcp_server.operations._get_allowed_mcp_servers",
                 new_callable=AsyncMock,
                 return_value=[MagicMock()],
             ),
             patch(
-                "litellm.proxy._experimental.mcp_server.server.execute_mcp_tool",
+                "litellm.proxy._experimental.mcp_server.operations.execute_mcp_tool",
                 new_callable=AsyncMock,
                 return_value=fake_result,
             ) as mock_execute,
@@ -669,12 +670,12 @@ class TestCallToolRestApiVirtualTools:
                 return_value="203.0.113.7",
             ),
             patch(
-                "litellm.proxy._experimental.mcp_server.server._get_allowed_mcp_servers",
+                "litellm.proxy._experimental.mcp_server.operations._get_allowed_mcp_servers",
                 new_callable=AsyncMock,
                 return_value=[MagicMock()],
             ) as mock_allowed,
             patch(
-                "litellm.proxy._experimental.mcp_server.server.execute_mcp_tool",
+                "litellm.proxy._experimental.mcp_server.operations.execute_mcp_tool",
                 new_callable=AsyncMock,
                 return_value=fake_result,
             ),
@@ -699,7 +700,7 @@ class TestCallToolRestApiVirtualTools:
                 return_value="203.0.113.7",
             ),
             patch(
-                "litellm.proxy._experimental.mcp_server.server._list_mcp_tools",
+                "litellm.proxy._experimental.mcp_server.operations._list_mcp_tools",
                 new_callable=AsyncMock,
                 return_value=AggregateToolListing(tools=[], outcomes={}),
             ) as mock_list,
@@ -832,7 +833,7 @@ class TestCallToolRestApiVirtualTools:
                 "litellm.proxy.proxy_server.proxy_logging_obj", key_limits
             ),
             patch(  # test-quality-ok: the authorized catalog is the seam every virtual tool shares; the ranking under test stays real
-                "litellm.proxy._experimental.mcp_server.server._list_mcp_tools",
+                "litellm.proxy._experimental.mcp_server.operations._list_mcp_tools",
                 new_callable=AsyncMock,
                 return_value=AggregateToolListing(tools=list(CATALOG), outcomes={}),
             ) as mock_list,
@@ -939,7 +940,7 @@ class TestDispatchVirtualMcpTool:
             new_callable=AsyncMock,
             return_value="SEARCH_RESULT",
         ) as mock_search:
-            result = await srv._dispatch_virtual_mcp_tool(
+            result = await mcp_operations._dispatch_virtual_mcp_tool(
                 name=MCP_TOOL_SEARCH_TOOL_NAME,
                 arguments={"query": "q", "top_k": 3},
                 user_api_key_auth=uak,
@@ -961,7 +962,7 @@ class TestDispatchVirtualMcpTool:
             new_callable=AsyncMock,
             return_value="AGENT_RESULT",
         ) as mock_agent_search:
-            result = await srv._dispatch_virtual_mcp_tool(
+            result = await mcp_operations._dispatch_virtual_mcp_tool(
                 name=AGENT_SEARCH_TOOL_NAME,
                 arguments={"query": "translate a document", "top_k": "2"},
                 user_api_key_auth=uak,
@@ -996,7 +997,7 @@ class TestDispatchVirtualMcpTool:
             new_callable=AsyncMock,
             return_value="CALL_RESULT",
         ) as mock_call:
-            result = await srv._dispatch_virtual_mcp_tool(
+            result = await mcp_operations._dispatch_virtual_mcp_tool(
                 name=MCP_TOOL_CALL_TOOL_NAME,
                 arguments={"tool_name": "math-add", "arguments": {"a": 1, "b": 2}},
                 user_api_key_auth=uak,
@@ -1027,8 +1028,7 @@ class TestDispatchVirtualMcpTool:
         sentinel_logging_obj = object()
         with (
             patch.object(
-                srv,
-                "_build_virtual_call_logging_obj",
+                mcp_operations, "_build_virtual_call_logging_obj",
                 new_callable=AsyncMock,
                 return_value=sentinel_logging_obj,
             ) as mock_build,
@@ -1038,7 +1038,7 @@ class TestDispatchVirtualMcpTool:
                 return_value="CALL_RESULT",
             ) as mock_call,
         ):
-            await srv._dispatch_virtual_mcp_tool(
+            await mcp_operations._dispatch_virtual_mcp_tool(
                 name=MCP_TOOL_CALL_TOOL_NAME,
                 arguments={"tool_name": "math-add", "arguments": {"a": 1}},
                 user_api_key_auth=uak,
@@ -1060,7 +1060,7 @@ class TestDispatchVirtualMcpTool:
             new_callable=AsyncMock,
             return_value="SEARCH_RESULT",
         ) as mock_search:
-            await srv._dispatch_virtual_mcp_tool(
+            await mcp_operations._dispatch_virtual_mcp_tool(
                 name=MCP_TOOL_SEARCH_TOOL_NAME,
                 arguments={"query": "issue", "top_k": "not-a-number"},
                 user_api_key_auth=uak,
@@ -1083,12 +1083,12 @@ class TestDispatchVirtualMcpTool:
         fake = CallToolResult(content=[TextContent(type="text", text="ok")], isError=False)
         with (
             patch(
-                "litellm.proxy._experimental.mcp_server.server._get_allowed_mcp_servers",
+                "litellm.proxy._experimental.mcp_server.operations._get_allowed_mcp_servers",
                 new_callable=AsyncMock,
                 return_value=[MagicMock()],
             ) as mock_allowed,
             patch(
-                "litellm.proxy._experimental.mcp_server.server.execute_mcp_tool",
+                "litellm.proxy._experimental.mcp_server.operations.execute_mcp_tool",
                 new_callable=AsyncMock,
                 return_value=fake,
             ) as mock_exec,
@@ -1130,12 +1130,12 @@ class TestDispatchVirtualMcpTool:
         uak = UserAPIKeyAuth(api_key="k", object_permission=_make_perm(mcp_tool_search_enabled=True))
         with (
             patch(
-                "litellm.proxy._experimental.mcp_server.server._get_allowed_mcp_servers",
+                "litellm.proxy._experimental.mcp_server.operations._get_allowed_mcp_servers",
                 new_callable=AsyncMock,
                 return_value=[],
             ),
             patch(
-                "litellm.proxy._experimental.mcp_server.server.execute_mcp_tool",
+                "litellm.proxy._experimental.mcp_server.operations.execute_mcp_tool",
                 new_callable=AsyncMock,
             ) as mock_exec,
         ):
@@ -1217,7 +1217,7 @@ class TestMcpServerToolCallErrorHandling:
                 return_value=(uak, None, None, None, None, None, None),
             ),
             patch(
-                "litellm.proxy._experimental.mcp_server.server._dispatch_virtual_mcp_tool",
+                "litellm.proxy._experimental.mcp_server.operations._dispatch_virtual_mcp_tool",
                 new_callable=AsyncMock,
                 side_effect=HTTPException(status_code=403, detail="User not allowed to call this tool"),
             ),
@@ -1254,7 +1254,7 @@ async def test_handle_mcp_tool_call_scoped_denial_names_the_binding_agent() -> N
         ]
 
     with patch(  # test-quality-ok: the permission resolver is a module-level function; the suite's only seam
-        "litellm.proxy._experimental.mcp_server.server._get_allowed_mcp_servers",
+        "litellm.proxy._experimental.mcp_server.operations._get_allowed_mcp_servers",
         new=AsyncMock(side_effect=resolve),
     ):
         with pytest.raises(HTTPException) as exc_info:
diff --git a/tests/test_litellm/proxy/_experimental/mcp_server/test_mcp_toolset_scope.py b/tests/test_litellm/proxy/_experimental/mcp_server/test_mcp_toolset_scope.py
index 519acc241c6..60098b1f656 100644
--- a/tests/test_litellm/proxy/_experimental/mcp_server/test_mcp_toolset_scope.py
+++ b/tests/test_litellm/proxy/_experimental/mcp_server/test_mcp_toolset_scope.py
@@ -564,7 +564,7 @@ class TestMCPActiveToolsetContextVar:
                 MagicMock(get_mcp_client_ip=MagicMock(return_value="127.0.0.1")),
             ),
             patch(
-                "litellm.proxy._experimental.mcp_server.server.global_mcp_server_manager",
+                "litellm.proxy._experimental.mcp_server.operations.global_mcp_server_manager",
                 MagicMock(get_mcp_server_by_name=MagicMock(return_value=None)),
             ),
             patch(
diff --git a/tests/test_litellm/proxy/_experimental/mcp_server/test_openapi_tool_auth.py b/tests/test_litellm/proxy/_experimental/mcp_server/test_openapi_tool_auth.py
index ac716bace3c..bb70f38285c 100644
--- a/tests/test_litellm/proxy/_experimental/mcp_server/test_openapi_tool_auth.py
+++ b/tests/test_litellm/proxy/_experimental/mcp_server/test_openapi_tool_auth.py
@@ -1,3 +1,4 @@
+from litellm.proxy._experimental.mcp_server import operations as mcp_operations
 """
 VERIA-7 regression: OpenAPI-backed (local-registry) MCP tools must run
 through `pre_call_tool_check` before dispatch, the same as managed
@@ -49,22 +50,22 @@ async def test_openapi_local_tool_runs_pre_call_tool_check():
 
     with (
         patch.object(
-            mcp_module.global_mcp_server_manager,
+            mcp_operations.global_mcp_server_manager,
             "_get_mcp_server_from_tool_name",
             return_value=fake_server,
         ),
         patch.object(
-            mcp_module.global_mcp_server_manager,
+            mcp_operations.global_mcp_server_manager,
             "pre_call_tool_check",
             new=pre_call,
         ),
         patch.object(
-            mcp_module.global_mcp_tool_registry,
+            mcp_operations.global_mcp_tool_registry,
             "get_tool",
             return_value=fake_tool,
         ),
         patch(
-            "litellm.proxy._experimental.mcp_server.server._handle_local_mcp_tool",
+            "litellm.proxy._experimental.mcp_server.operations._handle_local_mcp_tool",
             new=handle_local,
         ),
         patch(
@@ -72,7 +73,7 @@ async def test_openapi_local_tool_runs_pre_call_tool_check():
             return_value=True,
         ),
     ):
-        await mcp_module.execute_mcp_tool(
+        await mcp_operations.execute_mcp_tool(
             name="list_pets",
             arguments={"limit": 10},
             allowed_mcp_servers=[fake_server],
@@ -92,7 +93,7 @@ async def test_openapi_local_tool_runs_pre_call_tool_check():
     assert pre_call_kwargs["guardrail_context"] == {"metadata": {"guardrails": ("block-all",)}}
     assert pre_call_kwargs["name"] == "list_pets"
     assert pre_call_kwargs["server"] is fake_server
-    assert pre_call_kwargs["user_api_key_auth"] is user
+    assert pre_call_kwargs["user_api_key_auth"] == user
     # `proxy_logging_obj` must be sourced from the canonical proxy_server
     # module (same as the managed path) — passing None would crash the
     # downstream `_create_mcp_request_object_from_kwargs` call with
@@ -134,22 +135,22 @@ async def test_openapi_local_tool_blocked_when_pre_call_check_raises():
 
     with (
         patch.object(
-            mcp_module.global_mcp_server_manager,
+            mcp_operations.global_mcp_server_manager,
             "_get_mcp_server_from_tool_name",
             return_value=fake_server,
         ),
         patch.object(
-            mcp_module.global_mcp_server_manager,
+            mcp_operations.global_mcp_server_manager,
             "pre_call_tool_check",
             new=pre_call,
         ),
         patch.object(
-            mcp_module.global_mcp_tool_registry,
+            mcp_operations.global_mcp_tool_registry,
             "get_tool",
             return_value=fake_tool,
         ),
         patch(
-            "litellm.proxy._experimental.mcp_server.server._handle_local_mcp_tool",
+            "litellm.proxy._experimental.mcp_server.operations._handle_local_mcp_tool",
             new=handle_local,
         ),
         patch(
@@ -158,7 +159,7 @@ async def test_openapi_local_tool_blocked_when_pre_call_check_raises():
         ),
     ):
         with pytest.raises(HTTPException) as exc:
-            await mcp_module.execute_mcp_tool(
+            await mcp_operations.execute_mcp_tool(
                 name="delete_pet",
                 arguments={},
                 allowed_mcp_servers=[fake_server],
@@ -195,24 +196,24 @@ async def test_openapi_local_tool_denied_when_server_not_resolvable():
 
     # `_get_mcp_server_from_tool_name` returns None — no server context.
     with (
-        patch.object(mcp_module, "_resolve_openapi_tool_auth", new=resolve_auth),
+        patch.object(mcp_operations, "_resolve_openapi_tool_auth", new=resolve_auth),
         patch.object(
-            mcp_module.global_mcp_server_manager,
+            mcp_operations.global_mcp_server_manager,
             "_get_mcp_server_from_tool_name",
             return_value=None,
         ),
         patch.object(
-            mcp_module.global_mcp_server_manager,
+            mcp_operations.global_mcp_server_manager,
             "pre_call_tool_check",
             new=pre_call,
         ),
         patch.object(
-            mcp_module.global_mcp_tool_registry,
+            mcp_operations.global_mcp_tool_registry,
             "get_tool",
             return_value=fake_tool,
         ),
         patch(
-            "litellm.proxy._experimental.mcp_server.server._handle_local_mcp_tool",
+            "litellm.proxy._experimental.mcp_server.operations._handle_local_mcp_tool",
             new=handle_local,
         ),
         patch(
@@ -221,7 +222,7 @@ async def test_openapi_local_tool_denied_when_server_not_resolvable():
         ),
     ):
         with pytest.raises(HTTPException) as exc:
-            await mcp_module.execute_mcp_tool(
+            await mcp_operations.execute_mcp_tool(
                 name="list_pets",
                 arguments={},
                 allowed_mcp_servers=[],
@@ -280,27 +281,27 @@ async def test_openapi_local_tool_injects_resolved_oauth_token():
 
     with (
         patch.object(
-            mcp_module.global_mcp_server_manager,
+            mcp_operations.global_mcp_server_manager,
             "_get_mcp_server_from_tool_name",
             return_value=oauth_server,
         ),
         patch.object(
-            mcp_module.global_mcp_server_manager,
+            mcp_operations.global_mcp_server_manager,
             "pre_call_tool_check",
             new=AsyncMock(return_value={}),
         ),
         patch.object(
-            mcp_module.global_mcp_tool_registry,
+            mcp_operations.global_mcp_tool_registry,
             "get_tool",
             return_value=fake_tool,
         ),
         patch.object(
-            mcp_module.global_mcp_server_manager._cred_provider,
+            mcp_operations.global_mcp_server_manager._cred_provider,
             "resolve_credentials",
             new=AsyncMock(return_value=Ok(StaticHeaderAuth("Bearer stored-user-token"))),
         ),
         patch(
-            "litellm.proxy._experimental.mcp_server.server._handle_local_mcp_tool",
+            "litellm.proxy._experimental.mcp_server.operations._handle_local_mcp_tool",
             new=handle_local,
         ),
         patch(
@@ -308,7 +309,7 @@ async def test_openapi_local_tool_injects_resolved_oauth_token():
             return_value=True,
         ),
     ):
-        await mcp_module.execute_mcp_tool(
+        await mcp_operations.execute_mcp_tool(
             name="get_values",
             arguments={},
             allowed_mcp_servers=[oauth_server],
@@ -417,7 +418,7 @@ async def test_legacy_local_tool_fallback_refuses_unentitled_caller(legacy_local
     )
 
     with pytest.raises(HTTPException) as exc:
-        await mcp_module.execute_mcp_tool(
+        await mcp_operations.execute_mcp_tool(
             name=f"{LEGACY_SERVER_NAME}-{LEGACY_TOOL}",
             arguments={},
             allowed_mcp_servers=[server],
@@ -451,7 +452,7 @@ async def test_legacy_local_tool_fallback_still_dispatches_entitled_caller(
     server, executed = legacy_local_tool
     user = _caller_entitled_to([LEGACY_TOOL])
 
-    result = await mcp_module.execute_mcp_tool(
+    result = await mcp_operations.execute_mcp_tool(
         name=f"{LEGACY_SERVER_NAME}-{LEGACY_TOOL}",
         arguments={},
         allowed_mcp_servers=[server],
@@ -481,7 +482,7 @@ async def test_legacy_local_tool_fallback_fails_closed_on_empty_prefix(
     _server, executed = legacy_local_tool
 
     with pytest.raises(HTTPException) as exc:
-        await mcp_module.execute_mcp_tool(
+        await mcp_operations.execute_mcp_tool(
             name=f"-{LEGACY_TOOL}",
             arguments={},
             allowed_mcp_servers=[],
@@ -523,7 +524,7 @@ async def test_legacy_local_tool_fallback_fails_closed_when_prefix_names_no_serv
         return_value=True,
     ):
         with pytest.raises(HTTPException) as exc:
-            await mcp_module.execute_mcp_tool(
+            await mcp_operations.execute_mcp_tool(
                 name=f"{LEGACY_SERVER_NAME}-{LEGACY_TOOL}",
                 arguments={},
                 allowed_mcp_servers=[other_server],
@@ -546,7 +547,7 @@ async def test_unknown_tool_name_still_reports_not_found():
     from litellm.proxy._experimental.mcp_server import server as mcp_module
 
     with pytest.raises(HTTPException) as exc:
-        await mcp_module.execute_mcp_tool(
+        await mcp_operations.execute_mcp_tool(
             name="tool_no_registry_knows",
             arguments={},
             allowed_mcp_servers=[],
@@ -610,7 +611,7 @@ async def test_per_server_auth_header_reaches_both_openapi_dispatch_arms(dispatc
         captured["injected"] = _request_auth_header.get()
         return []
 
-    manager = mcp_module.global_mcp_server_manager
+    manager = mcp_operations.global_mcp_server_manager
     with (
         patch.object(manager, "resolve_openapi_upstream_auth", new=fake_resolver),
         patch.object(manager, "pre_call_tool_check", new=AsyncMock(return_value={})),
@@ -620,9 +621,9 @@ async def test_per_server_auth_header_reaches_both_openapi_dispatch_arms(dispatc
             fake_tool.name = "list_reports"
             with (
                 patch.object(manager, "_get_mcp_server_from_tool_name", return_value=server),
-                patch.object(mcp_module.global_mcp_tool_registry, "get_tool", return_value=fake_tool),
+                patch.object(mcp_operations.global_mcp_tool_registry, "get_tool", return_value=fake_tool),
                 patch(
-                    "litellm.proxy._experimental.mcp_server.server._handle_local_mcp_tool",
+                    "litellm.proxy._experimental.mcp_server.operations._handle_local_mcp_tool",
                     new=capture_local,
                 ),
                 patch(
@@ -630,7 +631,7 @@ async def test_per_server_auth_header_reaches_both_openapi_dispatch_arms(dispatc
                     return_value=True,
                 ),
             ):
-                await mcp_module.execute_mcp_tool(
+                await mcp_operations.execute_mcp_tool(
                     name="list_reports",
                     arguments={},
                     allowed_mcp_servers=[server],
@@ -702,11 +703,11 @@ async def test_local_dispatch_reports_the_outcome_instead_of_success(failure: st
     user = UserAPIKeyAuth(api_key="sk-user", user_id="alice", user_role=LitellmUserRoles.INTERNAL_USER.value)
 
     with (
-        patch.object(mcp_module.global_mcp_server_manager, "_get_mcp_server_from_tool_name", return_value=server),
-        patch.object(mcp_module.global_mcp_server_manager, "pre_call_tool_check", new=AsyncMock(return_value={})),
-        patch.object(mcp_module.global_mcp_tool_registry, "get_tool", return_value=fake_tool),
+        patch.object(mcp_operations.global_mcp_server_manager, "_get_mcp_server_from_tool_name", return_value=server),
+        patch.object(mcp_operations.global_mcp_server_manager, "pre_call_tool_check", new=AsyncMock(return_value={})),
+        patch.object(mcp_operations.global_mcp_tool_registry, "get_tool", return_value=fake_tool),
         patch.object(
-            mcp_module.global_mcp_server_manager,
+            mcp_operations.global_mcp_server_manager,
             "resolve_openapi_upstream_auth",
             new=AsyncMock(return_value=(None, None)),
         ),
@@ -715,7 +716,7 @@ async def test_local_dispatch_reports_the_outcome_instead_of_success(failure: st
             return_value=True,
         ),
     ):
-        call = mcp_module.execute_mcp_tool(
+        call = mcp_operations.execute_mcp_tool(
             name="list_reports",
             arguments={},
             allowed_mcp_servers=[server],
diff --git a/tests/test_litellm/proxy/_experimental/mcp_server/test_operations.py b/tests/test_litellm/proxy/_experimental/mcp_server/test_operations.py
new file mode 100644
index 00000000000..870f2cd5f8f
--- /dev/null
+++ b/tests/test_litellm/proxy/_experimental/mcp_server/test_operations.py
@@ -0,0 +1,343 @@
+import asyncio
+from unittest.mock import AsyncMock, patch
+
+import pytest
+from mcp.types import GetPromptRequest, GetPromptRequestParams, GetPromptResult
+
+from litellm.proxy._experimental.mcp_server.operations import GatewayOperations, prepare_context
+from litellm.proxy._types import UserAPIKeyAuth
+
+
+@pytest.mark.asyncio
+async def test_dispatch_uses_explicit_context_when_ambient_caller_differs():
+    from mcp.server.auth.middleware.auth_context import auth_context_var
+    from litellm.proxy._experimental.mcp_server.server import set_auth_context
+
+    context = prepare_context(
+        UserAPIKeyAuth(user_id="alpha"),
+        raw_headers={"x-caller": "alpha"},
+        mcp_servers=["alpha-server"],
+        client_ip="192.0.2.1",
+    )
+    token = auth_context_var.set(None)
+    handler = AsyncMock(return_value=GetPromptResult(messages=[]))
+    try:
+        set_auth_context(UserAPIKeyAuth(user_id="bravo"), raw_headers={"x-caller": "bravo"})
+        with patch("litellm.proxy._experimental.mcp_server.operations.mcp_get_prompt", handler):
+            result = await GatewayOperations().execute(
+                GetPromptRequest(params=GetPromptRequestParams(name="alpha-prompt")), context
+            )
+        assert result.messages == []
+        assert handler.await_args.kwargs["name"] == "alpha-prompt"
+        assert handler.await_args.kwargs["user_api_key_auth"].user_id == "alpha"
+        assert handler.await_args.kwargs["raw_headers"] == {"x-caller": "alpha"}
+        assert handler.await_args.kwargs["mcp_servers"] == ["alpha-server"]
+        assert handler.await_args.kwargs["client_ip"] == "192.0.2.1"
+    finally:
+        auth_context_var.reset(token)
+
+
+@pytest.mark.asyncio
+async def test_legacy_adapter_cleans_context_after_cancelled_operation():
+    from types import SimpleNamespace
+    from litellm.proxy._experimental.mcp_server import server
+    from litellm.proxy._experimental.mcp_server.mcp_context import active_mcp_request_ctx_var
+
+    previous_session = server.active_mcp_session_var.get()
+    previous_request = active_mcp_request_ctx_var.get()
+    request = SimpleNamespace(session=object())
+    auth = (None, None, None, None, None, None, None)
+
+    async def cancelled_operation():
+        async with server._legacy_operation_context(request, trace=False):
+            assert server.active_mcp_session_var.get() is request.session
+            assert active_mcp_request_ctx_var.get() is request
+            raise asyncio.CancelledError
+
+    with patch(
+        "litellm.proxy._experimental.mcp_server.server.get_or_extract_auth_context", AsyncMock(return_value=auth)
+    ):
+        with pytest.raises(asyncio.CancelledError):
+            await cancelled_operation()
+    assert server.active_mcp_session_var.get() is previous_session
+    assert active_mcp_request_ctx_var.get() is previous_request
+
+
+@pytest.mark.asyncio
+async def test_legacy_adapter_cleans_context_when_trace_setup_fails():
+    from types import SimpleNamespace
+    from litellm.proxy._experimental.mcp_server import server
+    from litellm.proxy._experimental.mcp_server.mcp_context import active_mcp_request_ctx_var
+
+    previous_session = server.active_mcp_session_var.get()
+    previous_request = active_mcp_request_ctx_var.get()
+    request = SimpleNamespace(session=object())
+
+    async def enter_operation():
+        async with server._legacy_operation_context(request, trace=True):
+            pytest.fail("Trace setup failure must prevent dispatch")
+
+    with patch.object(server, "_otel_set_mcp_transport_span", side_effect=RuntimeError("trace failure")):
+        with pytest.raises(RuntimeError, match="trace failure"):
+            await enter_operation()
+    assert server.active_mcp_session_var.get() is previous_session
+    assert active_mcp_request_ctx_var.get() is previous_request
+
+
+@pytest.mark.asyncio
+async def test_prompt_sampling_receives_explicit_operation_caller_headers_and_ip():
+    from unittest.mock import MagicMock
+    from litellm.proxy._experimental.mcp_server import operations
+    from litellm.types.mcp import MCPTransport
+    from litellm.types.mcp_server.mcp_server_manager import MCPServer
+
+    upstream = MCPServer(
+        server_id="explicit-prompt",
+        name="explicit_prompt",
+        url="https://example.invalid/mcp",
+        transport=MCPTransport.http,
+        allow_sampling=True,
+    )
+    context = prepare_context(
+        UserAPIKeyAuth(user_id="prompt-caller"),
+        raw_headers={"x-caller": "prompt-caller"},
+        client_ip="192.0.2.41",
+    )
+    client = MagicMock()
+    client.get_prompt = AsyncMock(return_value=GetPromptResult(messages=[]))
+    sampling = AsyncMock()
+    with (
+        patch.object(operations, "_get_allowed_mcp_servers", AsyncMock(return_value=[upstream])),
+        patch("litellm.proxy._experimental.mcp_server.mcp_server_manager.MCPClient", return_value=client) as factory,
+        patch("litellm.proxy._experimental.mcp_server.sampling_handler.handle_sampling_create_message", sampling),
+    ):
+        result = await GatewayOperations().execute(
+            GetPromptRequest(params=GetPromptRequestParams(name="explicit_prompt-prompt")), context
+        )
+        assert result.messages == []
+        await factory.call_args.kwargs["sampling_callback"](None, None)
+    captured = sampling.await_args.kwargs
+    assert captured["user_api_key_auth"] is not None
+    assert captured["user_api_key_auth"].user_id == "prompt-caller"
+    assert captured["raw_headers"] == {"x-caller": "prompt-caller"}
+    assert captured["client_ip"] == "192.0.2.41"
+
+
+def _catalog_case(method):
+    from mcp import types
+
+    cases = {
+        "prompts/list": (
+            types.ListPromptsRequest(),
+            "list_prompts",
+            "get_prompts_from_server",
+            [types.Prompt(name="catalog-prompt")],
+            "prompts",
+        ),
+        "prompts/get": (
+            types.GetPromptRequest(
+                params=types.GetPromptRequestParams(name="catalog-prompt", arguments={"topic": "test"})
+            ),
+            "get_prompt",
+            "get_prompt_from_server",
+            types.GetPromptResult(messages=[]),
+            None,
+        ),
+        "resources/list": (
+            types.ListResourcesRequest(),
+            "list_resources",
+            "get_resources_from_server",
+            [types.Resource(name="document", uri="https://example.com/document")],
+            "resources",
+        ),
+        "resources/templates/list": (
+            types.ListResourceTemplatesRequest(),
+            "list_resource_templates",
+            "get_resource_templates_from_server",
+            [types.ResourceTemplate(name="document", uri_template="https://example.com/{name}")],
+            "resource_templates",
+        ),
+        "resources/read": (
+            types.ReadResourceRequest(params=types.ReadResourceRequestParams(uri="https://example.com/document")),
+            "read_resource",
+            "read_resource_from_server",
+            types.ReadResourceResult(
+                contents=[types.TextResourceContents(uri="https://example.com/document", text="document body")]
+            ),
+            None,
+        ),
+    }
+    return cases[method]
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize(
+    "method", ["prompts/list", "prompts/get", "resources/list", "resources/templates/list", "resources/read"]
+)
+@pytest.mark.parametrize("state", ["success", "denied", "upstream_failure", "scope_failure"])
+async def test_native_catalog_operations_preserve_context_results_and_failure_policy(method, state):
+    from types import SimpleNamespace
+    from fastapi import HTTPException
+    from mcp.server.context import ServerRequestContext
+    from mcp.types import PaginatedRequestParams
+    from litellm.proxy._experimental.mcp_server import operations, server
+    from litellm.types.mcp import MCPTransport
+    from litellm.types.mcp_server.mcp_server_manager import MCPServer
+
+    operation, handler_name, manager_method, payload, collection = _catalog_case(method)
+    caller = UserAPIKeyAuth(user_id="catalog-caller")
+    headers = {"x-caller": "catalog-caller"}
+    upstream_server = MCPServer(server_id="catalog", name="catalog", transport=MCPTransport.http)
+    allowed = AsyncMock(
+        return_value=[] if state == "denied" else [upstream_server],
+        side_effect=HTTPException(status_code=403, detail="scope denied") if state == "scope_failure" else None,
+    )
+    upstream = AsyncMock(
+        return_value=payload, side_effect=RuntimeError("upstream unavailable") if state == "upstream_failure" else None
+    )
+    ctx = ServerRequestContext(
+        session=SimpleNamespace(), lifespan_context={}, protocol_version="2025-06-18", method=method
+    )
+    auth = (caller, None, ["catalog"], None, None, headers, "192.0.2.41")
+    with (
+        patch.object(server, "get_or_extract_auth_context", AsyncMock(return_value=auth)),
+        patch.object(operations, "_get_allowed_mcp_servers", allowed),
+        patch.object(operations.global_mcp_server_manager, manager_method, upstream),
+    ):
+        if collection is None and state != "success":
+            expected_error = RuntimeError if state == "upstream_failure" else HTTPException
+            with pytest.raises(expected_error):
+                await getattr(server, handler_name)(ctx, operation.params)
+        else:
+            result = await getattr(server, handler_name)(ctx, operation.params or PaginatedRequestParams())
+            if collection:
+                assert getattr(result, collection) == (payload if state == "success" else [])
+            else:
+                assert result == payload
+    assert allowed.await_args.kwargs == {
+        "user_api_key_auth": caller,
+        "mcp_servers": ["catalog"],
+        "client_ip": "192.0.2.41",
+    }
+    if state in ("denied", "scope_failure"):
+        upstream.assert_not_awaited()
+    else:
+        upstream.assert_awaited_once()
+        forwarded = upstream.await_args.kwargs
+        assert forwarded["user_api_key_auth"] == caller
+        assert forwarded["raw_headers"] == headers
+        assert forwarded["client_ip"] == "192.0.2.41"
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize(
+    "method", ["prompts/list", "prompts/get", "resources/list", "resources/templates/list", "resources/read"]
+)
+async def test_explicit_proxy_context_rejects_catalog_operations_before_upstream_access(method):
+    from mcp.shared.exceptions import MCPError
+    from mcp.types import METHOD_NOT_FOUND
+    from litellm.proxy._experimental.mcp_server import operations
+
+    operation, _, manager_method, _, _ = _catalog_case(method)
+    upstream = AsyncMock()
+    with patch.object(operations.global_mcp_server_manager, manager_method, upstream):
+        with pytest.raises(MCPError) as rejected:
+            await GatewayOperations().execute(operation, prepare_context(mcp_proxy_mode=True))
+    assert rejected.value.error.code == METHOD_NOT_FOUND
+    assert rejected.value.error.message == "Operation unavailable on /mcp/proxy"
+    upstream.assert_not_awaited()
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("failure", ["missing_env", "pii", "guardrail", "unexpected"])
+async def test_tool_operation_preserves_failure_messages_and_request_trace(failure):
+    from mcp.types import CallToolRequest, CallToolRequestParams
+    from litellm.exceptions import BlockedPiiEntityError, GuardrailRaisedException
+    from litellm.proxy._experimental.mcp_server import operations
+    from litellm.proxy._experimental.mcp_server.utils import MCPMissingUserEnvVarsError
+
+    failures = {
+        "missing_env": (
+            MCPMissingUserEnvVarsError(
+                server_id="server", server_name="server", missing=["TOKEN"], setup_url="https://example.com/setup"
+            ),
+            "https://example.com/setup",
+        ),
+        "pii": (
+            BlockedPiiEntityError(entity_type="EMAIL_ADDRESS", guardrail_name="test"),
+            "Blocked PII entity detected",
+        ),
+        "guardrail": (GuardrailRaisedException(message="request denied"), "Guardrail violation"),
+        "unexpected": (RuntimeError("upstream unavailable"), "Error: upstream unavailable"),
+    }
+    error, expected = failures[failure]
+    dispatch = AsyncMock(side_effect=error)
+    context = prepare_context(
+        raw_headers={"x-litellm-trace-id": "operation-trace", "authorization": "private-test-header"}
+    )
+    with patch.object(operations, "call_mcp_tool", dispatch):
+        result = await GatewayOperations().execute(
+            CallToolRequest(params=CallToolRequestParams(name="catalog-tool", arguments={})), context
+        )
+    assert result.is_error is True
+    assert expected in result.content[0].text
+    assert "private-test-header" not in result.content[0].text
+    dispatch.assert_awaited_once()
+    assert dispatch.await_args.kwargs["litellm_trace_id"] == "operation-trace"
+    assert dispatch.await_args.kwargs["litellm_session_id"] == "operation-trace"
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize(
+    "method,helper",
+    [
+        ("prompts/list", "_list_mcp_prompts"),
+        ("resources/list", "_list_mcp_resources"),
+        ("resources/templates/list", "_list_mcp_resource_templates"),
+    ],
+)
+async def test_catalog_operation_preserves_empty_result_for_malformed_upstream_items(method, helper):
+    from litellm.proxy._experimental.mcp_server import operations
+
+    operation, _, _, _, collection = _catalog_case(method)
+    with patch.object(operations, helper, AsyncMock(return_value=[{"unexpected": "item"}])):
+        result = await GatewayOperations().execute(operation, prepare_context())
+    assert getattr(result, collection) == []
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("catalog_unavailable", [False, True])
+async def test_tool_listing_returns_empty_result_without_dispatch_for_unavailable_catalog(catalog_unavailable):
+    from mcp.types import ListToolsRequest
+    from litellm.proxy._experimental.mcp_server import operations
+
+    allowed = AsyncMock(
+        return_value=[], side_effect=RuntimeError("catalog unavailable") if catalog_unavailable else None
+    )
+    upstream = AsyncMock()
+    with (
+        patch.object(operations, "_get_allowed_mcp_servers", allowed),
+        patch.object(operations.global_mcp_server_manager, "_get_tools_from_server", upstream),
+    ):
+        result = await GatewayOperations().execute(ListToolsRequest(), prepare_context())
+    assert result.tools == []
+    allowed.assert_awaited_once()
+    upstream.assert_not_awaited()
+
+
+@pytest.mark.asyncio
+async def test_explicit_proxy_context_lists_builtin_tools_and_blocks_direct_tool_dispatch():
+    from mcp.types import CallToolRequest, CallToolRequestParams, ListToolsRequest
+    from litellm.proxy._experimental.mcp_server import operations
+
+    context = prepare_context(mcp_proxy_mode=True)
+    allowed = AsyncMock()
+    with patch.object(operations, "_get_allowed_mcp_servers", allowed):
+        listing = await GatewayOperations().execute(ListToolsRequest(), context)
+        denied = await GatewayOperations().execute(
+            CallToolRequest(params=CallToolRequestParams(name="catalog-tool", arguments={})), context
+        )
+    assert {tool.name for tool in listing.tools} == {"search_tools", "get_tool_schema", "call_tool"}
+    assert denied.is_error is True
+    assert "unavailable on /mcp/proxy" in denied.content[0].text
+    allowed.assert_not_awaited()
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 13af58c15c0..233a8cc96ba 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
@@ -1,3 +1,4 @@
+from litellm.proxy._experimental.mcp_server import operations as mcp_operations
 import asyncio
 import inspect
 import json
@@ -1253,6 +1254,7 @@ class TestListToolsRestAPI:
             user_api_key_auth=None,
             extra_headers=None,
             apply_tool_filters=True,
+            client_ip=None,
         ):
             captured["called"] = True
             captured["server"] = server
@@ -1338,6 +1340,7 @@ class TestListToolsRestAPI:
             user_api_key_auth=None,
             extra_headers=None,
             apply_tool_filters=True,
+            client_ip=None,
         ):
             captured["user_api_key_auth"] = user_api_key_auth
             return ["tool-1"]
@@ -1891,6 +1894,7 @@ class TestListToolsRestAPI:
             user_api_key_auth=None,
             extra_headers=None,
             apply_tool_filters=True,
+            client_ip=None,
         ):
             captured["called"] = True
             captured["server_arg"] = server
@@ -2027,6 +2031,7 @@ class TestListToolsRestAPI:
             user_api_key_auth=None,
             extra_headers=None,
             apply_tool_filters=True,
+            client_ip=None,
         ):
             captured["called"] = True
             captured["server_arg"] = server
@@ -2112,6 +2117,7 @@ class TestListToolsRestAPI:
             user_api_key_auth=None,
             extra_headers=None,
             apply_tool_filters=True,
+            client_ip=None,
         ):
             return ["scoped-tool"]
 
@@ -2319,6 +2325,7 @@ class TestListToolsRestAPI:
             user_api_key_auth=None,
             extra_headers=None,
             apply_tool_filters=True,
+            client_ip=None,
         ):
             captured["server"] = server
             captured["auth_header"] = server_auth_header
@@ -3145,10 +3152,10 @@ async def test_request_selected_tool_specific_guardrail_applies_to_virtual_execu
     monkeypatch.setattr(litellm, "callbacks", [guardrail])
     monkeypatch.setattr(tool_registry, "global_mcp_tool_registry", registry)
     monkeypatch.setattr(mcp_server_manager, "global_mcp_server_manager", manager)
-    monkeypatch.setattr(server, "global_mcp_tool_registry", registry)
-    monkeypatch.setattr(server, "global_mcp_server_manager", manager)
+    monkeypatch.setattr(mcp_operations, "global_mcp_tool_registry", registry)
+    monkeypatch.setattr(mcp_operations, "global_mcp_server_manager", manager)
     monkeypatch.setattr(rest_endpoints, "global_mcp_server_manager", manager)
-    monkeypatch.setattr(server, "_get_allowed_mcp_servers", AsyncMock(return_value=[managed_server]))
+    monkeypatch.setattr(mcp_operations, "_get_allowed_mcp_servers", AsyncMock(return_value=[managed_server]))
     monkeypatch.setattr(proxy_server, "proxy_logging_obj", ProxyLogging(user_api_key_cache=DualCache()))
     monkeypatch.setattr(proxy_server, "add_litellm_data_to_request", passthrough_request_data)
     monkeypatch.setattr(proxy_server, "proxy_config", {})
diff --git a/tests/test_litellm/test_check_mcp_operation_boundary.py b/tests/test_litellm/test_check_mcp_operation_boundary.py
new file mode 100644
index 00000000000..d7ac72de9f0
--- /dev/null
+++ b/tests/test_litellm/test_check_mcp_operation_boundary.py
@@ -0,0 +1,52 @@
+from pathlib import Path
+
+import pytest
+
+from scripts.check_mcp_operation_boundary import main, violations
+
+
+@pytest.mark.parametrize(
+    "source",
+    (
+        "from mcp.server.auth.middleware.auth_context import auth_context_var as hidden",
+        "from litellm.proxy._experimental.mcp_server.mcp_context import _mcp_proxy_mode as mode",
+        "caller = legacy.get_active_auth_context()",
+        "owners = transport._stateful_session_owners",
+        "from weakref import WeakKeyDictionary",
+        "from litellm.proxy._experimental.mcp_server.server import get_auth_context",
+    ),
+)
+def test_shared_operation_boundary_rejects_ambient_state(source):
+    assert violations(Path("operations.py"), source)
+
+
+def test_legacy_adapter_may_resolve_context_but_policy_must_receive_it():
+    source = "from litellm.proxy._experimental.mcp_server.mcp_context import _mcp_proxy_mode"
+    assert violations(Path("server.py"), source) == ()
+    assert violations(Path("legacy_callbacks.py"), source) == ()
+    assert violations(Path("operations.py"), "def execute(context):\n    return context.client_ip") == ()
+    assert violations(Path("mcp_server_manager.py"), "def _mcp_registry_key(server):\n    return server.name") == ()
+
+
+def test_boundary_command_rejects_shared_state_and_accepts_explicit_context(tmp_path, monkeypatch, capsys):
+    import subprocess
+    import sys
+
+    package = tmp_path / "litellm/proxy/_experimental/mcp_server"
+    package.mkdir(parents=True)
+    module = package / "operations.py"
+    module.write_text("from mcp.server.auth.middleware.auth_context import auth_context_var as hidden\n")
+    command = [sys.executable, str(Path(__file__).resolve().parents[2] / "scripts/check_mcp_operation_boundary.py")]
+    monkeypatch.chdir(tmp_path)
+    assert main() == 1
+    assert "operations.py:1:" in capsys.readouterr().err
+    rejected = subprocess.run(command, cwd=tmp_path, capture_output=True, text=True, check=False)
+    assert rejected.returncode == 1
+    assert "operations.py:1: MCP request/session state belongs in a legacy adapter" in rejected.stderr
+
+    module.write_text("def execute(context):\n    return context.client_ip\n")
+    assert main() == 0
+    assert "MCP operation boundary: passed" in capsys.readouterr().out
+    accepted = subprocess.run(command, cwd=tmp_path, capture_output=True, text=True, check=False)
+    assert accepted.returncode == 0
+    assert "MCP operation boundary: passed" in accepted.stdout

From d2f30a77fded3a39c32b5dfc2f7f464bcd8f0409 Mon Sep 17 00:00:00 2001
From: Joshua Valluru <326636767+joshua-berri@users.noreply.github.com>
Date: Mon, 21 Sep 2026 12:31:48 -0700
Subject: [PATCH 21/55] test(mcp): preserve toolset scope across explicit
 context

---
 .../mcp_server/test_mcp_toolset_scope.py         | 16 ++++++++++++++++
 1 file changed, 16 insertions(+)

diff --git a/tests/test_litellm/proxy/_experimental/mcp_server/test_mcp_toolset_scope.py b/tests/test_litellm/proxy/_experimental/mcp_server/test_mcp_toolset_scope.py
index 60098b1f656..1398884783e 100644
--- a/tests/test_litellm/proxy/_experimental/mcp_server/test_mcp_toolset_scope.py
+++ b/tests/test_litellm/proxy/_experimental/mcp_server/test_mcp_toolset_scope.py
@@ -58,6 +58,22 @@ class TestApplyToolsetScope:
         assert set(op.mcp_servers or []) == {"server-a", "server-b"}
         assert op.mcp_tool_permissions == toolset_perms
 
+        from litellm.proxy._experimental.mcp_server.mcp_server_manager import MCPServerManager
+        from litellm.proxy._experimental.mcp_server.operations import prepare_context
+
+        manager = MCPServerManager()
+        unscoped_open = await manager.operator_open_server_ids(
+            auth, allow_all_server_ids=["operator-open-outside-toolset"], submitted_server_ids=[]
+        )
+        scoped_open = await manager.operator_open_server_ids(
+            prepare_context(result).user_api_key_auth,
+            allow_all_server_ids=["operator-open-outside-toolset"],
+            submitted_server_ids=[],
+        )
+        assert unscoped_open == {"operator-open-outside-toolset"}
+        assert scoped_open == set()
+        assert auth.mcp_toolset_id is None
+
     @pytest.mark.asyncio
     async def test_admin_creates_object_permission_when_none(self):
         """Admin key with object_permission=None can access any toolset."""

From e208b4e89ed41c6e4239c638f8e51a1239560959 Mon Sep 17 00:00:00 2001
From: Joshua Valluru <326636767+joshua-berri@users.noreply.github.com>
Date: Mon, 21 Sep 2026 12:40:12 -0700
Subject: [PATCH 22/55] fix(mcp): keep explicit legacy sampling callers
 isolated

---
 .../_experimental/mcp_server/legacy_callbacks.py    |  2 +-
 .../mcp_server/test_mcp_server_manager.py           | 13 +++++++++----
 2 files changed, 10 insertions(+), 5 deletions(-)

diff --git a/litellm/proxy/_experimental/mcp_server/legacy_callbacks.py b/litellm/proxy/_experimental/mcp_server/legacy_callbacks.py
index 4424907c28a..9e321062643 100644
--- a/litellm/proxy/_experimental/mcp_server/legacy_callbacks.py
+++ b/litellm/proxy/_experimental/mcp_server/legacy_callbacks.py
@@ -33,7 +33,7 @@ def create_sampling_callback(
 ) -> SamplingCallback:
     from litellm.proxy._experimental.mcp_server.server import get_active_auth_context
 
-    auth: Final = get_active_auth_context() if operation_context is None else None
+    auth: Final = get_active_auth_context() if operation_context is None and user_api_key_auth is None else None
     captured: Final = (
         operation_context
         if operation_context is not 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 7be79f9b514..2dc7e01966a 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
@@ -14214,10 +14214,11 @@ async def test_request_selected_during_guardrail_runs_concurrently_with_tool(mon
 
 
 @pytest.mark.asyncio
-@pytest.mark.parametrize("with_caller", [True, False])
-async def test_client_sampling_does_not_fill_explicit_context_from_another_ambient_caller(with_caller):
+@pytest.mark.parametrize("with_caller,legacy_factory", [(True, False), (False, False), (True, True)])
+async def test_client_sampling_does_not_fill_explicit_context_from_another_ambient_caller(with_caller, legacy_factory):
     from mcp.server.auth.middleware.auth_context import auth_context_var
     from litellm.proxy._experimental.mcp_server import server as legacy_server
+    from litellm.proxy._experimental.mcp_server.mcp_server_manager import _create_sampling_callback
 
     upstream = MCPServer(server_id="explicit-empty", name="explicit_empty", url="https://example.invalid/mcp", transport=MCPTransport.http, allow_sampling=True)
     token = auth_context_var.set(None)
@@ -14228,8 +14229,12 @@ async def test_client_sampling_does_not_fill_explicit_context_from_another_ambie
             patch("litellm.proxy._experimental.mcp_server.mcp_server_manager.MCPClient") as factory,
             patch("litellm.proxy._experimental.mcp_server.sampling_handler.handle_sampling_create_message", sampling),
         ):
-            await MCPServerManager()._create_mcp_client(upstream, user_api_key_auth=UserAPIKeyAuth(user_id="explicit") if with_caller else None)
-            await factory.call_args.kwargs["sampling_callback"](None, None)
+            if legacy_factory:
+                callback = _create_sampling_callback(user_api_key_auth=UserAPIKeyAuth(user_id="explicit"))
+            else:
+                await MCPServerManager()._create_mcp_client(upstream, user_api_key_auth=UserAPIKeyAuth(user_id="explicit") if with_caller else None)
+                callback = factory.call_args.kwargs["sampling_callback"]
+            await callback(None, None)
         captured = sampling.await_args.kwargs
         if with_caller:
             assert captured["user_api_key_auth"].user_id == "explicit"

From f0e87f2457011f01eecfbd3d07ddc94cd99bdf94 Mon Sep 17 00:00:00 2001
From: shivam <shivam@berri.ai>
Date: Mon, 21 Sep 2026 19:50:07 +0000
Subject: [PATCH 23/55] fix(router): keep refusal gates closed once every
 fallback entry was tried

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
 litellm/router.py                             |  9 +++---
 .../router_utils/fallback_event_handlers.py   | 12 +++++++
 .../test_fallback_event_handlers.py           | 19 ++++++++++-
 tests/test_litellm/test_router.py             | 32 +++++++++++++++++++
 4 files changed, 67 insertions(+), 5 deletions(-)

diff --git a/litellm/router.py b/litellm/router.py
index 98c7c319eaa..d9dd48a2c6a 100644
--- a/litellm/router.py
+++ b/litellm/router.py
@@ -191,6 +191,7 @@ from litellm.router_utils.fallback_event_handlers import (
     fallbacks_disabled_for_request,
     get_fallback_model_group_for_lookup_groups,
     get_pre_routing_selection,
+    has_unattempted_fallback_target,
     record_disable_fallbacks,
     record_pre_routing_selection,
     run_async_fallback,
@@ -8338,12 +8339,12 @@ class Router:
         """
         content_policy_fallbacks: Final = kwargs.get("content_policy_fallbacks", self.content_policy_fallbacks)
         if content_policy_fallbacks is not None:
-            return (
+            return has_unattempted_fallback_target(
                 self._get_fallback_model_group_for_lookup_groups(
                     fallbacks=content_policy_fallbacks,
                     lookup_groups=fallback_lookup_groups(kwargs, model_group),
-                )
-                is not None
+                ),
+                kwargs,
             )
         if self._has_default_fallbacks():
             return True
@@ -8375,7 +8376,7 @@ class Router:
             fallbacks=fallbacks,
             lookup_groups=fallback_lookup_groups(kwargs, model_group),
         )
-        return resolved is not None
+        return has_unattempted_fallback_target(resolved, kwargs)
 
     def _should_raise_content_policy_error(self, model: str, response: ModelResponse, kwargs: dict) -> bool:
         """
diff --git a/litellm/router_utils/fallback_event_handlers.py b/litellm/router_utils/fallback_event_handlers.py
index 156195f0587..08b9246e562 100644
--- a/litellm/router_utils/fallback_event_handlers.py
+++ b/litellm/router_utils/fallback_event_handlers.py
@@ -199,6 +199,18 @@ class AttemptedFallbackTargets:
         self.keys = self.keys | frozenset((key,))
 
 
+def has_unattempted_fallback_target(
+    fallback_model_group: Sequence[object] | None, kwargs: Mapping[str, object]
+) -> bool:
+    """Whether a resolved chain still holds an entry this request has not tried."""
+    if fallback_model_group is None:
+        return False
+    attempted: Final = kwargs.get("attempted_targets")
+    if not isinstance(attempted, AttemptedFallbackTargets):
+        return True
+    return any((key := fallback_attempt_key(target)) is None or key not in attempted for target in fallback_model_group)
+
+
 def _check_stripped_model_group(model_group: str, fallback_key: str) -> bool:
     """
     Handles wildcard routing scenario
diff --git a/tests/test_litellm/router_utils/test_fallback_event_handlers.py b/tests/test_litellm/router_utils/test_fallback_event_handlers.py
index 69772561172..b6ab21dfcef 100644
--- a/tests/test_litellm/router_utils/test_fallback_event_handlers.py
+++ b/tests/test_litellm/router_utils/test_fallback_event_handlers.py
@@ -1,6 +1,6 @@
 import json
 from datetime import datetime, timedelta
-from typing import NoReturn
+from typing import Final, NoReturn
 from unittest.mock import MagicMock, patch
 
 import httpx
@@ -1323,3 +1323,20 @@ class TestOrderedFallbackLookupGroups:
         assert get_fallback_model_group_for_lookup_groups(fallbacks, ("tier9", "smart-router")) == (["backup-b"], None)
         assert get_fallback_model_group_for_lookup_groups(fallbacks, ("tier9", "no-such")) == (["backup-c"], 2)
         assert get_fallback_model_group_for_lookup_groups([{"tier1": ["backup-a"]}], ("no", "nope")) == (None, None)
+
+
+class TestHasUnattemptedFallbackTarget:
+    def test_exhausted_chain_is_not_recoverable_but_a_fresh_entry_is(self):
+        from litellm.router_utils.fallback_event_handlers import (
+            has_unattempted_fallback_target,
+        )
+
+        attempted: Final = AttemptedFallbackTargets()
+        attempted.record("primary")
+        attempted.record("fb1")
+        attempted.record("fb2")
+
+        assert has_unattempted_fallback_target(["fb1", "fb2"], {"attempted_targets": attempted}) is False
+        assert has_unattempted_fallback_target(["fb1", "fb3"], {"attempted_targets": attempted}) is True
+        assert has_unattempted_fallback_target(["fb1"], {}) is True
+        assert has_unattempted_fallback_target(None, {}) is False
diff --git a/tests/test_litellm/test_router.py b/tests/test_litellm/test_router.py
index cf143744067..e31316009fa 100644
--- a/tests/test_litellm/test_router.py
+++ b/tests/test_litellm/test_router.py
@@ -3522,6 +3522,38 @@ async def test_acompletion_mid_stream_fallback_walks_every_entry_of_the_configur
     assert attempted_model_groups == ["primary", "fb1", "fb2"]
 
 
+def test_refusal_on_the_last_fallback_hop_is_returned_instead_of_raised():
+    """LIT-7400 follow-up: a refusal on the final hop of an exhausted list passes through."""
+    from litellm.router_utils.fallback_event_handlers import AttemptedFallbackTargets
+
+    router = litellm.Router(
+        model_list=[
+            {"model_name": "primary", "litellm_params": {"model": "openai/primary-model", "api_key": "fake-key"}},
+            {"model_name": "fb1", "litellm_params": {"model": "openai/fb1-model", "api_key": "fake-key"}},
+            {"model_name": "fb2", "litellm_params": {"model": "openai/fb2-model", "api_key": "fake-key"}},
+        ],
+        fallbacks=[{"primary": ["fb1", "fb2"]}],
+        num_retries=0,
+    )
+
+    attempted: Final = AttemptedFallbackTargets()
+    attempted.record("primary")
+    attempted.record("fb1")
+    attempted.record("fb2")
+    kwargs: Final = {
+        "attempted_targets": attempted,
+        "metadata": {"model_group": "fb2", "original_model_group": "primary"},
+    }
+
+    assert router._refusal_fallback_available("fb2", kwargs) is False
+    assert (
+        router._refusal_fallback_available(
+            "fb1", {"metadata": {"model_group": "fb1", "original_model_group": "primary"}}
+        )
+        is True
+    )
+
+
 def test_completion_streaming_iterator_adopts_fallback_response_headers():
     """LIT-6767, sync counterpart of the fallback-adoption test."""
     from unittest.mock import MagicMock, patch

From 9002749e29bcff3de2f8991ee988f923ffc5a3c5 Mon Sep 17 00:00:00 2001
From: Joshua Valluru <326636767+joshua-berri@users.noreply.github.com>
Date: Mon, 21 Sep 2026 12:58:06 -0700
Subject: [PATCH 24/55] fix(mcp): preserve Python 3.10 imports and integration
 test seams

---
 .../_experimental/mcp_server/operations.py    |  4 ++--
 tests/mcp_tests/test_mcp_logging.py           |  6 ++---
 tests/mcp_tests/test_mcp_server.py            | 24 ++++++++++---------
 3 files changed, 18 insertions(+), 16 deletions(-)

diff --git a/litellm/proxy/_experimental/mcp_server/operations.py b/litellm/proxy/_experimental/mcp_server/operations.py
index 3ee4f37add7..a579c33e702 100644
--- a/litellm/proxy/_experimental/mcp_server/operations.py
+++ b/litellm/proxy/_experimental/mcp_server/operations.py
@@ -6,7 +6,7 @@ import types
 import uuid
 from collections.abc import Mapping, Sequence
 from datetime import datetime
-from typing import Any, Final, NoReturn, TypeAlias, assert_never, overload
+from typing import Any, Final, NoReturn, TypeAlias, overload
 
 from fastapi import HTTPException
 from mcp import ReadResourceResult, Resource
@@ -34,7 +34,7 @@ from mcp.types import (
 )
 from mcp.types import Tool as MCPTool
 from pydantic import AnyUrl, ConfigDict, Field, TypeAdapter
-from typing_extensions import ReadOnly, TypedDict
+from typing_extensions import ReadOnly, TypedDict, assert_never
 
 from litellm._logging import verbose_logger
 from litellm.constants import (
diff --git a/tests/mcp_tests/test_mcp_logging.py b/tests/mcp_tests/test_mcp_logging.py
index ed8829945e5..41d0e2cb59b 100644
--- a/tests/mcp_tests/test_mcp_logging.py
+++ b/tests/mcp_tests/test_mcp_logging.py
@@ -142,7 +142,7 @@ async def test_mcp_cost_tracking():
                 local_mcp_server_manager,
             ),
             patch(
-                "litellm.proxy._experimental.mcp_server.server.global_mcp_server_manager",
+                "litellm.proxy._experimental.mcp_server.operations.global_mcp_server_manager",
                 local_mcp_server_manager,
             ),
         ):
@@ -293,7 +293,7 @@ async def test_mcp_cost_tracking_per_tool():
                 local_mcp_server_manager,
             ),
             patch(
-                "litellm.proxy._experimental.mcp_server.server.global_mcp_server_manager",
+                "litellm.proxy._experimental.mcp_server.operations.global_mcp_server_manager",
                 local_mcp_server_manager,
             ),
         ):
@@ -451,7 +451,7 @@ async def test_mcp_tool_call_hook():
                 local_mcp_server_manager,
             ),
             patch(
-                "litellm.proxy._experimental.mcp_server.server.global_mcp_server_manager",
+                "litellm.proxy._experimental.mcp_server.operations.global_mcp_server_manager",
                 local_mcp_server_manager,
             ),
         ):
diff --git a/tests/mcp_tests/test_mcp_server.py b/tests/mcp_tests/test_mcp_server.py
index 94cf35b675d..2b92367f186 100644
--- a/tests/mcp_tests/test_mcp_server.py
+++ b/tests/mcp_tests/test_mcp_server.py
@@ -922,7 +922,7 @@ async def test_get_tools_from_mcp_servers():
         )
 
         with patch(
-            "litellm.proxy._experimental.mcp_server.server.global_mcp_server_manager",
+            "litellm.proxy._experimental.mcp_server.operations.global_mcp_server_manager",
             mock_manager,
         ):
             # Test with specific servers
@@ -950,6 +950,7 @@ async def test_get_tools_from_mcp_servers():
                 extra_headers=None,
                 add_prefix=False,
                 raw_headers=None,
+                client_ip=None,
                 user_api_key_auth=None,
                 oauth2_headers=None,
             ):
@@ -966,7 +967,7 @@ async def test_get_tools_from_mcp_servers():
             )
 
         with patch(
-            "litellm.proxy._experimental.mcp_server.server.global_mcp_server_manager",
+            "litellm.proxy._experimental.mcp_server.operations.global_mcp_server_manager",
             mock_manager_2,
         ):
             result = await _get_tools_from_mcp_servers(
@@ -998,7 +999,7 @@ async def test_get_tools_from_mcp_servers():
         )
 
         with patch(
-            "litellm.proxy._experimental.mcp_server.server.global_mcp_server_manager",
+            "litellm.proxy._experimental.mcp_server.operations.global_mcp_server_manager",
             mock_manager,
         ):
             with patch(
@@ -1981,6 +1982,7 @@ async def test_get_tools_for_single_server():
             extra_headers=None,
             add_prefix=False,
             raw_headers=None,
+            client_ip=None,
             user_api_key_auth=None,
         )
 
@@ -2076,7 +2078,7 @@ async def test_rest_listing_hides_key_grants_dispatch_would_refuse():
     with patch(
         "litellm.proxy._experimental.mcp_server.rest_endpoints.global_mcp_server_manager"
     ) as mock_manager, patch(
-        "litellm.proxy._experimental.mcp_server.server.global_mcp_server_manager"
+        "litellm.proxy._experimental.mcp_server.operations.global_mcp_server_manager"
     ) as mock_server_manager, patch.object(
         MCPRequestHandler,
         "get_allowed_tools_for_server",
@@ -2473,7 +2475,7 @@ async def test_filter_tools_by_allowed_tools_integration():
 
     # Mock the global MCP server manager
     with patch(
-        "litellm.proxy._experimental.mcp_server.server.global_mcp_server_manager"
+        "litellm.proxy._experimental.mcp_server.operations.global_mcp_server_manager"
     ) as mock_manager:
         # Mock manager methods
         mock_manager.get_allowed_mcp_servers = AsyncMock(
@@ -2588,7 +2590,7 @@ async def test_filter_tools_by_disallowed_tools_integration():
 
     # Mock the global MCP server manager
     with patch(
-        "litellm.proxy._experimental.mcp_server.server.global_mcp_server_manager"
+        "litellm.proxy._experimental.mcp_server.operations.global_mcp_server_manager"
     ) as mock_manager:
         # Mock manager methods
         mock_manager.get_allowed_mcp_servers = AsyncMock(
@@ -2689,7 +2691,7 @@ async def test_filter_tools_no_restrictions_integration():
 
     # Mock the global MCP server manager
     with patch(
-        "litellm.proxy._experimental.mcp_server.server.global_mcp_server_manager"
+        "litellm.proxy._experimental.mcp_server.operations.global_mcp_server_manager"
     ) as mock_manager:
         # Mock manager methods
         mock_manager.get_allowed_mcp_servers = AsyncMock(
@@ -2970,10 +2972,10 @@ async def test_call_mcp_tool_uses_manager_permission_lookup():
             return_value=mock_server,
         ) as mock_get_server,
         patch(
-            "litellm.proxy._experimental.mcp_server.server.global_mcp_tool_registry"
+            "litellm.proxy._experimental.mcp_server.operations.global_mcp_tool_registry"
         ) as mock_tool_registry,
         patch(
-            "litellm.proxy._experimental.mcp_server.server._handle_managed_mcp_tool",
+            "litellm.proxy._experimental.mcp_server.operations._handle_managed_mcp_tool",
             new_callable=AsyncMock,
         ) as mock_handle_managed,
         patch(
@@ -3046,10 +3048,10 @@ async def test_call_mcp_tool_resolves_unprefixed_tool_name_and_checks_permission
             return_value=mock_server,
         ) as mock_get_server,
         patch(
-            "litellm.proxy._experimental.mcp_server.server.global_mcp_tool_registry"
+            "litellm.proxy._experimental.mcp_server.operations.global_mcp_tool_registry"
         ) as mock_tool_registry,
         patch(
-            "litellm.proxy._experimental.mcp_server.server._handle_managed_mcp_tool",
+            "litellm.proxy._experimental.mcp_server.operations._handle_managed_mcp_tool",
             new_callable=AsyncMock,
         ) as mock_handle_managed,
         patch(

From db7d52eedaf31d9a6d9b964048134d3e9d9bd0e2 Mon Sep 17 00:00:00 2001
From: shivam <shivam@berri.ai>
Date: Mon, 21 Sep 2026 20:01:50 +0000
Subject: [PATCH 25/55] test(router): track attempted fallback groups via the
 mock call log

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
 tests/test_litellm/test_router.py | 11 ++++++-----
 1 file changed, 6 insertions(+), 5 deletions(-)

diff --git a/tests/test_litellm/test_router.py b/tests/test_litellm/test_router.py
index e31316009fa..e642520bdbd 100644
--- a/tests/test_litellm/test_router.py
+++ b/tests/test_litellm/test_router.py
@@ -3460,8 +3460,6 @@ async def test_acompletion_mid_stream_fallback_walks_every_entry_of_the_configur
     from litellm.exceptions import MidStreamFallbackError
     from litellm.litellm_core_utils.streaming_handler import CustomStreamWrapper
 
-    attempted_model_groups: list[str] = []
-
     class FailingStream(CustomStreamWrapper):
         def __init__(self, model: str):
             super().__init__(
@@ -3497,7 +3495,6 @@ async def test_acompletion_mid_stream_fallback_walks_every_entry_of_the_configur
                 raise StopAsyncIteration from None
 
     async def fake_acompletion(**kwargs):
-        attempted_model_groups.append(kwargs["metadata"]["model_group"])
         if "fb2" in kwargs["model"]:
             return OkStream(kwargs["model"])
         return FailingStream(kwargs["model"])
@@ -3512,14 +3509,18 @@ async def test_acompletion_mid_stream_fallback_walks_every_entry_of_the_configur
         num_retries=0,
     )
 
-    with patch("litellm.acompletion", side_effect=fake_acompletion):
+    with patch("litellm.acompletion", side_effect=fake_acompletion) as mock_acompletion:
         response = await router.acompletion(model="primary", messages=[{"role": "user", "content": "hi"}], stream=True)
         content: Final = "".join(
             [chunk.choices[0].delta.content or "" async for chunk in response if chunk is not None]
         )
 
     assert content == "ok-from-openai/fb2-model"
-    assert attempted_model_groups == ["primary", "fb1", "fb2"]
+    assert [c.kwargs["metadata"]["model_group"] for c in mock_acompletion.call_args_list] == [
+        "primary",
+        "fb1",
+        "fb2",
+    ]
 
 
 def test_refusal_on_the_last_fallback_hop_is_returned_instead_of_raised():

From ef67412e50c9f3250eb473a0a14fbf00617e36ea Mon Sep 17 00:00:00 2001
From: Joshua Valluru <326636767+joshua-berri@users.noreply.github.com>
Date: Mon, 21 Sep 2026 13:13:20 -0700
Subject: [PATCH 26/55] fix(mcp): keep OAuth prefetch failure logs free of
 caller data

---
 .../_experimental/mcp_server/operations.py    |  6 ++---
 .../proxy/_experimental/mcp_server/server.py  |  3 +++
 .../mcp_server/test_operations.py             | 22 +++++++++++++++++++
 3 files changed, 28 insertions(+), 3 deletions(-)

diff --git a/litellm/proxy/_experimental/mcp_server/operations.py b/litellm/proxy/_experimental/mcp_server/operations.py
index a579c33e702..fcee3483e15 100644
--- a/litellm/proxy/_experimental/mcp_server/operations.py
+++ b/litellm/proxy/_experimental/mcp_server/operations.py
@@ -763,8 +763,8 @@ async def _prefetch_oauth_creds_for_user(
         )
         creds: Final = await list_user_oauth_credentials(prisma_client, user_id)
         return {c["server_id"]: c for c in creds if "server_id" in c}
-    except Exception as e:
-        verbose_logger.warning("_prefetch_oauth_creds_for_user: failed to prefetch for user=%s: %s", user_id, e)
+    except Exception:
+        verbose_logger.warning("_prefetch_oauth_creds_for_user: failed to prefetch OAuth credentials")
         return {}
 
 
@@ -3099,4 +3099,4 @@ class GatewayOperations:
             case ReadResourceRequest(params=params):
                 return await _execute_read_resource(context, params, self._host_progress_callback)
             case _:
-                assert_never(operation)
+                return assert_never(operation)
diff --git a/litellm/proxy/_experimental/mcp_server/server.py b/litellm/proxy/_experimental/mcp_server/server.py
index 33978bb9182..a57eed04419 100644
--- a/litellm/proxy/_experimental/mcp_server/server.py
+++ b/litellm/proxy/_experimental/mcp_server/server.py
@@ -416,7 +416,10 @@ def _proxy_exception_to_http_exception(exc: ProxyException) -> HTTPException:
 if MCP_AVAILABLE:
     __all__ = (
         "_MCP_CREDENTIAL_REQUEST_FIELDS",
+        "BlobResourceContents",
         "ListMCPToolsRestAPIResponseObject",
+        "ResourceTemplate",
+        "TextResourceContents",
         "_McpDeniedDetail",
         "_aggregate_server_key",
         "_build_virtual_call_logging_obj",
diff --git a/tests/test_litellm/proxy/_experimental/mcp_server/test_operations.py b/tests/test_litellm/proxy/_experimental/mcp_server/test_operations.py
index 870f2cd5f8f..abb925ddc77 100644
--- a/tests/test_litellm/proxy/_experimental/mcp_server/test_operations.py
+++ b/tests/test_litellm/proxy/_experimental/mcp_server/test_operations.py
@@ -8,6 +8,28 @@ from litellm.proxy._experimental.mcp_server.operations import GatewayOperations,
 from litellm.proxy._types import UserAPIKeyAuth
 
 
+@pytest.mark.asyncio
+async def test_oauth_prefetch_failure_does_not_log_caller_or_exception_text(caplog):
+    from litellm.proxy._experimental.mcp_server.operations import _prefetch_oauth_creds_for_user
+
+    user_id = "caller\nFORGED-USER-LINE"
+    fetch = AsyncMock(side_effect=RuntimeError("database\nFORGED-ERROR-LINE"))
+    database = object()
+    with (
+        patch("litellm.proxy.utils.get_prisma_client_or_throw", return_value=database),
+        patch("litellm.proxy._experimental.mcp_server.db.list_user_oauth_credentials", fetch),
+        caplog.at_level("WARNING", logger="LiteLLM"),
+    ):
+        result = await _prefetch_oauth_creds_for_user(UserAPIKeyAuth(user_id=user_id))
+    assert result == {}
+    fetch.assert_awaited_once_with(database, user_id)
+    warnings = [record.getMessage() for record in caplog.records if "prefetch" in record.getMessage()]
+    assert len(warnings) == 1
+    assert "failed" in warnings[0]
+    assert "\n" not in warnings[0]
+    assert "FORGED" not in warnings[0]
+
+
 @pytest.mark.asyncio
 async def test_dispatch_uses_explicit_context_when_ambient_caller_differs():
     from mcp.server.auth.middleware.auth_context import auth_context_var

From 56d1f042ef3de13f27d98a9acecf9bc7b5f5c3b3 Mon Sep 17 00:00:00 2001
From: mateo-berri <277851410+mateo-berri@users.noreply.github.com>
Date: Mon, 21 Sep 2026 13:16:58 -0700
Subject: [PATCH 27/55] fix(types): read upstream headers through a typed
 helper

---
 litellm/llms/custom_httpx/http_handler.py                    | 5 +++++
 .../_experimental/mcp_server/openapi_to_mcp_generator.py     | 3 ++-
 litellm/rag/ingestion/gemini_ingestion.py                    | 3 ++-
 3 files changed, 9 insertions(+), 2 deletions(-)

diff --git a/litellm/llms/custom_httpx/http_handler.py b/litellm/llms/custom_httpx/http_handler.py
index 6b90394043f..b7b2477e85c 100644
--- a/litellm/llms/custom_httpx/http_handler.py
+++ b/litellm/llms/custom_httpx/http_handler.py
@@ -479,6 +479,11 @@ def _safe_get_response_text(response: httpx.Response) -> str:
         return ""
 
 
+def header_value(headers: Mapping[str, str], name: str) -> str | None:
+    """Read one header as ``str | None``; ``httpx.Headers.get`` itself is typed ``Any``."""
+    return headers.get(name)
+
+
 async def _safe_aread_response(response: httpx.Response, timeout: float | None = None) -> bytes:
     """Safely read async response body, falling back to empty bytes on errors."""
     try:
diff --git a/litellm/proxy/_experimental/mcp_server/openapi_to_mcp_generator.py b/litellm/proxy/_experimental/mcp_server/openapi_to_mcp_generator.py
index 3c26937bfac..1247ff1ac28 100644
--- a/litellm/proxy/_experimental/mcp_server/openapi_to_mcp_generator.py
+++ b/litellm/proxy/_experimental/mcp_server/openapi_to_mcp_generator.py
@@ -49,6 +49,7 @@ from litellm.litellm_core_utils.url_utils import async_safe_get
 from litellm.llms.custom_httpx.http_handler import (
     AsyncHTTPHandler,
     get_async_httpx_client,
+    header_value,
     httpxSpecialProvider,
 )
 from litellm.proxy._experimental.mcp_server.tool_registry import (
@@ -457,7 +458,7 @@ def _raise_for_upstream_failure(
     if response.status_code == 401 and relays_upstream_auth:
         raise MCPUpstreamAuthError(
             status_code=response.status_code,
-            www_authenticate=dict(response.headers).get("www-authenticate"),
+            www_authenticate=header_value(response.headers, "www-authenticate"),
             server_name=upstream,
         )
     raise MCPOpenApiUpstreamError(response.status_code, upstream)
diff --git a/litellm/rag/ingestion/gemini_ingestion.py b/litellm/rag/ingestion/gemini_ingestion.py
index b81c2cc0ebe..1cf5db549e4 100644
--- a/litellm/rag/ingestion/gemini_ingestion.py
+++ b/litellm/rag/ingestion/gemini_ingestion.py
@@ -12,6 +12,7 @@ from typing import TYPE_CHECKING, Final, cast
 from litellm._logging import verbose_logger
 from litellm.llms.custom_httpx.http_handler import (
     get_async_httpx_client,
+    header_value,
     httpxSpecialProvider,
 )
 from litellm.llms.gemini.common_utils import GeminiModelInfo
@@ -277,7 +278,7 @@ class GeminiRAGIngestion(BaseRAGIngestion):
             raise Exception(error_msg)
         verbose_logger.debug("Initiate resumable upload response: %s", response.headers)
         # Extract upload URL from response headers
-        upload_url: Final = dict(response.headers).get("x-goog-upload-url")
+        upload_url: Final = header_value(response.headers, "x-goog-upload-url")
         if not upload_url:
             raise Exception("No upload URL returned in response headers")
 

From 94b8bf7fd6aa93afb8e8d9a84e047daf06ab01bc Mon Sep 17 00:00:00 2001
From: Yujong Lee <yujong@berri.ai>
Date: Mon, 21 Sep 2026 20:37:26 +0000
Subject: [PATCH 28/55] feat(rust): add native disk cache backend

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
 litellm-rust/Cargo.lock                       | 126 +++
 litellm-rust/Cargo.toml                       |   1 +
 litellm-rust/crates/cache-disk/Cargo.toml     |  17 +
 litellm-rust/crates/cache-disk/src/cache.rs   | 330 +++++++
 litellm-rust/crates/cache-disk/src/lib.rs     |   8 +
 litellm-rust/crates/cache-disk/src/pickle.rs  |  48 ++
 litellm-rust/crates/cache-disk/src/sqlite.rs  | 816 ++++++++++++++++++
 litellm-rust/crates/cache-disk/src/store.rs   |  33 +
 litellm-rust/crates/cache-disk/tests/cache.rs | 327 +++++++
 litellm-rust/crates/python-bridge/Cargo.toml  |   1 +
 .../crates/python-bridge/src/cache/config.rs  | 139 ++-
 .../crates/python-bridge/src/cache/facade.rs  |  38 +-
 .../crates/python-bridge/src/cache/handle.rs  |  12 +
 .../crates/python-bridge/src/cache/native.rs  |  31 +-
 tests/test_litellm_rust/test_cache.py         | 111 +++
 15 files changed, 2026 insertions(+), 12 deletions(-)
 create mode 100644 litellm-rust/crates/cache-disk/Cargo.toml
 create mode 100644 litellm-rust/crates/cache-disk/src/cache.rs
 create mode 100644 litellm-rust/crates/cache-disk/src/lib.rs
 create mode 100644 litellm-rust/crates/cache-disk/src/pickle.rs
 create mode 100644 litellm-rust/crates/cache-disk/src/sqlite.rs
 create mode 100644 litellm-rust/crates/cache-disk/src/store.rs
 create mode 100644 litellm-rust/crates/cache-disk/tests/cache.rs

diff --git a/litellm-rust/Cargo.lock b/litellm-rust/Cargo.lock
index ed4ae4e3353..554245dbb6e 100644
--- a/litellm-rust/Cargo.lock
+++ b/litellm-rust/Cargo.lock
@@ -1318,6 +1318,18 @@ dependencies = [
  "pin-project-lite",
 ]
 
+[[package]]
+name = "fallible-iterator"
+version = "0.3.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2acce4a10f12dc2fb14a218589d4f1f62ef011b2d0cc4b3cb1bba8e94da14649"
+
+[[package]]
+name = "fallible-streaming-iterator"
+version = "0.1.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7360491ce676a36bf9bb3c56c1aa791658183a54d2744120f27285738d90465a"
+
 [[package]]
 name = "fancy-regex"
 version = "0.17.0"
@@ -1369,6 +1381,12 @@ version = "1.0.7"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "3f9eec918d3f24069decb9af1554cad7c880e2da24a9afd88aca000531ab82c1"
 
+[[package]]
+name = "foldhash"
+version = "0.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "77ce24cb58228fbb8aa041425bb1050850ac19177686ea6e0f41a70416f56fdb"
+
 [[package]]
 name = "form_urlencoded"
 version = "1.2.2"
@@ -1833,11 +1851,32 @@ version = "0.12.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "8a9ee70c43aaf417c914396645a0fa852624801b24ebb7ae78fe8272889ac888"
 
+[[package]]
+name = "hashbrown"
+version = "0.16.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "841d1cc9bed7f9236f321df977030373f4a4163ae1a7dbfe1a51a2c1a51d9100"
+dependencies = [
+ "foldhash",
+]
+
 [[package]]
 name = "hashbrown"
 version = "0.17.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "ed5909b6e89a2db4456e54cd5f673791d7eca6732202bbf2a9cc504fe2f9b84a"
+dependencies = [
+ "foldhash",
+]
+
+[[package]]
+name = "hashlink"
+version = "0.12.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a596f1b20ed2cc5ecac41a164aaebc7258057060f06c0cf7a2ba3991ee7990fb"
+dependencies = [
+ "hashbrown 0.17.1",
+]
 
 [[package]]
 name = "heck"
@@ -2218,6 +2257,12 @@ version = "2.12.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "d98f6fed1fde3f8c21bc40a1abb88dd75e67924f9cffc3ef95607bad8017f8e2"
 
+[[package]]
+name = "iter-read"
+version = "1.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "071ed4cc1afd86650602c7b11aa2e1ce30762a1c27193201cb5cee9c6ebb1294"
+
 [[package]]
 name = "itertools"
 version = "0.13.0"
@@ -2376,6 +2421,17 @@ version = "0.2.186"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "68ab91017fe16c622486840e4c83c9a37afeff978bd239b5293d61ece587de66"
 
+[[package]]
+name = "libsqlite3-sys"
+version = "0.38.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f1d20bef17f513b9b3004532233187769cd072d790971f4e4da0e346eb6401e8"
+dependencies = [
+ "cc",
+ "pkg-config",
+ "vcpkg",
+]
+
 [[package]]
 name = "linux-raw-sys"
 version = "0.12.1"
@@ -2464,6 +2520,19 @@ dependencies = [
  "tokio",
 ]
 
+[[package]]
+name = "litellm-cache-disk"
+version = "0.1.0"
+dependencies = [
+ "litellm-cache",
+ "rand 0.8.7",
+ "rusqlite",
+ "serde-pickle",
+ "serde_json",
+ "tempfile",
+ "tokio",
+]
+
 [[package]]
 name = "litellm-cache-memory"
 version = "0.1.0"
@@ -2666,6 +2735,7 @@ dependencies = [
  "litellm-auth",
  "litellm-auth-gcp",
  "litellm-cache",
+ "litellm-cache-disk",
  "litellm-cache-memory",
  "litellm-cache-redis",
  "litellm-cache-response",
@@ -3901,6 +3971,16 @@ dependencies = [
  "windows-sys 0.52.0",
 ]
 
+[[package]]
+name = "rsqlite-vfs"
+version = "0.1.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c51c9ae4df8a7fba42103df5c621fa3c37eccf3a3c650879e90fc48b11cc192c"
+dependencies = [
+ "hashbrown 0.16.1",
+ "thiserror 2.0.19",
+]
+
 [[package]]
 name = "rstest"
 version = "0.26.1"
@@ -3941,6 +4021,21 @@ dependencies = [
  "syn 2.0.119",
 ]
 
+[[package]]
+name = "rusqlite"
+version = "0.40.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "23f2a97da3e3873c73cb2a2e71b35c40ff95e0b1eefa8d72d8499a6928c3b5b3"
+dependencies = [
+ "bitflags 2.13.1",
+ "fallible-iterator",
+ "fallible-streaming-iterator",
+ "hashlink",
+ "libsqlite3-sys",
+ "smallvec",
+ "sqlite-wasm-rs",
+]
+
 [[package]]
 name = "rustc-hash"
 version = "2.1.3"
@@ -4198,6 +4293,19 @@ dependencies = [
  "serde_derive",
 ]
 
+[[package]]
+name = "serde-pickle"
+version = "1.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b641fdc8bcf2781ee78b30c599700d64ad4f412976143e4c5d0b9df906bb4843"
+dependencies = [
+ "byteorder",
+ "iter-read",
+ "num-bigint 0.4.8",
+ "num-traits",
+ "serde",
+]
+
 [[package]]
 name = "serde_core"
 version = "1.0.229"
@@ -4425,6 +4533,18 @@ dependencies = [
  "unicode-segmentation",
 ]
 
+[[package]]
+name = "sqlite-wasm-rs"
+version = "0.5.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "dc3efc0da82635d7e1ced0053bbbfa8c7ab9645d0bf36ceb4f7127bb85315d75"
+dependencies = [
+ "cc",
+ "js-sys",
+ "rsqlite-vfs",
+ "wasm-bindgen",
+]
+
 [[package]]
 name = "sse-stream"
 version = "0.2.6"
@@ -5170,6 +5290,12 @@ version = "0.1.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "ba73ea9cf16a25df0c8caa16c51acb937d5712a8429db78a3ee29d5dcacd3a65"
 
+[[package]]
+name = "vcpkg"
+version = "0.2.15"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "accd4ea62f7bb7a82fe23066fb0957d48ef677f6eeb8215f372f52e48bb32426"
+
 [[package]]
 name = "veil"
 version = "0.3.0"
diff --git a/litellm-rust/Cargo.toml b/litellm-rust/Cargo.toml
index 570d0dd3568..53db97b2d01 100644
--- a/litellm-rust/Cargo.toml
+++ b/litellm-rust/Cargo.toml
@@ -29,6 +29,7 @@ litellm-core-utils = { path = "crates/core-utils" }
 litellm-cache = { path = "crates/cache" }
 litellm-cache-memory = { path = "crates/cache-memory" }
 litellm-cache-redis = { path = "crates/cache-redis" }
+litellm-cache-disk = { path = "crates/cache-disk" }
 litellm-cache-response = { path = "crates/cache-response" }
 litellm-token-counter = { path = "crates/token-counter" }
 litellm-token-counter-fast = { path = "crates/token-counter-fast" }
diff --git a/litellm-rust/crates/cache-disk/Cargo.toml b/litellm-rust/crates/cache-disk/Cargo.toml
new file mode 100644
index 00000000000..023055e391a
--- /dev/null
+++ b/litellm-rust/crates/cache-disk/Cargo.toml
@@ -0,0 +1,17 @@
+[package]
+name = "litellm-cache-disk"
+version = "0.1.0"
+edition.workspace = true
+license.workspace = true
+repository.workspace = true
+
+[dependencies]
+litellm-cache.workspace = true
+rand.workspace = true
+rusqlite = { version = "0.40", features = ["bundled"] }
+serde-pickle = "1.2"
+serde_json.workspace = true
+tokio.workspace = true
+
+[dev-dependencies]
+tempfile = "3.27.0"
diff --git a/litellm-rust/crates/cache-disk/src/cache.rs b/litellm-rust/crates/cache-disk/src/cache.rs
new file mode 100644
index 00000000000..bcce3a525b1
--- /dev/null
+++ b/litellm-rust/crates/cache-disk/src/cache.rs
@@ -0,0 +1,330 @@
+use std::{
+    path::Path,
+    sync::Arc,
+    time::{Duration, SystemTime, UNIX_EPOCH},
+};
+
+use litellm_cache::{
+    BaseCache, BatchCache, BatchEntry, CacheCodec, CacheConnectionResult, CacheConnectionStatus,
+    CounterCache, DeleteCache, Error, ExactCacheContext, FlushCache,
+};
+use serde_json::Value;
+
+use crate::{DiskStore, DiskcacheSqliteStore, StoredValue, pickle};
+
+pub struct DiskCache<S, D = DiskcacheSqliteStore> {
+    store: Arc<D>,
+    codec: S,
+}
+
+impl<S: CacheCodec> DiskCache<S> {
+    pub fn open(directory: impl AsRef<Path>, codec: S) -> Result<Self, Error> {
+        Ok(Self {
+            store: Arc::new(DiskcacheSqliteStore::open(directory)?),
+            codec,
+        })
+    }
+}
+
+impl<S: CacheCodec, D: DiskStore> DiskCache<S, D> {
+    pub fn with_store(store: D, codec: S) -> Self {
+        Self {
+            store: Arc::new(store),
+            codec,
+        }
+    }
+
+    pub fn directory(&self) -> &Path {
+        self.store.directory()
+    }
+
+    fn decode_stored(&self, value: StoredValue) -> Result<Option<S::Value>, Error> {
+        let Some(bytes) = payload(value)? else {
+            return Ok(None);
+        };
+        self.codec.decode(&bytes).map(Some)
+    }
+
+    async fn run_blocking<T, F>(store: Arc<D>, operation: F) -> Result<T, Error>
+    where
+        T: Send + 'static,
+        F: FnOnce(&D) -> Result<T, Error> + Send + 'static,
+    {
+        tokio::task::spawn_blocking(move || operation(&store))
+            .await
+            .map_err(|_| Error::Unavailable)?
+    }
+}
+
+impl<S: CacheCodec, D: DiskStore> BaseCache for DiskCache<S, D> {
+    type Value = S::Value;
+    type Context = ExactCacheContext;
+
+    fn get_ttl(&self, context: &Self::Context) -> Option<Duration> {
+        context.ttl
+    }
+
+    fn set_cache(
+        &self,
+        key: &str,
+        value: Self::Value,
+        context: &Self::Context,
+    ) -> Result<(), Error> {
+        let value = StoredValue::Bytes(self.codec.encode(&value)?);
+        let expire_time = context.ttl.map(|ttl| unix_now() + ttl.as_secs_f64());
+        self.store.set(key, value, expire_time, unix_now())
+    }
+
+    fn get_cache(&self, key: &str, _: &Self::Context) -> Result<Option<Self::Value>, Error> {
+        self.store
+            .get(key, unix_now())?
+            .map(|value| self.decode_stored(value))
+            .transpose()
+            .map(|value| value.flatten())
+    }
+
+    async fn async_set_cache(
+        &self,
+        key: &str,
+        value: Self::Value,
+        context: ExactCacheContext,
+    ) -> Result<(), Error> {
+        let value = StoredValue::Bytes(self.codec.encode(&value)?);
+        let expire_time = context.ttl.map(|ttl| unix_now() + ttl.as_secs_f64());
+        let key = key.to_string();
+        Self::run_blocking(Arc::clone(&self.store), move |store| {
+            store.set(&key, value, expire_time, unix_now())
+        })
+        .await
+    }
+
+    async fn async_get_cache(
+        &self,
+        key: &str,
+        _: &ExactCacheContext,
+    ) -> Result<Option<Self::Value>, Error> {
+        let key = key.to_string();
+        let value = Self::run_blocking(Arc::clone(&self.store), move |store| {
+            store.get(&key, unix_now())
+        })
+        .await?;
+        value
+            .map(|value| self.decode_stored(value))
+            .transpose()
+            .map(|value| value.flatten())
+    }
+
+    async fn async_set_cache_pipeline(
+        &self,
+        entries: Vec<(String, Self::Value)>,
+        context: ExactCacheContext,
+    ) -> Result<(), Error> {
+        let entries = entries
+            .into_iter()
+            .map(|(key, value)| {
+                self.codec
+                    .encode(&value)
+                    .map(|value| (key, StoredValue::Bytes(value)))
+            })
+            .collect::<Result<Vec<_>, _>>()?;
+        let expire_after = context.ttl;
+        Self::run_blocking(Arc::clone(&self.store), move |store| {
+            for (key, value) in entries {
+                let expire_time = expire_after.map(|ttl| unix_now() + ttl.as_secs_f64());
+                store.set(&key, value, expire_time, unix_now())?;
+            }
+            Ok(())
+        })
+        .await
+    }
+
+    async fn disconnect(&self) -> Result<(), Error> {
+        Ok(())
+    }
+
+    async fn test_connection(&self) -> Result<CacheConnectionResult, Error> {
+        let result = Self::run_blocking(Arc::clone(&self.store), |store| {
+            store.probe().map(|_| CacheConnectionResult {
+                status: CacheConnectionStatus::Success,
+                message: "Disk cache connection test successful".into(),
+                error: None,
+            })
+        })
+        .await;
+        Ok(match result {
+            Ok(result) => result,
+            Err(error) => CacheConnectionResult {
+                status: CacheConnectionStatus::Failed,
+                message: format!("Disk cache connection failed: {error}"),
+                error: Some(error.to_string()),
+            },
+        })
+    }
+}
+
+impl<S: CacheCodec, D: DiskStore> BatchCache for DiskCache<S, D> {
+    fn batch_get_cache(
+        &self,
+        keys: &[String],
+        context: &ExactCacheContext,
+    ) -> Result<Vec<BatchEntry<Self::Value>>, Error> {
+        keys.iter()
+            .map(|key| match self.get_cache(key, context) {
+                Ok(Some(value)) => Ok(BatchEntry::Hit(value)),
+                Ok(None) => Ok(BatchEntry::Miss),
+                Err(Error::InvalidEntry) => Ok(BatchEntry::Invalid),
+                Err(error) => Err(error),
+            })
+            .collect()
+    }
+
+    async fn async_batch_get_cache(
+        &self,
+        keys: Vec<String>,
+        _: ExactCacheContext,
+    ) -> Result<Vec<BatchEntry<Self::Value>>, Error> {
+        let values = Self::run_blocking(Arc::clone(&self.store), move |store| {
+            keys.into_iter()
+                .map(|key| store.get(&key, unix_now()).map(|value| (key, value)))
+                .collect::<Result<Vec<_>, _>>()
+        })
+        .await?;
+        values
+            .into_iter()
+            .map(|(_, value)| match value {
+                None => Ok(BatchEntry::Miss),
+                Some(value) => match self.decode_stored(value) {
+                    Ok(Some(value)) => Ok(BatchEntry::Hit(value)),
+                    Ok(None) => Ok(BatchEntry::Miss),
+                    Err(Error::InvalidEntry) => Ok(BatchEntry::Invalid),
+                    Err(error) => Err(error),
+                },
+            })
+            .collect()
+    }
+}
+
+impl<S: CacheCodec, D: DiskStore> DeleteCache for DiskCache<S, D> {
+    fn delete_cache(&self, key: &str) -> Result<(), Error> {
+        self.store.pop(key, unix_now()).map(|_| ())
+    }
+
+    async fn async_delete_cache(&self, key: &str) -> Result<(), Error> {
+        let key = key.to_string();
+        Self::run_blocking(Arc::clone(&self.store), move |store| {
+            store.pop(&key, unix_now()).map(|_| ())
+        })
+        .await
+    }
+}
+
+impl<S: CacheCodec, D: DiskStore> FlushCache for DiskCache<S, D> {
+    fn flush_cache(&self) -> Result<(), Error> {
+        self.store.clear()
+    }
+
+    async fn async_flush_cache(&self) -> Result<(), Error> {
+        Self::run_blocking(Arc::clone(&self.store), |store| store.clear()).await
+    }
+}
+
+impl<S: CacheCodec<Value = f64>, D: DiskStore> CounterCache for DiskCache<S, D> {
+    fn increment_cache(
+        &self,
+        key: &str,
+        amount: f64,
+        context: ExactCacheContext,
+    ) -> Result<f64, Error> {
+        increment(self.store.as_ref(), key, amount, context.ttl)
+    }
+
+    async fn async_increment(
+        &self,
+        key: &str,
+        amount: f64,
+        context: ExactCacheContext,
+    ) -> Result<f64, Error> {
+        let key = key.to_string();
+        Self::run_blocking(Arc::clone(&self.store), move |store| {
+            increment(store, &key, amount, context.ttl)
+        })
+        .await
+    }
+}
+
+fn increment<D: DiskStore>(
+    store: &D,
+    key: &str,
+    amount: f64,
+    ttl: Option<Duration>,
+) -> Result<f64, Error> {
+    let mut result = None;
+    let mut apply = |current: Option<StoredValue>| {
+        let initial = match current {
+            Some(StoredValue::Integer(value)) => value as f64,
+            Some(StoredValue::Pickle(value)) => match pickle::decode(&value)? {
+                Value::Number(value) => value
+                    .as_i64()
+                    .map(|value| value as f64)
+                    .or_else(|| value.as_u64().map(|value| value as f64))
+                    .unwrap_or_default(),
+                _ => 0.0,
+            },
+            _ => 0.0,
+        };
+        let value = initial + amount;
+        let stored = if value.fract() == 0.0 && value >= i64::MIN as f64 && value <= i64::MAX as f64
+        {
+            StoredValue::Integer(value as i64)
+        } else {
+            StoredValue::Float(value)
+        };
+        result = Some(value);
+        Ok((stored, ttl.map(|ttl| unix_now() + ttl.as_secs_f64())))
+    };
+    store.update(key, unix_now(), &mut apply)?;
+    result.ok_or(Error::InvalidEntry)
+}
+
+fn payload(value: StoredValue) -> Result<Option<Vec<u8>>, Error> {
+    match value {
+        StoredValue::Bytes(value) if value.is_empty() => Ok(None),
+        StoredValue::Bytes(value) => Ok(Some(value)),
+        StoredValue::Text(value) if value.is_empty() => Ok(None),
+        StoredValue::Text(value) => Ok(Some(value.into_bytes())),
+        StoredValue::Integer(0) => Ok(None),
+        StoredValue::Integer(value) => Ok(Some(value.to_string().into_bytes())),
+        StoredValue::Float(0.0) => Ok(None),
+        StoredValue::Float(value) => serde_json::to_vec(&value)
+            .map(Some)
+            .map_err(|_| Error::InvalidEntry),
+        StoredValue::Pickle(value) => {
+            let value = pickle::decode(&value)?;
+            if is_falsy(&value) {
+                Ok(None)
+            } else {
+                serde_json::to_vec(&value)
+                    .map(Some)
+                    .map_err(|_| Error::InvalidEntry)
+            }
+        }
+    }
+}
+
+fn is_falsy(value: &Value) -> bool {
+    match value {
+        Value::Null | Value::Bool(false) => true,
+        Value::Number(value) => value.as_f64().is_some_and(|value| value == 0.0),
+        Value::String(value) => value.is_empty(),
+        Value::Array(value) => value.is_empty(),
+        Value::Object(value) => value.is_empty(),
+        Value::Bool(true) => false,
+    }
+}
+
+fn unix_now() -> f64 {
+    SystemTime::now()
+        .duration_since(UNIX_EPOCH)
+        .unwrap_or_default()
+        .as_secs_f64()
+}
diff --git a/litellm-rust/crates/cache-disk/src/lib.rs b/litellm-rust/crates/cache-disk/src/lib.rs
new file mode 100644
index 00000000000..189d12ea793
--- /dev/null
+++ b/litellm-rust/crates/cache-disk/src/lib.rs
@@ -0,0 +1,8 @@
+mod cache;
+mod pickle;
+mod sqlite;
+mod store;
+
+pub use cache::DiskCache;
+pub use sqlite::DiskcacheSqliteStore;
+pub use store::{DiskStore, StoredValue};
diff --git a/litellm-rust/crates/cache-disk/src/pickle.rs b/litellm-rust/crates/cache-disk/src/pickle.rs
new file mode 100644
index 00000000000..1d31e0bbeb6
--- /dev/null
+++ b/litellm-rust/crates/cache-disk/src/pickle.rs
@@ -0,0 +1,48 @@
+use litellm_cache::Error;
+use serde_json::{Map, Number, Value};
+
+pub(crate) fn decode(bytes: &[u8]) -> Result<Value, Error> {
+    let value = serde_pickle::value_from_slice(bytes, Default::default())
+        .map_err(|_| Error::InvalidEntry)?;
+    convert(value)
+}
+
+fn convert(value: serde_pickle::Value) -> Result<Value, Error> {
+    match value {
+        serde_pickle::Value::None => Ok(Value::Null),
+        serde_pickle::Value::Bool(value) => Ok(Value::Bool(value)),
+        serde_pickle::Value::I64(value) => Ok(Value::Number(value.into())),
+        serde_pickle::Value::Int(value) => {
+            if let Ok(value) = value.to_string().parse::<i64>() {
+                Ok(Value::Number(value.into()))
+            } else if let Ok(value) = value.to_string().parse::<u64>() {
+                Ok(Value::Number(value.into()))
+            } else {
+                Err(Error::InvalidEntry)
+            }
+        }
+        serde_pickle::Value::F64(value) => Number::from_f64(value)
+            .map(Value::Number)
+            .ok_or(Error::InvalidEntry),
+        serde_pickle::Value::String(value) => Ok(Value::String(value)),
+        serde_pickle::Value::List(values) | serde_pickle::Value::Tuple(values) => values
+            .into_iter()
+            .map(convert)
+            .collect::<Result<Vec<_>, _>>()
+            .map(Value::Array),
+        serde_pickle::Value::Set(values) | serde_pickle::Value::FrozenSet(values) => values
+            .into_iter()
+            .map(|value| convert(value.into_value()))
+            .collect::<Result<Vec<_>, _>>()
+            .map(Value::Array),
+        serde_pickle::Value::Dict(values) => values
+            .into_iter()
+            .map(|(key, value)| match key {
+                serde_pickle::HashableValue::String(key) => Ok((key, convert(value)?)),
+                _ => Err(Error::InvalidEntry),
+            })
+            .collect::<Result<Map<_, _>, _>>()
+            .map(Value::Object),
+        serde_pickle::Value::Bytes(_) => Err(Error::InvalidEntry),
+    }
+}
diff --git a/litellm-rust/crates/cache-disk/src/sqlite.rs b/litellm-rust/crates/cache-disk/src/sqlite.rs
new file mode 100644
index 00000000000..ff5a44b5c38
--- /dev/null
+++ b/litellm-rust/crates/cache-disk/src/sqlite.rs
@@ -0,0 +1,816 @@
+use std::{
+    collections::HashMap,
+    fs::{self, OpenOptions},
+    io::Write,
+    path::{Path, PathBuf},
+    sync::Mutex,
+};
+
+use litellm_cache::Error;
+use rand::RngCore;
+use rusqlite::{Connection, OptionalExtension, params, types::Value};
+
+use crate::{DiskStore, StoredValue};
+
+const MODE_RAW: i64 = 1;
+const MODE_BINARY: i64 = 2;
+const MODE_TEXT: i64 = 3;
+const MODE_PICKLE: i64 = 4;
+
+const DEFAULT_DISK_MIN_FILE_SIZE: i64 = 2_i64.pow(15);
+const DEFAULT_SIZE_LIMIT: i64 = 2_i64.pow(30);
+const DEFAULT_CULL_LIMIT: i64 = 10;
+
+pub struct DiskcacheSqliteStore {
+    directory: PathBuf,
+    connection: Mutex<Connection>,
+    min_file_size: usize,
+    eviction_policy: String,
+    size_limit: i64,
+    cull_limit: i64,
+    statistics: bool,
+}
+
+struct StoredColumns {
+    size: i64,
+    mode: i64,
+    filename: Option<String>,
+    value: Option<Value>,
+}
+
+struct Row {
+    rowid: i64,
+    mode: i64,
+    filename: Option<String>,
+    value: Value,
+}
+
+impl DiskcacheSqliteStore {
+    pub fn open(directory: impl AsRef<Path>) -> Result<Self, Error> {
+        let directory = directory.as_ref().to_path_buf();
+        fs::create_dir_all(&directory).map_err(|_| Error::Unavailable)?;
+        let database = directory.join("cache.db");
+        let connection = Connection::open(database).map_err(|_| Error::Unavailable)?;
+        connection
+            .busy_timeout(std::time::Duration::from_secs(60))
+            .map_err(|_| Error::Unavailable)?;
+
+        let mut settings = read_settings(&connection)?;
+        for (key, value) in default_settings() {
+            settings.entry(key).or_insert(value);
+        }
+        for (key, value) in settings
+            .iter()
+            .filter(|(key, _)| key.starts_with("sqlite_"))
+        {
+            apply_pragma(&connection, key, value)?;
+        }
+
+        connection
+            .execute_batch(
+                "CREATE TABLE IF NOT EXISTS Settings (
+                    key TEXT NOT NULL UNIQUE,
+                    value
+                )",
+            )
+            .map_err(|_| Error::Unavailable)?;
+        for (key, value) in &settings {
+            if !matches!(key.as_str(), "count" | "size" | "hits" | "misses") {
+                connection
+                    .execute(
+                        "INSERT OR REPLACE INTO Settings VALUES (?, ?)",
+                        params![key, value],
+                    )
+                    .map_err(|_| Error::Unavailable)?;
+            }
+        }
+        for (key, value) in [
+            ("count", Value::Integer(0)),
+            ("size", Value::Integer(0)),
+            ("hits", Value::Integer(0)),
+            ("misses", Value::Integer(0)),
+        ] {
+            connection
+                .execute(
+                    "INSERT OR IGNORE INTO Settings VALUES (?, ?)",
+                    params![key, value],
+                )
+                .map_err(|_| Error::Unavailable)?;
+        }
+        connection
+            .execute_batch(
+                "CREATE TABLE IF NOT EXISTS Cache (
+                    rowid INTEGER PRIMARY KEY,
+                    key BLOB,
+                    raw INTEGER,
+                    store_time REAL,
+                    expire_time REAL,
+                    access_time REAL,
+                    access_count INTEGER DEFAULT 0,
+                    tag BLOB,
+                    size INTEGER DEFAULT 0,
+                    mode INTEGER DEFAULT 0,
+                    filename TEXT,
+                    value BLOB
+                );
+                CREATE UNIQUE INDEX IF NOT EXISTS Cache_key_raw ON Cache(key, raw);
+                CREATE INDEX IF NOT EXISTS Cache_expire_time ON Cache(expire_time);",
+            )
+            .map_err(|_| Error::Unavailable)?;
+
+        let eviction_policy = setting_string(&settings, "eviction_policy")
+            .unwrap_or_else(|| "least-recently-stored".to_string());
+        match eviction_policy.as_str() {
+            "none" => {}
+            "least-recently-stored" => {
+                connection
+                    .execute_batch(
+                        "CREATE INDEX IF NOT EXISTS Cache_store_time ON Cache(store_time)",
+                    )
+                    .map_err(|_| Error::Unavailable)?;
+            }
+            "least-recently-used" => {
+                connection
+                    .execute_batch(
+                        "CREATE INDEX IF NOT EXISTS Cache_access_time ON Cache(access_time)",
+                    )
+                    .map_err(|_| Error::Unavailable)?;
+            }
+            "least-frequently-used" => {
+                connection
+                    .execute_batch(
+                        "CREATE INDEX IF NOT EXISTS Cache_access_count ON Cache(access_count)",
+                    )
+                    .map_err(|_| Error::Unavailable)?;
+            }
+            _ => return Err(Error::Unavailable),
+        }
+        connection
+            .execute_batch(
+                "CREATE TRIGGER IF NOT EXISTS Settings_count_insert
+                    AFTER INSERT ON Cache FOR EACH ROW BEGIN
+                    UPDATE Settings SET value = value + 1
+                    WHERE key = \"count\"; END;
+                 CREATE TRIGGER IF NOT EXISTS Settings_count_delete
+                    AFTER DELETE ON Cache FOR EACH ROW BEGIN
+                    UPDATE Settings SET value = value - 1
+                    WHERE key = \"count\"; END;
+                 CREATE TRIGGER IF NOT EXISTS Settings_size_insert
+                    AFTER INSERT ON Cache FOR EACH ROW BEGIN
+                    UPDATE Settings SET value = value + NEW.size
+                    WHERE key = \"size\"; END;
+                 CREATE TRIGGER IF NOT EXISTS Settings_size_update
+                    AFTER UPDATE ON Cache FOR EACH ROW BEGIN
+                    UPDATE Settings
+                    SET value = value + NEW.size - OLD.size
+                    WHERE key = \"size\"; END;
+                 CREATE TRIGGER IF NOT EXISTS Settings_size_delete
+                    AFTER DELETE ON Cache FOR EACH ROW BEGIN
+                    UPDATE Settings SET value = value - OLD.size
+                    WHERE key = \"size\"; END;",
+            )
+            .map_err(|_| Error::Unavailable)?;
+
+        let min_file_size = setting_i64(&settings, "disk_min_file_size")
+            .unwrap_or(DEFAULT_DISK_MIN_FILE_SIZE)
+            .try_into()
+            .map_err(|_| Error::Unavailable)?;
+        let size_limit = setting_i64(&settings, "size_limit").unwrap_or(DEFAULT_SIZE_LIMIT);
+        let cull_limit = setting_i64(&settings, "cull_limit").unwrap_or(DEFAULT_CULL_LIMIT);
+        let statistics = setting_i64(&settings, "statistics").unwrap_or_default() != 0;
+
+        Ok(Self {
+            directory,
+            connection: Mutex::new(connection),
+            min_file_size,
+            eviction_policy,
+            size_limit,
+            cull_limit,
+            statistics,
+        })
+    }
+
+    fn set_locked(
+        &self,
+        connection: &Connection,
+        key: &str,
+        columns: StoredColumns,
+        expire_time: Option<f64>,
+        now: f64,
+    ) -> Result<Vec<String>, Error> {
+        let mut cleanup = Vec::new();
+        if let Some(old_filename) = connection
+            .query_row(
+                "SELECT filename FROM Cache WHERE key = ? AND raw = 1",
+                params![key],
+                |row| row.get::<_, Option<String>>(0),
+            )
+            .optional()
+            .map_err(|_| Error::Unavailable)?
+            .flatten()
+        {
+            cleanup.push(old_filename);
+        }
+        let (size, mode, filename, value) =
+            (columns.size, columns.mode, columns.filename, columns.value);
+        let rowid = connection
+            .query_row(
+                "SELECT rowid FROM Cache WHERE key = ? AND raw = 1",
+                params![key],
+                |row| row.get::<_, i64>(0),
+            )
+            .optional()
+            .map_err(|_| Error::Unavailable)?;
+        if let Some(rowid) = rowid {
+            connection
+                .execute(
+                    "UPDATE Cache SET store_time = ?, expire_time = ?, access_time = ?,
+                        access_count = 0, tag = NULL, size = ?, mode = ?, filename = ?, value = ?
+                        WHERE rowid = ?",
+                    params![now, expire_time, now, size, mode, filename, value, rowid],
+                )
+                .map_err(|_| Error::Unavailable)?;
+        } else {
+            connection
+                .execute(
+                    "INSERT INTO Cache(
+                        key, raw, store_time, expire_time, access_time, access_count,
+                        tag, size, mode, filename, value
+                    ) VALUES (?, 1, ?, ?, ?, 0, NULL, ?, ?, ?, ?)",
+                    params![key, now, expire_time, now, size, mode, filename, value],
+                )
+                .map_err(|_| Error::Unavailable)?;
+        }
+        cleanup.extend(self.cull(connection, now)?);
+        Ok(cleanup)
+    }
+
+    fn cull(&self, connection: &Connection, now: f64) -> Result<Vec<String>, Error> {
+        if self.cull_limit <= 0 {
+            return Ok(Vec::new());
+        }
+        let mut cleanup = Vec::new();
+        let expired = connection
+            .prepare(
+                "SELECT rowid, filename FROM Cache
+                 WHERE expire_time IS NOT NULL AND expire_time < ?
+                 ORDER BY expire_time LIMIT ?",
+            )
+            .map_err(|_| Error::Unavailable)?
+            .query_map(params![now, self.cull_limit], |row| {
+                Ok((row.get::<_, i64>(0)?, row.get::<_, Option<String>>(1)?))
+            })
+            .map_err(|_| Error::Unavailable)?
+            .collect::<Result<Vec<_>, _>>()
+            .map_err(|_| Error::Unavailable)?;
+        for (_, filename) in &expired {
+            if let Some(filename) = filename {
+                cleanup.push(filename.clone());
+            }
+        }
+        for (rowid, _) in &expired {
+            connection
+                .execute("DELETE FROM Cache WHERE rowid = ?", params![rowid])
+                .map_err(|_| Error::Unavailable)?;
+        }
+        let remaining = self.cull_limit - i64::try_from(expired.len()).unwrap_or(self.cull_limit);
+        if remaining <= 0 || self.volume(connection)? < self.size_limit {
+            return Ok(cleanup);
+        }
+        let order = match self.eviction_policy.as_str() {
+            "none" => return Ok(cleanup),
+            "least-recently-stored" => "store_time",
+            "least-recently-used" => "access_time",
+            "least-frequently-used" => "access_count",
+            _ => return Err(Error::Unavailable),
+        };
+        let rows = connection
+            .prepare(&format!(
+                "SELECT rowid, filename FROM Cache ORDER BY {order} LIMIT ?"
+            ))
+            .map_err(|_| Error::Unavailable)?
+            .query_map(params![remaining], |row| {
+                Ok((row.get::<_, i64>(0)?, row.get::<_, Option<String>>(1)?))
+            })
+            .map_err(|_| Error::Unavailable)?
+            .collect::<Result<Vec<_>, _>>()
+            .map_err(|_| Error::Unavailable)?;
+        for (_, filename) in &rows {
+            if let Some(filename) = filename {
+                cleanup.push(filename.clone());
+            }
+        }
+        for (rowid, _) in rows {
+            connection
+                .execute("DELETE FROM Cache WHERE rowid = ?", params![rowid])
+                .map_err(|_| Error::Unavailable)?;
+        }
+        Ok(cleanup)
+    }
+
+    fn volume(&self, connection: &Connection) -> Result<i64, Error> {
+        let page_count: i64 = connection
+            .query_row("PRAGMA page_count", [], |row| row.get(0))
+            .map_err(|_| Error::Unavailable)?;
+        let page_size: i64 = connection
+            .query_row("PRAGMA page_size", [], |row| row.get(0))
+            .map_err(|_| Error::Unavailable)?;
+        let size: i64 = connection
+            .query_row("SELECT value FROM Settings WHERE key = 'size'", [], |row| {
+                row.get(0)
+            })
+            .map_err(|_| Error::Unavailable)?;
+        Ok(page_count.saturating_mul(page_size).saturating_add(size))
+    }
+}
+
+impl DiskStore for DiskcacheSqliteStore {
+    fn directory(&self) -> &Path {
+        &self.directory
+    }
+
+    fn get(&self, key: &str, now: f64) -> Result<Option<StoredValue>, Error> {
+        let connection = self.connection.lock().map_err(|_| Error::Unavailable)?;
+        let select = "SELECT rowid, expire_time, mode, filename, value FROM Cache
+            WHERE key = ? AND raw = 1 AND (expire_time IS NULL OR expire_time > ?)";
+        let row = connection
+            .query_row(select, params![key, now], row_from_query)
+            .optional()
+            .map_err(|_| Error::Unavailable)?;
+        if !self.statistics && !has_get_update(&self.eviction_policy) {
+            return row
+                .map(|row| fetch_row(&self.directory, row))
+                .transpose()
+                .map(|value| value.flatten());
+        }
+        transactional(&connection, |connection| {
+            let row = connection
+                .query_row(select, params![key, now], row_from_query)
+                .optional()
+                .map_err(|_| Error::Unavailable)?;
+            let Some(row) = row else {
+                if self.statistics {
+                    connection
+                        .execute(
+                            "UPDATE Settings SET value = value + 1 WHERE key = 'misses'",
+                            [],
+                        )
+                        .map_err(|_| Error::Unavailable)?;
+                }
+                return Ok(None);
+            };
+            let rowid = row.rowid;
+            let value = fetch_row(&self.directory, row);
+            let hit = value.as_ref().is_ok_and(Option::is_some);
+            if hit && self.statistics {
+                connection
+                    .execute(
+                        "UPDATE Settings SET value = value + 1 WHERE key = 'hits'",
+                        [],
+                    )
+                    .map_err(|_| Error::Unavailable)?;
+            } else if !hit && self.statistics {
+                connection
+                    .execute(
+                        "UPDATE Settings SET value = value + 1 WHERE key = 'misses'",
+                        [],
+                    )
+                    .map_err(|_| Error::Unavailable)?;
+            }
+            if has_get_update(&self.eviction_policy) && hit {
+                let update = match self.eviction_policy.as_str() {
+                    "least-recently-used" => "UPDATE Cache SET access_time = ? WHERE rowid = ?",
+                    "least-frequently-used" => {
+                        "UPDATE Cache SET access_count = access_count + 1 WHERE rowid = ?"
+                    }
+                    _ => return Err(Error::Unavailable),
+                };
+                if self.eviction_policy == "least-recently-used" {
+                    connection
+                        .execute(update, params![now, rowid])
+                        .map_err(|_| Error::Unavailable)?;
+                } else {
+                    connection
+                        .execute(update, params![rowid])
+                        .map_err(|_| Error::Unavailable)?;
+                }
+            }
+            value
+        })
+    }
+
+    fn set(
+        &self,
+        key: &str,
+        value: StoredValue,
+        expire_time: Option<f64>,
+        now: f64,
+    ) -> Result<(), Error> {
+        let columns = store_value(&self.directory, self.min_file_size, value)?;
+        let new_filename = columns.filename.clone();
+        let connection = self.connection.lock().map_err(|_| Error::Unavailable)?;
+        let result = transactional(&connection, |connection| {
+            self.set_locked(connection, key, columns, expire_time, now)
+        });
+        match result {
+            Ok(cleanup) => {
+                cleanup_files(&self.directory, cleanup);
+                Ok(())
+            }
+            Err(error) => {
+                if let Some(filename) = new_filename {
+                    remove_file(&self.directory, &filename);
+                }
+                Err(error)
+            }
+        }
+    }
+
+    fn pop(&self, key: &str, now: f64) -> Result<Option<StoredValue>, Error> {
+        let connection = self.connection.lock().map_err(|_| Error::Unavailable)?;
+        let selected = transactional(&connection, |connection| {
+            let row = connection
+                .query_row(
+                    "SELECT rowid, expire_time, mode, filename, value FROM Cache
+                     WHERE key = ? AND raw = 1
+                     AND (expire_time IS NULL OR expire_time > ?)",
+                    params![key, now],
+                    row_from_query,
+                )
+                .optional()
+                .map_err(|_| Error::Unavailable)?;
+            let Some(row) = row else {
+                return Ok(None);
+            };
+            connection
+                .execute("DELETE FROM Cache WHERE rowid = ?", params![row.rowid])
+                .map_err(|_| Error::Unavailable)?;
+            Ok(Some(row))
+        })?;
+        let Some(row) = selected else {
+            return Ok(None);
+        };
+        let filename = row.filename.clone();
+        let result = fetch_row(&self.directory, row)?;
+        if let Some(filename) = filename {
+            remove_file(&self.directory, &filename);
+        }
+        Ok(result)
+    }
+
+    fn clear(&self) -> Result<(), Error> {
+        let connection = self.connection.lock().map_err(|_| Error::Unavailable)?;
+        let mut last_rowid = 0_i64;
+        loop {
+            let batch = transactional(&connection, |connection| {
+                let rows = connection
+                    .prepare(
+                        "SELECT rowid, filename FROM Cache
+                         WHERE rowid > ? ORDER BY rowid LIMIT 100",
+                    )
+                    .map_err(|_| Error::Unavailable)?
+                    .query_map(params![last_rowid], |row| {
+                        Ok((row.get::<_, i64>(0)?, row.get::<_, Option<String>>(1)?))
+                    })
+                    .map_err(|_| Error::Unavailable)?
+                    .collect::<Result<Vec<_>, _>>()
+                    .map_err(|_| Error::Unavailable)?;
+                if rows.is_empty() {
+                    return Ok(rows);
+                }
+                let ids = rows
+                    .iter()
+                    .map(|(rowid, _)| rowid.to_string())
+                    .collect::<Vec<_>>()
+                    .join(",");
+                connection
+                    .execute(&format!("DELETE FROM Cache WHERE rowid IN ({ids})"), [])
+                    .map_err(|_| Error::Unavailable)?;
+                Ok(rows)
+            })?;
+            if batch.is_empty() {
+                return Ok(());
+            }
+            last_rowid = batch.last().map(|(rowid, _)| *rowid).unwrap_or(last_rowid);
+            cleanup_files(
+                &self.directory,
+                batch
+                    .into_iter()
+                    .filter_map(|(_, filename)| filename)
+                    .collect(),
+            );
+        }
+    }
+
+    fn update(
+        &self,
+        key: &str,
+        now: f64,
+        apply: &mut dyn FnMut(Option<StoredValue>) -> Result<(StoredValue, Option<f64>), Error>,
+    ) -> Result<(), Error> {
+        let connection = self.connection.lock().map_err(|_| Error::Unavailable)?;
+        let mut created_filename = None;
+        let result = transactional(&connection, |connection| {
+            let current = connection
+                .query_row(
+                    "SELECT rowid, expire_time, mode, filename, value FROM Cache
+                     WHERE key = ? AND raw = 1
+                     AND (expire_time IS NULL OR expire_time > ?)",
+                    params![key, now],
+                    row_from_query,
+                )
+                .optional()
+                .map_err(|_| Error::Unavailable)?
+                .map(|row| fetch_row(&self.directory, row))
+                .transpose()?
+                .flatten();
+            let (value, expire_time) = apply(current)?;
+            let columns = store_value(&self.directory, self.min_file_size, value)?;
+            created_filename = columns.filename.clone();
+            let cleanup = self.set_locked(connection, key, columns, expire_time, now)?;
+            Ok(cleanup)
+        });
+        match result {
+            Ok(cleanup) => {
+                cleanup_files(&self.directory, cleanup);
+                Ok(())
+            }
+            Err(error) => {
+                if let Some(filename) = created_filename {
+                    remove_file(&self.directory, &filename);
+                }
+                Err(error)
+            }
+        }
+    }
+
+    fn probe(&self) -> Result<(), Error> {
+        let connection = self.connection.lock().map_err(|_| Error::Unavailable)?;
+        connection
+            .query_row(
+                "SELECT value FROM Settings WHERE key = 'count'",
+                [],
+                |row| row.get::<_, i64>(0),
+            )
+            .map(|_| ())
+            .map_err(|_| Error::Unavailable)
+    }
+}
+
+fn default_settings() -> HashMap<String, Value> {
+    HashMap::from([
+        ("statistics".to_string(), Value::Integer(0)),
+        ("tag_index".to_string(), Value::Integer(0)),
+        (
+            "eviction_policy".to_string(),
+            Value::Text("least-recently-stored".to_string()),
+        ),
+        ("size_limit".to_string(), Value::Integer(DEFAULT_SIZE_LIMIT)),
+        ("cull_limit".to_string(), Value::Integer(DEFAULT_CULL_LIMIT)),
+        ("sqlite_auto_vacuum".to_string(), Value::Integer(1)),
+        ("sqlite_cache_size".to_string(), Value::Integer(8192)),
+        (
+            "sqlite_journal_mode".to_string(),
+            Value::Text("wal".to_string()),
+        ),
+        (
+            "sqlite_mmap_size".to_string(),
+            Value::Integer(2_i64.pow(26)),
+        ),
+        ("sqlite_synchronous".to_string(), Value::Integer(1)),
+        (
+            "disk_min_file_size".to_string(),
+            Value::Integer(DEFAULT_DISK_MIN_FILE_SIZE),
+        ),
+        ("disk_pickle_protocol".to_string(), Value::Integer(5)),
+    ])
+}
+
+fn read_settings(connection: &Connection) -> Result<HashMap<String, Value>, Error> {
+    let mut statement = match connection.prepare("SELECT key, value FROM Settings") {
+        Ok(statement) => statement,
+        Err(_) => return Ok(HashMap::new()),
+    };
+    statement
+        .query_map([], |row| Ok((row.get(0)?, row.get(1)?)))
+        .map_err(|_| Error::Unavailable)?
+        .collect::<Result<HashMap<_, _>, _>>()
+        .map_err(|_| Error::Unavailable)
+}
+
+fn apply_pragma(connection: &Connection, key: &str, value: &Value) -> Result<(), Error> {
+    let pragma = key.strip_prefix("sqlite_").ok_or(Error::Unavailable)?;
+    match value {
+        Value::Integer(value) => connection
+            .pragma_update(None, pragma, value)
+            .map_err(|_| Error::Unavailable),
+        Value::Text(value) => connection
+            .pragma_update(None, pragma, value)
+            .map_err(|_| Error::Unavailable),
+        _ => Err(Error::Unavailable),
+    }
+}
+
+fn setting_i64(settings: &HashMap<String, Value>, key: &str) -> Option<i64> {
+    match settings.get(key) {
+        Some(Value::Integer(value)) => Some(*value),
+        _ => None,
+    }
+}
+
+fn setting_string(settings: &HashMap<String, Value>, key: &str) -> Option<String> {
+    match settings.get(key) {
+        Some(Value::Text(value)) => Some(value.clone()),
+        _ => None,
+    }
+}
+
+fn has_get_update(policy: &str) -> bool {
+    matches!(policy, "least-recently-used" | "least-frequently-used")
+}
+
+fn row_from_query(row: &rusqlite::Row<'_>) -> rusqlite::Result<Row> {
+    Ok(Row {
+        rowid: row.get(0)?,
+        mode: row.get(2)?,
+        filename: row.get(3)?,
+        value: row.get(4)?,
+    })
+}
+
+fn fetch_row(directory: &Path, row: Row) -> Result<Option<StoredValue>, Error> {
+    match row.mode {
+        MODE_RAW => match row.value {
+            Value::Blob(value) => Ok(Some(StoredValue::Bytes(value))),
+            Value::Text(value) => Ok(Some(StoredValue::Text(value))),
+            Value::Integer(value) => Ok(Some(StoredValue::Integer(value))),
+            Value::Real(value) => Ok(Some(StoredValue::Float(value))),
+            Value::Null => Err(Error::InvalidEntry),
+        },
+        MODE_BINARY | MODE_PICKLE => {
+            let bytes = match row.value {
+                Value::Blob(value) => value,
+                Value::Null => {
+                    let Some(value) = read_file(directory, row.filename.as_deref())? else {
+                        return Ok(None);
+                    };
+                    value
+                }
+                _ => return Err(Error::InvalidEntry),
+            };
+            Ok(Some(if row.mode == MODE_BINARY {
+                StoredValue::Bytes(bytes)
+            } else {
+                StoredValue::Pickle(bytes)
+            }))
+        }
+        MODE_TEXT => {
+            let bytes = match row.value {
+                Value::Null => {
+                    let Some(value) = read_file(directory, row.filename.as_deref())? else {
+                        return Ok(None);
+                    };
+                    value
+                }
+                Value::Blob(value) => value,
+                Value::Text(value) => value.into_bytes(),
+                _ => return Err(Error::InvalidEntry),
+            };
+            Ok(Some(StoredValue::Text(
+                String::from_utf8(bytes).map_err(|_| Error::InvalidEntry)?,
+            )))
+        }
+        _ => Err(Error::InvalidEntry),
+    }
+}
+
+fn read_file(directory: &Path, filename: Option<&str>) -> Result<Option<Vec<u8>>, Error> {
+    let Some(filename) = filename else {
+        return Err(Error::InvalidEntry);
+    };
+    match fs::read(directory.join(filename)) {
+        Ok(value) => Ok(Some(value)),
+        Err(error) if error.kind() == std::io::ErrorKind::NotFound => Ok(None),
+        Err(_) => Err(Error::Unavailable),
+    }
+}
+
+fn store_value(
+    directory: &Path,
+    min_file_size: usize,
+    value: StoredValue,
+) -> Result<StoredColumns, Error> {
+    match value {
+        StoredValue::Integer(value) => Ok(StoredColumns {
+            size: 0,
+            mode: MODE_RAW,
+            filename: None,
+            value: Some(Value::Integer(value)),
+        }),
+        StoredValue::Float(value) => Ok(StoredColumns {
+            size: 0,
+            mode: MODE_RAW,
+            filename: None,
+            value: Some(Value::Real(value)),
+        }),
+        StoredValue::Text(value) if value.chars().count() < min_file_size => Ok(StoredColumns {
+            size: 0,
+            mode: MODE_RAW,
+            filename: None,
+            value: Some(Value::Text(value)),
+        }),
+        StoredValue::Text(value) => {
+            let bytes = value.into_bytes();
+            let filename = write_file(directory, &bytes)?;
+            Ok(StoredColumns {
+                size: i64::try_from(bytes.len()).map_err(|_| Error::Unavailable)?,
+                mode: MODE_TEXT,
+                filename: Some(filename),
+                value: None,
+            })
+        }
+        StoredValue::Bytes(value) if value.len() < min_file_size => Ok(StoredColumns {
+            size: 0,
+            mode: MODE_RAW,
+            filename: None,
+            value: Some(Value::Blob(value)),
+        }),
+        StoredValue::Bytes(value) => {
+            let filename = write_file(directory, &value)?;
+            Ok(StoredColumns {
+                size: i64::try_from(value.len()).map_err(|_| Error::Unavailable)?,
+                mode: MODE_BINARY,
+                filename: Some(filename),
+                value: None,
+            })
+        }
+        StoredValue::Pickle(value) if value.len() < min_file_size => Ok(StoredColumns {
+            size: 0,
+            mode: MODE_PICKLE,
+            filename: None,
+            value: Some(Value::Blob(value)),
+        }),
+        StoredValue::Pickle(value) => {
+            let filename = write_file(directory, &value)?;
+            Ok(StoredColumns {
+                size: i64::try_from(value.len()).map_err(|_| Error::Unavailable)?,
+                mode: MODE_PICKLE,
+                filename: Some(filename),
+                value: None,
+            })
+        }
+    }
+}
+
+fn write_file(directory: &Path, bytes: &[u8]) -> Result<String, Error> {
+    let mut random = [0_u8; 16];
+    rand::rngs::OsRng.fill_bytes(&mut random);
+    let hex = random
+        .iter()
+        .map(|byte| format!("{byte:02x}"))
+        .collect::<String>();
+    let filename = format!("{}/{}/{}.val", &hex[..2], &hex[2..4], &hex[4..]);
+    let path = directory.join(&filename);
+    if let Some(parent) = path.parent() {
+        fs::create_dir_all(parent).map_err(|_| Error::Unavailable)?;
+    }
+    let mut file = OpenOptions::new()
+        .write(true)
+        .create_new(true)
+        .open(path)
+        .map_err(|_| Error::Unavailable)?;
+    file.write_all(bytes).map_err(|_| Error::Unavailable)?;
+    Ok(filename)
+}
+
+fn cleanup_files(directory: &Path, filenames: Vec<String>) {
+    for filename in filenames {
+        remove_file(directory, &filename);
+    }
+}
+
+fn remove_file(directory: &Path, filename: &str) {
+    let path = directory.join(filename);
+    let _ = fs::remove_file(&path);
+}
+
+fn transactional<T>(
+    connection: &Connection,
+    operation: impl FnOnce(&Connection) -> Result<T, Error>,
+) -> Result<T, Error> {
+    connection
+        .execute_batch("BEGIN IMMEDIATE")
+        .map_err(|_| Error::Unavailable)?;
+    match operation(connection) {
+        Ok(value) => {
+            connection
+                .execute_batch("COMMIT")
+                .map_err(|_| Error::Unavailable)?;
+            Ok(value)
+        }
+        Err(error) => {
+            let _ = connection.execute_batch("ROLLBACK");
+            Err(error)
+        }
+    }
+}
diff --git a/litellm-rust/crates/cache-disk/src/store.rs b/litellm-rust/crates/cache-disk/src/store.rs
new file mode 100644
index 00000000000..ed167317cf0
--- /dev/null
+++ b/litellm-rust/crates/cache-disk/src/store.rs
@@ -0,0 +1,33 @@
+use std::path::Path;
+
+use litellm_cache::Error;
+
+#[derive(Clone, Debug, PartialEq)]
+pub enum StoredValue {
+    Bytes(Vec<u8>),
+    Text(String),
+    Integer(i64),
+    Float(f64),
+    Pickle(Vec<u8>),
+}
+
+pub trait DiskStore: Send + Sync + 'static {
+    fn directory(&self) -> &Path;
+    fn get(&self, key: &str, now: f64) -> Result<Option<StoredValue>, Error>;
+    fn set(
+        &self,
+        key: &str,
+        value: StoredValue,
+        expire_time: Option<f64>,
+        now: f64,
+    ) -> Result<(), Error>;
+    fn pop(&self, key: &str, now: f64) -> Result<Option<StoredValue>, Error>;
+    fn clear(&self) -> Result<(), Error>;
+    fn update(
+        &self,
+        key: &str,
+        now: f64,
+        apply: &mut dyn FnMut(Option<StoredValue>) -> Result<(StoredValue, Option<f64>), Error>,
+    ) -> Result<(), Error>;
+    fn probe(&self) -> Result<(), Error>;
+}
diff --git a/litellm-rust/crates/cache-disk/tests/cache.rs b/litellm-rust/crates/cache-disk/tests/cache.rs
new file mode 100644
index 00000000000..1e3e39db0c8
--- /dev/null
+++ b/litellm-rust/crates/cache-disk/tests/cache.rs
@@ -0,0 +1,327 @@
+use std::{
+    fs,
+    path::{Path, PathBuf},
+    sync::Arc,
+    thread,
+    time::Duration,
+};
+
+use litellm_cache::{
+    BaseCache, BatchCache, BatchEntry, CounterCache, DeleteCache, ExactCacheContext, FlushCache,
+    JsonCodec,
+};
+use litellm_cache_disk::{DiskCache, DiskStore, DiskcacheSqliteStore, StoredValue};
+use rusqlite::Connection;
+use serde_json::json;
+use tempfile::TempDir;
+
+fn store() -> (TempDir, DiskcacheSqliteStore) {
+    let directory = tempfile::tempdir().unwrap();
+    let store = DiskcacheSqliteStore::open(directory.path()).unwrap();
+    (directory, store)
+}
+
+fn cache(directory: &Path) -> DiskCache<JsonCodec<serde_json::Value>> {
+    DiskCache::open(directory, JsonCodec::new()).unwrap()
+}
+
+fn value_files(directory: &Path) -> Vec<PathBuf> {
+    fn visit(directory: &Path, files: &mut Vec<PathBuf>) {
+        for entry in fs::read_dir(directory).unwrap() {
+            let path = entry.unwrap().path();
+            if path.is_dir() {
+                visit(&path, files);
+            } else if path.extension().is_some_and(|extension| extension == "val") {
+                files.push(path);
+            }
+        }
+    }
+
+    let mut files = Vec::new();
+    visit(directory, &mut files);
+    files
+}
+
+#[test]
+fn roundtrip_persists_and_reopens() {
+    let directory = tempfile::tempdir().unwrap();
+    let context = ExactCacheContext::default();
+    let opened = cache(directory.path());
+    opened
+        .set_cache("key", json!({"answer": 42}), &context)
+        .unwrap();
+    assert_eq!(
+        opened.get_cache("key", &context).unwrap(),
+        Some(json!({"answer": 42}))
+    );
+    drop(opened);
+    let reopened = cache(directory.path());
+    assert_eq!(
+        reopened.get_cache("key", &context).unwrap(),
+        Some(json!({"answer": 42}))
+    );
+}
+
+#[test]
+fn ttl_and_expired_culling_match_cache_contract() {
+    let (directory, store) = store();
+    store
+        .set(
+            "expired",
+            StoredValue::Bytes(b"old".to_vec()),
+            Some(10.0),
+            0.0,
+        )
+        .unwrap();
+    assert_eq!(store.get("expired", 10.0).unwrap(), None);
+    store
+        .set("new", StoredValue::Bytes(b"new".to_vec()), None, 11.0)
+        .unwrap();
+    let connection = Connection::open(directory.path().join("cache.db")).unwrap();
+    assert_eq!(
+        connection
+            .query_row("SELECT COUNT(*) FROM Cache", [], |row| row.get::<_, i64>(0))
+            .unwrap(),
+        1
+    );
+    assert_eq!(
+        connection
+            .query_row(
+                "SELECT value FROM Settings WHERE key = 'count'",
+                [],
+                |row| row.get::<_, i64>(0)
+            )
+            .unwrap(),
+        1
+    );
+}
+
+#[test]
+fn batch_preserves_order_and_classifies_misses_and_invalid_values() {
+    let (directory, store) = store();
+    store
+        .set(
+            "hit",
+            StoredValue::Bytes(br#"{"ok":true}"#.to_vec()),
+            None,
+            0.0,
+        )
+        .unwrap();
+    store
+        .set(
+            "invalid",
+            StoredValue::Pickle(vec![0x80, 0x05, 0x2e]),
+            None,
+            0.0,
+        )
+        .unwrap();
+    let cache = cache(directory.path());
+    let entries = cache
+        .batch_get_cache(
+            &["hit".into(), "missing".into(), "invalid".into()],
+            &ExactCacheContext::default(),
+        )
+        .unwrap();
+    assert_eq!(
+        entries,
+        vec![
+            BatchEntry::Hit(json!({"ok": true})),
+            BatchEntry::Miss,
+            BatchEntry::Invalid
+        ]
+    );
+}
+
+#[test]
+fn falsy_values_are_misses_and_protocol_five_pickle_decodes() {
+    let (directory, store) = store();
+    for (key, value) in [
+        ("empty-bytes", StoredValue::Bytes(Vec::new())),
+        ("empty-text", StoredValue::Text(String::new())),
+        ("zero-int", StoredValue::Integer(0)),
+        ("zero-float", StoredValue::Float(0.0)),
+        (
+            "empty-pickle",
+            StoredValue::Pickle(vec![0x80, 0x05, 0x7d, 0x94, 0x2e]),
+        ),
+    ] {
+        store.set(key, value, None, 0.0).unwrap();
+    }
+    store
+        .set(
+            "pickle",
+            StoredValue::Pickle(
+                b"\x80\x05\x95\x30\x00\x00\x00\x00\x00\x00\x00\x7d\x94\x28\x8c\x09timestamp\x94G\x3f\xf8\x00\x00\x00\x00\x00\x00\x8c\x08response\x94\x8c\x08{\"a\": 1}\x94u."
+                    .to_vec(),
+            ),
+            None,
+            0.0,
+        )
+        .unwrap();
+    let cache = cache(directory.path());
+    for key in [
+        "empty-bytes",
+        "empty-text",
+        "zero-int",
+        "zero-float",
+        "empty-pickle",
+    ] {
+        assert_eq!(
+            cache.get_cache(key, &ExactCacheContext::default()).unwrap(),
+            None
+        );
+    }
+    assert_eq!(
+        cache
+            .get_cache("pickle", &ExactCacheContext::default())
+            .unwrap(),
+        Some(json!({"timestamp": 1.5, "response": "{\"a\": 1}"}))
+    );
+}
+
+#[test]
+fn counters_use_atomic_native_values_and_ignore_invalid_initial_values() {
+    let (directory, store) = store();
+    store
+        .set("counter", StoredValue::Integer(2), None, 0.0)
+        .unwrap();
+    store
+        .set(
+            "invalid",
+            StoredValue::Text("not a number".into()),
+            None,
+            0.0,
+        )
+        .unwrap();
+    store
+        .set(
+            "pickle-counter",
+            StoredValue::Pickle(vec![0x80, 0x05, 0x4b, 0x02, 0x2e]),
+            None,
+            0.0,
+        )
+        .unwrap();
+    let cache = DiskCache::open(directory.path(), JsonCodec::<f64>::new()).unwrap();
+    assert_eq!(
+        cache
+            .increment_cache("counter", 1.5, ExactCacheContext::default())
+            .unwrap(),
+        3.5
+    );
+    assert_eq!(
+        cache
+            .increment_cache("invalid", 2.0, ExactCacheContext::default())
+            .unwrap(),
+        2.0
+    );
+    assert_eq!(
+        cache
+            .increment_cache("pickle-counter", 1.0, ExactCacheContext::default())
+            .unwrap(),
+        3.0
+    );
+    let connection = Connection::open(directory.path().join("cache.db")).unwrap();
+    assert_eq!(
+        connection
+            .query_row(
+                "SELECT typeof(value) FROM Cache WHERE key = 'counter'",
+                [],
+                |row| row.get::<_, String>(0)
+            )
+            .unwrap(),
+        "real"
+    );
+}
+
+#[test]
+fn counters_are_atomic_across_concurrent_callers() {
+    let directory = tempfile::tempdir().unwrap();
+    let cache = Arc::new(DiskCache::open(directory.path(), JsonCodec::<f64>::new()).unwrap());
+    let workers = (0..8)
+        .map(|_| {
+            let cache = Arc::clone(&cache);
+            thread::spawn(move || {
+                for _ in 0..25 {
+                    cache
+                        .increment_cache("counter", 1.0, ExactCacheContext::default())
+                        .unwrap();
+                }
+            })
+        })
+        .collect::<Vec<_>>();
+    for worker in workers {
+        worker.join().unwrap();
+    }
+    assert_eq!(
+        cache
+            .increment_cache("counter", 0.0, ExactCacheContext::default())
+            .unwrap(),
+        200.0
+    );
+}
+
+#[test]
+fn delete_flush_and_spilled_file_replacement_clean_up_storage() {
+    let (directory, store) = store();
+    let large = vec![b'x'; 32 * 1024];
+    store
+        .set("large", StoredValue::Bytes(large.clone()), None, 0.0)
+        .unwrap();
+    assert_eq!(value_files(directory.path()).len(), 1);
+    store
+        .set(
+            "large",
+            StoredValue::Bytes(vec![b'y'; 32 * 1024]),
+            None,
+            0.0,
+        )
+        .unwrap();
+    assert_eq!(value_files(directory.path()).len(), 1);
+    store.pop("large", 0.0).unwrap();
+    assert!(value_files(directory.path()).is_empty());
+    store
+        .set("a", StoredValue::Bytes(large.clone()), None, 0.0)
+        .unwrap();
+    store
+        .set("b", StoredValue::Bytes(large), None, 0.0)
+        .unwrap();
+    store.clear().unwrap();
+    assert!(value_files(directory.path()).is_empty());
+}
+
+#[tokio::test]
+async fn async_operations_connection_and_delete_match_sync_operations() {
+    let directory = tempfile::tempdir().unwrap();
+    let cache = cache(directory.path());
+    let context = ExactCacheContext {
+        ttl: Some(Duration::from_secs(60)),
+    };
+    cache
+        .async_set_cache("a", json!(1), context.clone())
+        .await
+        .unwrap();
+    cache
+        .async_set_cache_pipeline(
+            vec![("b".into(), json!(2)), ("c".into(), json!(3))],
+            context.clone(),
+        )
+        .await
+        .unwrap();
+    assert_eq!(
+        cache.async_get_cache("a", &context).await.unwrap(),
+        Some(json!(1))
+    );
+    assert_eq!(
+        cache
+            .async_batch_get_cache(vec!["c".into(), "missing".into()], context.clone())
+            .await
+            .unwrap(),
+        vec![BatchEntry::Hit(json!(3)), BatchEntry::Miss]
+    );
+    cache.async_delete_cache("a").await.unwrap();
+    cache.async_flush_cache().await.unwrap();
+    assert_eq!(
+        cache.test_connection().await.unwrap().status,
+        litellm_cache::CacheConnectionStatus::Success
+    );
+}
diff --git a/litellm-rust/crates/python-bridge/Cargo.toml b/litellm-rust/crates/python-bridge/Cargo.toml
index 1eb2ec28036..71846dcacbd 100644
--- a/litellm-rust/crates/python-bridge/Cargo.toml
+++ b/litellm-rust/crates/python-bridge/Cargo.toml
@@ -23,6 +23,7 @@ bytes.workspace = true
 litellm-cache.workspace = true
 litellm-cache-memory.workspace = true
 litellm-cache-redis.workspace = true
+litellm-cache-disk.workspace = true
 litellm-cache-response.workspace = true
 serde.workspace = true
 litellm-auth.workspace = true
diff --git a/litellm-rust/crates/python-bridge/src/cache/config.rs b/litellm-rust/crates/python-bridge/src/cache/config.rs
index 0e7d6aee11d..17c4cb40903 100644
--- a/litellm-rust/crates/python-bridge/src/cache/config.rs
+++ b/litellm-rust/crates/python-bridge/src/cache/config.rs
@@ -1,4 +1,4 @@
-use std::time::Duration;
+use std::{path::PathBuf, time::Duration};
 
 use litellm_cache::CacheType;
 use pyo3::{
@@ -25,6 +25,10 @@ pub(super) struct MemoryCacheConfig {
     pub(super) max_entry_bytes: usize,
 }
 
+pub(super) struct DiskCacheConfig {
+    pub(super) directory: PathBuf,
+}
+
 #[derive(Debug, PartialEq)]
 pub(super) enum RedisProtocol {
     Resp2,
@@ -76,6 +80,7 @@ pub(super) struct RedisCacheConfig {
 pub(super) enum CacheBackendConfig {
     Memory(MemoryCacheConfig),
     Redis(Box<RedisCacheConfig>),
+    Disk(DiskCacheConfig),
 }
 
 #[allow(dead_code, reason = "consumed by the cache activation follow-up")]
@@ -90,6 +95,7 @@ pub(super) enum UnsupportedCacheConfig {
     RedisCredentials,
     RedisConnection,
     RedisOption,
+    DiskStore,
 }
 
 impl UnsupportedCacheConfig {
@@ -100,6 +106,7 @@ impl UnsupportedCacheConfig {
             Self::RedisCredentials => "native Redis credentials require Python",
             Self::RedisConnection => "native Redis connection type is not implemented",
             Self::RedisOption => "native Redis configuration requires Python",
+            Self::DiskStore => "native disk cache requires the built-in diskcache store",
         }
     }
 }
@@ -142,11 +149,17 @@ impl NativeCacheConfig {
                 }))),
                 Err(reason) => Ok(CacheConfigProjection::Unsupported(reason)),
             },
+            Some(CacheType::Disk) => match project_disk(&backend)? {
+                Ok(backend) => Ok(CacheConfigProjection::Native(Box::new(Self {
+                    policy,
+                    backend: CacheBackendConfig::Disk(backend),
+                }))),
+                Err(reason) => Ok(CacheConfigProjection::Unsupported(reason)),
+            },
             Some(
                 CacheType::RedisSemantic
                 | CacheType::ValkeySemantic
                 | CacheType::S3
-                | CacheType::Disk
                 | CacheType::QdrantSemantic
                 | CacheType::AzureBlob
                 | CacheType::Gcs,
@@ -158,12 +171,12 @@ impl NativeCacheConfig {
     }
 
     pub(super) fn service_mismatch(&self, service: &NativeResponseCache) -> Option<&'static str> {
-        if service.default_ttl()
-            != Some(match &self.backend {
-                CacheBackendConfig::Memory(config) => config.default_ttl,
-                CacheBackendConfig::Redis(config) => config.default_ttl,
-            })
-        {
+        let default_ttl = match &self.backend {
+            CacheBackendConfig::Memory(config) => Some(config.default_ttl),
+            CacheBackendConfig::Redis(config) => Some(config.default_ttl),
+            CacheBackendConfig::Disk(_) => None,
+        };
+        if service.default_ttl() != default_ttl {
             return Some("facade and native backend default TTLs must match");
         }
         match &self.backend {
@@ -185,6 +198,17 @@ impl NativeCacheConfig {
             CacheBackendConfig::Redis(config) => (service.namespace()
                 != config.namespace.as_deref())
             .then_some("facade and native backend namespaces must match"),
+            CacheBackendConfig::Disk(_) if service.kind() != "disk" => {
+                Some("facade and native backend types must match")
+            }
+            CacheBackendConfig::Disk(config) => {
+                let Some(directory) = service.directory() else {
+                    return Some("facade and native backend types must match");
+                };
+                let native = std::fs::canonicalize(directory).ok();
+                let facade = std::fs::canonicalize(&config.directory).ok();
+                (native != facade).then_some("facade and native backend directories must match")
+            }
         }
     }
 }
@@ -201,6 +225,21 @@ fn project_memory(backend: &Bound<'_, PyAny>) -> PyResult<MemoryCacheConfig> {
     })
 }
 
+#[inline(never)]
+fn project_disk(
+    backend: &Bound<'_, PyAny>,
+) -> PyResult<Result<DiskCacheConfig, UnsupportedCacheConfig>> {
+    let store = backend.getattr("disk_cache")?;
+    if !instance_class_is(&store, "diskcache.core", "Cache")?
+        || !instance_class_is(&store.getattr("_disk")?, "diskcache.core", "Disk")?
+    {
+        return Ok(Err(UnsupportedCacheConfig::DiskStore));
+    }
+    Ok(Ok(DiskCacheConfig {
+        directory: PathBuf::from(store.getattr("directory")?.extract::<String>()?),
+    }))
+}
+
 #[inline(never)]
 fn project_redis(
     backend: &Bound<'_, PyAny>,
@@ -468,8 +507,8 @@ mod tests {
     use pyo3::{prelude::*, types::PyDict};
 
     use super::{
-        CacheBackendConfig, CacheConfigProjection, CertificateRequirement, NativeCacheConfig,
-        RedisProtocol,
+        CacheBackendConfig, CacheConfigProjection, CachePolicy, CertificateRequirement,
+        DiskCacheConfig, NativeCacheConfig, RedisProtocol,
     };
     use crate::cache::native::NativeResponseCache;
 
@@ -591,4 +630,84 @@ mod tests {
             assert_eq!(reason.message(), "native Redis credentials require Python");
         });
     }
+
+    #[test]
+    fn projects_builtin_disk_configuration_and_rejects_custom_stores() {
+        Python::initialize();
+        Python::attach(|py| {
+            let root =
+                std::env::temp_dir().join(format!("litellm-disk-config-{}", std::process::id()));
+            let directory = root.to_string_lossy();
+            let disk_facade = facade(
+                py,
+                &format!(
+                    "Cache = type('Cache', (), {{'__module__': 'diskcache.core'}})\n\
+                     Disk = type('Disk', (), {{'__module__': 'diskcache.core'}})\n\
+                     store = Cache()\n\
+                     store._disk = Disk()\n\
+                     store.directory = {directory:?}\n\
+                     backend = SimpleNamespace(disk_cache=store)\n\
+                     facade = SimpleNamespace(type='disk', mode='default-on', ttl=None, namespace=None, supported_call_types=None, redis_flush_size=None, semantic_cache_scope='key', cache=backend)"
+                ),
+            );
+            let CacheConfigProjection::Native(config) =
+                NativeCacheConfig::project(&disk_facade).unwrap()
+            else {
+                panic!("disk cache should be supported");
+            };
+            let CacheBackendConfig::Disk(disk) = config.backend else {
+                panic!("expected disk configuration");
+            };
+            assert_eq!(disk.directory, root);
+            let matching = NativeResponseCache::disk(&directory).unwrap();
+            assert_eq!(
+                (NativeCacheConfig {
+                    policy: config.policy,
+                    backend: CacheBackendConfig::Disk(disk),
+                })
+                .service_mismatch(&matching),
+                None
+            );
+            let other = NativeResponseCache::disk(&root.join("other").to_string_lossy()).unwrap();
+            let mismatch = NativeCacheConfig {
+                policy: CachePolicy {
+                    mode: "default-on".into(),
+                    ttl: None,
+                    namespace: None,
+                    supported_call_types: None,
+                    redis_flush_size: None,
+                    semantic_cache_scope: "key".into(),
+                },
+                backend: CacheBackendConfig::Disk(DiskCacheConfig {
+                    directory: root.clone(),
+                }),
+            };
+            assert_eq!(
+                mismatch.service_mismatch(&other),
+                Some("facade and native backend directories must match")
+            );
+
+            let custom = facade(
+                py,
+                &format!(
+                    "CustomCache = type('CustomCache', (), {{'__module__': 'mypkg'}})\n\
+                     CustomDisk = type('CustomDisk', (), {{'__module__': 'mypkg'}})\n\
+                     store = CustomCache()\n\
+                     store._disk = CustomDisk()\n\
+                     store.directory = {directory:?}\n\
+                     backend = SimpleNamespace(disk_cache=store)\n\
+                     facade = SimpleNamespace(type='disk', mode='default-on', ttl=None, namespace=None, supported_call_types=None, redis_flush_size=None, semantic_cache_scope='key', cache=backend)"
+                ),
+            );
+            let CacheConfigProjection::Unsupported(reason) =
+                NativeCacheConfig::project(&custom).unwrap()
+            else {
+                panic!("custom disk store must stay on Python");
+            };
+            assert_eq!(
+                reason.message(),
+                "native disk cache requires the built-in diskcache store"
+            );
+        });
+    }
 }
diff --git a/litellm-rust/crates/python-bridge/src/cache/facade.rs b/litellm-rust/crates/python-bridge/src/cache/facade.rs
index f2f86c14b37..a22a1754169 100644
--- a/litellm-rust/crates/python-bridge/src/cache/facade.rs
+++ b/litellm-rust/crates/python-bridge/src/cache/facade.rs
@@ -32,10 +32,16 @@ struct RedisPoolGuard {
     max_connections: usize,
 }
 
+struct DiskStoreGuard {
+    reference: Py<PyAny>,
+    directory: String,
+}
+
 pub(super) struct FacadeGuard {
     outer: ObjectGuard,
     backend: ObjectGuard,
     redis_pool: Option<RedisPoolGuard>,
+    disk_store: Option<DiskStoreGuard>,
 }
 
 impl ObjectGuard {
@@ -176,6 +182,26 @@ impl RedisPoolGuard {
     }
 }
 
+impl DiskStoreGuard {
+    fn capture(backend: &Bound<'_, PyAny>) -> PyResult<Self> {
+        let store = backend.getattr("disk_cache")?;
+        Ok(Self {
+            reference: store.clone().unbind(),
+            directory: store.getattr("directory")?.extract()?,
+        })
+    }
+
+    fn matches(&self, py: Python<'_>, backend: &Bound<'_, PyAny>) -> PyResult<bool> {
+        let store = backend.getattr("disk_cache")?;
+        Ok(self.reference.bind(py).is(&store)
+            && self.directory == store.getattr("directory")?.extract::<String>()?)
+    }
+
+    fn traverse(&self, visit: &PyVisit<'_>) -> Result<(), PyTraverseError> {
+        visit.call(&self.reference)
+    }
+}
+
 impl FacadeGuard {
     pub(super) fn capture(
         py: Python<'_>,
@@ -192,6 +218,7 @@ impl FacadeGuard {
         let (module, name, cache_kind) = match kind {
             "memory" => ("litellm.caching.in_memory_cache", "InMemoryCache", "local"),
             "redis" => ("litellm.caching.redis_cache", "RedisCache", "redis"),
+            "disk" => ("litellm.caching.disk_cache", "DiskCache", "disk"),
             _ => unreachable!(),
         };
         let backend = facade.getattr("cache")?;
@@ -240,6 +267,9 @@ impl FacadeGuard {
             redis_pool: (kind == "redis")
                 .then(|| RedisPoolGuard::capture(&backend))
                 .transpose()?,
+            disk_store: (kind == "disk")
+                .then(|| DiskStoreGuard::capture(&backend))
+                .transpose()?,
         })
     }
 
@@ -253,7 +283,10 @@ impl FacadeGuard {
         }
         match &self.redis_pool {
             Some(guard) => guard.matches(py, &backend),
-            None => Ok(true),
+            None => match &self.disk_store {
+                Some(guard) => guard.matches(py, &backend),
+                None => Ok(true),
+            },
         }
     }
 
@@ -263,6 +296,9 @@ impl FacadeGuard {
         if let Some(guard) = &self.redis_pool {
             guard.traverse(&visit)?;
         }
+        if let Some(guard) = &self.disk_store {
+            guard.traverse(&visit)?;
+        }
         Ok(())
     }
 }
diff --git a/litellm-rust/crates/python-bridge/src/cache/handle.rs b/litellm-rust/crates/python-bridge/src/cache/handle.rs
index 8251b3df06c..2cb2045577c 100644
--- a/litellm-rust/crates/python-bridge/src/cache/handle.rs
+++ b/litellm-rust/crates/python-bridge/src/cache/handle.rs
@@ -51,6 +51,18 @@ impl CacheTestHandle {
         })
     }
 
+    #[staticmethod]
+    #[pyo3(signature = (directory))]
+    fn disk(py: Python<'_>, directory: String) -> PyResult<Self> {
+        let service =
+            release_gil(py, move || NativeResponseCache::disk(&directory)).map_err(cache_error)?;
+        Ok(Self {
+            service,
+            guard: None,
+            pid: std::process::id(),
+        })
+    }
+
     #[getter]
     fn backend(&self) -> &'static str {
         self.service.kind()
diff --git a/litellm-rust/crates/python-bridge/src/cache/native.rs b/litellm-rust/crates/python-bridge/src/cache/native.rs
index a9475429e45..14993a6e8e3 100644
--- a/litellm-rust/crates/python-bridge/src/cache/native.rs
+++ b/litellm-rust/crates/python-bridge/src/cache/native.rs
@@ -1,6 +1,7 @@
-use std::{sync::Arc, time::Duration};
+use std::{path::Path, sync::Arc, time::Duration};
 
 use litellm_cache::{CacheCodec, CacheConnectionResult, Error};
+use litellm_cache_disk::DiskCache;
 use litellm_cache_memory::InMemoryCache;
 use litellm_cache_redis::RedisCache;
 use litellm_cache_response::{
@@ -15,6 +16,7 @@ pub(super) enum NativeResponseCache {
         cache: Arc<ResponseCache<RedisCache<ResponseCacheCodec>>>,
         buffer: Option<Arc<WriteBuffer>>,
     },
+    Disk(Arc<ResponseCache<DiskCache<ResponseCacheCodec>>>),
 }
 
 impl NativeResponseCache {
@@ -43,6 +45,11 @@ impl NativeResponseCache {
             buffer: None,
         })
     }
+
+    pub fn disk(directory: &str) -> Result<Self, Error> {
+        let cache = DiskCache::open(directory, ResponseCacheCodec)?;
+        Ok(Self::Disk(Arc::new(ResponseCache::new(Arc::new(cache)))))
+    }
 }
 
 impl NativeResponseCache {
@@ -50,6 +57,7 @@ impl NativeResponseCache {
         match self {
             Self::Memory(_) => "memory",
             Self::Redis { .. } => "redis",
+            Self::Disk(_) => "disk",
         }
     }
 
@@ -57,6 +65,7 @@ impl NativeResponseCache {
         match self {
             Self::Memory(cache) => cache.default_ttl(),
             Self::Redis { cache, .. } => cache.default_ttl(),
+            Self::Disk(cache) => cache.default_ttl(),
         }
     }
 
@@ -64,6 +73,7 @@ impl NativeResponseCache {
         match self {
             Self::Memory(_) => None,
             Self::Redis { cache, .. } => cache.backend().namespace(),
+            Self::Disk(_) => None,
         }
     }
 
@@ -71,6 +81,7 @@ impl NativeResponseCache {
         match self {
             Self::Memory(cache) => Some(cache.backend().max_size_in_memory()),
             Self::Redis { .. } => None,
+            Self::Disk(_) => None,
         }
     }
 
@@ -78,6 +89,7 @@ impl NativeResponseCache {
         match self {
             Self::Memory(cache) => cache.backend().max_entry_bytes(),
             Self::Redis { .. } => None,
+            Self::Disk(_) => None,
         }
     }
 
@@ -87,10 +99,18 @@ impl NativeResponseCache {
                 cache,
                 buffer: flush_size.map(|flush_size| Arc::new(WriteBuffer::new(flush_size))),
             },
+            disk @ Self::Disk(_) => disk,
             memory => memory,
         }
     }
 
+    pub fn directory(&self) -> Option<&Path> {
+        match self {
+            Self::Disk(cache) => Some(cache.backend().directory()),
+            Self::Memory(_) | Self::Redis { .. } => None,
+        }
+    }
+
     pub fn lookup(
         &self,
         request: &ResponseCacheRequest,
@@ -99,6 +119,7 @@ impl NativeResponseCache {
         match self {
             Self::Memory(cache) => cache.lookup(request, now),
             Self::Redis { cache, .. } => cache.lookup(request, now),
+            Self::Disk(cache) => cache.lookup(request, now),
         }
     }
 
@@ -111,6 +132,7 @@ impl NativeResponseCache {
         match self {
             Self::Memory(cache) => cache.store(request, response, now),
             Self::Redis { cache, .. } => cache.store(request, response, now),
+            Self::Disk(cache) => cache.store(request, response, now),
         }
     }
 
@@ -122,6 +144,7 @@ impl NativeResponseCache {
         match self {
             Self::Memory(cache) => cache.lookup_batch(requests, now),
             Self::Redis { cache, .. } => cache.lookup_batch(requests, now),
+            Self::Disk(cache) => cache.lookup_batch(requests, now),
         }
     }
 
@@ -133,6 +156,7 @@ impl NativeResponseCache {
         match self {
             Self::Memory(cache) => cache.async_lookup(request, now).await,
             Self::Redis { cache, .. } => cache.async_lookup(request, now).await,
+            Self::Disk(cache) => cache.async_lookup(request, now).await,
         }
     }
 
@@ -152,6 +176,7 @@ impl NativeResponseCache {
                 cache,
                 buffer: Some(buffer),
             } => buffer.async_store(cache, request, response, now).await,
+            Self::Disk(cache) => cache.async_store(request, response, now).await,
         }
     }
 
@@ -163,6 +188,7 @@ impl NativeResponseCache {
         match self {
             Self::Memory(cache) => cache.async_lookup_batch(requests, now).await,
             Self::Redis { cache, .. } => cache.async_lookup_batch(requests, now).await,
+            Self::Disk(cache) => cache.async_lookup_batch(requests, now).await,
         }
     }
 
@@ -174,6 +200,7 @@ impl NativeResponseCache {
         match self {
             Self::Memory(cache) => cache.async_store_batch(entries, now).await,
             Self::Redis { cache, .. } => cache.async_store_batch(entries, now).await,
+            Self::Disk(cache) => cache.async_store_batch(entries, now).await,
         }
     }
 
@@ -186,6 +213,7 @@ impl NativeResponseCache {
                 }
                 cache.async_flush().await
             }
+            Self::Disk(cache) => cache.async_flush().await,
         }
     }
 
@@ -193,6 +221,7 @@ impl NativeResponseCache {
         match self {
             Self::Memory(cache) => cache.test_connection().await,
             Self::Redis { cache, .. } => cache.test_connection().await,
+            Self::Disk(cache) => cache.test_connection().await,
         }
     }
 }
diff --git a/tests/test_litellm_rust/test_cache.py b/tests/test_litellm_rust/test_cache.py
index c35cb1a20fb..13f5f686464 100644
--- a/tests/test_litellm_rust/test_cache.py
+++ b/tests/test_litellm_rust/test_cache.py
@@ -6,16 +6,19 @@ import threading
 import time
 import weakref
 from collections.abc import Generator
+from pathlib import Path
 from types import SimpleNamespace
 from typing import Final, Protocol, cast
 from urllib.parse import urlparse
 
+import diskcache
 import fakeredis
 import pytest
 import redis
 
 import litellm
 from litellm.caching.caching import Cache, disable_cache, enable_cache, update_cache
+from litellm.caching.disk_cache import DiskCache
 from litellm.caching.in_memory_cache import InMemoryCache
 from litellm.rust_bridge import _native
 from litellm.types.caching import LiteLLMCacheType
@@ -393,3 +396,111 @@ async def test_redis_facade_buffers_native_async_writes(redis_url: str) -> None:
     assert client.get("second") is not None
     await facade.cache.disconnect()
     client.close()
+
+
+async def test_disk_reads_python_entries_and_python_reads_native_entries(tmp_path: Path) -> None:
+    disk_cache: Final = DiskCache(disk_cache_dir=str(tmp_path))
+    response: Final = {"choices": [{"text": "cached"}], "usage": {"total_tokens": 3}}
+    disk_cache.disk_cache.set(
+        "sync",
+        {"timestamp": time.time(), "response": json.dumps(response)},
+    )
+    disk_cache.disk_cache.set("async", json.dumps({"timestamp": time.time(), "response": response}))
+    disk_cache.disk_cache.set("raw", json.dumps(response))
+    disk_cache.disk_cache.set("invalid", "not a cache entry")
+    disk_cache.disk_cache.set(
+        "large",
+        {"timestamp": time.time(), "response": {"text": "x" * 70_000}},
+    )
+    binding: Final = _native._CacheTestResolver(
+        SimpleNamespace(cache=_native._CacheTestHandle.disk(str(tmp_path)))
+    ).resolve()
+
+    assert binding.lookup(request("sync")) == response
+    assert await binding.async_lookup(request("async")) == response
+    assert binding.lookup(request("raw")) == response
+    assert await binding.async_lookup(request("invalid")) is None
+    assert binding.lookup(request("large")) == {"text": "x" * 70_000}
+
+    await binding.async_store({**request("native"), "ttl_seconds": 12.0}, response)
+    stored_response: Final = disk_cache.get_cache("native")
+    assert isinstance(stored_response, dict)
+    assert stored_response["response"] == response
+    stored, expire_time = disk_cache.disk_cache.get("native", expire_time=True)
+    assert stored is not None
+    assert time.time() < expire_time <= time.time() + 12.0
+    await binding.async_store(request("no-ttl"), response)
+    _, no_expiry = disk_cache.disk_cache.get("no-ttl", expire_time=True)
+    assert no_expiry is None
+
+
+async def test_disk_entries_survive_a_fresh_handle_and_expire_on_time(tmp_path: Path) -> None:
+    first: Final = _native._CacheTestResolver(
+        SimpleNamespace(cache=_native._CacheTestHandle.disk(str(tmp_path)))
+    ).resolve()
+    await first.async_store(request("persistent"), {"value": "persistent"})
+    await first.async_store({**request("expiring"), "ttl_seconds": 0.3}, {"value": "expiring"})
+    fresh: Final = _native._CacheTestResolver(
+        SimpleNamespace(cache=_native._CacheTestHandle.disk(str(tmp_path)))
+    ).resolve()
+    assert fresh.lookup(request("persistent")) == {"value": "persistent"}
+    assert fresh.lookup(request("expiring")) == {"value": "expiring"}
+    await asyncio.sleep(0.4)
+    assert fresh.lookup(request("expiring")) is None
+    assert fresh.lookup(request("persistent")) == {"value": "persistent"}
+
+
+def test_disk_facade_registers_and_store_changes_fall_back(tmp_path: Path) -> None:
+    facade: Final = Cache(type=LiteLLMCacheType.DISK, disk_cache_dir=str(tmp_path))
+    with pytest.raises(TypeError, match="directories must match"):
+        _native._CacheTestHandle.disk(str(tmp_path / "other"))._bind_facade(facade)
+    handle: Final = _native._CacheTestHandle.disk(str(tmp_path))
+    handle._bind_facade(facade)
+    resolver: Final = _native._CacheTestResolver(SimpleNamespace(cache=facade))
+    binding: Final = resolver.resolve()
+    assert binding.kind == "native"
+    binding.store(request("native"), {"value": "native"})
+    assert facade.get_cache(cache_key="native") == {"value": "native"}
+
+    with rebound(facade.cache, "disk_cache", diskcache.Cache(str(tmp_path))):
+        assert resolver.resolve().kind == "python_callback"
+    assert resolver.resolve().kind == "native"
+
+    class CustomDiskCache(DiskCache):
+        pass
+
+    with rebound(facade, "cache", CustomDiskCache(disk_cache_dir=str(tmp_path))):
+        assert resolver.resolve().kind == "python_callback"
+
+    class CustomStore(diskcache.Cache):
+        pass
+
+    custom_facade: Final = Cache(type=LiteLLMCacheType.DISK, disk_cache_dir=str(tmp_path))
+    custom_facade.cache.disk_cache = CustomStore(str(tmp_path))
+    with pytest.raises(TypeError, match="built-in diskcache store"):
+        _native._CacheTestHandle.disk(str(tmp_path))._bind_facade(custom_facade)
+
+
+async def test_disk_native_batch_lookup_and_store_report_partial_hits(tmp_path: Path) -> None:
+    binding: Final = _native._CacheTestResolver(
+        SimpleNamespace(cache=_native._CacheTestHandle.disk(str(tmp_path)))
+    ).resolve()
+    requests: Final = [request("hit"), request("miss"), request("disabled")]
+    requests[2]["controls"] = {
+        "supported_call_type": True,
+        "configured": True,
+        "native_backend": True,
+        "default_on": True,
+        "caching": False,
+        "no_cache": False,
+        "no_store": False,
+        "use_cache": False,
+    }
+    await binding.async_store_batch(requests, [{"value": 1}, {"value": 2}, {"value": 3}])
+
+    partial: Final = await binding.async_lookup_batch(requests)
+
+    assert partial == {
+        "values": [{"value": 1}, {"value": 2}, None],
+        "missing_indices": [2],
+    }

From b8c793b9625467d5647e9a49e251fe5480953350 Mon Sep 17 00:00:00 2001
From: mateo-berri <277851410+mateo-berri@users.noreply.github.com>
Date: Mon, 21 Sep 2026 13:44:58 -0700
Subject: [PATCH 29/55] fix(types): drop restating docstrings, import search
 tool types at runtime, close the spend-table match

---
 .../proxy/common_utils/check_batch_cost.py           |  6 ------
 .../proxy/common_utils/check_responses_cost.py       |  3 ---
 litellm/proxy/db/db_spend_update_writer.py           |  5 +++--
 litellm/router_utils/search_api_router.py            | 12 ++++--------
 4 files changed, 7 insertions(+), 19 deletions(-)

diff --git a/enterprise/litellm_enterprise/proxy/common_utils/check_batch_cost.py b/enterprise/litellm_enterprise/proxy/common_utils/check_batch_cost.py
index 3ea9b7d9bfd..41974c26158 100644
--- a/enterprise/litellm_enterprise/proxy/common_utils/check_batch_cost.py
+++ b/enterprise/litellm_enterprise/proxy/common_utils/check_batch_cost.py
@@ -43,8 +43,6 @@ TERMINAL_MANAGED_OBJECT_STATUSES: Final[Tuple[str, ...]] = (
 
 
 class _ManagedObjectRow(Protocol):
-    """The managed-object row fields this poller reads off whatever the DB hands back."""
-
     @property
     def id(self) -> str: ...
 
@@ -59,19 +57,16 @@ class _ManagedObjectRow(Protocol):
 
 
 def _managed_object_table(prisma_client: "PrismaClient") -> "TableActions[_ManagedObjectRow]":
-    """The managed-object table's prisma actions, typed to the row fields this module reads."""
     table: Final[TableActions[_ManagedObjectRow]] = prisma_client.db.litellm_managedobjecttable
     return table
 
 
 def _user_table(prisma_client: "PrismaClient") -> "TableActions[prisma_models.LiteLLM_UserTable]":
-    """The user table's prisma actions."""
     table: Final[TableActions[prisma_models.LiteLLM_UserTable]] = prisma_client.db.litellm_usertable
     return table
 
 
 def _token_table(prisma_client: "PrismaClient") -> "TableActions[prisma_models.LiteLLM_VerificationToken]":
-    """The virtual-key table's prisma actions."""
     table: Final[TableActions[prisma_models.LiteLLM_VerificationToken]] = (
         prisma_client.db.litellm_verificationtoken
     )
@@ -79,7 +74,6 @@ def _token_table(prisma_client: "PrismaClient") -> "TableActions[prisma_models.L
 
 
 def _team_table(prisma_client: "PrismaClient") -> "TableActions[prisma_models.LiteLLM_TeamTable]":
-    """The team table's prisma actions."""
     table: Final[TableActions[prisma_models.LiteLLM_TeamTable]] = prisma_client.db.litellm_teamtable
     return table
 
diff --git a/enterprise/litellm_enterprise/proxy/common_utils/check_responses_cost.py b/enterprise/litellm_enterprise/proxy/common_utils/check_responses_cost.py
index 1bc41f2aa5b..cdeea0d3d4b 100644
--- a/enterprise/litellm_enterprise/proxy/common_utils/check_responses_cost.py
+++ b/enterprise/litellm_enterprise/proxy/common_utils/check_responses_cost.py
@@ -29,8 +29,6 @@ TERMINAL_RESPONSE_STATUSES = frozenset({"completed", "failed", "cancelled", "inc
 
 
 class _ManagedObjectRow(Protocol):
-    """The managed-object row fields this poller reads off whatever the DB hands back."""
-
     @property
     def id(self) -> str: ...
 
@@ -45,7 +43,6 @@ class _ManagedObjectRow(Protocol):
 
 
 def _managed_object_table(prisma_client: "PrismaClient") -> "TableActions[_ManagedObjectRow]":
-    """The managed-object table's prisma actions, typed to the row fields this poller reads."""
     table: Final[TableActions[_ManagedObjectRow]] = prisma_client.db.litellm_managedobjecttable
     return table
 
diff --git a/litellm/proxy/db/db_spend_update_writer.py b/litellm/proxy/db/db_spend_update_writer.py
index 0516f5460a7..865a8c39f03 100644
--- a/litellm/proxy/db/db_spend_update_writer.py
+++ b/litellm/proxy/db/db_spend_update_writer.py
@@ -19,7 +19,7 @@ from typing import TYPE_CHECKING, Any, Final, Literal, Protocol, TypeAlias, Type
 from urllib.parse import quote, unquote
 
 from pydantic import TypeAdapter
-from typing_extensions import LiteralString, ReadOnly, TypedDict
+from typing_extensions import LiteralString, ReadOnly, TypedDict, assert_never
 
 import litellm
 from litellm._logging import verbose_proxy_logger
@@ -142,7 +142,6 @@ _EntitySpendTable: TypeAlias = Literal[
 
 
 def _entity_spend_table(batcher: _SpendBatch, table_accessor: _EntitySpendTable) -> BatchTable:
-    """The batch table an entity type's spend increments are written to."""
     match table_accessor:
         case "litellm_tagtable":
             return batcher.litellm_tagtable
@@ -152,6 +151,8 @@ def _entity_spend_table(batcher: _SpendBatch, table_accessor: _EntitySpendTable)
             return batcher.litellm_modelaccessgroupbudgettable
         case "litellm_projecttable":
             return batcher.litellm_projecttable
+        case _ as unreachable:
+            assert_never(unreachable)
 
 
 class _SpendBatchManager(Protocol):
diff --git a/litellm/router_utils/search_api_router.py b/litellm/router_utils/search_api_router.py
index 76e833563ba..1cfb311d796 100644
--- a/litellm/router_utils/search_api_router.py
+++ b/litellm/router_utils/search_api_router.py
@@ -10,18 +10,16 @@ import traceback
 from collections.abc import Callable
 from functools import partial
 from types import MappingProxyType
-from typing import TYPE_CHECKING, Any, Final, Protocol
+from typing import Any, Final, Protocol
 
 from litellm._logging import verbose_router_logger
-
-if TYPE_CHECKING:
-    from litellm.types.router import SearchToolLiteLLMParams, SearchToolTypedDict
+from litellm.types.router import SearchToolLiteLLMParams, SearchToolTypedDict
 
 
 class _SearchToolsRouter(Protocol):
     """The one router attribute the search-tool helpers read and replace."""
 
-    search_tools: "list[SearchToolTypedDict]"
+    search_tools: list[SearchToolTypedDict]
 
 
 class SearchAPIRouter:
@@ -34,7 +32,7 @@ class SearchAPIRouter:
     @staticmethod
     def _resolve_search_provider_credentials(
         *,
-        tool_litellm_params: "SearchToolLiteLLMParams",
+        tool_litellm_params: SearchToolLiteLLMParams,
     ) -> tuple[str | None, str | None]:
         """
         Resolve search provider credentials from tool configuration ONLY.
@@ -65,8 +63,6 @@ class SearchAPIRouter:
             search_tools: List of search tool configurations from the database
         """
         try:
-            from litellm.types.router import SearchToolTypedDict
-
             verbose_router_logger.debug("Adding %s search tools to router", len(search_tools))
 
             # Convert search tools to the format expected by the router

From 5f84e8331689c95c333d0309e89ad566cd613122 Mon Sep 17 00:00:00 2001
From: mateo-berri <277851410+mateo-berri@users.noreply.github.com>
Date: Mon, 21 Sep 2026 13:48:11 -0700
Subject: [PATCH 30/55] chore(responses): drop narrative comments from the MCP
 streaming iterator

---
 litellm/responses/mcp/mcp_streaming_iterator.py | 15 ---------------
 1 file changed, 15 deletions(-)

diff --git a/litellm/responses/mcp/mcp_streaming_iterator.py b/litellm/responses/mcp/mcp_streaming_iterator.py
index 1c892eec803..fb05e7bff99 100644
--- a/litellm/responses/mcp/mcp_streaming_iterator.py
+++ b/litellm/responses/mcp/mcp_streaming_iterator.py
@@ -341,11 +341,6 @@ class MCPEnhancedStreamingIterator(BaseResponsesAPIStreamingIterator):
         self._error_event_emitted = False
         self._last_sequence_number = 0
 
-        # Every auto-execute round is a distinct upstream response, but the
-        # client is reading one stream. Fold the rounds into one public
-        # lifecycle: one response.created, one response.completed whose
-        # output holds every round's items, and output indexes that are
-        # never reused for a different item.
         self._round_index = 0
         self._output_index_offset = 0
         self._round_max_output_index = -1
@@ -438,8 +433,6 @@ class MCPEnhancedStreamingIterator(BaseResponsesAPIStreamingIterator):
         chunk: Final = await self._anext_impl()
         sequence_number: Final = getattr(chunk, "sequence_number", None)
         if isinstance(sequence_number, int):
-            # Follow-up rounds and gateway events restart their numbering.
-            # Keep the public stream strictly increasing.
             if sequence_number <= self._last_sequence_number and self._last_sequence_number > 0:
                 self._last_sequence_number += 1
                 _set_event_field(chunk, "sequence_number", self._last_sequence_number)
@@ -560,8 +553,6 @@ class MCPEnhancedStreamingIterator(BaseResponsesAPIStreamingIterator):
                             self.phase = "mcp_discovery"
                             return await self._compose_round_chunk(chunk)
 
-                    # None means the chunk was folded into the single public
-                    # lifecycle; fall through so phase 4 runs the follow-up.
                     return await self._compose_round_chunk(chunk)
                 except StopAsyncIteration:
                     if self.should_auto_execute and self.collected_response:
@@ -683,7 +674,6 @@ class MCPEnhancedStreamingIterator(BaseResponsesAPIStreamingIterator):
 
         composed: Final = await self._compose_round_chunk(chunk)
         if composed is None:
-            # The chunk stays internal; hand the next public event back instead.
             return await self._anext_impl()
         return composed
 
@@ -749,10 +739,6 @@ class MCPEnhancedStreamingIterator(BaseResponsesAPIStreamingIterator):
                 return
             self.tool_call_round += 1
 
-            # Each executed tool is one mcp_call output item of the single
-            # public response. Announce it at an output_index past the items
-            # this round already streamed, and keep that item id for the
-            # completion events below.
             from litellm.types.llms.openai import OutputItemAddedEvent
 
             next_output_index = self._output_index_offset + self._round_output_width(  # rebind-ok: advances per item
@@ -870,7 +856,6 @@ class MCPEnhancedStreamingIterator(BaseResponsesAPIStreamingIterator):
                     item=mcp_call_item,
                 )
                 self.tool_execution_events.append(output_item_done_event)
-                # The response model accepts output items as dicts, not as the generic event object.
                 self._pending_mcp_call_items.append(mcp_call_item.model_dump())
 
             # Store tool results for follow-up call

From cf8a211048368b8fea9f161dae5eb1b8ef4b2e30 Mon Sep 17 00:00:00 2001
From: Yujong Lee <yujong@berri.ai>
Date: Mon, 21 Sep 2026 20:52:03 +0000
Subject: [PATCH 31/55] test(rust): pin disk counter restart after a fractional
 value

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
 litellm-rust/crates/cache-disk/tests/cache.rs | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/litellm-rust/crates/cache-disk/tests/cache.rs b/litellm-rust/crates/cache-disk/tests/cache.rs
index 1e3e39db0c8..c6cd6006148 100644
--- a/litellm-rust/crates/cache-disk/tests/cache.rs
+++ b/litellm-rust/crates/cache-disk/tests/cache.rs
@@ -231,6 +231,12 @@ fn counters_use_atomic_native_values_and_ignore_invalid_initial_values() {
             .unwrap(),
         "real"
     );
+    assert_eq!(
+        cache
+            .increment_cache("counter", 1.0, ExactCacheContext::default())
+            .unwrap(),
+        1.0
+    );
 }
 
 #[test]

From 239bff3315ee9836559b7947157abe71c3cdcd0c Mon Sep 17 00:00:00 2001
From: mateo-berri <277851410+mateo-berri@users.noreply.github.com>
Date: Mon, 21 Sep 2026 13:57:50 -0700
Subject: [PATCH 32/55] test(responses): type the MCP lifecycle test helpers

---
 .../responses/mcp/test_mcp_streaming_iterator.py   | 14 +++++++++-----
 1 file changed, 9 insertions(+), 5 deletions(-)

diff --git a/tests/test_litellm/responses/mcp/test_mcp_streaming_iterator.py b/tests/test_litellm/responses/mcp/test_mcp_streaming_iterator.py
index 57ccbbfa493..1587557f3d2 100644
--- a/tests/test_litellm/responses/mcp/test_mcp_streaming_iterator.py
+++ b/tests/test_litellm/responses/mcp/test_mcp_streaming_iterator.py
@@ -11,7 +11,11 @@ from litellm.responses.mcp.mcp_streaming_iterator import (
     MAX_MCP_TOOL_CALL_ROUNDS,
     MCPEnhancedStreamingIterator,
 )
-from litellm.types.llms.openai import ResponsesAPIResponse, ResponsesAPIStreamEvents
+from litellm.types.llms.openai import (
+    BaseLiteLLMOpenAIResponseObject,
+    ResponsesAPIResponse,
+    ResponsesAPIStreamEvents,
+)
 
 # `litellm.__init__` re-exports a function named `responses`, which shadows the
 # `litellm.responses` subpackage as an attribute — `import litellm.responses.main`
@@ -57,8 +61,8 @@ def _text_message(text: str):
     return {"type": "message", "role": "assistant", "content": [{"type": "output_text", "text": text}]}
 
 
-def _item_type(item) -> str:
-    return item["type"] if isinstance(item, dict) else item.type
+def _item_type(item: dict[str, object] | BaseLiteLLMOpenAIResponseObject) -> str:
+    return str(item["type"]) if isinstance(item, dict) else str(item.type)
 
 
 def _tool_call_stream(call_id: str, tool_name: str, response_id: str = "resp-1") -> _FakeAsyncStream:
@@ -354,11 +358,11 @@ async def test_streaming_follow_up_keeps_previous_response_id_when_stored(monkey
     assert not [item for item in follow_up_kwargs["input"] if item.get("type") == "reasoning"]
 
 
-def _event(event_type, **fields):
+def _event(event_type: ResponsesAPIStreamEvents, **fields: object) -> SimpleNamespace:
     return SimpleNamespace(type=event_type, **fields)
 
 
-def _lifecycle_round(response_id: str, item: dict, sequence_start: int = 0):
+def _lifecycle_round(response_id: str, item: dict[str, object], sequence_start: int = 0) -> list[SimpleNamespace]:
     """One upstream Responses round as a provider streams it: its own id, indexes from 0, numbering from 0."""
     return [
         _event(

From a64febb3e7d32aef73dc7b90665c33d0b65b4805 Mon Sep 17 00:00:00 2001
From: mateo-berri <277851410+mateo-berri@users.noreply.github.com>
Date: Mon, 21 Sep 2026 14:01:08 -0700
Subject: [PATCH 33/55] fix(streaming): keep an explicit provider
 prompt_tokens=0 or completion_tokens=0 in streamed usage

The stream chunk builder started its per-chunk accumulators at 0 and adopted only nonzero counts, then fell back to litellm's tokenizer whenever the accumulated value was falsy, so a provider that reported an explicit 0 for prompt or completion tokens was billed the estimate instead. The accumulators now start at None, a usage chunk that reports a count marks it reported (a later chunk's 0 never replaces a reported nonzero), and the estimate only runs when no chunk reported the count. The Anthropic message_start cursor reset now yields None so the estimate still covers a cancelled stream, and Ollama chat streaming only attaches usage on the done chunk when both counts are present instead of inventing 0/0 on every chunk
---
 .../streaming_chunk_builder_utils.py          | 46 ++++++-----
 litellm/llms/ollama/chat/transformation.py    | 22 +++--
 .../streaming_chunk_builder_utils.py          |  4 +-
 .../test_streaming_chunk_builder_cursor.py    | 26 +++---
 .../test_streaming_chunk_builder_utils.py     | 80 +++++++++++++++++++
 .../ollama/test_ollama_chat_transformation.py | 47 ++++++++++-
 6 files changed, 183 insertions(+), 42 deletions(-)

diff --git a/litellm/litellm_core_utils/streaming_chunk_builder_utils.py b/litellm/litellm_core_utils/streaming_chunk_builder_utils.py
index fcd55c844c6..025db65a7ce 100644
--- a/litellm/litellm_core_utils/streaming_chunk_builder_utils.py
+++ b/litellm/litellm_core_utils/streaming_chunk_builder_utils.py
@@ -839,15 +839,17 @@ class ChunkProcessor:
             UsagePerChunk,
         )
 
-        # # Update usage information if needed
-        prompt_tokens = 0
-        completion_tokens = 0
+        # None means no usage chunk reported the count, which is the only case
+        # calculate_usage() estimates with the tokenizer. An explicit provider 0
+        # is a reported count and stays 0; a reported count is never replaced by
+        # a later chunk's 0 (Ollama sends 0/0 on every chunk before the done one).
+        prompt_tokens: int | None = None
+        completion_tokens: int | None = None
         # Anthropic's `message_start` SSE event carries usage.output_tokens=1 as a
         # cursor/placeholder; the real value only arrives in `message_delta`.
-        # If a stream is cancelled before `message_delta` lands, the last-wins
-        # accumulator below leaves completion_tokens stuck at 1 — which then
-        # bypasses the `completion_tokens or token_counter(...)` fallback in
-        # calculate_usage() because 1 is truthy. Count the completion-bearing
+        # If a stream is cancelled before `message_delta` lands, the accumulator
+        # below leaves completion_tokens stuck at 1, a reported count that
+        # calculate_usage() would keep. Count the completion-bearing
         # usage events so `_reset_anthropic_cursor_completion_tokens` can tell a
         # legitimate single-token reply (Anthropic emits 1 in BOTH message_start
         # AND message_delta, so >=2 events is positive evidence message_delta
@@ -875,10 +877,15 @@ class ChunkProcessor:
 
             if usage_chunk is not None:
                 usage_chunk_dict = self._usage_chunk_calculation_helper(usage_chunk)
-                if usage_chunk_dict["prompt_tokens"] is not None and usage_chunk_dict["prompt_tokens"] > 0:
+                if usage_chunk_dict["prompt_tokens"] is not None and (
+                    usage_chunk_dict["prompt_tokens"] > 0 or prompt_tokens is None
+                ):
                     prompt_tokens = usage_chunk_dict["prompt_tokens"]
-                if usage_chunk_dict["completion_tokens"] is not None and usage_chunk_dict["completion_tokens"] > 0:
+                if usage_chunk_dict["completion_tokens"] is not None and (
+                    usage_chunk_dict["completion_tokens"] > 0 or completion_tokens is None
+                ):
                     completion_tokens = usage_chunk_dict["completion_tokens"]
+                if usage_chunk_dict["completion_tokens"] is not None and usage_chunk_dict["completion_tokens"] > 0:
                     completion_usage_updates += 1
                 if usage_chunk_dict["cache_creation_input_tokens"] is not None and (
                     usage_chunk_dict["cache_creation_input_tokens"] > 0 or cache_creation_input_tokens is None
@@ -995,10 +1002,10 @@ class ChunkProcessor:
     @staticmethod
     def _reset_anthropic_cursor_completion_tokens(
         chunks: Sequence["_UsageBearingChunk | ModelResponse"],
-        completion_tokens: int,
+        completion_tokens: int | None,
         completion_usage_updates: int,
-    ) -> int:
-        """Reset a stale Anthropic ``message_start`` cursor placeholder to 0.
+    ) -> int | None:
+        """Reset a stale Anthropic ``message_start`` cursor placeholder to unreported.
 
         See the ``completion_usage_updates`` comment in
         ``_calculate_usage_per_chunk``. The accumulated value is NOT a stale
@@ -1006,8 +1013,8 @@ class ChunkProcessor:
         carried a ``finish_reason`` (positive evidence ``message_delta``
         arrived). Otherwise the only completion update we ever saw was the
         Anthropic ``message_start`` cursor, a small placeholder whose magnitude
-        varies per request (1 and 8 both observed live), so reset to 0 and let
-        ``calculate_usage()``'s ``or token_counter(...)`` fallback estimate from
+        varies per request (1 and 8 both observed live), so reset to None and let
+        ``calculate_usage()``'s ``token_counter(...)`` fallback estimate from
         the actually-received text and reasoning instead. Gated on
         ``custom_llm_provider == "anthropic"`` so the heuristic (which encodes
         Anthropic's specific message_start SSE shape) does not silently affect
@@ -1028,7 +1035,7 @@ class ChunkProcessor:
                 custom_llm_provider = hp.get("custom_llm_provider")
 
         if custom_llm_provider == "anthropic":
-            return 0
+            return None
         return completion_tokens
 
     def calculate_usage(
@@ -1063,15 +1070,18 @@ class ChunkProcessor:
         cost: Final[float | None] = calculated_usage_per_chunk["cost"]
 
         try:
-            returned_usage.prompt_tokens = prompt_tokens or (
-                count_prompt_tokens() if count_prompt_tokens else token_counter(model=model, messages=messages)
+            returned_usage.prompt_tokens = (
+                prompt_tokens
+                if prompt_tokens is not None
+                else (count_prompt_tokens() if count_prompt_tokens else token_counter(model=model, messages=messages))
             )
         except Exception:  # don't allow this failing to block a complete streaming response from being returned
             print_verbose("token_counter failed, assuming prompt tokens is 0")
             returned_usage.prompt_tokens = 0
         returned_usage.completion_tokens = (
             completion_tokens
-            or (
+            if completion_tokens is not None
+            else (
                 token_counter(
                     model=model,
                     text=completion_output,
diff --git a/litellm/llms/ollama/chat/transformation.py b/litellm/llms/ollama/chat/transformation.py
index 181894646e3..d39b4049903 100644
--- a/litellm/llms/ollama/chat/transformation.py
+++ b/litellm/llms/ollama/chat/transformation.py
@@ -1,6 +1,6 @@
 import json
 import time
-from collections.abc import AsyncIterator, Iterator
+from collections.abc import AsyncIterator, Iterator, Mapping
 from typing import TYPE_CHECKING, Any, Final, cast
 
 from httpx._models import Headers, Response
@@ -420,6 +420,18 @@ class OllamaChatConfig(BaseConfig):
         )
 
 
+def _done_chunk_usage(chunk: Mapping[str, object]) -> ChatCompletionUsageBlock | None:
+    prompt_eval_count: Final = chunk.get("prompt_eval_count")
+    eval_count: Final = chunk.get("eval_count")
+    if chunk.get("done") is not True or not isinstance(prompt_eval_count, int) or not isinstance(eval_count, int):
+        return None
+    return ChatCompletionUsageBlock(
+        prompt_tokens=prompt_eval_count,
+        completion_tokens=eval_count,
+        total_tokens=prompt_eval_count + eval_count,
+    )
+
+
 class OllamaChatCompletionResponseIterator(BaseModelResponseIterator):
     started_reasoning_content: bool = False
     finished_reasoning_content: bool = False
@@ -528,17 +540,11 @@ class OllamaChatCompletionResponseIterator(BaseModelResponseIterator):
                     )
                 ]
 
-            usage: Final = ChatCompletionUsageBlock(
-                prompt_tokens=chunk.get("prompt_eval_count", 0),
-                completion_tokens=chunk.get("eval_count", 0),
-                total_tokens=chunk.get("prompt_eval_count", 0) + chunk.get("eval_count", 0),
-            )
-
             return ModelResponseStream(
                 id=str(uuid.uuid4()),
                 object="chat.completion.chunk",
                 created=int(time.time()),  # ollama created_at is in UTC
-                usage=usage,
+                usage=_done_chunk_usage(chunk),
                 model=chunk["model"],
                 choices=choices,
             )
diff --git a/litellm/types/litellm_core_utils/streaming_chunk_builder_utils.py b/litellm/types/litellm_core_utils/streaming_chunk_builder_utils.py
index f981089d370..3deb307881f 100644
--- a/litellm/types/litellm_core_utils/streaming_chunk_builder_utils.py
+++ b/litellm/types/litellm_core_utils/streaming_chunk_builder_utils.py
@@ -4,8 +4,8 @@ from ..utils import CompletionTokensDetails, PromptTokensDetailsWrapper, ServerT
 
 
 class UsagePerChunk(TypedDict):
-    prompt_tokens: int
-    completion_tokens: int
+    prompt_tokens: ReadOnly[int | None]
+    completion_tokens: ReadOnly[int | None]
     cache_creation_input_tokens: int | None
     cache_read_input_tokens: int | None
     server_tool_use: ServerToolUse | None
diff --git a/tests/test_litellm/litellm_core_utils/test_streaming_chunk_builder_cursor.py b/tests/test_litellm/litellm_core_utils/test_streaming_chunk_builder_cursor.py
index 8617c5b81e8..b4a1f7733e7 100644
--- a/tests/test_litellm/litellm_core_utils/test_streaming_chunk_builder_cursor.py
+++ b/tests/test_litellm/litellm_core_utils/test_streaming_chunk_builder_cursor.py
@@ -15,7 +15,7 @@ calculate_usage() never fires, and the request is billed for 1 output
 token even when several thousand tokens of text were actually streamed.
 
 These tests pin the post-fix behavior: completion_tokens should reset
-to 0 when the only update we saw was the cursor, allowing the
+to None when the only update we saw was the cursor, allowing the
 text-based fallback to estimate from the real completion text.
 """
 
@@ -63,10 +63,10 @@ def _make_chunk(
 class TestAnthropicCursorBug:
     """The core regression: completion_tokens=1 cursor must not leak through."""
 
-    def test_only_message_start_cursor_resets_completion_to_zero(self):
+    def test_only_message_start_cursor_resets_completion_to_unreported(self):
         """
         Stream cancelled before message_delta — only the message_start cursor
-        (output_tokens=1) was seen. Per-chunk accumulator must reset to 0 so
+        (output_tokens=1) was seen. Per-chunk accumulator must reset to None so
         token_counter fallback can estimate from completion text.
         """
         # Anthropic message_start: input_tokens accurate, output_tokens=1 cursor
@@ -83,11 +83,11 @@ class TestAnthropicCursorBug:
         result = processor._calculate_usage_per_chunk(chunks=chunks)
 
         assert result["prompt_tokens"] == 1024
-        # The cursor value of 1 must NOT leak through — should be reset to 0
+        # The cursor value of 1 must NOT leak through — should be reset to None
         # so the text-based fallback estimates the real completion length.
-        assert result["completion_tokens"] == 0, (
+        assert result["completion_tokens"] is None, (
             "completion_tokens=1 from message_start cursor leaked through. "
-            "Should reset to 0 when only cursor was seen, so token_counter "
+            "Should reset to None when only cursor was seen, so token_counter "
             "fallback in calculate_usage() can estimate from completion text."
         )
 
@@ -233,10 +233,10 @@ class TestAnthropicCursorBug:
         result = processor._calculate_usage_per_chunk(chunks=chunks)
 
         assert result["cache_read_input_tokens"] == 4096
-        assert result["completion_tokens"] == 0, (
+        assert result["completion_tokens"] is None, (
             "cache chunks alone don't count as completion progress — only "
             "completion_tokens > 0 in a usage event proves real output happened. "
-            "Reset to 0 forces token_counter fallback."
+            "Reset to None forces token_counter fallback."
         )
 
     @pytest.mark.parametrize("placeholder", [1, 3, 8])
@@ -326,7 +326,7 @@ class TestAnthropicCursorBug:
         ]
         processor = ChunkProcessor(chunks=chunks, messages=[])
         result = processor._calculate_usage_per_chunk(chunks=chunks)
-        assert result["completion_tokens"] == 0
+        assert result["completion_tokens"] is None
         assert result["completion_tokens_details"] is None
 
     def test_estimated_reasoning_is_capped_to_trusted_completion_total(self):
@@ -403,11 +403,11 @@ class TestNonAnthropicStreamingIntact:
         result = processor._calculate_usage_per_chunk(chunks=chunks)
         assert result["completion_tokens"] == 5
 
-    def test_no_usage_chunks_leaves_zero(self):
-        """Stream with zero usage info → completion_tokens stays 0
+    def test_no_usage_chunks_leaves_unreported(self):
+        """Stream with zero usage info → both counts stay None
         (token_counter fallback will handle it)."""
         chunks = [_make_chunk(content="hi"), _make_chunk(content=" there")]
         processor = ChunkProcessor(chunks=chunks, messages=[])
         result = processor._calculate_usage_per_chunk(chunks=chunks)
-        assert result["prompt_tokens"] == 0
-        assert result["completion_tokens"] == 0
+        assert result["prompt_tokens"] is None
+        assert result["completion_tokens"] is None
diff --git a/tests/test_litellm/litellm_core_utils/test_streaming_chunk_builder_utils.py b/tests/test_litellm/litellm_core_utils/test_streaming_chunk_builder_utils.py
index 8e7ed52fade..5d75c6699cf 100644
--- a/tests/test_litellm/litellm_core_utils/test_streaming_chunk_builder_utils.py
+++ b/tests/test_litellm/litellm_core_utils/test_streaming_chunk_builder_utils.py
@@ -1648,3 +1648,83 @@ def test_calculate_usage_falls_back_to_prompt_counter_when_mock_stream_has_no_ad
     )
 
     assert usage.prompt_tokens == 77
+
+
+_ZERO_USAGE_TEXT_CHUNKS: Final = (
+    _openai_chunk(choices=[{"index": 0, "delta": {"role": "assistant", "content": "Hi"}, "finish_reason": None}]),
+    _openai_chunk(choices=[{"index": 0, "delta": {"content": " there"}, "finish_reason": None}]),
+    _openai_chunk(choices=[{"index": 0, "delta": {}, "finish_reason": "stop"}]),
+)
+
+
+@pytest.mark.parametrize(
+    "reported",
+    [
+        pytest.param({"prompt_tokens": 0, "completion_tokens": 17, "total_tokens": 17}, id="zero_prompt"),
+        pytest.param({"prompt_tokens": 5, "completion_tokens": 0, "total_tokens": 5}, id="zero_completion"),
+        pytest.param({"prompt_tokens": 0, "completion_tokens": 0, "total_tokens": 0}, id="all_zero"),
+    ],
+)
+def test_calculate_usage_keeps_an_explicit_provider_zero(reported: Mapping[str, int]) -> None:
+    chunks: Final = [*_ZERO_USAGE_TEXT_CHUNKS, _openai_chunk(choices=[], usage=reported)]
+
+    usage: Final = ChunkProcessor(chunks=chunks).calculate_usage(
+        chunks=chunks,
+        model="gpt-5.4-mini",
+        completion_output="Hi there",
+        messages=[{"role": "user", "content": "hi"}],
+        count_prompt_tokens=lambda: 999,
+    )
+
+    assert (usage.prompt_tokens, usage.completion_tokens, usage.total_tokens) == (
+        reported["prompt_tokens"],
+        reported["completion_tokens"],
+        reported["prompt_tokens"] + reported["completion_tokens"],
+    )
+
+
+def test_stream_chunk_builder_keeps_an_explicit_zero_prompt_count_end_to_end() -> None:
+    reported: Final = {"prompt_tokens": 0, "completion_tokens": 17, "total_tokens": 17}
+    chunks: Final = [*_ZERO_USAGE_TEXT_CHUNKS, _openai_chunk(choices=[], usage=reported)]
+
+    response: Final = stream_chunk_builder(chunks=chunks, messages=[{"role": "user", "content": "hi"}])
+
+    assert response is not None
+    assert (response.usage.prompt_tokens, response.usage.completion_tokens, response.usage.total_tokens) == (0, 17, 17)
+
+
+def test_calculate_usage_estimates_only_when_no_chunk_reported_usage() -> None:
+    chunks: Final = list(_ZERO_USAGE_TEXT_CHUNKS)
+
+    usage: Final = ChunkProcessor(chunks=chunks).calculate_usage(
+        chunks=chunks,
+        model="gpt-5.4-mini",
+        completion_output="Hi there",
+        count_prompt_tokens=lambda: 77,
+    )
+
+    assert usage.prompt_tokens == 77
+    assert usage.completion_tokens > 0
+    assert usage.total_tokens == 77 + usage.completion_tokens
+
+
+def test_calculate_usage_keeps_a_reported_count_over_a_later_chunks_zero() -> None:
+    chunks: Final = [
+        _openai_chunk(
+            choices=[{"index": 0, "delta": {"role": "assistant", "content": "Hi"}, "finish_reason": None}],
+            usage={"prompt_tokens": 5, "completion_tokens": 0, "total_tokens": 5},
+        ),
+        _openai_chunk(
+            choices=[{"index": 0, "delta": {"content": " there"}, "finish_reason": "stop"}],
+            usage={"prompt_tokens": 0, "completion_tokens": 17, "total_tokens": 17},
+        ),
+    ]
+
+    usage: Final = ChunkProcessor(chunks=chunks).calculate_usage(
+        chunks=chunks,
+        model="gpt-5.4-mini",
+        completion_output="Hi there",
+        count_prompt_tokens=lambda: 999,
+    )
+
+    assert (usage.prompt_tokens, usage.completion_tokens, usage.total_tokens) == (5, 17, 22)
diff --git a/tests/test_litellm/llms/ollama/test_ollama_chat_transformation.py b/tests/test_litellm/llms/ollama/test_ollama_chat_transformation.py
index 25f9645faa0..c7fba21d222 100644
--- a/tests/test_litellm/llms/ollama/test_ollama_chat_transformation.py
+++ b/tests/test_litellm/llms/ollama/test_ollama_chat_transformation.py
@@ -22,7 +22,7 @@ import json
 from unittest.mock import MagicMock
 
 import litellm
-from litellm.types.utils import Choices, Message, ModelResponse
+from litellm.types.utils import Choices, Message, ModelResponse, ModelResponseStream
 
 
 class TestEvent(BaseModel):
@@ -944,3 +944,48 @@ class TestOllamaToolCallTransformation:
         assert tool_msg["content"] == "Sunny, 72°F"
         assert "tool_call_id" in tool_msg, "tool_call_id must be forwarded to Ollama"
         assert tool_msg["tool_call_id"] == "call_abc123"
+
+
+class TestOllamaStreamingUsage:
+    @staticmethod
+    def _parse(chunk: dict) -> ModelResponseStream:
+        iterator = OllamaChatCompletionResponseIterator(streaming_response=iter([]), sync_stream=True)
+        return iterator.chunk_parser(chunk)
+
+    def test_done_chunk_reports_the_counts_ollama_sent(self):
+        result = self._parse(
+            {
+                "model": "qwen3:0.6b",
+                "message": {"role": "assistant", "content": ""},
+                "done": True,
+                "done_reason": "stop",
+                "prompt_eval_count": 100,
+                "eval_count": 50,
+            }
+        )
+
+        assert result.usage is not None
+        assert (result.usage.prompt_tokens, result.usage.completion_tokens, result.usage.total_tokens) == (100, 50, 150)
+
+    def test_done_chunk_without_counts_reports_no_usage_instead_of_zeros(self):
+        result = self._parse(
+            {
+                "model": "qwen3:0.6b",
+                "message": {"role": "assistant", "content": ""},
+                "done": True,
+                "done_reason": "stop",
+            }
+        )
+
+        assert result.usage is None
+
+    def test_chunk_before_done_reports_no_usage(self):
+        result = self._parse(
+            {
+                "model": "qwen3:0.6b",
+                "message": {"role": "assistant", "content": "Hi"},
+                "done": False,
+            }
+        )
+
+        assert result.usage is None

From c1382086d69f176114003a5fcf32ac2a8cbaaa64 Mon Sep 17 00:00:00 2001
From: Yujong Lee <yujong@berri.ai>
Date: Mon, 21 Sep 2026 21:05:21 +0000
Subject: [PATCH 34/55] ci(rust): raise native wheel size gate to 35 MB

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
 .github/scripts/verify_linux_native_wheel.py | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/.github/scripts/verify_linux_native_wheel.py b/.github/scripts/verify_linux_native_wheel.py
index 4fb8f068eb0..d86ad7b15c6 100644
--- a/.github/scripts/verify_linux_native_wheel.py
+++ b/.github/scripts/verify_linux_native_wheel.py
@@ -205,7 +205,7 @@ def main(
     native_module: Final = load_native_module(native_path)
     native_module_loads: Final = native_module is not None
     panic_test_hook_absent: Final = native_module is not None and not hasattr(native_module, "_panic_for_test")
-    native_size_limit: Final = 25_000_000
+    native_size_limit: Final = 35_000_000
     native_size_within_limit: Final = native_member.file_size <= native_size_limit
     validations: Final = (
         (f"Python tag is {EXPECTED_PYTHON_TAG}", python_tag == EXPECTED_PYTHON_TAG),
@@ -222,7 +222,7 @@ def main(
         ("Python extension entry point is present", extension_entry_point_present),
         ("Native module loads", native_module_loads),
         ("Production module omits the panic test hook", panic_test_hook_absent),
-        ("Native extension does not exceed 25 MB", native_size_within_limit),
+        ("Native extension does not exceed 35 MB", native_size_within_limit),
         ("Wheel contents are valid", not unexpected_members),
     )
 
@@ -267,7 +267,7 @@ def main(
             ),
             (
                 not native_size_within_limit,
-                f"native extension exceeds 20 MB: {native_member.file_size / 1_000_000:.2f} MB",
+                f"native extension exceeds 35 MB: {native_member.file_size / 1_000_000:.2f} MB",
             ),
             (bool(unexpected_members), f"wheel contains unexpected build artifacts: {', '.join(unexpected_members)}"),
         )

From 1b568319d070875c5137cc7f942cba85c80e6133 Mon Sep 17 00:00:00 2001
From: mateo-berri <277851410+mateo-berri@users.noreply.github.com>
Date: Mon, 21 Sep 2026 14:10:09 -0700
Subject: [PATCH 35/55] fix(types): blank non-string datadog tool text fields,
 look the spend table up by name

---
 .../integrations/datadog/datadog_llm_obs.py   | 24 +++++++++++--------
 litellm/proxy/db/db_spend_update_writer.py    | 22 ++++++++---------
 .../datadog/test_datadog_llm_obs.py           | 17 +++++++++++++
 3 files changed, 41 insertions(+), 22 deletions(-)

diff --git a/litellm/integrations/datadog/datadog_llm_obs.py b/litellm/integrations/datadog/datadog_llm_obs.py
index 3afe38ea075..98aac7336bf 100644
--- a/litellm/integrations/datadog/datadog_llm_obs.py
+++ b/litellm/integrations/datadog/datadog_llm_obs.py
@@ -254,13 +254,17 @@ def _reasoning_output_tokens(usage_object: Mapping[str, object] | None) -> float
     )
 
 
-def _mapping_field(source: Mapping[str, object], key: str) -> Mapping[str, Any]:
+def _mapping_field(source: Mapping[str, object], key: str) -> Mapping[str, object]:
     """The value at `key` when it is a mapping, else an empty one."""
     value: Final = source.get(key)
     return value if isinstance(value, dict) else _EMPTY_MAPPING
 
 
-def _content_blocks(message: Mapping[str, object]) -> tuple[Mapping[str, Any], ...]:
+def _text_field(source: Mapping[str, object], key: str, default: str = "") -> str:
+    return _safe_identifier(source.get(key, default))
+
+
+def _content_blocks(message: Mapping[str, object]) -> tuple[Mapping[str, object], ...]:
     content: Final = message.get("content")
     if not isinstance(content, list):
         return ()
@@ -293,10 +297,10 @@ def _to_dd_tool_calls(message: Mapping[str, object]) -> tuple[ToolCall, ...]:
     raw_tool_calls: Final = message.get("tool_calls")
     openai_calls: Final = tuple(
         ToolCall(
-            name=function.get("name", ""),
+            name=_text_field(function, "name"),
             arguments=_to_dd_arguments(function.get("arguments", "")),
-            tool_id=tool_call.get("id", ""),
-            type=tool_call.get("type", "function"),
+            tool_id=_text_field(tool_call, "id"),
+            type=_text_field(tool_call, "type", "function"),
         )
         for tool_call in (raw_tool_calls if isinstance(raw_tool_calls, list) else ())
         if isinstance(tool_call, dict)
@@ -304,9 +308,9 @@ def _to_dd_tool_calls(message: Mapping[str, object]) -> tuple[ToolCall, ...]:
     )
     anthropic_calls: Final = tuple(
         ToolCall(
-            name=block.get("name", ""),
+            name=_text_field(block, "name"),
             arguments=_to_dd_arguments(block.get("input") or {}),
-            tool_id=block.get("id", ""),
+            tool_id=_text_field(block, "id"),
             type="tool_use",
         )
         for block in _content_blocks(message)
@@ -402,12 +406,12 @@ def _to_dd_messages(messages: object) -> tuple[Message, ...]:
 
 def _to_dd_tool_definition(entry: Mapping[str, object]) -> ToolDefinition | None:
     function: Final = entry.get("function")
-    declared: Final[Mapping[str, Any]] = function if isinstance(function, dict) else entry
-    name: Final = declared.get("name")
+    declared: Final[Mapping[str, object]] = function if isinstance(function, dict) else entry
+    name: Final = _text_field(declared, "name")
     if not name:
         return None
     schema: Final = declared.get("parameters") or declared.get("input_schema")
-    description: Final = declared.get("description", "")
+    description: Final = _text_field(declared, "description")
     if not isinstance(schema, dict):
         return ToolDefinition(name=name, description=description)
     return ToolDefinition(name=name, description=description, schema=schema)
diff --git a/litellm/proxy/db/db_spend_update_writer.py b/litellm/proxy/db/db_spend_update_writer.py
index 865a8c39f03..5381071172f 100644
--- a/litellm/proxy/db/db_spend_update_writer.py
+++ b/litellm/proxy/db/db_spend_update_writer.py
@@ -19,7 +19,7 @@ from typing import TYPE_CHECKING, Any, Final, Literal, Protocol, TypeAlias, Type
 from urllib.parse import quote, unquote
 
 from pydantic import TypeAdapter
-from typing_extensions import LiteralString, ReadOnly, TypedDict, assert_never
+from typing_extensions import LiteralString, ReadOnly, TypedDict
 
 import litellm
 from litellm._logging import verbose_proxy_logger
@@ -142,17 +142,15 @@ _EntitySpendTable: TypeAlias = Literal[
 
 
 def _entity_spend_table(batcher: _SpendBatch, table_accessor: _EntitySpendTable) -> BatchTable:
-    match table_accessor:
-        case "litellm_tagtable":
-            return batcher.litellm_tagtable
-        case "litellm_agentstable":
-            return batcher.litellm_agentstable
-        case "litellm_modelaccessgroupbudgettable":
-            return batcher.litellm_modelaccessgroupbudgettable
-        case "litellm_projecttable":
-            return batcher.litellm_projecttable
-        case _ as unreachable:
-            assert_never(unreachable)
+    tables: Final[Mapping[_EntitySpendTable, BatchTable]] = MappingProxyType(
+        {
+            "litellm_tagtable": batcher.litellm_tagtable,
+            "litellm_agentstable": batcher.litellm_agentstable,
+            "litellm_modelaccessgroupbudgettable": batcher.litellm_modelaccessgroupbudgettable,
+            "litellm_projecttable": batcher.litellm_projecttable,
+        }
+    )
+    return tables[table_accessor]
 
 
 class _SpendBatchManager(Protocol):
diff --git a/tests/test_litellm/integrations/datadog/test_datadog_llm_obs.py b/tests/test_litellm/integrations/datadog/test_datadog_llm_obs.py
index a2f81091893..77d2518696c 100644
--- a/tests/test_litellm/integrations/datadog/test_datadog_llm_obs.py
+++ b/tests/test_litellm/integrations/datadog/test_datadog_llm_obs.py
@@ -110,6 +110,23 @@ def test_output_tool_calls_use_the_datadog_tool_call_schema(logger: DataDogLLMOb
     assert "function" not in message["tool_calls"][0]
 
 
+def test_tool_call_identifiers_that_are_not_strings_are_blanked_not_stringified(logger: DataDogLLMObsLogger) -> None:
+    payload = build(
+        logger,
+        response_message={
+            "role": "assistant",
+            "content": None,
+            "tool_calls": [
+                {"id": {"nested": "call_1"}, "type": 7, "function": {"name": ["get_weather"], "arguments": "{}"}}
+            ],
+        },
+    )
+
+    assert payload["meta"]["output"]["messages"][0]["tool_calls"] == [
+        {"name": "", "arguments": {}, "tool_id": "", "type": ""}
+    ]
+
+
 def test_tool_calls_are_not_duplicated_into_metadata(logger: DataDogLLMObsLogger) -> None:
     """The flat `output_tool_calls.*` keys were a second copy of a fact that now has its own field."""
     payload = build(

From 7590012a03998278cc66fc14bf7506f44124e68c Mon Sep 17 00:00:00 2001
From: Yuneng Jiang <yuneng@berri.ai>
Date: Mon, 21 Sep 2026 14:12:55 -0700
Subject: [PATCH 36/55] feat(docker): add a quickstart compose file served from
 the product repo

The docs quickstart pipes a compose file hosted on the docs site straight
into `docker compose -f -`. That puts the content users execute in the docs
repo rather than here, and nothing lands on disk for them to read first.

Move the two-service stack (gateway + Postgres) into docker/ so it ships and
is reviewed alongside the code it starts, and pin the image to main-stable
instead of latest. The docs change to download-then-run follows separately.

Verified: `docker compose up -d` brings the stack healthy, /health/liveliness
returns 200, /v1/models returns 200 with the placeholder key and 401 without,
and /ui/ serves.
---
 docker/README.md                     | 10 +++++++
 docker/docker-compose.quickstart.yml | 40 ++++++++++++++++++++++++++++
 2 files changed, 50 insertions(+)
 create mode 100644 docker/docker-compose.quickstart.yml

diff --git a/docker/README.md b/docker/README.md
index 26d8c9a37b0..787866ce35a 100644
--- a/docker/README.md
+++ b/docker/README.md
@@ -2,6 +2,16 @@
 
 This guide provides instructions for building and running the LiteLLM application using Docker and Docker Compose.
 
+> **Just want to run LiteLLM?** This guide builds from source. To run the published
+> image instead, use `docker-compose.quickstart.yml` in this directory — the
+> two-service stack (gateway + Postgres) that the
+> [Docker quickstart](https://docs.litellm.ai/docs/proxy/docker_quick_start) documents:
+>
+> ```bash
+> curl -sSLO https://github.com/BerriAI/litellm/raw/main/docker/docker-compose.quickstart.yml
+> docker compose -f docker-compose.quickstart.yml up -d
+> ```
+
 ## Prerequisites
 
 - Docker
diff --git a/docker/docker-compose.quickstart.yml b/docker/docker-compose.quickstart.yml
new file mode 100644
index 00000000000..7c849c759f0
--- /dev/null
+++ b/docker/docker-compose.quickstart.yml
@@ -0,0 +1,40 @@
+# LiteLLM quickstart stack: the gateway plus a Postgres database that stores
+# models, virtual keys, and spend logs. Used by
+# https://docs.litellm.ai/docs/proxy/docker_quick_start
+#
+#   curl -sSLO https://github.com/BerriAI/litellm/raw/main/docker/docker-compose.quickstart.yml
+#   docker compose -f docker-compose.quickstart.yml up -d
+#
+# The credentials below are placeholders for local evaluation. Before any real
+# use, set LITELLM_MASTER_KEY and LITELLM_SALT_KEY to long random values and
+# pin the image to a specific release tag.
+services:
+  litellm:
+    image: docker.litellm.ai/berriai/litellm:main-stable
+    ports:
+      - "4000:4000"
+    environment:
+      LITELLM_MASTER_KEY: sk-1234
+      LITELLM_SALT_KEY: sk-XXXXXXXXXXXXXXXX
+      DATABASE_URL: postgresql://litellm:litellm@db:5432/litellm
+      STORE_MODEL_IN_DB: "True"
+    depends_on:
+      db:
+        condition: service_healthy
+
+  db:
+    image: postgres:16
+    environment:
+      POSTGRES_USER: litellm
+      POSTGRES_PASSWORD: litellm
+      POSTGRES_DB: litellm
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U litellm"]
+      interval: 5s
+      timeout: 5s
+      retries: 10
+    volumes:
+      - postgres_data:/var/lib/postgresql/data
+
+volumes:
+  postgres_data:

From a2ae80ec9bb61057ae186a4930152f5ba7f41d61 Mon Sep 17 00:00:00 2001
From: mateo-berri <277851410+mateo-berri@users.noreply.github.com>
Date: Mon, 21 Sep 2026 14:19:52 -0700
Subject: [PATCH 37/55] fix(router): wrap every Responses and Messages fallback
 hop for mid-stream failover

The /v1/responses and /v1/messages streaming wrappers only ever wrapped the
primary's stream, so a hop reached through the regular fallback chain had no
mid-stream handler: its failure re-raised, or the outer wrapper retried the
same entry with a fresh attempted set and never reached the rest of the list.
Every attempt of the chain now runs through a per-endpoint attempt function
that wraps its own stream, mirroring chat completions, and the per-request
fallback and retry overrides ride a frozen carrier so each hop's re-entry
still sees them after the retry layer pops them.
---
 litellm/router.py                             | 170 ++++++++----------
 .../router_utils/fallback_event_handlers.py   |  74 +++++++-
 ...st_router_aresponses_streaming_fallback.py | 133 +++++++++++++-
 tests/test_litellm/test_router.py             |  55 +++++-
 4 files changed, 328 insertions(+), 104 deletions(-)

diff --git a/litellm/router.py b/litellm/router.py
index d9dd48a2c6a..9a5c770e78a 100644
--- a/litellm/router.py
+++ b/litellm/router.py
@@ -184,14 +184,17 @@ from litellm.router_utils.cooldown_handlers import (
     is_caller_timeout_408,
 )
 from litellm.router_utils.fallback_event_handlers import (
+    MID_STREAM_FALLBACK_CONTROLS_KEY,
     AttemptedFallbackTargets,
     _check_non_standard_fallback_format,
+    carry_over_pre_routing_selection,
     clear_pre_routing_selection,
     fallback_lookup_groups,
     fallbacks_disabled_for_request,
     get_fallback_model_group_for_lookup_groups,
-    get_pre_routing_selection,
     has_unattempted_fallback_target,
+    mid_stream_fallback_hop_kwargs,
+    per_request_fallback_controls,
     record_disable_fallbacks,
     record_pre_routing_selection,
     run_async_fallback,
@@ -3305,12 +3308,7 @@ class Router:
                     content_policy_fallbacks: Final[list | None] = initial_kwargs.get(
                         "content_policy_fallbacks", self.content_policy_fallbacks
                     )
-                    # Re-enter via the per-attempt helper so the fallback chain
-                    # picks deployments through
-                    # _ageneric_api_call_with_fallbacks_helper.
-                    # original_generic_function is preserved by the caller so
-                    # the helper knows what underlying API to invoke per attempt.
-                    initial_kwargs["original_function"] = self._ageneric_api_call_with_fallbacks_helper
+                    initial_kwargs["original_function"] = self._ageneric_api_call_with_fallbacks_responses_attempt
                     if e.is_pre_first_chunk or not e.generated_content:
                         # No content generated before the error — retry with the
                         # original input. Adding a continuation prompt would
@@ -5141,22 +5139,28 @@ class Router:
             request_kwargs=None,
         )
 
-    async def _ageneric_api_call_with_fallbacks(self, model: str, original_function: Callable, **kwargs):
+    async def _ageneric_api_call_with_fallbacks(
+        self, model: str, original_function: Callable, attempt_function: Callable | None = None, **kwargs
+    ):
         """
         Helper function to make a generic LLM API call through the router, this allows you to use retries/fallbacks with litellm router
+
+        attempt_function runs every attempt of the chain instead of the plain helper, so a streaming
+        endpoint can wrap each attempt's stream with its own mid-stream fallback handling.
         """
         try:
             kwargs["model"] = model
             kwargs["original_generic_function"] = original_function
-            kwargs["original_function"] = self._ageneric_api_call_with_fallbacks_helper
+            kwargs["original_function"] = attempt_function or self._ageneric_api_call_with_fallbacks_helper
+            if attempt_function is not None:
+                controls: Final = per_request_fallback_controls(kwargs)
+                kwargs[MID_STREAM_FALLBACK_CONTROLS_KEY] = controls  # rebind-ok: forwarded to every hop
             self._update_kwargs_before_fallbacks(model=model, kwargs=kwargs, metadata_variable_name="litellm_metadata")
             verbose_router_logger.debug(
                 "Inside ageneric_api_call_with_fallbacks() - model: %s; kwargs: %s", model, kwargs
             )
             response: Final = await self.async_function_with_fallbacks(**kwargs)
             return response
-
-            return response
         except Exception as e:
             asyncio.create_task(
                 send_llm_exception_alert(
@@ -5277,61 +5281,42 @@ class Router:
         self, original_function: Callable, **kwargs: Any
     ) -> Union["ResponsesAPIResponse", "BaseResponsesAPIStreamingIterator"]:
         """
-        _ageneric_api_call_with_fallbacks for the Responses API, with the
-        addition of mid-stream fallback handling.
-
-        When stream=True and the underlying call returns a
-        BaseResponsesAPIStreamingIterator, wrap it with
-        _aresponses_streaming_iterator so MidStreamFallbackError raised
-        during iteration triggers the Router's cross-provider fallback chain.
+        _ageneric_api_call_with_fallbacks for the Responses API, with every attempt's stream
+        carrying its own mid-stream fallback handling
+        (see _ageneric_api_call_with_fallbacks_responses_attempt).
+        """
+        return await self._ageneric_api_call_with_fallbacks(
+            original_function=original_function,
+            attempt_function=self._ageneric_api_call_with_fallbacks_responses_attempt,
+            **kwargs,
+        )
+
+    async def _ageneric_api_call_with_fallbacks_responses_attempt(
+        self,
+        model: str,
+        original_generic_function: Callable,
+        **kwargs: object,  # kwargs-ok: forwarded verbatim to the per-attempt helper, shape varies per call site
+    ) -> Union["ResponsesAPIResponse", "BaseResponsesAPIStreamingIterator"]:
+        """
+        One attempt of the Responses API fallback chain. A streaming result is wrapped with
+        _aresponses_streaming_iterator over this attempt's own kwargs, so a fallback hop that
+        fails mid-stream resumes the original group's chain instead of re-raising; the name keeps
+        _get_router_metadata_variable_name resolving to litellm_metadata for every hop.
         """
-        from litellm.litellm_core_utils.core_helpers import safe_deep_copy
         from litellm.responses.streaming_iterator import (
             BaseResponsesAPIStreamingIterator,
         )
 
-        # Snapshot the request kwargs before _ageneric_api_call_with_fallbacks
-        # mutates them. A shallow copy alone is not enough: the primary
-        # attempt mutates nested dicts in place — notably `litellm_metadata`,
-        # which `_update_kwargs_with_deployment` populates with
-        # deployment-specific fields (`deployment`, `model_info`, `api_base`,
-        # tags, etc.). Without an explicit copy of that dict, the shallow
-        # copy would still share its reference, leaking primary-deployment
-        # metadata into the mid-stream fallback request.
-        #
-        # We avoid deep-copying the full kwargs because it can contain
-        # non-deepcopyable objects (logging handles, async clients, etc.);
-        # `safe_deep_copy` deep-copies the metadata dicts key-by-key with a
-        # fallback to the original reference for any non-picklable value.
-        # The original_generic_function is preserved so the per-attempt
-        # helper knows which underlying API to call on fallback.
-        # The pre-routing hook stamps its tier selection into this bucket during the primary
-        # attempt; seeding it before the snapshot gives both the live kwargs and the copy a
-        # bucket, so the post-call carry-over below always has somewhere to read and write.
-        kwargs.setdefault("litellm_metadata", {})  # mutable-ok: shared bucket  # rebind-ok: stamp must be readable here
-
-        fallback_kwargs: Final[dict[str, object]] = kwargs.copy()
-        if isinstance(fallback_kwargs.get("litellm_metadata"), dict):
-            fallback_kwargs["litellm_metadata"] = safe_deep_copy(fallback_kwargs["litellm_metadata"])
-        if isinstance(fallback_kwargs.get("metadata"), dict):
-            fallback_kwargs["metadata"] = safe_deep_copy(fallback_kwargs["metadata"])
-        fallback_kwargs["original_generic_function"] = original_function
-
-        response: Final = await self._ageneric_api_call_with_fallbacks(original_function=original_function, **kwargs)
-
-        # The snapshot predates the pre-routing hook, so the tier it stamped into the live kwargs
-        # is carried over write-or-clear: a stale or caller-supplied selection left in the copy
-        # would key the mid-stream fallback lookup off a tier this attempt never routed to.
-        clear_pre_routing_selection(fallback_kwargs)
-        live_pre_routing_selection: Final = get_pre_routing_selection(kwargs)
-        if live_pre_routing_selection is not None:
-            record_pre_routing_selection(fallback_kwargs, live_pre_routing_selection)
-
+        controls: Final = kwargs.pop(MID_STREAM_FALLBACK_CONTROLS_KEY, None)
+        hop_kwargs: Final = mid_stream_fallback_hop_kwargs(
+            model=model, original_generic_function=original_generic_function, controls=controls, kwargs=kwargs
+        )
+        response: Final = await self._ageneric_api_call_with_fallbacks_helper(
+            model=model, original_generic_function=original_generic_function, **kwargs
+        )
+        carry_over_pre_routing_selection(live_kwargs=kwargs, snapshot=hop_kwargs)
         if kwargs.get("stream") and isinstance(response, BaseResponsesAPIStreamingIterator):
-            return await self._aresponses_streaming_iterator(
-                response=response,
-                initial_kwargs=fallback_kwargs,
-            )
+            return await self._aresponses_streaming_iterator(response=response, initial_kwargs=hop_kwargs)
         return response
 
     async def _aanthropic_messages_streaming_iterator(
@@ -5560,7 +5545,7 @@ class Router:
             content_policy_fallbacks: Final[list | None] = initial_kwargs.get(  # mutable-ok: matches the param below
                 "content_policy_fallbacks", self.content_policy_fallbacks
             )
-            initial_kwargs["original_function"] = self._ageneric_api_call_with_fallbacks_helper
+            initial_kwargs["original_function"] = self._ageneric_api_call_with_fallbacks_anthropic_messages_attempt
             self._update_kwargs_before_fallbacks(
                 model=model_group,
                 kwargs=initial_kwargs,
@@ -5614,46 +5599,41 @@ class Router:
         **kwargs: object,  # kwargs-ok: forwarded verbatim to original_function, shape varies per call site
     ) -> Union["AnthropicMessagesResponse", AsyncIterator[bytes]]:
         """
-        _ageneric_api_call_with_fallbacks for anthropic_messages, with the
-        addition of mid-stream fallback handling (see
-        _aanthropic_messages_streaming_iterator). Parity with
+        _ageneric_api_call_with_fallbacks for anthropic_messages, with every attempt's stream
+        carrying its own mid-stream fallback handling
+        (see _ageneric_api_call_with_fallbacks_anthropic_messages_attempt). Parity with
         _aresponses_with_streaming_fallbacks for the Responses API.
         """
-        from litellm.litellm_core_utils.core_helpers import safe_deep_copy
-
-        # Snapshot the request kwargs before the primary attempt mutates them
-        # in place: _update_kwargs_with_deployment writes deployment-specific
-        # fields (deployment, model_info, api_base, tags, ...) into the
-        # SAME litellm_metadata/metadata dicts a shallow .copy() would still
-        # share, leaking primary-deployment metadata into the mid-stream
-        # fallback request. safe_deep_copy avoids deep-copying the full
-        # kwargs (which can hold non-deepcopyable logging handles/clients).
-        # The pre-routing hook stamps its tier selection into this bucket during the primary
-        # attempt; seeding it before the snapshot gives both the live kwargs and the copy a
-        # bucket, so the post-call carry-over below always has somewhere to read and write.
-        kwargs.setdefault("litellm_metadata", {})  # mutable-ok: shared bucket  # rebind-ok: stamp must be readable here
-
-        fallback_kwargs: Final[dict[str, object]] = kwargs.copy()  # mutable-ok: mutated below before re-entry
-        if isinstance(fallback_kwargs.get("litellm_metadata"), dict):
-            fallback_kwargs["litellm_metadata"] = safe_deep_copy(fallback_kwargs["litellm_metadata"])
-        if isinstance(fallback_kwargs.get("metadata"), dict):
-            fallback_kwargs["metadata"] = safe_deep_copy(fallback_kwargs["metadata"])
-        fallback_kwargs["original_generic_function"] = original_function
-
-        response: Final = await self._ageneric_api_call_with_fallbacks(original_function=original_function, **kwargs)
-
-        # The snapshot predates the pre-routing hook, so the tier it stamped into the live kwargs
-        # is carried over write-or-clear: a stale or caller-supplied selection left in the copy
-        # would key the mid-stream fallback lookup off a tier this attempt never routed to.
-        clear_pre_routing_selection(fallback_kwargs)
-        live_pre_routing_selection: Final = get_pre_routing_selection(kwargs)
-        if live_pre_routing_selection is not None:
-            record_pre_routing_selection(fallback_kwargs, live_pre_routing_selection)
+        return await self._ageneric_api_call_with_fallbacks(
+            original_function=original_function,
+            attempt_function=self._ageneric_api_call_with_fallbacks_anthropic_messages_attempt,
+            **kwargs,
+        )
 
+    async def _ageneric_api_call_with_fallbacks_anthropic_messages_attempt(
+        self,
+        model: str,
+        original_generic_function: Callable,
+        **kwargs: object,  # kwargs-ok: forwarded verbatim to the per-attempt helper, shape varies per call site
+    ) -> Union["AnthropicMessagesResponse", AsyncIterator[bytes]]:
+        """
+        One attempt of the anthropic_messages fallback chain. A streaming result is wrapped with
+        _aanthropic_messages_streaming_iterator over this attempt's own kwargs, so a fallback hop
+        that fails mid-stream resumes the original group's chain instead of re-raising; the name
+        keeps _get_router_metadata_variable_name resolving to litellm_metadata for every hop.
+        """
+        controls: Final = kwargs.pop(MID_STREAM_FALLBACK_CONTROLS_KEY, None)
+        hop_kwargs: Final = mid_stream_fallback_hop_kwargs(
+            model=model, original_generic_function=original_generic_function, controls=controls, kwargs=kwargs
+        )
+        response: Final = await self._ageneric_api_call_with_fallbacks_helper(
+            model=model, original_generic_function=original_generic_function, **kwargs
+        )
+        carry_over_pre_routing_selection(live_kwargs=kwargs, snapshot=hop_kwargs)
         if kwargs.get("stream") and hasattr(response, "__aiter__"):
             return await self._aanthropic_messages_streaming_iterator(
                 response=cast("AsyncIterator[bytes]", response),  # cast-ok: stream=True always returns a byte iterator
-                initial_kwargs=fallback_kwargs,
+                initial_kwargs=hop_kwargs,
             )
         return response
 
diff --git a/litellm/router_utils/fallback_event_handlers.py b/litellm/router_utils/fallback_event_handlers.py
index 08b9246e562..f3ab2c5e493 100644
--- a/litellm/router_utils/fallback_event_handlers.py
+++ b/litellm/router_utils/fallback_event_handlers.py
@@ -1,6 +1,6 @@
 import hashlib
 import json
-from collections.abc import Mapping, Sequence
+from collections.abc import Callable, Mapping, Sequence
 from dataclasses import dataclass
 from datetime import datetime
 from enum import Enum
@@ -10,7 +10,7 @@ from typing import TYPE_CHECKING, Any, Final
 import litellm
 from litellm._logging import verbose_router_logger
 from litellm.integrations.custom_logger import CustomLogger
-from litellm.litellm_core_utils.core_helpers import get_metadata_variable_name_from_kwargs
+from litellm.litellm_core_utils.core_helpers import get_metadata_variable_name_from_kwargs, safe_deep_copy
 from litellm.litellm_core_utils.sensitive_data_masker import mask_sensitive_structure
 from litellm.router_utils.add_retry_fallback_headers import (
     add_fallback_headers_to_response,
@@ -284,6 +284,76 @@ def get_pre_routing_selection(kwargs: Mapping[str, object]) -> str | None:
     return next((selected for selected in selections if isinstance(selected, str) and selected), None)
 
 
+def carry_over_pre_routing_selection(live_kwargs: Mapping[str, object], snapshot: Mapping[str, object]) -> None:
+    """
+    Replace whatever selection the snapshot carries with the one the pre-routing hook stamped
+    into the live kwargs while routing this attempt, so a mid-stream fallback keys its lookup
+    off the tier this attempt actually routed to.
+    """
+    clear_pre_routing_selection(snapshot)
+    live_selection: Final = get_pre_routing_selection(live_kwargs)
+    if live_selection is not None:
+        record_pre_routing_selection(snapshot, live_selection)
+
+
+MID_STREAM_FALLBACK_CONTROLS_KEY: Final = "_mid_stream_fallback_controls"
+_PER_REQUEST_FALLBACK_CONTROL_KEYS: Final = (
+    "fallbacks",
+    "context_window_fallbacks",
+    "content_policy_fallbacks",
+    "num_retries",
+    "model_group_retry_policy",
+)
+
+
+@dataclass(frozen=True, slots=True)
+class MidStreamFallbackControls:
+    """
+    The per-request fallback and retry overrides every streaming attempt must see again.
+
+    async_function_with_retries pops them before the attempt function runs, so without this
+    carrier a fallback hop's own mid-stream re-entry would fall back to the router-level settings.
+    """
+
+    overrides: Mapping[str, object]
+
+
+_NO_FALLBACK_CONTROLS: Final = MidStreamFallbackControls(MappingProxyType({}))
+
+
+def per_request_fallback_controls(kwargs: Mapping[str, object]) -> MidStreamFallbackControls:
+    return MidStreamFallbackControls(
+        MappingProxyType({key: kwargs[key] for key in _PER_REQUEST_FALLBACK_CONTROL_KEYS if key in kwargs})
+    )
+
+
+def mid_stream_fallback_hop_kwargs(
+    model: str,
+    original_generic_function: Callable[..., object],
+    controls: object,
+    kwargs: Mapping[str, object],
+) -> dict[str, object]:  # mutable-ok: the streaming iterators rewrite it in place when they re-enter the chain
+    """
+    The kwargs one streaming attempt re-enters the fallback chain with if its stream fails.
+
+    A shallow copy keeps ``attempted_targets`` shared with the outer chain, so entries this
+    request already tried are never retried; the metadata buckets are copied key by key because
+    the attempt writes deployment-specific fields into them in place.
+    """
+    hop_controls: Final = controls if isinstance(controls, MidStreamFallbackControls) else _NO_FALLBACK_CONTROLS
+    copied_buckets: Final = MappingProxyType(
+        {name: safe_deep_copy(kwargs[name]) for name in _ROUTER_METADATA_BUCKETS if isinstance(kwargs.get(name), dict)}
+    )
+    return {  # mutable-ok: handed to the streaming iterator as its initial_kwargs, which it rewrites on re-entry
+        **kwargs,
+        **copied_buckets,
+        **hop_controls.overrides,
+        MID_STREAM_FALLBACK_CONTROLS_KEY: hop_controls,
+        "model": model,
+        "original_generic_function": original_generic_function,
+    }
+
+
 DISABLE_FALLBACKS_METADATA_KEY: Final = "_disable_fallbacks"
 
 
diff --git a/tests/router_unit_tests/test_router_aresponses_streaming_fallback.py b/tests/router_unit_tests/test_router_aresponses_streaming_fallback.py
index 0d33435cf7a..18b10e9c8e5 100644
--- a/tests/router_unit_tests/test_router_aresponses_streaming_fallback.py
+++ b/tests/router_unit_tests/test_router_aresponses_streaming_fallback.py
@@ -251,7 +251,7 @@ async def test_aresponses_with_streaming_fallbacks_non_streaming_passthrough():
 
     with patch.object(
         router,
-        "_ageneric_api_call_with_fallbacks",
+        "_ageneric_api_call_with_fallbacks_helper",
         new=AsyncMock(return_value=plain_response),
     ):
         out = await router._aresponses_with_streaming_fallbacks(
@@ -278,7 +278,7 @@ async def test_aresponses_with_streaming_fallbacks_wraps_streaming_iterator():
 
     with patch.object(
         router,
-        "_ageneric_api_call_with_fallbacks",
+        "_ageneric_api_call_with_fallbacks_helper",
         new=AsyncMock(return_value=streaming_iter),
     ), patch.object(
         router,
@@ -294,6 +294,135 @@ async def test_aresponses_with_streaming_fallbacks_wraps_streaming_iterator():
     mock_wrap.assert_awaited_once()
 
 
+# -------- every fallback entry stays reachable across hops --------
+
+
+def _make_three_tier_router(**router_kwargs) -> Router:
+    return Router(
+        model_list=[
+            {"model_name": "primary", "litellm_params": {"model": "openai/primary-model", "api_key": "sk-test"}},
+            {"model_name": "fb1", "litellm_params": {"model": "openai/fb1-model", "api_key": "sk-test"}},
+            {"model_name": "fb2", "litellm_params": {"model": "openai/fb2-model", "api_key": "sk-test"}},
+        ],
+        num_retries=0,
+        **router_kwargs,
+    )
+
+
+def _mid_stream_failure(model: str):
+    import litellm
+    from litellm.exceptions import MidStreamFallbackError
+
+    return MidStreamFallbackError(
+        message="stream dropped",
+        model=model,
+        llm_provider="openai",
+        original_exception=litellm.InternalServerError(message="stream dropped", llm_provider="openai", model=model),
+        is_pre_first_chunk=True,
+    )
+
+
+def _scripted_responses_stream(events: list, error: Exception | None = None):
+    from litellm.responses.streaming_iterator import BaseResponsesAPIStreamingIterator
+
+    class _ScriptedStream(BaseResponsesAPIStreamingIterator):
+        def __init__(self) -> None:
+            self._events = list(events)
+            self._hidden_params: dict = {}
+            self.completed_response = None
+
+        def __aiter__(self):
+            return self
+
+        async def __anext__(self):
+            if self._events:
+                return self._events.pop(0)
+            if error is not None:
+                raise error
+            raise StopAsyncIteration
+
+        async def aclose(self) -> None:
+            return None
+
+    return _ScriptedStream()
+
+
+def _three_tier_original(calls: list, primary_fails_pre_stream: bool):
+    import litellm
+
+    completed_event = _make_completed_event(1, 1, 2)
+
+    async def fake_original(**kwargs):
+        model = kwargs["model"]
+        calls.append(model)
+        if model == "openai/primary-model":
+            if primary_fails_pre_stream:
+                raise litellm.InternalServerError(message="primary down", llm_provider="openai", model=model)
+            return _scripted_responses_stream([], _mid_stream_failure(model))
+        if model == "openai/fb1-model":
+            return _scripted_responses_stream([], _mid_stream_failure(model))
+        return _scripted_responses_stream([completed_event])
+
+    return fake_original, completed_event
+
+
+@pytest.mark.asyncio
+async def test_aresponses_pre_stream_primary_failure_then_hop_stream_failure_reaches_second_entry():
+    """Regression: fallbacks=[{"primary": ["fb1", "fb2"]}]. The primary fails before streaming,
+    fb1 is reached through the regular fallback chain and then fails mid-stream. Only the
+    primary's stream used to be wrapped, so fb1's mid-stream failure either re-raised or
+    re-tried fb1 itself; fb2 was unreachable."""
+    router = _make_three_tier_router(fallbacks=[{"primary": ["fb1", "fb2"]}])
+    calls: list = []
+    fake_original, completed_event = _three_tier_original(calls, primary_fails_pre_stream=True)
+
+    stream = await router._aresponses_with_streaming_fallbacks(
+        original_function=fake_original, model="primary", stream=True, input="hi"
+    )
+    collected = [event async for event in stream]
+
+    assert calls == ["openai/primary-model", "openai/fb1-model", "openai/fb2-model"]
+    assert collected == [completed_event]
+
+
+@pytest.mark.asyncio
+async def test_aresponses_two_consecutive_mid_stream_failures_reach_second_entry():
+    """Regression: the primary and fb1 both fail mid-stream; fb2 must still be tried."""
+    router = _make_three_tier_router(fallbacks=[{"primary": ["fb1", "fb2"]}])
+    calls: list = []
+    fake_original, completed_event = _three_tier_original(calls, primary_fails_pre_stream=False)
+
+    stream = await router._aresponses_with_streaming_fallbacks(
+        original_function=fake_original, model="primary", stream=True, input="hi"
+    )
+    collected = [event async for event in stream]
+
+    assert calls == ["openai/primary-model", "openai/fb1-model", "openai/fb2-model"]
+    assert collected == [completed_event]
+
+
+@pytest.mark.asyncio
+async def test_aresponses_per_request_fallbacks_survive_into_hop_streams():
+    """Regression: a request-level fallbacks list (key or team router_settings) is popped
+    before each attempt runs, so a hop's mid-stream re-entry used to see only the router's
+    own (empty) list and gave up after fb1."""
+    router = _make_three_tier_router()
+    calls: list = []
+    fake_original, completed_event = _three_tier_original(calls, primary_fails_pre_stream=False)
+
+    stream = await router._aresponses_with_streaming_fallbacks(
+        original_function=fake_original,
+        model="primary",
+        stream=True,
+        input="hi",
+        fallbacks=[{"primary": ["fb1", "fb2"]}],
+    )
+    collected = [event async for event in stream]
+
+    assert calls == ["openai/primary-model", "openai/fb1-model", "openai/fb2-model"]
+    assert collected == [completed_event]
+
+
 @pytest.mark.asyncio
 async def test_aresponses_fallback_on_in_stream_error_event():
     """A retriable in-stream error event (429) must trigger the router's mid-stream
diff --git a/tests/test_litellm/test_router.py b/tests/test_litellm/test_router.py
index e642520bdbd..1ff04a1722f 100644
--- a/tests/test_litellm/test_router.py
+++ b/tests/test_litellm/test_router.py
@@ -4234,7 +4234,7 @@ async def test_aresponses_streaming_iterator_fallback():
     call_kwargs = mock_fallback_utils.call_args.kwargs
     fbk = call_kwargs["kwargs"]
     # Bound methods compare equal when they share the same instance + __func__.
-    assert fbk["original_function"] == router._ageneric_api_call_with_fallbacks_helper
+    assert fbk["original_function"] == router._ageneric_api_call_with_fallbacks_responses_attempt
     assert fbk["original_generic_function"] is litellm.aresponses
     assert call_kwargs["model_group"] == "anthropic/claude-sonnet-4-6"
     assert call_kwargs["disable_fallbacks"] is False
@@ -13819,7 +13819,7 @@ async def test_aanthropic_messages_with_streaming_fallbacks_non_streaming_passth
 
     with patch.object(
         router,
-        "_ageneric_api_call_with_fallbacks",
+        "_ageneric_api_call_with_fallbacks_helper",
         new=AsyncMock(return_value=plain_response),
     ):
         out = await router._aanthropic_messages_with_streaming_fallbacks(
@@ -13843,7 +13843,7 @@ async def test_aanthropic_messages_with_streaming_fallbacks_wraps_streaming_iter
     with (
         patch.object(
             router,
-            "_ageneric_api_call_with_fallbacks",
+            "_ageneric_api_call_with_fallbacks_helper",
             new=AsyncMock(return_value=streaming_iter),
         ),
         patch.object(
@@ -14128,7 +14128,7 @@ async def test_aanthropic_messages_with_streaming_fallbacks_deep_copies_nested_m
     ):
         with patch.object(
             router,
-            "_ageneric_api_call_with_fallbacks",
+            "_ageneric_api_call_with_fallbacks_helper",
             new=AsyncMock(side_effect=fake_original),
         ):
             await router._aanthropic_messages_with_streaming_fallbacks(
@@ -14162,7 +14162,7 @@ async def test_aanthropic_messages_with_streaming_fallbacks_deep_copies_metadata
     ):
         with patch.object(
             router,
-            "_ageneric_api_call_with_fallbacks",
+            "_ageneric_api_call_with_fallbacks_helper",
             new=AsyncMock(side_effect=fake_original),
         ):
             await router._aanthropic_messages_with_streaming_fallbacks(
@@ -14177,6 +14177,51 @@ async def test_aanthropic_messages_with_streaming_fallbacks_deep_copies_metadata
     assert "deployment" not in fallback_kwargs["metadata"]
 
 
+@pytest.mark.asyncio
+async def test_anthropic_messages_hop_stream_failure_reaches_second_fallback_entry():
+    """Regression: fallbacks=[{"primary": ["fb1", "fb2"]}]. The primary fails before
+    streaming, fb1 is reached through the regular fallback chain and then sends an
+    error frame mid-stream. Only the primary's stream used to be wrapped, so the outer
+    wrapper re-tried fb1 with a fresh attempted set and forwarded fb1's error frame to
+    the client on an HTTP 200; fb2 was unreachable."""
+    router = Router(
+        model_list=[
+            {"model_name": "primary", "litellm_params": {"model": "anthropic/primary-model", "api_key": "sk-test"}},
+            {"model_name": "fb1", "litellm_params": {"model": "anthropic/fb1-model", "api_key": "sk-test"}},
+            {"model_name": "fb2", "litellm_params": {"model": "anthropic/fb2-model", "api_key": "sk-test"}},
+        ],
+        num_retries=0,
+        fallbacks=[{"primary": ["fb1", "fb2"]}],
+    )
+    calls: list = []
+
+    async def fake_original(**kwargs):
+        model = kwargs["model"]
+        calls.append(model)
+        if model == "anthropic/primary-model":
+            raise litellm.InternalServerError(message="primary down", llm_provider="anthropic", model=model)
+        if model == "anthropic/fb1-model":
+            return _AnthropicMessagesFakeByteStream(
+                [_anthropic_messages_message_start_chunk(), _anthropic_messages_overloaded_error_chunk()]
+            )
+        return _AnthropicMessagesFakeByteStream(
+            [_anthropic_messages_message_start_chunk(), _anthropic_messages_content_chunk("from fb2")]
+        )
+
+    stream = await router._aanthropic_messages_with_streaming_fallbacks(
+        original_function=fake_original,
+        model="primary",
+        stream=True,
+        messages=[{"role": "user", "content": "hi"}],
+        max_tokens=10,
+    )
+    body = b"".join([chunk async for chunk in stream])
+
+    assert calls == ["anthropic/primary-model", "anthropic/fb1-model", "anthropic/fb2-model"]
+    assert b"from fb2" in body
+    assert b"overloaded_error" not in body
+
+
 @pytest.mark.asyncio
 async def test_anthropic_messages_fallback_triggers_after_lifecycle_only_frame():
     """Regression: Anthropic routinely sends a message_start lifecycle frame

From 3ce436af5ed72281214df3449ebf31323e8d3874 Mon Sep 17 00:00:00 2001
From: Yujong Lee <yujong@berri.ai>
Date: Mon, 21 Sep 2026 21:22:22 +0000
Subject: [PATCH 38/55] refactor(cache-disk): isolate python compatibility
 behind a value adapter

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
 litellm-rust/Cargo.lock                       |   2 +
 litellm-rust/crates/cache-disk/Cargo.toml     |   2 +
 litellm-rust/crates/cache-disk/src/adapter.rs |  10 +
 litellm-rust/crates/cache-disk/src/cache.rs   | 112 ++----
 litellm-rust/crates/cache-disk/src/lib.rs     |   5 +-
 litellm-rust/crates/cache-disk/src/pickle.rs  |  48 ---
 .../crates/cache-disk/src/python/mod.rs       |  81 ++++
 .../crates/cache-disk/src/python/value.rs     | 173 ++++++++
 litellm-rust/crates/cache-disk/tests/cache.rs | 369 +++++++++++-------
 .../crates/cache-disk/tests/python_compat.rs  | 105 +++++
 10 files changed, 643 insertions(+), 264 deletions(-)
 create mode 100644 litellm-rust/crates/cache-disk/src/adapter.rs
 delete mode 100644 litellm-rust/crates/cache-disk/src/pickle.rs
 create mode 100644 litellm-rust/crates/cache-disk/src/python/mod.rs
 create mode 100644 litellm-rust/crates/cache-disk/src/python/value.rs
 create mode 100644 litellm-rust/crates/cache-disk/tests/python_compat.rs

diff --git a/litellm-rust/Cargo.lock b/litellm-rust/Cargo.lock
index 554245dbb6e..0a1208787eb 100644
--- a/litellm-rust/Cargo.lock
+++ b/litellm-rust/Cargo.lock
@@ -2525,7 +2525,9 @@ name = "litellm-cache-disk"
 version = "0.1.0"
 dependencies = [
  "litellm-cache",
+ "py_literal",
  "rand 0.8.7",
+ "rstest",
  "rusqlite",
  "serde-pickle",
  "serde_json",
diff --git a/litellm-rust/crates/cache-disk/Cargo.toml b/litellm-rust/crates/cache-disk/Cargo.toml
index 023055e391a..b96994b3b55 100644
--- a/litellm-rust/crates/cache-disk/Cargo.toml
+++ b/litellm-rust/crates/cache-disk/Cargo.toml
@@ -7,6 +7,7 @@ repository.workspace = true
 
 [dependencies]
 litellm-cache.workspace = true
+py_literal = "0.4.0"
 rand.workspace = true
 rusqlite = { version = "0.40", features = ["bundled"] }
 serde-pickle = "1.2"
@@ -14,4 +15,5 @@ serde_json.workspace = true
 tokio.workspace = true
 
 [dev-dependencies]
+rstest.workspace = true
 tempfile = "3.27.0"
diff --git a/litellm-rust/crates/cache-disk/src/adapter.rs b/litellm-rust/crates/cache-disk/src/adapter.rs
new file mode 100644
index 00000000000..b6d318d5509
--- /dev/null
+++ b/litellm-rust/crates/cache-disk/src/adapter.rs
@@ -0,0 +1,10 @@
+use litellm_cache::Error;
+
+use crate::StoredValue;
+
+pub trait ValueAdapter: Send + Sync + 'static {
+    fn read(&self, value: StoredValue) -> Result<Option<Vec<u8>>, Error>;
+    fn write(&self, payload: Vec<u8>) -> StoredValue;
+    fn counter_seed(&self, value: Option<StoredValue>) -> Result<f64, Error>;
+    fn counter_value(&self, value: f64) -> StoredValue;
+}
diff --git a/litellm-rust/crates/cache-disk/src/cache.rs b/litellm-rust/crates/cache-disk/src/cache.rs
index bcce3a525b1..98182d93968 100644
--- a/litellm-rust/crates/cache-disk/src/cache.rs
+++ b/litellm-rust/crates/cache-disk/src/cache.rs
@@ -8,28 +8,42 @@ use litellm_cache::{
     BaseCache, BatchCache, BatchEntry, CacheCodec, CacheConnectionResult, CacheConnectionStatus,
     CounterCache, DeleteCache, Error, ExactCacheContext, FlushCache,
 };
-use serde_json::Value;
 
-use crate::{DiskStore, DiskcacheSqliteStore, StoredValue, pickle};
+use crate::{DiskStore, DiskcacheSqliteStore, PythonDiskCacheAdapter, StoredValue, ValueAdapter};
 
-pub struct DiskCache<S, D = DiskcacheSqliteStore> {
+pub struct DiskCache<S, D = DiskcacheSqliteStore, A = PythonDiskCacheAdapter> {
     store: Arc<D>,
+    adapter: Arc<A>,
     codec: S,
 }
 
 impl<S: CacheCodec> DiskCache<S> {
+    #[allow(clippy::default_constructed_unit_structs)]
     pub fn open(directory: impl AsRef<Path>, codec: S) -> Result<Self, Error> {
         Ok(Self {
             store: Arc::new(DiskcacheSqliteStore::open(directory)?),
+            adapter: Arc::new(PythonDiskCacheAdapter::default()),
             codec,
         })
     }
 }
 
-impl<S: CacheCodec, D: DiskStore> DiskCache<S, D> {
+impl<S: CacheCodec, D: DiskStore> DiskCache<S, D, PythonDiskCacheAdapter> {
+    #[allow(clippy::default_constructed_unit_structs)]
     pub fn with_store(store: D, codec: S) -> Self {
         Self {
             store: Arc::new(store),
+            adapter: Arc::new(PythonDiskCacheAdapter::default()),
+            codec,
+        }
+    }
+}
+
+impl<S: CacheCodec, D: DiskStore, A: ValueAdapter> DiskCache<S, D, A> {
+    pub fn with_adapter(store: D, adapter: A, codec: S) -> Self {
+        Self {
+            store: Arc::new(store),
+            adapter: Arc::new(adapter),
             codec,
         }
     }
@@ -39,7 +53,7 @@ impl<S: CacheCodec, D: DiskStore> DiskCache<S, D> {
     }
 
     fn decode_stored(&self, value: StoredValue) -> Result<Option<S::Value>, Error> {
-        let Some(bytes) = payload(value)? else {
+        let Some(bytes) = self.adapter.read(value)? else {
             return Ok(None);
         };
         self.codec.decode(&bytes).map(Some)
@@ -56,7 +70,7 @@ impl<S: CacheCodec, D: DiskStore> DiskCache<S, D> {
     }
 }
 
-impl<S: CacheCodec, D: DiskStore> BaseCache for DiskCache<S, D> {
+impl<S: CacheCodec, D: DiskStore, A: ValueAdapter> BaseCache for DiskCache<S, D, A> {
     type Value = S::Value;
     type Context = ExactCacheContext;
 
@@ -70,7 +84,7 @@ impl<S: CacheCodec, D: DiskStore> BaseCache for DiskCache<S, D> {
         value: Self::Value,
         context: &Self::Context,
     ) -> Result<(), Error> {
-        let value = StoredValue::Bytes(self.codec.encode(&value)?);
+        let value = self.adapter.write(self.codec.encode(&value)?);
         let expire_time = context.ttl.map(|ttl| unix_now() + ttl.as_secs_f64());
         self.store.set(key, value, expire_time, unix_now())
     }
@@ -89,7 +103,7 @@ impl<S: CacheCodec, D: DiskStore> BaseCache for DiskCache<S, D> {
         value: Self::Value,
         context: ExactCacheContext,
     ) -> Result<(), Error> {
-        let value = StoredValue::Bytes(self.codec.encode(&value)?);
+        let value = self.adapter.write(self.codec.encode(&value)?);
         let expire_time = context.ttl.map(|ttl| unix_now() + ttl.as_secs_f64());
         let key = key.to_string();
         Self::run_blocking(Arc::clone(&self.store), move |store| {
@@ -124,7 +138,7 @@ impl<S: CacheCodec, D: DiskStore> BaseCache for DiskCache<S, D> {
             .map(|(key, value)| {
                 self.codec
                     .encode(&value)
-                    .map(|value| (key, StoredValue::Bytes(value)))
+                    .map(|value| (key, self.adapter.write(value)))
             })
             .collect::<Result<Vec<_>, _>>()?;
         let expire_after = context.ttl;
@@ -162,7 +176,7 @@ impl<S: CacheCodec, D: DiskStore> BaseCache for DiskCache<S, D> {
     }
 }
 
-impl<S: CacheCodec, D: DiskStore> BatchCache for DiskCache<S, D> {
+impl<S: CacheCodec, D: DiskStore, A: ValueAdapter> BatchCache for DiskCache<S, D, A> {
     fn batch_get_cache(
         &self,
         keys: &[String],
@@ -204,7 +218,7 @@ impl<S: CacheCodec, D: DiskStore> BatchCache for DiskCache<S, D> {
     }
 }
 
-impl<S: CacheCodec, D: DiskStore> DeleteCache for DiskCache<S, D> {
+impl<S: CacheCodec, D: DiskStore, A: ValueAdapter> DeleteCache for DiskCache<S, D, A> {
     fn delete_cache(&self, key: &str) -> Result<(), Error> {
         self.store.pop(key, unix_now()).map(|_| ())
     }
@@ -218,7 +232,7 @@ impl<S: CacheCodec, D: DiskStore> DeleteCache for DiskCache<S, D> {
     }
 }
 
-impl<S: CacheCodec, D: DiskStore> FlushCache for DiskCache<S, D> {
+impl<S: CacheCodec, D: DiskStore, A: ValueAdapter> FlushCache for DiskCache<S, D, A> {
     fn flush_cache(&self) -> Result<(), Error> {
         self.store.clear()
     }
@@ -228,14 +242,22 @@ impl<S: CacheCodec, D: DiskStore> FlushCache for DiskCache<S, D> {
     }
 }
 
-impl<S: CacheCodec<Value = f64>, D: DiskStore> CounterCache for DiskCache<S, D> {
+impl<S: CacheCodec<Value = f64>, D: DiskStore, A: ValueAdapter> CounterCache
+    for DiskCache<S, D, A>
+{
     fn increment_cache(
         &self,
         key: &str,
         amount: f64,
         context: ExactCacheContext,
     ) -> Result<f64, Error> {
-        increment(self.store.as_ref(), key, amount, context.ttl)
+        increment(
+            self.adapter.as_ref(),
+            self.store.as_ref(),
+            key,
+            amount,
+            context.ttl,
+        )
     }
 
     async fn async_increment(
@@ -245,14 +267,16 @@ impl<S: CacheCodec<Value = f64>, D: DiskStore> CounterCache for DiskCache<S, D>
         context: ExactCacheContext,
     ) -> Result<f64, Error> {
         let key = key.to_string();
+        let adapter = Arc::clone(&self.adapter);
         Self::run_blocking(Arc::clone(&self.store), move |store| {
-            increment(store, &key, amount, context.ttl)
+            increment(adapter.as_ref(), store, &key, amount, context.ttl)
         })
         .await
     }
 }
 
-fn increment<D: DiskStore>(
+fn increment<A: ValueAdapter, D: DiskStore>(
+    adapter: &A,
     store: &D,
     key: &str,
     amount: f64,
@@ -260,25 +284,9 @@ fn increment<D: DiskStore>(
 ) -> Result<f64, Error> {
     let mut result = None;
     let mut apply = |current: Option<StoredValue>| {
-        let initial = match current {
-            Some(StoredValue::Integer(value)) => value as f64,
-            Some(StoredValue::Pickle(value)) => match pickle::decode(&value)? {
-                Value::Number(value) => value
-                    .as_i64()
-                    .map(|value| value as f64)
-                    .or_else(|| value.as_u64().map(|value| value as f64))
-                    .unwrap_or_default(),
-                _ => 0.0,
-            },
-            _ => 0.0,
-        };
+        let initial = adapter.counter_seed(current)?;
         let value = initial + amount;
-        let stored = if value.fract() == 0.0 && value >= i64::MIN as f64 && value <= i64::MAX as f64
-        {
-            StoredValue::Integer(value as i64)
-        } else {
-            StoredValue::Float(value)
-        };
+        let stored = adapter.counter_value(value);
         result = Some(value);
         Ok((stored, ttl.map(|ttl| unix_now() + ttl.as_secs_f64())))
     };
@@ -286,42 +294,6 @@ fn increment<D: DiskStore>(
     result.ok_or(Error::InvalidEntry)
 }
 
-fn payload(value: StoredValue) -> Result<Option<Vec<u8>>, Error> {
-    match value {
-        StoredValue::Bytes(value) if value.is_empty() => Ok(None),
-        StoredValue::Bytes(value) => Ok(Some(value)),
-        StoredValue::Text(value) if value.is_empty() => Ok(None),
-        StoredValue::Text(value) => Ok(Some(value.into_bytes())),
-        StoredValue::Integer(0) => Ok(None),
-        StoredValue::Integer(value) => Ok(Some(value.to_string().into_bytes())),
-        StoredValue::Float(0.0) => Ok(None),
-        StoredValue::Float(value) => serde_json::to_vec(&value)
-            .map(Some)
-            .map_err(|_| Error::InvalidEntry),
-        StoredValue::Pickle(value) => {
-            let value = pickle::decode(&value)?;
-            if is_falsy(&value) {
-                Ok(None)
-            } else {
-                serde_json::to_vec(&value)
-                    .map(Some)
-                    .map_err(|_| Error::InvalidEntry)
-            }
-        }
-    }
-}
-
-fn is_falsy(value: &Value) -> bool {
-    match value {
-        Value::Null | Value::Bool(false) => true,
-        Value::Number(value) => value.as_f64().is_some_and(|value| value == 0.0),
-        Value::String(value) => value.is_empty(),
-        Value::Array(value) => value.is_empty(),
-        Value::Object(value) => value.is_empty(),
-        Value::Bool(true) => false,
-    }
-}
-
 fn unix_now() -> f64 {
     SystemTime::now()
         .duration_since(UNIX_EPOCH)
diff --git a/litellm-rust/crates/cache-disk/src/lib.rs b/litellm-rust/crates/cache-disk/src/lib.rs
index 189d12ea793..9b2ffc24915 100644
--- a/litellm-rust/crates/cache-disk/src/lib.rs
+++ b/litellm-rust/crates/cache-disk/src/lib.rs
@@ -1,8 +1,11 @@
+mod adapter;
 mod cache;
-mod pickle;
+mod python;
 mod sqlite;
 mod store;
 
+pub use adapter::ValueAdapter;
 pub use cache::DiskCache;
+pub use python::PythonDiskCacheAdapter;
 pub use sqlite::DiskcacheSqliteStore;
 pub use store::{DiskStore, StoredValue};
diff --git a/litellm-rust/crates/cache-disk/src/pickle.rs b/litellm-rust/crates/cache-disk/src/pickle.rs
deleted file mode 100644
index 1d31e0bbeb6..00000000000
--- a/litellm-rust/crates/cache-disk/src/pickle.rs
+++ /dev/null
@@ -1,48 +0,0 @@
-use litellm_cache::Error;
-use serde_json::{Map, Number, Value};
-
-pub(crate) fn decode(bytes: &[u8]) -> Result<Value, Error> {
-    let value = serde_pickle::value_from_slice(bytes, Default::default())
-        .map_err(|_| Error::InvalidEntry)?;
-    convert(value)
-}
-
-fn convert(value: serde_pickle::Value) -> Result<Value, Error> {
-    match value {
-        serde_pickle::Value::None => Ok(Value::Null),
-        serde_pickle::Value::Bool(value) => Ok(Value::Bool(value)),
-        serde_pickle::Value::I64(value) => Ok(Value::Number(value.into())),
-        serde_pickle::Value::Int(value) => {
-            if let Ok(value) = value.to_string().parse::<i64>() {
-                Ok(Value::Number(value.into()))
-            } else if let Ok(value) = value.to_string().parse::<u64>() {
-                Ok(Value::Number(value.into()))
-            } else {
-                Err(Error::InvalidEntry)
-            }
-        }
-        serde_pickle::Value::F64(value) => Number::from_f64(value)
-            .map(Value::Number)
-            .ok_or(Error::InvalidEntry),
-        serde_pickle::Value::String(value) => Ok(Value::String(value)),
-        serde_pickle::Value::List(values) | serde_pickle::Value::Tuple(values) => values
-            .into_iter()
-            .map(convert)
-            .collect::<Result<Vec<_>, _>>()
-            .map(Value::Array),
-        serde_pickle::Value::Set(values) | serde_pickle::Value::FrozenSet(values) => values
-            .into_iter()
-            .map(|value| convert(value.into_value()))
-            .collect::<Result<Vec<_>, _>>()
-            .map(Value::Array),
-        serde_pickle::Value::Dict(values) => values
-            .into_iter()
-            .map(|(key, value)| match key {
-                serde_pickle::HashableValue::String(key) => Ok((key, convert(value)?)),
-                _ => Err(Error::InvalidEntry),
-            })
-            .collect::<Result<Map<_, _>, _>>()
-            .map(Value::Object),
-        serde_pickle::Value::Bytes(_) => Err(Error::InvalidEntry),
-    }
-}
diff --git a/litellm-rust/crates/cache-disk/src/python/mod.rs b/litellm-rust/crates/cache-disk/src/python/mod.rs
new file mode 100644
index 00000000000..5c9b57de000
--- /dev/null
+++ b/litellm-rust/crates/cache-disk/src/python/mod.rs
@@ -0,0 +1,81 @@
+mod value;
+
+use litellm_cache::Error;
+use py_literal::Value;
+
+use crate::{StoredValue, ValueAdapter};
+
+#[derive(Clone, Copy, Debug, Default)]
+pub struct PythonDiskCacheAdapter;
+
+impl PythonDiskCacheAdapter {
+    fn python_get_cache(value: StoredValue) -> Result<Option<Value>, Error> {
+        let value = match value {
+            StoredValue::Bytes(value) => Value::Bytes(value),
+            StoredValue::Text(value) => Value::String(value),
+            StoredValue::Integer(value) => {
+                value::from_json(serde_json::Value::Number(value.into()))
+            }
+            StoredValue::Float(value) => Value::Float(value),
+            StoredValue::Pickle(value) => value::from_pickle(&value)?,
+        };
+        if !value::is_truthy(&value) {
+            return Ok(None);
+        }
+        match value {
+            Value::String(text) => Ok(Some(
+                value::from_json_text(&text).unwrap_or(Value::String(text)),
+            )),
+            Value::Bytes(bytes) => match std::str::from_utf8(&bytes) {
+                Ok(text) => Ok(Some(
+                    value::from_json_text(text).unwrap_or(Value::Bytes(bytes)),
+                )),
+                Err(_) => Ok(Some(Value::Bytes(bytes))),
+            },
+            value => Ok(Some(value)),
+        }
+    }
+}
+
+impl ValueAdapter for PythonDiskCacheAdapter {
+    fn read(&self, value: StoredValue) -> Result<Option<Vec<u8>>, Error> {
+        let raw = match &value {
+            StoredValue::Text(value) => Some(value.as_bytes().to_vec()),
+            StoredValue::Bytes(value) => Some(value.clone()),
+            StoredValue::Integer(_) | StoredValue::Float(_) | StoredValue::Pickle(_) => None,
+        };
+        let Some(value) = Self::python_get_cache(value)? else {
+            return Ok(None);
+        };
+        if let Some(raw) = raw {
+            return Ok(Some(raw));
+        }
+        value::to_json(&value).map(Some)
+    }
+
+    fn write(&self, payload: Vec<u8>) -> StoredValue {
+        StoredValue::Bytes(payload)
+    }
+
+    fn counter_seed(&self, value: Option<StoredValue>) -> Result<f64, Error> {
+        let Some(value) = value else {
+            return Ok(0.0);
+        };
+        let Some(value) = Self::python_get_cache(value)? else {
+            return Ok(0.0);
+        };
+        Ok(if value::is_int(&value) {
+            value::to_f64(&value).unwrap_or(0.0)
+        } else {
+            0.0
+        })
+    }
+
+    fn counter_value(&self, value: f64) -> StoredValue {
+        if value.fract() == 0.0 && value >= i64::MIN as f64 && value <= i64::MAX as f64 {
+            StoredValue::Integer(value as i64)
+        } else {
+            StoredValue::Float(value)
+        }
+    }
+}
diff --git a/litellm-rust/crates/cache-disk/src/python/value.rs b/litellm-rust/crates/cache-disk/src/python/value.rs
new file mode 100644
index 00000000000..645eba7b757
--- /dev/null
+++ b/litellm-rust/crates/cache-disk/src/python/value.rs
@@ -0,0 +1,173 @@
+use litellm_cache::Error;
+use py_literal::Value;
+use serde_json::{Map, Number};
+
+pub(crate) fn from_pickle(bytes: &[u8]) -> Result<Value, Error> {
+    let value = serde_pickle::value_from_slice(bytes, Default::default())
+        .map_err(|_| Error::InvalidEntry)?;
+    from_pickle_value(value)
+}
+
+fn from_pickle_value(value: serde_pickle::Value) -> Result<Value, Error> {
+    match value {
+        serde_pickle::Value::None => Ok(Value::None),
+        serde_pickle::Value::Bool(value) => Ok(Value::Boolean(value)),
+        serde_pickle::Value::I64(value) => integer(value.to_string()),
+        serde_pickle::Value::Int(value) => integer(value.to_string()),
+        serde_pickle::Value::F64(value) => Ok(Value::Float(value)),
+        serde_pickle::Value::String(value) => Ok(Value::String(value)),
+        serde_pickle::Value::Bytes(value) => Ok(Value::Bytes(value)),
+        serde_pickle::Value::List(values) => values
+            .into_iter()
+            .map(from_pickle_value)
+            .collect::<Result<Vec<_>, _>>()
+            .map(Value::List),
+        serde_pickle::Value::Tuple(values) => values
+            .into_iter()
+            .map(from_pickle_value)
+            .collect::<Result<Vec<_>, _>>()
+            .map(Value::Tuple),
+        serde_pickle::Value::Set(values) => values
+            .into_iter()
+            .map(from_pickle_hashable)
+            .collect::<Result<Vec<_>, _>>()
+            .map(Value::Set),
+        serde_pickle::Value::FrozenSet(values) => values
+            .into_iter()
+            .map(from_pickle_hashable)
+            .collect::<Result<Vec<_>, _>>()
+            .map(Value::Set),
+        serde_pickle::Value::Dict(values) => values
+            .into_iter()
+            .map(|(key, value)| Ok((from_pickle_hashable(key)?, from_pickle_value(value)?)))
+            .collect::<Result<Vec<_>, Error>>()
+            .map(Value::Dict),
+    }
+}
+
+fn from_pickle_hashable(value: serde_pickle::HashableValue) -> Result<Value, Error> {
+    Ok(match value {
+        serde_pickle::HashableValue::None => Value::None,
+        serde_pickle::HashableValue::Bool(value) => Value::Boolean(value),
+        serde_pickle::HashableValue::I64(value) => integer(value.to_string())?,
+        serde_pickle::HashableValue::Int(value) => integer(value.to_string())?,
+        serde_pickle::HashableValue::F64(value) => Value::Float(value),
+        serde_pickle::HashableValue::Bytes(value) => Value::Bytes(value),
+        serde_pickle::HashableValue::String(value) => Value::String(value),
+        serde_pickle::HashableValue::Tuple(values) => Value::Tuple(
+            values
+                .into_iter()
+                .map(from_pickle_hashable)
+                .collect::<Result<Vec<_>, _>>()?,
+        ),
+        serde_pickle::HashableValue::FrozenSet(values) => Value::Set(
+            values
+                .into_iter()
+                .map(from_pickle_hashable)
+                .collect::<Result<Vec<_>, _>>()?,
+        ),
+    })
+}
+
+fn integer(value: String) -> Result<Value, Error> {
+    value.parse().map_err(|_| Error::InvalidEntry)
+}
+
+pub(crate) fn from_json(value: serde_json::Value) -> Value {
+    match value {
+        serde_json::Value::Null => Value::None,
+        serde_json::Value::Bool(value) => Value::Boolean(value),
+        serde_json::Value::Number(value) => {
+            if value.is_i64() || value.is_u64() {
+                integer(value.to_string())
+                    .unwrap_or(Value::Float(value.as_f64().unwrap_or(f64::NAN)))
+            } else {
+                Value::Float(value.as_f64().unwrap_or(f64::NAN))
+            }
+        }
+        serde_json::Value::String(value) => Value::String(value),
+        serde_json::Value::Array(values) => {
+            Value::List(values.into_iter().map(from_json).collect())
+        }
+        serde_json::Value::Object(values) => Value::Dict(
+            values
+                .into_iter()
+                .map(|(key, value)| (Value::String(key), from_json(value)))
+                .collect(),
+        ),
+    }
+}
+
+pub(crate) fn from_json_text(value: &str) -> Result<Value, Error> {
+    serde_json::from_str(value)
+        .map(from_json)
+        .map_err(|_| Error::InvalidEntry)
+}
+
+pub(crate) fn is_truthy(value: &Value) -> bool {
+    match value {
+        Value::None => false,
+        Value::Boolean(value) => *value,
+        Value::Integer(value) => value.to_string() != "0",
+        Value::Float(value) => *value != 0.0,
+        Value::Complex(value) => value.re != 0.0 || value.im != 0.0,
+        Value::String(value) => !value.is_empty(),
+        Value::Bytes(value) => !value.is_empty(),
+        Value::Tuple(value) | Value::List(value) | Value::Set(value) => !value.is_empty(),
+        Value::Dict(value) => !value.is_empty(),
+    }
+}
+
+pub(crate) fn is_int(value: &Value) -> bool {
+    matches!(value, Value::Integer(_) | Value::Boolean(_))
+}
+
+pub(crate) fn to_f64(value: &Value) -> Option<f64> {
+    match value {
+        Value::Integer(value) => value.to_string().parse().ok(),
+        Value::Boolean(value) => Some(if *value { 1.0 } else { 0.0 }),
+        _ => None,
+    }
+}
+
+pub(crate) fn to_json(value: &Value) -> Result<Vec<u8>, Error> {
+    serde_json::to_vec(&to_json_value(value)?).map_err(|_| Error::InvalidEntry)
+}
+
+fn to_json_value(value: &Value) -> Result<serde_json::Value, Error> {
+    Ok(match value {
+        Value::None => serde_json::Value::Null,
+        Value::Boolean(value) => serde_json::Value::Bool(*value),
+        Value::Integer(value) => serde_json::Value::Number(
+            value
+                .to_string()
+                .parse::<Number>()
+                .map_err(|_| Error::InvalidEntry)?,
+        ),
+        Value::Float(value) => {
+            serde_json::Value::Number(Number::from_f64(*value).ok_or(Error::InvalidEntry)?)
+        }
+        Value::Complex(_) | Value::Bytes(_) => return Err(Error::InvalidEntry),
+        Value::String(value) => serde_json::Value::String(value.clone()),
+        Value::Tuple(values) | Value::List(values) | Value::Set(values) => {
+            serde_json::Value::Array(
+                values
+                    .iter()
+                    .map(to_json_value)
+                    .collect::<Result<Vec<_>, _>>()?,
+            )
+        }
+        Value::Dict(values) => {
+            let values = values
+                .iter()
+                .map(|(key, value)| {
+                    let Value::String(key) = key else {
+                        return Err(Error::InvalidEntry);
+                    };
+                    Ok((key.clone(), to_json_value(value)?))
+                })
+                .collect::<Result<Map<String, serde_json::Value>, _>>()?;
+            serde_json::Value::Object(values)
+        }
+    })
+}
diff --git a/litellm-rust/crates/cache-disk/tests/cache.rs b/litellm-rust/crates/cache-disk/tests/cache.rs
index c6cd6006148..4fb77d233ec 100644
--- a/litellm-rust/crates/cache-disk/tests/cache.rs
+++ b/litellm-rust/crates/cache-disk/tests/cache.rs
@@ -7,46 +7,92 @@ use std::{
 };
 
 use litellm_cache::{
-    BaseCache, BatchCache, BatchEntry, CounterCache, DeleteCache, ExactCacheContext, FlushCache,
-    JsonCodec,
+    BaseCache, BatchCache, BatchEntry, CacheCodec, CounterCache, DeleteCache, ExactCacheContext,
+    FlushCache, JsonCodec,
 };
-use litellm_cache_disk::{DiskCache, DiskStore, DiskcacheSqliteStore, StoredValue};
+use litellm_cache_disk::{DiskCache, DiskStore, DiskcacheSqliteStore, StoredValue, ValueAdapter};
+use rstest::{fixture, rstest};
 use rusqlite::Connection;
-use serde_json::json;
+use serde_json::{Value, json};
 use tempfile::TempDir;
 
-fn store() -> (TempDir, DiskcacheSqliteStore) {
-    let directory = tempfile::tempdir().unwrap();
-    let store = DiskcacheSqliteStore::open(directory.path()).unwrap();
-    (directory, store)
+struct Sandbox {
+    directory: TempDir,
 }
 
-fn cache(directory: &Path) -> DiskCache<JsonCodec<serde_json::Value>> {
-    DiskCache::open(directory, JsonCodec::new()).unwrap()
+#[fixture]
+fn sandbox() -> Sandbox {
+    Sandbox {
+        directory: tempfile::tempdir().unwrap(),
+    }
 }
 
-fn value_files(directory: &Path) -> Vec<PathBuf> {
-    fn visit(directory: &Path, files: &mut Vec<PathBuf>) {
-        for entry in fs::read_dir(directory).unwrap() {
-            let path = entry.unwrap().path();
-            if path.is_dir() {
-                visit(&path, files);
-            } else if path.extension().is_some_and(|extension| extension == "val") {
-                files.push(path);
+impl Sandbox {
+    fn store(&self) -> DiskcacheSqliteStore {
+        DiskcacheSqliteStore::open(self.directory.path()).unwrap()
+    }
+
+    fn cache<V>(&self) -> DiskCache<JsonCodec<V>>
+    where
+        JsonCodec<V>: CacheCodec,
+    {
+        DiskCache::open(self.directory.path(), JsonCodec::new()).unwrap()
+    }
+
+    fn db(&self) -> Connection {
+        Connection::open(self.directory.path().join("cache.db")).unwrap()
+    }
+
+    fn value_files(&self) -> Vec<PathBuf> {
+        fn visit(directory: &Path, files: &mut Vec<PathBuf>) {
+            for entry in fs::read_dir(directory).unwrap() {
+                let path = entry.unwrap().path();
+                if path.is_dir() {
+                    visit(&path, files);
+                } else if path.extension().is_some_and(|extension| extension == "val") {
+                    files.push(path);
+                }
             }
         }
+
+        let mut files = Vec::new();
+        visit(self.directory.path(), &mut files);
+        files
+    }
+}
+
+#[derive(Clone, Copy, Debug, Default)]
+struct TextAdapter;
+
+impl ValueAdapter for TextAdapter {
+    fn read(&self, value: StoredValue) -> Result<Option<Vec<u8>>, litellm_cache::Error> {
+        match value {
+            StoredValue::Text(value) => Ok(Some(value.into_bytes())),
+            _ => Ok(None),
+        }
     }
 
-    let mut files = Vec::new();
-    visit(directory, &mut files);
-    files
+    fn write(&self, payload: Vec<u8>) -> StoredValue {
+        StoredValue::Text(String::from_utf8(payload).unwrap())
+    }
+
+    fn counter_seed(&self, _: Option<StoredValue>) -> Result<f64, litellm_cache::Error> {
+        Ok(0.0)
+    }
+
+    fn counter_value(&self, value: f64) -> StoredValue {
+        if value.fract() == 0.0 {
+            StoredValue::Integer(value as i64)
+        } else {
+            StoredValue::Float(value)
+        }
+    }
 }
 
-#[test]
-fn roundtrip_persists_and_reopens() {
-    let directory = tempfile::tempdir().unwrap();
+#[rstest]
+fn roundtrip_persists_and_reopens(sandbox: Sandbox) {
     let context = ExactCacheContext::default();
-    let opened = cache(directory.path());
+    let opened = sandbox.cache::<Value>();
     opened
         .set_cache("key", json!({"answer": 42}), &context)
         .unwrap();
@@ -55,16 +101,16 @@ fn roundtrip_persists_and_reopens() {
         Some(json!({"answer": 42}))
     );
     drop(opened);
-    let reopened = cache(directory.path());
+    let reopened = sandbox.cache::<Value>();
     assert_eq!(
         reopened.get_cache("key", &context).unwrap(),
         Some(json!({"answer": 42}))
     );
 }
 
-#[test]
-fn ttl_and_expired_culling_match_cache_contract() {
-    let (directory, store) = store();
+#[rstest]
+fn ttl_and_expired_culling_match_cache_contract(sandbox: Sandbox) {
+    let store = sandbox.store();
     store
         .set(
             "expired",
@@ -77,15 +123,16 @@ fn ttl_and_expired_culling_match_cache_contract() {
     store
         .set("new", StoredValue::Bytes(b"new".to_vec()), None, 11.0)
         .unwrap();
-    let connection = Connection::open(directory.path().join("cache.db")).unwrap();
     assert_eq!(
-        connection
+        sandbox
+            .db()
             .query_row("SELECT COUNT(*) FROM Cache", [], |row| row.get::<_, i64>(0))
             .unwrap(),
         1
     );
     assert_eq!(
-        connection
+        sandbox
+            .db()
             .query_row(
                 "SELECT value FROM Settings WHERE key = 'count'",
                 [],
@@ -96,9 +143,9 @@ fn ttl_and_expired_culling_match_cache_contract() {
     );
 }
 
-#[test]
-fn batch_preserves_order_and_classifies_misses_and_invalid_values() {
-    let (directory, store) = store();
+#[rstest]
+fn batch_preserves_order_and_classifies_misses_and_invalid_values(sandbox: Sandbox) {
+    let store = sandbox.store();
     store
         .set(
             "hit",
@@ -115,8 +162,8 @@ fn batch_preserves_order_and_classifies_misses_and_invalid_values() {
             0.0,
         )
         .unwrap();
-    let cache = cache(directory.path());
-    let entries = cache
+    let entries = sandbox
+        .cache::<Value>()
         .batch_get_cache(
             &["hit".into(), "missing".into(), "invalid".into()],
             &ExactCacheContext::default(),
@@ -132,117 +179,74 @@ fn batch_preserves_order_and_classifies_misses_and_invalid_values() {
     );
 }
 
-#[test]
-fn falsy_values_are_misses_and_protocol_five_pickle_decodes() {
-    let (directory, store) = store();
-    for (key, value) in [
-        ("empty-bytes", StoredValue::Bytes(Vec::new())),
-        ("empty-text", StoredValue::Text(String::new())),
-        ("zero-int", StoredValue::Integer(0)),
-        ("zero-float", StoredValue::Float(0.0)),
-        (
-            "empty-pickle",
-            StoredValue::Pickle(vec![0x80, 0x05, 0x7d, 0x94, 0x2e]),
-        ),
-    ] {
-        store.set(key, value, None, 0.0).unwrap();
-    }
-    store
-        .set(
-            "pickle",
-            StoredValue::Pickle(
-                b"\x80\x05\x95\x30\x00\x00\x00\x00\x00\x00\x00\x7d\x94\x28\x8c\x09timestamp\x94G\x3f\xf8\x00\x00\x00\x00\x00\x00\x8c\x08response\x94\x8c\x08{\"a\": 1}\x94u."
-                    .to_vec(),
-            ),
-            None,
-            0.0,
-        )
-        .unwrap();
-    let cache = cache(directory.path());
-    for key in [
-        "empty-bytes",
-        "empty-text",
-        "zero-int",
-        "zero-float",
-        "empty-pickle",
-    ] {
-        assert_eq!(
-            cache.get_cache(key, &ExactCacheContext::default()).unwrap(),
-            None
-        );
-    }
+#[rstest]
+#[case(StoredValue::Bytes(Vec::new()))]
+#[case(StoredValue::Text(String::new()))]
+#[case(StoredValue::Integer(0))]
+#[case(StoredValue::Float(0.0))]
+#[case(StoredValue::Pickle(vec![0x80, 0x05, 0x4e, 0x2e]))]
+#[case(StoredValue::Pickle(vec![0x80, 0x05, 0x89, 0x2e]))]
+#[case(StoredValue::Pickle(vec![0x80, 0x05, 0x4b, 0x00, 0x2e]))]
+#[case(StoredValue::Pickle(vec![0x80, 0x05, 0x95, 0x0a, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x47, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x2e]))]
+#[case(StoredValue::Pickle(vec![0x80, 0x05, 0x95, 0x04, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x8c, 0x00, 0x94, 0x2e]))]
+#[case(StoredValue::Pickle(vec![0x80, 0x05, 0x5d, 0x94, 0x2e]))]
+#[case(StoredValue::Pickle(vec![0x80, 0x05, 0x7d, 0x94, 0x2e]))]
+#[case(StoredValue::Pickle(vec![0x80, 0x05, 0x29, 0x2e]))]
+fn falsy_values_are_misses(sandbox: Sandbox, #[case] value: StoredValue) {
+    sandbox.store().set("key", value, None, 0.0).unwrap();
     assert_eq!(
-        cache
-            .get_cache("pickle", &ExactCacheContext::default())
+        sandbox
+            .cache::<Value>()
+            .get_cache("key", &ExactCacheContext::default())
             .unwrap(),
-        Some(json!({"timestamp": 1.5, "response": "{\"a\": 1}"}))
+        None
     );
 }
 
-#[test]
-fn counters_use_atomic_native_values_and_ignore_invalid_initial_values() {
-    let (directory, store) = store();
-    store
-        .set("counter", StoredValue::Integer(2), None, 0.0)
-        .unwrap();
-    store
-        .set(
-            "invalid",
-            StoredValue::Text("not a number".into()),
-            None,
-            0.0,
-        )
-        .unwrap();
-    store
-        .set(
-            "pickle-counter",
-            StoredValue::Pickle(vec![0x80, 0x05, 0x4b, 0x02, 0x2e]),
-            None,
-            0.0,
-        )
-        .unwrap();
-    let cache = DiskCache::open(directory.path(), JsonCodec::<f64>::new()).unwrap();
+#[rstest]
+#[case(Some(StoredValue::Integer(2)), 1.5, 3.5, "real")]
+#[case(Some(StoredValue::Integer(2)), 1.0, 3.0, "integer")]
+#[case(Some(StoredValue::Float(3.5)), 1.0, 1.0, "integer")]
+#[case(Some(StoredValue::Text("not a number".into())), 2.0, 2.0, "integer")]
+#[case(Some(StoredValue::Text("5".into())), 2.0, 7.0, "integer")]
+#[case(Some(StoredValue::Text("3.5".into())), 2.0, 2.0, "integer")]
+#[case(Some(StoredValue::Pickle(vec![0x80, 0x05, 0x88, 0x2e])), 1.0, 2.0, "integer")]
+#[case(Some(StoredValue::Pickle(vec![0x80, 0x05, 0x4b, 0x02, 0x2e])), 1.0, 3.0, "integer")]
+#[case(Some(StoredValue::Pickle(vec![0x80, 0x05, 0x95, 0x0a, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x7d, 0x94, 0x8c, 0x01, 0x61, 0x94, 0x4b, 0x01, 0x73, 0x2e])), 1.0, 1.0, "integer")]
+#[case(Some(StoredValue::Pickle(vec![0x80, 0x05, 0x4e, 0x2e])), 4.0, 4.0, "integer")]
+fn counters_follow_python_initialization(
+    sandbox: Sandbox,
+    #[case] initial: Option<StoredValue>,
+    #[case] amount: f64,
+    #[case] expected: f64,
+    #[case] sqlite_type: &str,
+) {
+    if let Some(initial) = initial {
+        sandbox.store().set("counter", initial, None, 0.0).unwrap();
+    }
+    let cache = sandbox.cache::<f64>();
     assert_eq!(
         cache
-            .increment_cache("counter", 1.5, ExactCacheContext::default())
+            .increment_cache("counter", amount, ExactCacheContext::default())
             .unwrap(),
-        3.5
+        expected
     );
     assert_eq!(
-        cache
-            .increment_cache("invalid", 2.0, ExactCacheContext::default())
-            .unwrap(),
-        2.0
-    );
-    assert_eq!(
-        cache
-            .increment_cache("pickle-counter", 1.0, ExactCacheContext::default())
-            .unwrap(),
-        3.0
-    );
-    let connection = Connection::open(directory.path().join("cache.db")).unwrap();
-    assert_eq!(
-        connection
+        sandbox
+            .db()
             .query_row(
                 "SELECT typeof(value) FROM Cache WHERE key = 'counter'",
                 [],
                 |row| row.get::<_, String>(0)
             )
             .unwrap(),
-        "real"
-    );
-    assert_eq!(
-        cache
-            .increment_cache("counter", 1.0, ExactCacheContext::default())
-            .unwrap(),
-        1.0
+        sqlite_type
     );
 }
 
-#[test]
-fn counters_are_atomic_across_concurrent_callers() {
-    let directory = tempfile::tempdir().unwrap();
-    let cache = Arc::new(DiskCache::open(directory.path(), JsonCodec::<f64>::new()).unwrap());
+#[rstest]
+fn counters_are_atomic_across_concurrent_callers(sandbox: Sandbox) {
+    let cache = Arc::new(sandbox.cache::<f64>());
     let workers = (0..8)
         .map(|_| {
             let cache = Arc::clone(&cache);
@@ -266,15 +270,88 @@ fn counters_are_atomic_across_concurrent_callers() {
     );
 }
 
-#[test]
-fn delete_flush_and_spilled_file_replacement_clean_up_storage() {
-    let (directory, store) = store();
+#[rstest]
+fn fractional_then_integer_increment_follows_python_behavior(sandbox: Sandbox) {
+    let cache = sandbox.cache::<f64>();
+    assert_eq!(
+        cache
+            .increment_cache("counter", 3.5, ExactCacheContext::default())
+            .unwrap(),
+        3.5
+    );
+    assert_eq!(
+        cache
+            .increment_cache("counter", 1.0, ExactCacheContext::default())
+            .unwrap(),
+        1.0
+    );
+}
+
+#[rstest]
+fn increment_ttl_replacement_clears_expiry_without_ttl(sandbox: Sandbox) {
+    let cache = sandbox.cache::<f64>();
+    cache
+        .increment_cache(
+            "counter",
+            1.0,
+            ExactCacheContext {
+                ttl: Some(Duration::from_secs(60)),
+            },
+        )
+        .unwrap();
+    assert!(
+        sandbox
+            .db()
+            .query_row(
+                "SELECT expire_time IS NOT NULL FROM Cache WHERE key = 'counter'",
+                [],
+                |row| row.get::<_, bool>(0)
+            )
+            .unwrap()
+    );
+    cache
+        .increment_cache("counter", 1.0, ExactCacheContext::default())
+        .unwrap();
+    assert!(
+        !sandbox
+            .db()
+            .query_row(
+                "SELECT expire_time IS NOT NULL FROM Cache WHERE key = 'counter'",
+                [],
+                |row| row.get::<_, bool>(0)
+            )
+            .unwrap()
+    );
+}
+
+#[rstest]
+fn custom_adapter_controls_storage_and_reads(sandbox: Sandbox) {
+    let cache = DiskCache::with_adapter(sandbox.store(), TextAdapter, JsonCodec::<Value>::new());
+    cache
+        .set_cache("key", json!({"answer": 42}), &ExactCacheContext::default())
+        .unwrap();
+    assert!(matches!(
+        sandbox.store().get("key", 0.0).unwrap(),
+        Some(StoredValue::Text(_))
+    ));
+    assert_eq!(
+        cache
+            .get_cache("key", &ExactCacheContext::default())
+            .unwrap(),
+        Some(json!({"answer": 42}))
+    );
+}
+
+#[rstest]
+fn delete_flush_and_spilled_file_replacement_clean_up_storage(sandbox: Sandbox) {
     let large = vec![b'x'; 32 * 1024];
-    store
+    sandbox
+        .store()
         .set("large", StoredValue::Bytes(large.clone()), None, 0.0)
         .unwrap();
-    assert_eq!(value_files(directory.path()).len(), 1);
-    store
+    assert_eq!(sandbox.value_files().len(), 1);
+    sandbox
+        .store()
         .set(
             "large",
             StoredValue::Bytes(vec![b'y'; 32 * 1024]),
@@ -282,23 +359,25 @@ fn delete_flush_and_spilled_file_replacement_clean_up_storage() {
             0.0,
         )
         .unwrap();
-    assert_eq!(value_files(directory.path()).len(), 1);
-    store.pop("large", 0.0).unwrap();
-    assert!(value_files(directory.path()).is_empty());
-    store
+    assert_eq!(sandbox.value_files().len(), 1);
+    sandbox.store().pop("large", 0.0).unwrap();
+    assert!(sandbox.value_files().is_empty());
+    sandbox
+        .store()
         .set("a", StoredValue::Bytes(large.clone()), None, 0.0)
         .unwrap();
-    store
+    sandbox
+        .store()
         .set("b", StoredValue::Bytes(large), None, 0.0)
         .unwrap();
-    store.clear().unwrap();
-    assert!(value_files(directory.path()).is_empty());
+    sandbox.store().clear().unwrap();
+    assert!(sandbox.value_files().is_empty());
 }
 
+#[rstest]
 #[tokio::test]
-async fn async_operations_connection_and_delete_match_sync_operations() {
-    let directory = tempfile::tempdir().unwrap();
-    let cache = cache(directory.path());
+async fn async_operations_connection_and_delete_match_sync_operations(sandbox: Sandbox) {
+    let cache = sandbox.cache::<Value>();
     let context = ExactCacheContext {
         ttl: Some(Duration::from_secs(60)),
     };
diff --git a/litellm-rust/crates/cache-disk/tests/python_compat.rs b/litellm-rust/crates/cache-disk/tests/python_compat.rs
new file mode 100644
index 00000000000..f9e12af6424
--- /dev/null
+++ b/litellm-rust/crates/cache-disk/tests/python_compat.rs
@@ -0,0 +1,105 @@
+use litellm_cache::Error;
+use litellm_cache_disk::{PythonDiskCacheAdapter, StoredValue, ValueAdapter};
+use rstest::rstest;
+
+enum ReadExpectation {
+    Bytes(&'static [u8]),
+    Miss,
+    Invalid,
+}
+
+#[rstest]
+#[case::pickled_dictionary_with_string_keys(
+    StoredValue::Pickle(vec![0x80, 0x05, 0x95, 0x0a, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x7d, 0x94, 0x8c, 0x01, 0x61, 0x94, 0x4b, 0x01, 0x73, 0x2e]),
+    ReadExpectation::Bytes(br#"{"a":1}"#)
+)]
+#[case::pickled_list_of_integers(
+    StoredValue::Pickle(vec![0x80, 0x05, 0x95, 0x09, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x5d, 0x94, 0x28, 0x4b, 0x01, 0x4b, 0x02, 0x65, 0x2e]),
+    ReadExpectation::Bytes(br#"[1,2]"#)
+)]
+#[case::pickled_tuple_of_integers(
+    StoredValue::Pickle(vec![0x80, 0x05, 0x95, 0x07, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x4b, 0x01, 0x4b, 0x02, 0x86, 0x94, 0x2e]),
+    ReadExpectation::Bytes(br#"[1,2]"#)
+)]
+#[case::pickled_set_of_integers(
+    StoredValue::Pickle(vec![0x80, 0x05, 0x95, 0x09, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x8f, 0x94, 0x28, 0x4b, 0x01, 0x4b, 0x02, 0x90, 0x2e]),
+    ReadExpectation::Bytes(br#"[1,2]"#)
+)]
+#[case::pickled_response_envelope(
+    StoredValue::Pickle(vec![0x80, 0x05, 0x95, 0x30, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x7d, 0x94, 0x28, 0x8c, 0x09, 0x74, 0x69, 0x6d, 0x65, 0x73, 0x74, 0x61, 0x6d, 0x70, 0x94, 0x47, 0x3f, 0xf8, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x8c, 0x08, 0x72, 0x65, 0x73, 0x70, 0x6f, 0x6e, 0x73, 0x65, 0x94, 0x8c, 0x08, 0x7b, 0x22, 0x61, 0x22, 0x3a, 0x20, 0x31, 0x7d, 0x94, 0x75, 0x2e]),
+    ReadExpectation::Bytes(br#"{"response":"{\"a\": 1}","timestamp":1.5}"#)
+)]
+#[case::non_json_text(
+    StoredValue::Text("not json".into()),
+    ReadExpectation::Bytes(b"not json")
+)]
+#[case::json_text(
+    StoredValue::Text("{\"a\": 1}".into()),
+    ReadExpectation::Bytes(br#"{"a": 1}"#)
+)]
+#[case::non_utf8_bytes(
+    StoredValue::Bytes(vec![0xff, 0xfe]),
+    ReadExpectation::Bytes(&[0xff, 0xfe])
+)]
+#[case::integer_seven(StoredValue::Integer(7), ReadExpectation::Bytes(b"7"))]
+#[case::float_one_point_five(StoredValue::Float(1.5), ReadExpectation::Bytes(b"1.5"))]
+#[case::pickled_bytes(
+    StoredValue::Pickle(vec![0x80, 0x05, 0x95, 0x09, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x43, 0x05, 0x62, 0x79, 0x74, 0x65, 0x73, 0x94, 0x2e]),
+    ReadExpectation::Invalid
+)]
+#[case::pickled_dictionary_with_integer_key(
+    StoredValue::Pickle(vec![0x80, 0x05, 0x95, 0x0a, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x7d, 0x94, 0x4b, 0x01, 0x8c, 0x01, 0x61, 0x94, 0x73, 0x2e]),
+    ReadExpectation::Invalid
+)]
+#[case::pickled_complex(
+    StoredValue::Pickle(vec![0x80, 0x05, 0x95, 0x2e, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x8c, 0x08, 0x62, 0x75, 0x69, 0x6c, 0x74, 0x69, 0x6e, 0x73, 0x94, 0x8c, 0x07, 0x63, 0x6f, 0x6d, 0x70, 0x6c, 0x65, 0x78, 0x94, 0x93, 0x94, 0x47, 0x3f, 0xf0, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x47, 0x40, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x86, 0x94, 0x52, 0x94, 0x2e]),
+    ReadExpectation::Invalid
+)]
+#[case::truncated_pickle(
+    StoredValue::Pickle(vec![0x80, 0x05, 0x2e]),
+    ReadExpectation::Invalid
+)]
+#[case::empty_bytes(StoredValue::Bytes(Vec::new()), ReadExpectation::Miss)]
+#[case::empty_text(StoredValue::Text(String::new()), ReadExpectation::Miss)]
+#[case::zero_integer(StoredValue::Integer(0), ReadExpectation::Miss)]
+#[case::zero_float(StoredValue::Float(0.0), ReadExpectation::Miss)]
+#[case::pickled_none(StoredValue::Pickle(vec![0x80, 0x05, 0x4e, 0x2e]), ReadExpectation::Miss)]
+#[case::pickled_false(StoredValue::Pickle(vec![0x80, 0x05, 0x89, 0x2e]), ReadExpectation::Miss)]
+#[case::pickled_zero(StoredValue::Pickle(vec![0x80, 0x05, 0x4b, 0x00, 0x2e]), ReadExpectation::Miss)]
+#[case::pickled_zero_float(StoredValue::Pickle(vec![0x80, 0x05, 0x95, 0x0a, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x47, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x2e]), ReadExpectation::Miss)]
+#[case::pickled_empty_string(StoredValue::Pickle(vec![0x80, 0x05, 0x95, 0x04, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x8c, 0x00, 0x94, 0x2e]), ReadExpectation::Miss)]
+#[case::pickled_empty_list(StoredValue::Pickle(vec![0x80, 0x05, 0x5d, 0x94, 0x2e]), ReadExpectation::Miss)]
+#[case::pickled_empty_dictionary(StoredValue::Pickle(vec![0x80, 0x05, 0x7d, 0x94, 0x2e]), ReadExpectation::Miss)]
+#[case::pickled_empty_tuple(StoredValue::Pickle(vec![0x80, 0x05, 0x29, 0x2e]), ReadExpectation::Miss)]
+fn python_read_cases(#[case] row: StoredValue, #[case] expected: ReadExpectation) {
+    let result = PythonDiskCacheAdapter.read(row);
+    match expected {
+        ReadExpectation::Bytes(expected) => assert_eq!(result.unwrap().unwrap(), expected),
+        ReadExpectation::Miss => assert_eq!(result.unwrap(), None),
+        ReadExpectation::Invalid => assert!(matches!(result, Err(Error::InvalidEntry))),
+    }
+}
+
+#[rstest]
+#[case::integer_two(Some(StoredValue::Integer(2)), 2.0)]
+#[case::float_three_point_five(Some(StoredValue::Float(3.5)), 0.0)]
+#[case::text_not_a_number(Some(StoredValue::Text("not a number".into())), 0.0)]
+#[case::text_five(Some(StoredValue::Text("5".into())), 5.0)]
+#[case::text_three_point_five(Some(StoredValue::Text("3.5".into())), 0.0)]
+#[case::pickled_true(Some(StoredValue::Pickle(vec![0x80, 0x05, 0x88, 0x2e])), 1.0)]
+#[case::pickled_two(Some(StoredValue::Pickle(vec![0x80, 0x05, 0x4b, 0x02, 0x2e])), 2.0)]
+#[case::pickled_dictionary(Some(StoredValue::Pickle(vec![0x80, 0x05, 0x95, 0x0a, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x7d, 0x94, 0x8c, 0x01, 0x61, 0x94, 0x4b, 0x01, 0x73, 0x2e])), 0.0)]
+#[case::missing(None, 0.0)]
+#[case::pickled_none(Some(StoredValue::Pickle(vec![0x80, 0x05, 0x4e, 0x2e])), 0.0)]
+fn python_counter_seed_cases(#[case] row: Option<StoredValue>, #[case] expected: f64) {
+    assert_eq!(PythonDiskCacheAdapter.counter_seed(row).unwrap(), expected);
+}
+
+#[rstest]
+#[case::integer_three(3.0, StoredValue::Integer(3))]
+#[case::fractional_three_point_five(3.5, StoredValue::Float(3.5))]
+#[case::negative_zero(-0.0, StoredValue::Integer(0))]
+#[case::large_float(1e300, StoredValue::Float(1e300))]
+fn python_counter_value_cases(#[case] value: f64, #[case] expected: StoredValue) {
+    assert_eq!(PythonDiskCacheAdapter.counter_value(value), expected);
+}

From 59675bc0c948d124affe549f5ffc277bd8a31585 Mon Sep 17 00:00:00 2001
From: Yujong Lee <yujong@berri.ai>
Date: Mon, 21 Sep 2026 21:22:26 +0000
Subject: [PATCH 39/55] Revert "ci(rust): raise native wheel size gate to 35
 MB"

This reverts commit c1382086d69f176114003a5fcf32ac2a8cbaaa64.
---
 .github/scripts/verify_linux_native_wheel.py | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/.github/scripts/verify_linux_native_wheel.py b/.github/scripts/verify_linux_native_wheel.py
index d86ad7b15c6..4fb8f068eb0 100644
--- a/.github/scripts/verify_linux_native_wheel.py
+++ b/.github/scripts/verify_linux_native_wheel.py
@@ -205,7 +205,7 @@ def main(
     native_module: Final = load_native_module(native_path)
     native_module_loads: Final = native_module is not None
     panic_test_hook_absent: Final = native_module is not None and not hasattr(native_module, "_panic_for_test")
-    native_size_limit: Final = 35_000_000
+    native_size_limit: Final = 25_000_000
     native_size_within_limit: Final = native_member.file_size <= native_size_limit
     validations: Final = (
         (f"Python tag is {EXPECTED_PYTHON_TAG}", python_tag == EXPECTED_PYTHON_TAG),
@@ -222,7 +222,7 @@ def main(
         ("Python extension entry point is present", extension_entry_point_present),
         ("Native module loads", native_module_loads),
         ("Production module omits the panic test hook", panic_test_hook_absent),
-        ("Native extension does not exceed 35 MB", native_size_within_limit),
+        ("Native extension does not exceed 25 MB", native_size_within_limit),
         ("Wheel contents are valid", not unexpected_members),
     )
 
@@ -267,7 +267,7 @@ def main(
             ),
             (
                 not native_size_within_limit,
-                f"native extension exceeds 35 MB: {native_member.file_size / 1_000_000:.2f} MB",
+                f"native extension exceeds 20 MB: {native_member.file_size / 1_000_000:.2f} MB",
             ),
             (bool(unexpected_members), f"wheel contains unexpected build artifacts: {', '.join(unexpected_members)}"),
         )

From 4a8826e03b08311901cd8cb8186b9c1192206811 Mon Sep 17 00:00:00 2001
From: Yujong Lee <yujong@berri.ai>
Date: Mon, 21 Sep 2026 21:23:56 +0000
Subject: [PATCH 40/55] refactor(cache-disk): tidy python adapter

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
 litellm-rust/crates/cache-disk/src/cache.rs   |  6 ++---
 .../crates/cache-disk/src/python/mod.rs       | 24 ++++++++-----------
 .../crates/cache-disk/tests/python_compat.rs  |  8 +++++++
 3 files changed, 20 insertions(+), 18 deletions(-)

diff --git a/litellm-rust/crates/cache-disk/src/cache.rs b/litellm-rust/crates/cache-disk/src/cache.rs
index 98182d93968..adff078a89b 100644
--- a/litellm-rust/crates/cache-disk/src/cache.rs
+++ b/litellm-rust/crates/cache-disk/src/cache.rs
@@ -18,22 +18,20 @@ pub struct DiskCache<S, D = DiskcacheSqliteStore, A = PythonDiskCacheAdapter> {
 }
 
 impl<S: CacheCodec> DiskCache<S> {
-    #[allow(clippy::default_constructed_unit_structs)]
     pub fn open(directory: impl AsRef<Path>, codec: S) -> Result<Self, Error> {
         Ok(Self {
             store: Arc::new(DiskcacheSqliteStore::open(directory)?),
-            adapter: Arc::new(PythonDiskCacheAdapter::default()),
+            adapter: Arc::new(PythonDiskCacheAdapter),
             codec,
         })
     }
 }
 
 impl<S: CacheCodec, D: DiskStore> DiskCache<S, D, PythonDiskCacheAdapter> {
-    #[allow(clippy::default_constructed_unit_structs)]
     pub fn with_store(store: D, codec: S) -> Self {
         Self {
             store: Arc::new(store),
-            adapter: Arc::new(PythonDiskCacheAdapter::default()),
+            adapter: Arc::new(PythonDiskCacheAdapter),
             codec,
         }
     }
diff --git a/litellm-rust/crates/cache-disk/src/python/mod.rs b/litellm-rust/crates/cache-disk/src/python/mod.rs
index 5c9b57de000..7a370db357c 100644
--- a/litellm-rust/crates/cache-disk/src/python/mod.rs
+++ b/litellm-rust/crates/cache-disk/src/python/mod.rs
@@ -13,9 +13,7 @@ impl PythonDiskCacheAdapter {
         let value = match value {
             StoredValue::Bytes(value) => Value::Bytes(value),
             StoredValue::Text(value) => Value::String(value),
-            StoredValue::Integer(value) => {
-                value::from_json(serde_json::Value::Number(value.into()))
-            }
+            StoredValue::Integer(value) => Value::Integer(value.into()),
             StoredValue::Float(value) => Value::Float(value),
             StoredValue::Pickle(value) => value::from_pickle(&value)?,
         };
@@ -39,18 +37,16 @@ impl PythonDiskCacheAdapter {
 
 impl ValueAdapter for PythonDiskCacheAdapter {
     fn read(&self, value: StoredValue) -> Result<Option<Vec<u8>>, Error> {
-        let raw = match &value {
-            StoredValue::Text(value) => Some(value.as_bytes().to_vec()),
-            StoredValue::Bytes(value) => Some(value.clone()),
-            StoredValue::Integer(_) | StoredValue::Float(_) | StoredValue::Pickle(_) => None,
-        };
-        let Some(value) = Self::python_get_cache(value)? else {
-            return Ok(None);
-        };
-        if let Some(raw) = raw {
-            return Ok(Some(raw));
+        match value {
+            StoredValue::Text(value) => Ok((!value.is_empty()).then(|| value.into_bytes())),
+            StoredValue::Bytes(value) => Ok((!value.is_empty()).then_some(value)),
+            value => {
+                let Some(value) = Self::python_get_cache(value)? else {
+                    return Ok(None);
+                };
+                value::to_json(&value).map(Some)
+            }
         }
-        value::to_json(&value).map(Some)
     }
 
     fn write(&self, payload: Vec<u8>) -> StoredValue {
diff --git a/litellm-rust/crates/cache-disk/tests/python_compat.rs b/litellm-rust/crates/cache-disk/tests/python_compat.rs
index f9e12af6424..9cbef8573bd 100644
--- a/litellm-rust/crates/cache-disk/tests/python_compat.rs
+++ b/litellm-rust/crates/cache-disk/tests/python_compat.rs
@@ -43,6 +43,14 @@ enum ReadExpectation {
 )]
 #[case::integer_seven(StoredValue::Integer(7), ReadExpectation::Bytes(b"7"))]
 #[case::float_one_point_five(StoredValue::Float(1.5), ReadExpectation::Bytes(b"1.5"))]
+#[case::pickled_true(
+    StoredValue::Pickle(vec![0x80, 0x05, 0x88, 0x2e]),
+    ReadExpectation::Bytes(b"true")
+)]
+#[case::pickled_negative_integer(
+    StoredValue::Pickle(vec![0x80, 0x05, 0x95, 0x06, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x4a, 0xfd, 0xff, 0xff, 0xff, 0x2e]),
+    ReadExpectation::Bytes(b"-3")
+)]
 #[case::pickled_bytes(
     StoredValue::Pickle(vec![0x80, 0x05, 0x95, 0x09, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x43, 0x05, 0x62, 0x79, 0x74, 0x65, 0x73, 0x94, 0x2e]),
     ReadExpectation::Invalid

From d1b160310f680f6c19e63dd8cd492847c66ce684 Mon Sep 17 00:00:00 2001
From: Yuneng Jiang <yuneng@berri.ai>
Date: Mon, 21 Sep 2026 14:27:29 -0700
Subject: [PATCH 41/55] fix(docker): require a generated master key in the
 quickstart stack

The committed sk-1234 placeholder is in PUBLICLY_KNOWN_MASTER_KEYS, so once an
image ships fe480533e8 the proxy refuses to boot and the quickstart stops
working. It also meant the documented stack came up on port 4000 with a
credential anyone could guess.

Both keys now come from .env and compose refuses to render without them. The
salt key is generated alongside so it stays stable across restarts, which
keeps stored credentials readable.

Verified: no .env -> compose fails closed naming the missing variable; with a
generated .env the stack is healthy, /v1/models returns 200 for the generated
key, 401 for sk-1234 and 401 unauthenticated, /ui/ serves, and the key still
works after a restart.
---
 docker/README.md                     |  1 +
 docker/docker-compose.quickstart.yml | 11 ++++++-----
 2 files changed, 7 insertions(+), 5 deletions(-)

diff --git a/docker/README.md b/docker/README.md
index 787866ce35a..376dc7b2d97 100644
--- a/docker/README.md
+++ b/docker/README.md
@@ -9,6 +9,7 @@ This guide provides instructions for building and running the LiteLLM applicatio
 >
 > ```bash
 > curl -sSLO https://github.com/BerriAI/litellm/raw/main/docker/docker-compose.quickstart.yml
+> printf 'LITELLM_MASTER_KEY=sk-%s\nLITELLM_SALT_KEY=sk-%s\n' "$(openssl rand -hex 32)" "$(openssl rand -hex 32)" > .env
 > docker compose -f docker-compose.quickstart.yml up -d
 > ```
 
diff --git a/docker/docker-compose.quickstart.yml b/docker/docker-compose.quickstart.yml
index 7c849c759f0..11631603a72 100644
--- a/docker/docker-compose.quickstart.yml
+++ b/docker/docker-compose.quickstart.yml
@@ -3,19 +3,20 @@
 # https://docs.litellm.ai/docs/proxy/docker_quick_start
 #
 #   curl -sSLO https://github.com/BerriAI/litellm/raw/main/docker/docker-compose.quickstart.yml
+#   printf 'LITELLM_MASTER_KEY=sk-%s\nLITELLM_SALT_KEY=sk-%s\n' "$(openssl rand -hex 32)" "$(openssl rand -hex 32)" > .env
 #   docker compose -f docker-compose.quickstart.yml up -d
 #
-# The credentials below are placeholders for local evaluation. Before any real
-# use, set LITELLM_MASTER_KEY and LITELLM_SALT_KEY to long random values and
-# pin the image to a specific release tag.
+# Compose reads .env from this directory. Keep it: regenerating LITELLM_SALT_KEY
+# makes credentials already stored in the database unreadable. For anything
+# beyond local evaluation, pin the image to a specific release tag.
 services:
   litellm:
     image: docker.litellm.ai/berriai/litellm:main-stable
     ports:
       - "4000:4000"
     environment:
-      LITELLM_MASTER_KEY: sk-1234
-      LITELLM_SALT_KEY: sk-XXXXXXXXXXXXXXXX
+      LITELLM_MASTER_KEY: ${LITELLM_MASTER_KEY:?set it in .env - see the header of this file}
+      LITELLM_SALT_KEY: ${LITELLM_SALT_KEY:?set it in .env - see the header of this file}
       DATABASE_URL: postgresql://litellm:litellm@db:5432/litellm
       STORE_MODEL_IN_DB: "True"
     depends_on:

From 51eaad657baf790379ed7d047d45c08364f2de40 Mon Sep 17 00:00:00 2001
From: mateo-berri <277851410+mateo-berri@users.noreply.github.com>
Date: Mon, 21 Sep 2026 14:42:23 -0700
Subject: [PATCH 42/55] fix(proxy): look the entity spend table up lazily so
 only the selected batcher table is touched

---
 litellm/proxy/db/db_spend_update_writer.py | 20 +++++++++++---------
 1 file changed, 11 insertions(+), 9 deletions(-)

diff --git a/litellm/proxy/db/db_spend_update_writer.py b/litellm/proxy/db/db_spend_update_writer.py
index 5381071172f..d9c8b271646 100644
--- a/litellm/proxy/db/db_spend_update_writer.py
+++ b/litellm/proxy/db/db_spend_update_writer.py
@@ -141,16 +141,18 @@ _EntitySpendTable: TypeAlias = Literal[
 ]
 
 
+_ENTITY_SPEND_TABLES: Final[Mapping[_EntitySpendTable, Callable[[_SpendBatch], BatchTable]]] = MappingProxyType(
+    {
+        "litellm_tagtable": lambda batcher: batcher.litellm_tagtable,
+        "litellm_agentstable": lambda batcher: batcher.litellm_agentstable,
+        "litellm_modelaccessgroupbudgettable": lambda batcher: batcher.litellm_modelaccessgroupbudgettable,
+        "litellm_projecttable": lambda batcher: batcher.litellm_projecttable,
+    }
+)
+
+
 def _entity_spend_table(batcher: _SpendBatch, table_accessor: _EntitySpendTable) -> BatchTable:
-    tables: Final[Mapping[_EntitySpendTable, BatchTable]] = MappingProxyType(
-        {
-            "litellm_tagtable": batcher.litellm_tagtable,
-            "litellm_agentstable": batcher.litellm_agentstable,
-            "litellm_modelaccessgroupbudgettable": batcher.litellm_modelaccessgroupbudgettable,
-            "litellm_projecttable": batcher.litellm_projecttable,
-        }
-    )
-    return tables[table_accessor]
+    return _ENTITY_SPEND_TABLES[table_accessor](batcher)
 
 
 class _SpendBatchManager(Protocol):

From f43f9012f1a0d58402aaec5393937225c1636869 Mon Sep 17 00:00:00 2001
From: Yujong Lee <yujong@berri.ai>
Date: Mon, 21 Sep 2026 21:44:24 +0000
Subject: [PATCH 43/55] fix(rust): handle disk cache topology

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
 litellm-rust/crates/python-bridge/src/cache/native.rs | 1 +
 1 file changed, 1 insertion(+)

diff --git a/litellm-rust/crates/python-bridge/src/cache/native.rs b/litellm-rust/crates/python-bridge/src/cache/native.rs
index e764fde8b39..50e02338574 100644
--- a/litellm-rust/crates/python-bridge/src/cache/native.rs
+++ b/litellm-rust/crates/python-bridge/src/cache/native.rs
@@ -83,6 +83,7 @@ impl NativeResponseCache {
         match self {
             Self::Memory(_) => None,
             Self::Redis { cache, .. } => Some(cache.backend().topology()),
+            Self::Disk(_) => None,
         }
     }
 

From 4845beddc067cd852c79a45e676c7128cd3bc23d Mon Sep 17 00:00:00 2001
From: Yujong Lee <yujong@berri.ai>
Date: Mon, 21 Sep 2026 21:44:26 +0000
Subject: [PATCH 44/55] ci(rust): raise native wheel size gate to 40 MB

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
 .github/scripts/verify_linux_native_wheel.py | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/.github/scripts/verify_linux_native_wheel.py b/.github/scripts/verify_linux_native_wheel.py
index 0adbc015ad0..7723c022351 100644
--- a/.github/scripts/verify_linux_native_wheel.py
+++ b/.github/scripts/verify_linux_native_wheel.py
@@ -205,7 +205,7 @@ def main(
     native_module: Final = load_native_module(native_path)
     native_module_loads: Final = native_module is not None
     panic_test_hook_absent: Final = native_module is not None and not hasattr(native_module, "_panic_for_test")
-    native_size_limit: Final = 30_000_000
+    native_size_limit: Final = 40_000_000
     native_size_within_limit: Final = native_member.file_size <= native_size_limit
     validations: Final = (
         (f"Python tag is {EXPECTED_PYTHON_TAG}", python_tag == EXPECTED_PYTHON_TAG),
@@ -222,7 +222,7 @@ def main(
         ("Python extension entry point is present", extension_entry_point_present),
         ("Native module loads", native_module_loads),
         ("Production module omits the panic test hook", panic_test_hook_absent),
-        ("Native extension does not exceed 30 MB", native_size_within_limit),
+        ("Native extension does not exceed 40 MB", native_size_within_limit),
         ("Wheel contents are valid", not unexpected_members),
     )
 
@@ -267,7 +267,7 @@ def main(
             ),
             (
                 not native_size_within_limit,
-                f"native extension exceeds 30 MB: {native_member.file_size / 1_000_000:.2f} MB",
+                f"native extension exceeds 40 MB: {native_member.file_size / 1_000_000:.2f} MB",
             ),
             (bool(unexpected_members), f"wheel contains unexpected build artifacts: {', '.join(unexpected_members)}"),
         )

From b0305d0a31a4eb4dd1ff6204ef2e1e5f84db07c4 Mon Sep 17 00:00:00 2001
From: mateo-berri <277851410+mateo-berri@users.noreply.github.com>
Date: Mon, 21 Sep 2026 14:48:42 -0700
Subject: [PATCH 45/55] test(router): call both mid-stream fallback attempt
 functions directly

The router coverage gate wants every router.py function reached by name from
a router test. The two per-endpoint attempt functions were only reached through
their callers, so each now has a direct test proving the per-request controls
carrier never reaches the provider call and every hop's stream comes back wrapped.
---
 ...st_router_aresponses_streaming_fallback.py | 38 ++++++++++++++++
 tests/test_litellm/test_router.py             | 44 +++++++++++++++++++
 2 files changed, 82 insertions(+)

diff --git a/tests/router_unit_tests/test_router_aresponses_streaming_fallback.py b/tests/router_unit_tests/test_router_aresponses_streaming_fallback.py
index 18b10e9c8e5..5370089eef5 100644
--- a/tests/router_unit_tests/test_router_aresponses_streaming_fallback.py
+++ b/tests/router_unit_tests/test_router_aresponses_streaming_fallback.py
@@ -423,6 +423,44 @@ async def test_aresponses_per_request_fallbacks_survive_into_hop_streams():
     assert collected == [completed_event]
 
 
+@pytest.mark.asyncio
+async def test_aresponses_attempt_strips_the_controls_carrier_and_wraps_every_hop_stream():
+    """Each attempt of the chain, not only the primary's, comes back wrapped for mid-stream
+    failover, and the per-request controls carrier rides into the wrapper's re-entry kwargs
+    without ever reaching the provider call."""
+    from types import MappingProxyType
+
+    from litellm.router_utils.fallback_event_handlers import (
+        MID_STREAM_FALLBACK_CONTROLS_KEY,
+        MidStreamFallbackControls,
+    )
+
+    router = _make_three_tier_router()
+    completed_event = _make_completed_event(1, 1, 2)
+    hop_stream = _scripted_responses_stream([completed_event])
+    seen: dict = {}
+
+    async def fake_original(**kwargs):
+        seen.update(kwargs)
+        return hop_stream
+
+    controls = MidStreamFallbackControls(MappingProxyType({"fallbacks": [{"primary": ["fb1", "fb2"]}]}))
+    stream = await router._ageneric_api_call_with_fallbacks_responses_attempt(
+        model="fb1",
+        original_generic_function=fake_original,
+        stream=True,
+        input="hi",
+        **{MID_STREAM_FALLBACK_CONTROLS_KEY: controls},
+    )
+    collected = [event async for event in stream]
+
+    assert seen["model"] == "openai/fb1-model"
+    assert MID_STREAM_FALLBACK_CONTROLS_KEY not in seen
+    assert "fallbacks" not in seen
+    assert stream is not hop_stream
+    assert collected == [completed_event]
+
+
 @pytest.mark.asyncio
 async def test_aresponses_fallback_on_in_stream_error_event():
     """A retriable in-stream error event (429) must trigger the router's mid-stream
diff --git a/tests/test_litellm/test_router.py b/tests/test_litellm/test_router.py
index 1ff04a1722f..9d2e37b4fb5 100644
--- a/tests/test_litellm/test_router.py
+++ b/tests/test_litellm/test_router.py
@@ -14222,6 +14222,50 @@ async def test_anthropic_messages_hop_stream_failure_reaches_second_fallback_ent
     assert b"overloaded_error" not in body
 
 
+@pytest.mark.asyncio
+async def test_anthropic_messages_attempt_strips_the_controls_carrier_and_wraps_every_hop_stream():
+    """Each attempt of the chain, not only the primary's, comes back wrapped for mid-stream
+    failover, and the per-request controls carrier never reaches the provider call."""
+    from types import MappingProxyType
+
+    from litellm.router_utils.fallback_event_handlers import (
+        MID_STREAM_FALLBACK_CONTROLS_KEY,
+        MidStreamFallbackControls,
+    )
+
+    router = Router(
+        model_list=[
+            {"model_name": "fb1", "litellm_params": {"model": "anthropic/fb1-model", "api_key": "sk-test"}},
+        ],
+        num_retries=0,
+    )
+    hop_stream = _AnthropicMessagesFakeByteStream(
+        [_anthropic_messages_message_start_chunk(), _anthropic_messages_content_chunk("from fb1")]
+    )
+    seen: dict = {}
+
+    async def fake_original(**kwargs):
+        seen.update(kwargs)
+        return hop_stream
+
+    controls = MidStreamFallbackControls(MappingProxyType({"fallbacks": [{"primary": ["fb1", "fb2"]}]}))
+    stream = await router._ageneric_api_call_with_fallbacks_anthropic_messages_attempt(
+        model="fb1",
+        original_generic_function=fake_original,
+        stream=True,
+        messages=[{"role": "user", "content": "hi"}],
+        max_tokens=10,
+        **{MID_STREAM_FALLBACK_CONTROLS_KEY: controls},
+    )
+    body = b"".join([chunk async for chunk in stream])
+
+    assert seen["model"] == "anthropic/fb1-model"
+    assert MID_STREAM_FALLBACK_CONTROLS_KEY not in seen
+    assert "fallbacks" not in seen
+    assert stream is not hop_stream
+    assert b"from fb1" in body
+
+
 @pytest.mark.asyncio
 async def test_anthropic_messages_fallback_triggers_after_lifecycle_only_frame():
     """Regression: Anthropic routinely sends a message_start lifecycle frame

From e7557ada57ad649fc0b0063aa2d89e1f7186f979 Mon Sep 17 00:00:00 2001
From: mateo-berri <277851410+mateo-berri@users.noreply.github.com>
Date: Mon, 21 Sep 2026 14:56:02 -0700
Subject: [PATCH 46/55] fix(responses): list executed MCP calls as completed
 mcp_call items in the final output

---
 .../responses/mcp/mcp_streaming_iterator.py   | 23 ++++++++-
 .../mcp/test_mcp_streaming_iterator.py        | 48 +++++++++++++++----
 2 files changed, 60 insertions(+), 11 deletions(-)

diff --git a/litellm/responses/mcp/mcp_streaming_iterator.py b/litellm/responses/mcp/mcp_streaming_iterator.py
index fb05e7bff99..101000b14a9 100644
--- a/litellm/responses/mcp/mcp_streaming_iterator.py
+++ b/litellm/responses/mcp/mcp_streaming_iterator.py
@@ -39,6 +39,19 @@ def _output_items(response: ResponsesAPIResponse) -> Sequence[object]:
     return tuple(cast("Sequence[object]", response.output))  # cast-ok: items are only carried, never inspected
 
 
+def _function_call_id(item: object) -> str | None:
+    """The call id of a function_call item, None for every other item kind."""
+    item_type: Final[object] = item.get("type") if isinstance(item, dict) else getattr(item, "type", None)
+    if item_type != "function_call":
+        return None
+    call_id: Final[object] = (
+        item.get("call_id") or item.get("id")
+        if isinstance(item, dict)
+        else getattr(item, "call_id", None) or getattr(item, "id", None)
+    )
+    return call_id if isinstance(call_id, str) else None
+
+
 def _set_event_field(event: ResponsesAPIStreamingResponse, name: str, value: object) -> None:
     """Events are pydantic models with extra fields allowed, so any event type can carry the field."""
     setattr(event, name, value)
@@ -588,9 +601,14 @@ class MCPEnhancedStreamingIterator(BaseResponsesAPIStreamingIterator):
         return max(len(_output_items(response)), self._round_max_output_index + 1)
 
     def _absorb_round(self, response: ResponsesAPIResponse) -> None:
-        """Bank a finished round's items so the final response.completed can list them."""
+        """Bank a finished round's items, each function_call the gateway answered replaced by its mcp_call."""
         width: Final = self._round_output_width(response)
-        self._composed_output.extend(_output_items(response))
+        answered_call_ids: Final = frozenset(
+            call_id for result in self.tool_results if (call_id := result.get("tool_call_id")) is not None
+        )
+        self._composed_output.extend(
+            item for item in _output_items(response) if _function_call_id(item) not in answered_call_ids
+        )
         self._composed_output.extend(self._pending_mcp_call_items)
         self._output_index_offset += width + len(self._pending_mcp_call_items)
         self._pending_mcp_call_items.clear()
@@ -842,6 +860,7 @@ class MCPEnhancedStreamingIterator(BaseResponsesAPIStreamingIterator):
                     **{  # mutable-ok: consumed once by the model constructor
                         "id": item_id,
                         "type": "mcp_call",
+                        "status": "completed",
                         "approval_request_id": f"mcpr_{uuid.uuid4().hex[:8]}",
                         "arguments": tool_arguments,
                         "error": None,
diff --git a/tests/test_litellm/responses/mcp/test_mcp_streaming_iterator.py b/tests/test_litellm/responses/mcp/test_mcp_streaming_iterator.py
index 1587557f3d2..1e869745dc3 100644
--- a/tests/test_litellm/responses/mcp/test_mcp_streaming_iterator.py
+++ b/tests/test_litellm/responses/mcp/test_mcp_streaming_iterator.py
@@ -143,17 +143,12 @@ async def test_second_round_tool_call_is_executed_and_reaches_final_text(monkeyp
 
     # The stream reached round 3 and produced the final text response instead
     # of stopping after round 1 or round 2. The client sees one lifecycle whose
-    # final output lists every round's items in order.
+    # final output lists every round's items in order, each executed call as
+    # the gateway's mcp_call rather than the function_call the model emitted.
     completed_chunks = [c for c in chunks if getattr(c, "type", None) == ResponsesAPIStreamEvents.RESPONSE_COMPLETED]
     assert len(completed_chunks) == 1
     final_output = completed_chunks[-1].response.output
-    assert [_item_type(item) for item in final_output] == [
-        "function_call",
-        "mcp_call",
-        "function_call",
-        "mcp_call",
-        "message",
-    ]
+    assert [_item_type(item) for item in final_output] == ["mcp_call", "mcp_call", "message"]
     assert final_output[-1]["content"][0]["text"] == "Here's what I found after retrying."
 
 
@@ -422,7 +417,7 @@ async def test_auto_execute_rounds_share_one_public_lifecycle(monkeypatch):
     # The single completed event lists every round's items and keeps the final round's id for continuation.
     completed = chunks[-1]
     assert completed.response.id == "resp-final"
-    assert [_item_type(item) for item in completed.response.output] == ["function_call", "mcp_call", "message"]
+    assert [_item_type(item) for item in completed.response.output] == ["mcp_call", "message"]
     assert completed.response.output[-1]["content"][0]["text"] == "Alpha."
     # The proxy serializes every chunk; the merged output must still be a valid response.
     assert '"type":"mcp_call"' in completed.response.model_dump_json(exclude_none=True, exclude_unset=True)
@@ -433,6 +428,41 @@ async def test_auto_execute_rounds_share_one_public_lifecycle(monkeypatch):
     assert len(set(sequence_numbers)) == len(sequence_numbers)
 
 
+@pytest.mark.asyncio
+async def test_final_output_lists_executed_call_as_completed_mcp_call(monkeypatch):
+    """
+    A function_call the gateway executed must not reach the final output: an
+    agent framework reading it (the OpenAI Agents SDK) tries to run a tool the
+    caller never declared and aborts the run. The final output lists the
+    gateway's completed mcp_call in its place, next to the round's other items.
+    """
+    _mock_mcp_environment(monkeypatch)
+
+    follow_up = _FakeAsyncStream(_lifecycle_round("resp-final", _text_message("Alpha.")))
+    monkeypatch.setattr(responses_main_module, "aresponses", AsyncMock(side_effect=[follow_up]))
+
+    reasoning = {"type": "reasoning", "id": "rs_1", "summary": []}
+    iterator = _make_iterator(
+        [
+            _created_chunk("resp-interim"),
+            _completed_chunk([reasoning, _function_call("call_1", "read_wiki_contents")], response_id="resp-interim"),
+        ]
+    )
+    chunks = [chunk async for chunk in iterator]
+
+    final_output = chunks[-1].response.output
+    assert [_item_type(item) for item in final_output] == ["reasoning", "mcp_call", "message"]
+    executed_call = final_output[1]
+    assert executed_call["status"] == "completed"
+    assert executed_call["name"] == "read_wiki_contents"
+    assert executed_call["arguments"] == "{}"
+
+    done_mcp_items = [
+        c.item for c in chunks if c.type == ResponsesAPIStreamEvents.OUTPUT_ITEM_DONE and _item_type(c.item) == "mcp_call"
+    ]
+    assert [item.status for item in done_mcp_items] == ["completed"]
+
+
 @pytest.mark.asyncio
 async def test_stream_without_auto_execute_is_forwarded_unchanged(monkeypatch):
     """With approval required there is one round, and it passes through untouched."""

From 5c6854510400ca53a8718401adf0ca911f65e62a Mon Sep 17 00:00:00 2001
From: Yuneng Jiang <yuneng@berri.ai>
Date: Mon, 21 Sep 2026 15:00:54 -0700
Subject: [PATCH 47/55] test: fix stale budget-status and bad-database-url
 assertions
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Two CI checks were asserting behaviour the proxy no longer has. Neither
was catching anything; both now fail for the right reason.

budget_exceeded (tests/otel_tests/test_e2e_budgeting.py)

bf804f5188 made 422 the default for budget refusals and added
budget_exceeded_status_code to restore 429 for callers that need it. The
e2e budget tests still asserted 429, so all six have been failing on a
status change that was deliberate. Assert 422, the documented default,
rather than reading litellm.budget_exceeded_status_code back — a test
that asks the code what it does would have passed straight through this
change and through the next one.

The helpers also caught bare Exception, so a connection error reached
`e.body` and surfaced as an AttributeError instead of a failed
assertion. Narrow both to openai.APIStatusError, which is what a refusal
actually raises (UnprocessableEntityError for 422, RateLimitError for
429), and let anything else propagate as itself.

test_bad_database_url (.circleci/config.yml)

The check required "Database setup failed after multiple retries", which
only the v1 resolver emits, OR uvicorn's "Application startup failed.
Exiting.". With v2 the default, the first branch is dead and the whole
assertion rests on an incidental uvicorn line that HEAD's run did not
emit at all.

Assert the behaviour instead of the wording: the container exits
non-zero, the log names the unreachable server (P1001), it never reaches
"Application startup complete", and it is not left running. The exit
code was previously discarded by `|| true`, so the one thing the job
most needed to check was never checked.

Verified by running the bad-DATABASE_URL container: exit 3, P1001
present, no startup-complete line, container stopped — the new check
passes and the old one passed only by the uvicorn line's accident.
---
 .circleci/config.yml                   | 23 ++++++++++++-----------
 tests/otel_tests/test_e2e_budgeting.py | 13 +++++++------
 2 files changed, 19 insertions(+), 17 deletions(-)

diff --git a/.circleci/config.yml b/.circleci/config.yml
index cc9aa7fe1c4..c69ed6a3510 100644
--- a/.circleci/config.yml
+++ b/.circleci/config.yml
@@ -3033,28 +3033,29 @@ jobs:
       - run:
           name: Run Docker container with bad DATABASE_URL
           command: |
+            set +e
             docker run --name my-app \
               -p 4000:4000 \
               -e LITELLM_DANGEROUSLY_PERMIT_WEAK_OR_UNSET_MASTER_KEY=true \
               -e DEFAULT_NUM_WORKERS_LITELLM_PROXY=1 \
               -e DATABASE_URL="postgresql://wrong:wrong@wrong:5432/wrong" \
               myapp:latest \
-              --port 4000 > docker_output.log 2>&1 || true
+              --port 4000 > docker_output.log 2>&1
+            echo "$?" > docker_exit_code
+            set -e
       - run:
           name: Display Docker logs
           command: cat docker_output.log
       - run:
-          name: Check for expected error
+          name: Proxy must refuse to serve on an unreachable database
           command: |
-            if grep -q "Error: P1001: Can't reach database server at" docker_output.log && \
-               (grep -q "Database setup failed after multiple retries" docker_output.log || \
-                grep -q "ERROR:    Application startup failed. Exiting." docker_output.log); then
-              echo "Expected error found. Test passed."
-            else
-              echo "Expected error not found. Test failed."
-              cat docker_output.log
-              exit 1
-            fi
+            fail() { echo "FAILED: $1"; cat docker_output.log; exit 1; }
+            exit_code="$(cat docker_exit_code)"
+            [ "$exit_code" -ne 0 ] || fail "proxy exited 0 with an unreachable database"
+            grep -q "P1001" docker_output.log || fail "log does not name the unreachable database server"
+            ! grep -q "Application startup complete" docker_output.log || fail "proxy reached serving state"
+            ! docker exec my-app true 2>/dev/null || fail "container is still running"
+            echo "Proxy refused to serve (exit $exit_code) and never reached startup. Test passed."
 
   provider_replay_harness:
     docker:
diff --git a/tests/otel_tests/test_e2e_budgeting.py b/tests/otel_tests/test_e2e_budgeting.py
index ca5058818e4..ae8f0ddc3ec 100644
--- a/tests/otel_tests/test_e2e_budgeting.py
+++ b/tests/otel_tests/test_e2e_budgeting.py
@@ -5,6 +5,7 @@ import uuid
 from typing import Any, Optional
 
 import aiohttp
+import openai
 import pytest
 from httpx import AsyncClient
 
@@ -23,7 +24,7 @@ async def make_calls_until_budget_exceeded(session, key: str, call_function, **k
             call_count += 1
             await asyncio.sleep(0.1)  # allow spend tracking to catch up
         pytest.fail(f"Budget was not exceeded after {MAX_CALLS} calls")
-    except Exception as e:
+    except openai.APIStatusError as e:
         print("vars: ", vars(e))
         print("e.body: ", e.body)
 
@@ -32,8 +33,8 @@ async def make_calls_until_budget_exceeded(session, key: str, call_function, **k
 
         # Check error structure and values that should be consistent
         assert (
-            error_dict["code"] == "429"
-        ), f"Expected error code 429, got: {error_dict['code']}"
+            error_dict["code"] == "422"
+        ), f"Expected error code 422, got: {error_dict['code']}"
         assert (
             error_dict["type"] == "budget_exceeded"
         ), f"Expected error type budget_exceeded, got: {error_dict['type']}"
@@ -506,9 +507,9 @@ async def make_calls_until_team_budget_exceeded_cli_sso(
             call_count += 1
             await asyncio.sleep(0.1)
         pytest.fail(f"Budget was not exceeded after {MAX_CALLS} calls")
-    except Exception as e:
+    except openai.APIStatusError as e:
         error_dict = e.body
-        assert error_dict["code"] == "429"
+        assert error_dict["code"] == "422"
         assert error_dict["type"] == "budget_exceeded"
         message = error_dict["message"]
         assert "Budget has been exceeded!" in message
@@ -556,7 +557,7 @@ async def test_team_budget_enforcement_cli_sso_token():
     1. Create team with a tiny max_budget and a user on that team
     2. Obtain a CLI SSO JWT (HTTP poll flow when Redis is shared, else mint)
     3. Make chat completion calls until the team budget is exceeded
-    4. Verify HTTP 429 budget_exceeded names the team
+    4. Verify HTTP 422 budget_exceeded names the team
     """
     user_id = f"cli-budget-user-{uuid.uuid4().hex[:8]}"
     user_email = f"{user_id}@example.com"

From 0eea01427d99f3d17844e1688be3b4c7be4891b4 Mon Sep 17 00:00:00 2001
From: "berriai-litellm-provider-info-sync[bot]"
 <328147090+berriai-litellm-provider-info-sync[bot]@users.noreply.github.com>
Date: Mon, 21 Sep 2026 22:01:13 +0000
Subject: [PATCH 48/55] chore(prices): sync OpenRouter prices: 3 models

openrouter/~deepseek/deepseek-v4-flash-latest: output_cost_per_token
openrouter/deepseek/deepseek-v4-flash-0731: output_cost_per_token
openrouter/deepseek/deepseek-v4-pro: input_cost_per_token, output_cost_per_token, cache_read_input_token_cost
---
 litellm/model_prices_and_context_window_backup.json | 10 +++++-----
 model_prices_and_context_window.json                | 10 +++++-----
 2 files changed, 10 insertions(+), 10 deletions(-)

diff --git a/litellm/model_prices_and_context_window_backup.json b/litellm/model_prices_and_context_window_backup.json
index 4288a87491c..5aea9cffcec 100644
--- a/litellm/model_prices_and_context_window_backup.json
+++ b/litellm/model_prices_and_context_window_backup.json
@@ -43011,21 +43011,21 @@
         "supports_web_search": false
     },
     "openrouter/deepseek/deepseek-v4-pro": {
-        "input_cost_per_token": 9.00798e-07,
+        "input_cost_per_token": 8.95578e-07,
         "input_cost_per_token_cache_hit": 4.4e-08,
         "litellm_provider": "openrouter",
         "max_input_tokens": 1048576,
         "max_output_tokens": 384000,
         "max_tokens": 384000,
         "mode": "chat",
-        "output_cost_per_token": 1.801596e-06,
+        "output_cost_per_token": 1.791156e-06,
         "source": "https://openrouter.ai/api/v1/models",
         "supports_function_calling": true,
         "supports_prompt_caching": true,
         "supports_reasoning": true,
         "supports_response_schema": true,
         "supports_tool_choice": true,
-        "cache_read_input_token_cost": 7.50665e-08,
+        "cache_read_input_token_cost": 7.46315e-08,
         "supports_audio_input": false,
         "supports_pdf_input": false,
         "supports_vision": false,
@@ -68346,7 +68346,7 @@
     },
     "openrouter/deepseek/deepseek-v4-flash-0731": {
         "input_cost_per_token": 4e-08,
-        "output_cost_per_token": 3.2e-07,
+        "output_cost_per_token": 6.4e-07,
         "cache_read_input_token_cost": 1.6e-08,
         "litellm_provider": "openrouter",
         "max_input_tokens": 1310720,
@@ -73001,7 +73001,7 @@
         "max_output_tokens": 943718,
         "max_tokens": 943718,
         "mode": "chat",
-        "output_cost_per_token": 3.2e-07,
+        "output_cost_per_token": 6.4e-07,
         "source": "https://openrouter.ai/api/v1/models",
         "supports_audio_input": false,
         "supports_function_calling": true,
diff --git a/model_prices_and_context_window.json b/model_prices_and_context_window.json
index 4288a87491c..5aea9cffcec 100644
--- a/model_prices_and_context_window.json
+++ b/model_prices_and_context_window.json
@@ -43011,21 +43011,21 @@
         "supports_web_search": false
     },
     "openrouter/deepseek/deepseek-v4-pro": {
-        "input_cost_per_token": 9.00798e-07,
+        "input_cost_per_token": 8.95578e-07,
         "input_cost_per_token_cache_hit": 4.4e-08,
         "litellm_provider": "openrouter",
         "max_input_tokens": 1048576,
         "max_output_tokens": 384000,
         "max_tokens": 384000,
         "mode": "chat",
-        "output_cost_per_token": 1.801596e-06,
+        "output_cost_per_token": 1.791156e-06,
         "source": "https://openrouter.ai/api/v1/models",
         "supports_function_calling": true,
         "supports_prompt_caching": true,
         "supports_reasoning": true,
         "supports_response_schema": true,
         "supports_tool_choice": true,
-        "cache_read_input_token_cost": 7.50665e-08,
+        "cache_read_input_token_cost": 7.46315e-08,
         "supports_audio_input": false,
         "supports_pdf_input": false,
         "supports_vision": false,
@@ -68346,7 +68346,7 @@
     },
     "openrouter/deepseek/deepseek-v4-flash-0731": {
         "input_cost_per_token": 4e-08,
-        "output_cost_per_token": 3.2e-07,
+        "output_cost_per_token": 6.4e-07,
         "cache_read_input_token_cost": 1.6e-08,
         "litellm_provider": "openrouter",
         "max_input_tokens": 1310720,
@@ -73001,7 +73001,7 @@
         "max_output_tokens": 943718,
         "max_tokens": 943718,
         "mode": "chat",
-        "output_cost_per_token": 3.2e-07,
+        "output_cost_per_token": 6.4e-07,
         "source": "https://openrouter.ai/api/v1/models",
         "supports_audio_input": false,
         "supports_function_calling": true,

From b305928422e511dd11e288c4b4f19ae743dd6f35 Mon Sep 17 00:00:00 2001
From: "berriai-litellm-provider-info-sync[bot]"
 <328147090+berriai-litellm-provider-info-sync[bot]@users.noreply.github.com>
Date: Mon, 21 Sep 2026 22:01:14 +0000
Subject: [PATCH 49/55] chore(prices): sync AWS Bedrock prices: 6 models
 [enrichment failed: AWS Bedrock, 4 held]

minimax.minimax-m2: max_tokens, supports_vision, max_input_tokens, max_output_tokens, supports_audio_input, supports_response_schema, supports_function_calling
minimax.minimax-m2.1: max_tokens, supports_vision, max_output_tokens, supports_audio_input, supports_response_schema
minimax.minimax-m2.5: max_tokens, supports_vision, max_input_tokens, max_output_tokens, supports_audio_input, supports_response_schema
moonshot.kimi-k2-thinking: max_tokens, supports_vision, max_input_tokens, max_output_tokens, supports_audio_input, supports_response_schema, supports_function_calling
openai.gpt-oss-safeguard-120b: max_tokens, supports_vision, max_output_tokens, supports_audio_input, supports_response_schema, supports_function_calling
openai.gpt-oss-safeguard-20b: max_tokens, supports_vision, max_output_tokens, supports_audio_input, supports_response_schema, supports_function_calling
---
 ...odel_prices_and_context_window_backup.json | 68 +++++++++++++------
 model_prices_and_context_window.json          | 68 +++++++++++++------
 2 files changed, 94 insertions(+), 42 deletions(-)

diff --git a/litellm/model_prices_and_context_window_backup.json b/litellm/model_prices_and_context_window_backup.json
index 4288a87491c..5526867ce74 100644
--- a/litellm/model_prices_and_context_window_backup.json
+++ b/litellm/model_prices_and_context_window_backup.json
@@ -38214,39 +38214,50 @@
     "minimax.minimax-m2": {
         "input_cost_per_token": 3e-07,
         "litellm_provider": "bedrock_converse",
-        "max_input_tokens": 128000,
-        "max_output_tokens": 8192,
-        "max_tokens": 8192,
+        "max_input_tokens": 1000000,
+        "max_output_tokens": 8000,
+        "max_tokens": 8000,
         "mode": "chat",
         "output_cost_per_token": 1.2e-06,
+        "source": "https://aws.amazon.com/bedrock/pricing/",
+        "supports_audio_input": false,
+        "supports_function_calling": true,
         "supports_system_messages": true,
-        "supports_native_structured_output": true
+        "supports_native_structured_output": true,
+        "supports_response_schema": true,
+        "supports_vision": false
     },
     "minimax.minimax-m2.1": {
         "input_cost_per_token": 3e-07,
         "litellm_provider": "bedrock_converse",
         "max_input_tokens": 196000,
-        "max_output_tokens": 8192,
-        "max_tokens": 8192,
+        "max_output_tokens": 8000,
+        "max_tokens": 8000,
         "mode": "chat",
         "output_cost_per_token": 1.2e-06,
         "supports_function_calling": true,
         "supports_system_messages": true,
         "supports_tool_choice": true,
-        "source": "https://aws.amazon.com/bedrock/pricing/"
+        "source": "https://aws.amazon.com/bedrock/pricing/",
+        "supports_audio_input": false,
+        "supports_response_schema": true,
+        "supports_vision": false
     },
     "minimax.minimax-m2.5": {
         "input_cost_per_token": 3e-07,
         "output_cost_per_token": 1.2e-06,
         "litellm_provider": "bedrock_converse",
-        "max_input_tokens": 1000000,
-        "max_output_tokens": 8192,
-        "max_tokens": 8192,
+        "max_input_tokens": 196000,
+        "max_output_tokens": 8000,
+        "max_tokens": 8000,
         "mode": "chat",
         "supports_function_calling": true,
         "supports_system_messages": true,
         "supports_tool_choice": true,
-        "source": "https://aws.amazon.com/bedrock/pricing/"
+        "source": "https://aws.amazon.com/bedrock/pricing/",
+        "supports_audio_input": false,
+        "supports_response_schema": true,
+        "supports_vision": false
     },
     "minimax/speech-02-hd": {
         "input_cost_per_character": 0.0001,
@@ -39705,14 +39716,19 @@
     "moonshot.kimi-k2-thinking": {
         "input_cost_per_token": 6e-07,
         "litellm_provider": "bedrock_converse",
-        "max_input_tokens": 128000,
-        "max_output_tokens": 8192,
-        "max_tokens": 8192,
+        "max_input_tokens": 256000,
+        "max_output_tokens": 16000,
+        "max_tokens": 16000,
         "mode": "chat",
         "output_cost_per_token": 2.5e-06,
+        "source": "https://aws.amazon.com/bedrock/pricing/",
+        "supports_audio_input": false,
+        "supports_function_calling": true,
         "supports_reasoning": true,
         "supports_system_messages": true,
-        "supports_native_structured_output": true
+        "supports_native_structured_output": true,
+        "supports_response_schema": true,
+        "supports_vision": false
     },
     "moonshotai.kimi-k2.5": {
         "input_cost_per_token": 6e-07,
@@ -42492,21 +42508,31 @@
         "input_cost_per_token": 1.5e-07,
         "litellm_provider": "bedrock_converse",
         "max_input_tokens": 128000,
-        "max_output_tokens": 8192,
-        "max_tokens": 8192,
+        "max_output_tokens": 16000,
+        "max_tokens": 16000,
         "mode": "chat",
         "output_cost_per_token": 6e-07,
-        "supports_system_messages": true
+        "source": "https://aws.amazon.com/bedrock/pricing/",
+        "supports_audio_input": false,
+        "supports_function_calling": true,
+        "supports_response_schema": true,
+        "supports_system_messages": true,
+        "supports_vision": false
     },
     "openai.gpt-oss-safeguard-20b": {
         "input_cost_per_token": 7e-08,
         "litellm_provider": "bedrock_converse",
         "max_input_tokens": 128000,
-        "max_output_tokens": 8192,
-        "max_tokens": 8192,
+        "max_output_tokens": 16000,
+        "max_tokens": 16000,
         "mode": "chat",
         "output_cost_per_token": 2e-07,
-        "supports_system_messages": true
+        "source": "https://aws.amazon.com/bedrock/pricing/",
+        "supports_audio_input": false,
+        "supports_function_calling": true,
+        "supports_response_schema": true,
+        "supports_system_messages": true,
+        "supports_vision": false
     },
     "openrouter/anthropic/claude-3-haiku": {
         "cache_creation_input_token_cost": 3e-07,
diff --git a/model_prices_and_context_window.json b/model_prices_and_context_window.json
index 4288a87491c..5526867ce74 100644
--- a/model_prices_and_context_window.json
+++ b/model_prices_and_context_window.json
@@ -38214,39 +38214,50 @@
     "minimax.minimax-m2": {
         "input_cost_per_token": 3e-07,
         "litellm_provider": "bedrock_converse",
-        "max_input_tokens": 128000,
-        "max_output_tokens": 8192,
-        "max_tokens": 8192,
+        "max_input_tokens": 1000000,
+        "max_output_tokens": 8000,
+        "max_tokens": 8000,
         "mode": "chat",
         "output_cost_per_token": 1.2e-06,
+        "source": "https://aws.amazon.com/bedrock/pricing/",
+        "supports_audio_input": false,
+        "supports_function_calling": true,
         "supports_system_messages": true,
-        "supports_native_structured_output": true
+        "supports_native_structured_output": true,
+        "supports_response_schema": true,
+        "supports_vision": false
     },
     "minimax.minimax-m2.1": {
         "input_cost_per_token": 3e-07,
         "litellm_provider": "bedrock_converse",
         "max_input_tokens": 196000,
-        "max_output_tokens": 8192,
-        "max_tokens": 8192,
+        "max_output_tokens": 8000,
+        "max_tokens": 8000,
         "mode": "chat",
         "output_cost_per_token": 1.2e-06,
         "supports_function_calling": true,
         "supports_system_messages": true,
         "supports_tool_choice": true,
-        "source": "https://aws.amazon.com/bedrock/pricing/"
+        "source": "https://aws.amazon.com/bedrock/pricing/",
+        "supports_audio_input": false,
+        "supports_response_schema": true,
+        "supports_vision": false
     },
     "minimax.minimax-m2.5": {
         "input_cost_per_token": 3e-07,
         "output_cost_per_token": 1.2e-06,
         "litellm_provider": "bedrock_converse",
-        "max_input_tokens": 1000000,
-        "max_output_tokens": 8192,
-        "max_tokens": 8192,
+        "max_input_tokens": 196000,
+        "max_output_tokens": 8000,
+        "max_tokens": 8000,
         "mode": "chat",
         "supports_function_calling": true,
         "supports_system_messages": true,
         "supports_tool_choice": true,
-        "source": "https://aws.amazon.com/bedrock/pricing/"
+        "source": "https://aws.amazon.com/bedrock/pricing/",
+        "supports_audio_input": false,
+        "supports_response_schema": true,
+        "supports_vision": false
     },
     "minimax/speech-02-hd": {
         "input_cost_per_character": 0.0001,
@@ -39705,14 +39716,19 @@
     "moonshot.kimi-k2-thinking": {
         "input_cost_per_token": 6e-07,
         "litellm_provider": "bedrock_converse",
-        "max_input_tokens": 128000,
-        "max_output_tokens": 8192,
-        "max_tokens": 8192,
+        "max_input_tokens": 256000,
+        "max_output_tokens": 16000,
+        "max_tokens": 16000,
         "mode": "chat",
         "output_cost_per_token": 2.5e-06,
+        "source": "https://aws.amazon.com/bedrock/pricing/",
+        "supports_audio_input": false,
+        "supports_function_calling": true,
         "supports_reasoning": true,
         "supports_system_messages": true,
-        "supports_native_structured_output": true
+        "supports_native_structured_output": true,
+        "supports_response_schema": true,
+        "supports_vision": false
     },
     "moonshotai.kimi-k2.5": {
         "input_cost_per_token": 6e-07,
@@ -42492,21 +42508,31 @@
         "input_cost_per_token": 1.5e-07,
         "litellm_provider": "bedrock_converse",
         "max_input_tokens": 128000,
-        "max_output_tokens": 8192,
-        "max_tokens": 8192,
+        "max_output_tokens": 16000,
+        "max_tokens": 16000,
         "mode": "chat",
         "output_cost_per_token": 6e-07,
-        "supports_system_messages": true
+        "source": "https://aws.amazon.com/bedrock/pricing/",
+        "supports_audio_input": false,
+        "supports_function_calling": true,
+        "supports_response_schema": true,
+        "supports_system_messages": true,
+        "supports_vision": false
     },
     "openai.gpt-oss-safeguard-20b": {
         "input_cost_per_token": 7e-08,
         "litellm_provider": "bedrock_converse",
         "max_input_tokens": 128000,
-        "max_output_tokens": 8192,
-        "max_tokens": 8192,
+        "max_output_tokens": 16000,
+        "max_tokens": 16000,
         "mode": "chat",
         "output_cost_per_token": 2e-07,
-        "supports_system_messages": true
+        "source": "https://aws.amazon.com/bedrock/pricing/",
+        "supports_audio_input": false,
+        "supports_function_calling": true,
+        "supports_response_schema": true,
+        "supports_system_messages": true,
+        "supports_vision": false
     },
     "openrouter/anthropic/claude-3-haiku": {
         "cache_creation_input_token_cost": 3e-07,

From 28f70c75d17815cc9b88963c0825b2c31e1a1853 Mon Sep 17 00:00:00 2001
From: ryan <ryan@berri.ai>
Date: Mon, 21 Sep 2026 22:02:05 +0000
Subject: [PATCH 50/55] fix(auth): reject unchanged password on
 /user/password/change

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
 .../password_endpoints.py                     | 17 +++++++++----
 .../test_password_endpoints.py                | 25 +++++++++++++++++++
 2 files changed, 37 insertions(+), 5 deletions(-)

diff --git a/litellm/proxy/management_endpoints/password_endpoints.py b/litellm/proxy/management_endpoints/password_endpoints.py
index a2466c83ef9..c94399ba25d 100644
--- a/litellm/proxy/management_endpoints/password_endpoints.py
+++ b/litellm/proxy/management_endpoints/password_endpoints.py
@@ -63,11 +63,12 @@ async def change_password(
     """
     Change the calling user's own password.
 
-    Requires the current password. The new password must satisfy the
-    configured password policy (`general_settings.password_policy_*`: minimum
-    length, character classes, and, when enabled, breached-password screening
-    via haveibeenpwned.com). A successful change lifts any pending forced
-    password reset (`password_reset_required`) on the account.
+    Requires the current password. The new password must differ from the
+    current one and satisfy the configured password policy
+    (`general_settings.password_policy_*`: minimum length, character classes,
+    and, when enabled, breached-password screening via haveibeenpwned.com).
+    A successful change lifts any pending forced password reset
+    (`password_reset_required`) on the account.
 
     Parameters:
     - current_password: str - The user's current password.
@@ -103,6 +104,12 @@ async def change_password(
     if not verify_password(data.current_password, stored_password):
         raise HTTPException(status_code=400, detail=_error_detail("Current password is incorrect."))
 
+    if data.new_password == data.current_password:
+        raise HTTPException(
+            status_code=400,
+            detail=_error_detail("New password must be different from the current password."),
+        )
+
     validate_password_policy(data.new_password, general_settings)
     await validate_password_not_breached(data.new_password, general_settings)
 
diff --git a/tests/test_litellm/proxy/management_endpoints/test_password_endpoints.py b/tests/test_litellm/proxy/management_endpoints/test_password_endpoints.py
index bd154ebab41..581a2ef8df8 100644
--- a/tests/test_litellm/proxy/management_endpoints/test_password_endpoints.py
+++ b/tests/test_litellm/proxy/management_endpoints/test_password_endpoints.py
@@ -105,6 +105,31 @@ async def test_change_password_rejects_wrong_current_password():
     prisma.db.litellm_usertable.update.assert_not_called()
 
 
+@pytest.mark.asyncio
+async def test_change_password_rejects_unchanged_password():
+    from litellm.proxy._types import ChangePasswordRequest
+
+    prisma = _make_prisma(_make_user_row(hash_password(CURRENT_PASSWORD)))
+
+    with (
+        patch(  # test-quality-ok: change_password reads proxy_server module globals; no injection seam
+            "litellm.proxy.proxy_server.prisma_client", prisma
+        ),
+        patch(  # test-quality-ok: change_password reads proxy_server module globals; no injection seam
+            "litellm.proxy.proxy_server.general_settings", _POLICY_NO_BREACH_CHECK
+        ),
+    ):
+        with pytest.raises(HTTPException) as exc_info:
+            await change_password(
+                data=ChangePasswordRequest(current_password=CURRENT_PASSWORD, new_password=CURRENT_PASSWORD),
+                user_api_key_dict=_caller(),
+            )
+
+    assert exc_info.value.status_code == 400
+    assert "must be different from the current password" in exc_info.value.detail["error"]
+    prisma.db.litellm_usertable.update.assert_not_called()
+
+
 @pytest.mark.asyncio
 async def test_change_password_rejects_session_without_user():
     from litellm.proxy._types import ChangePasswordRequest

From 5da590a3c535e0c351ff70e8ee1fb4afb9dc5c28 Mon Sep 17 00:00:00 2001
From: ryan <ryan@berri.ai>
Date: Mon, 21 Sep 2026 22:05:44 +0000
Subject: [PATCH 51/55] chore(ui): regenerate schema.d.ts for change_password
 docstring

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
 ui/litellm-dashboard/src/lib/http/schema.d.ts | 11 ++++++-----
 1 file changed, 6 insertions(+), 5 deletions(-)

diff --git a/ui/litellm-dashboard/src/lib/http/schema.d.ts b/ui/litellm-dashboard/src/lib/http/schema.d.ts
index ad8e2623d3a..93753d29993 100644
--- a/ui/litellm-dashboard/src/lib/http/schema.d.ts
+++ b/ui/litellm-dashboard/src/lib/http/schema.d.ts
@@ -17386,11 +17386,12 @@ export interface paths {
          * Change Password
          * @description Change the calling user's own password.
          *
-         *     Requires the current password. The new password must satisfy the
-         *     configured password policy (`general_settings.password_policy_*`: minimum
-         *     length, character classes, and, when enabled, breached-password screening
-         *     via haveibeenpwned.com). A successful change lifts any pending forced
-         *     password reset (`password_reset_required`) on the account.
+         *     Requires the current password. The new password must differ from the
+         *     current one and satisfy the configured password policy
+         *     (`general_settings.password_policy_*`: minimum length, character classes,
+         *     and, when enabled, breached-password screening via haveibeenpwned.com).
+         *     A successful change lifts any pending forced password reset
+         *     (`password_reset_required`) on the account.
          *
          *     Parameters:
          *     - current_password: str - The user's current password.

From 1827be1302b912ace13a56de2760a2f487025083 Mon Sep 17 00:00:00 2001
From: Yujong Lee <yujong@berri.ai>
Date: Mon, 21 Sep 2026 22:06:55 +0000
Subject: [PATCH 52/55] fix(cache-disk): absolutize store directory and stamp
 async expiry at write time

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
 litellm-rust/crates/cache-disk/src/cache.rs   |  3 ++-
 litellm-rust/crates/cache-disk/src/sqlite.rs  |  1 +
 litellm-rust/crates/cache-disk/tests/cache.rs | 19 +++++++++++++++++++
 3 files changed, 22 insertions(+), 1 deletion(-)

diff --git a/litellm-rust/crates/cache-disk/src/cache.rs b/litellm-rust/crates/cache-disk/src/cache.rs
index adff078a89b..8e1223309b4 100644
--- a/litellm-rust/crates/cache-disk/src/cache.rs
+++ b/litellm-rust/crates/cache-disk/src/cache.rs
@@ -102,9 +102,10 @@ impl<S: CacheCodec, D: DiskStore, A: ValueAdapter> BaseCache for DiskCache<S, D,
         context: ExactCacheContext,
     ) -> Result<(), Error> {
         let value = self.adapter.write(self.codec.encode(&value)?);
-        let expire_time = context.ttl.map(|ttl| unix_now() + ttl.as_secs_f64());
+        let ttl = context.ttl;
         let key = key.to_string();
         Self::run_blocking(Arc::clone(&self.store), move |store| {
+            let expire_time = ttl.map(|ttl| unix_now() + ttl.as_secs_f64());
             store.set(&key, value, expire_time, unix_now())
         })
         .await
diff --git a/litellm-rust/crates/cache-disk/src/sqlite.rs b/litellm-rust/crates/cache-disk/src/sqlite.rs
index ff5a44b5c38..9a36f8af6ad 100644
--- a/litellm-rust/crates/cache-disk/src/sqlite.rs
+++ b/litellm-rust/crates/cache-disk/src/sqlite.rs
@@ -49,6 +49,7 @@ impl DiskcacheSqliteStore {
     pub fn open(directory: impl AsRef<Path>) -> Result<Self, Error> {
         let directory = directory.as_ref().to_path_buf();
         fs::create_dir_all(&directory).map_err(|_| Error::Unavailable)?;
+        let directory = std::path::absolute(&directory).map_err(|_| Error::Unavailable)?;
         let database = directory.join("cache.db");
         let connection = Connection::open(database).map_err(|_| Error::Unavailable)?;
         connection
diff --git a/litellm-rust/crates/cache-disk/tests/cache.rs b/litellm-rust/crates/cache-disk/tests/cache.rs
index 4fb77d233ec..dd1f2b1f04e 100644
--- a/litellm-rust/crates/cache-disk/tests/cache.rs
+++ b/litellm-rust/crates/cache-disk/tests/cache.rs
@@ -61,6 +61,25 @@ impl Sandbox {
     }
 }
 
+#[rstest]
+fn relative_store_directory_is_absolutized(sandbox: Sandbox) {
+    let relative = PathBuf::from(format!(
+        ".litellm-cache-disk-{}",
+        sandbox
+            .directory
+            .path()
+            .file_name()
+            .unwrap()
+            .to_string_lossy()
+    ));
+    let store = DiskcacheSqliteStore::open(&relative).unwrap();
+    assert!(store.directory().is_absolute());
+    assert!(store.directory().ends_with(&relative));
+    let directory = store.directory().to_path_buf();
+    drop(store);
+    fs::remove_dir_all(directory).unwrap();
+}
+
 #[derive(Clone, Copy, Debug, Default)]
 struct TextAdapter;
 

From 2a3ae253d49f0a5147ff2f571d9a8b601f21de38 Mon Sep 17 00:00:00 2001
From: Yujong Lee <yujong@berri.ai>
Date: Mon, 21 Sep 2026 22:14:22 +0000
Subject: [PATCH 53/55] refactor(rust): fold disk arms into shared match
 patterns

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
 .../crates/python-bridge/src/cache/native.rs      | 15 ++++-----------
 1 file changed, 4 insertions(+), 11 deletions(-)

diff --git a/litellm-rust/crates/python-bridge/src/cache/native.rs b/litellm-rust/crates/python-bridge/src/cache/native.rs
index bbd72e58825..80789cc279a 100644
--- a/litellm-rust/crates/python-bridge/src/cache/native.rs
+++ b/litellm-rust/crates/python-bridge/src/cache/native.rs
@@ -99,35 +99,29 @@ impl NativeResponseCache {
 
     pub fn namespace(&self) -> Option<&str> {
         match self {
-            Self::Memory(_) | Self::AzureBlob(_) => None,
+            Self::Memory(_) | Self::Disk(_) | Self::AzureBlob(_) => None,
             Self::Redis { cache, .. } => cache.backend().namespace(),
-            Self::Disk(_) => None,
         }
     }
 
     pub fn topology(&self) -> Option<&RedisTopology> {
         match self {
-            Self::Memory(_) | Self::AzureBlob(_) => None,
+            Self::Memory(_) | Self::Disk(_) | Self::AzureBlob(_) => None,
             Self::Redis { cache, .. } => Some(cache.backend().topology()),
-            Self::Disk(_) => None,
         }
     }
 
     pub fn capacity(&self) -> Option<usize> {
         match self {
             Self::Memory(cache) => Some(cache.backend().max_size_in_memory()),
-            Self::Redis { .. } => None,
-            Self::Disk(_) => None,
-            Self::AzureBlob(_) => None,
+            Self::Redis { .. } | Self::Disk(_) | Self::AzureBlob(_) => None,
         }
     }
 
     pub fn max_entry_bytes(&self) -> Option<usize> {
         match self {
             Self::Memory(cache) => cache.backend().max_entry_bytes(),
-            Self::Redis { .. } => None,
-            Self::Disk(_) => None,
-            Self::AzureBlob(_) => None,
+            Self::Redis { .. } | Self::Disk(_) | Self::AzureBlob(_) => None,
         }
     }
 
@@ -137,7 +131,6 @@ impl NativeResponseCache {
                 cache,
                 buffer: flush_size.map(|flush_size| Arc::new(WriteBuffer::new(flush_size))),
             },
-            disk @ Self::Disk(_) => disk,
             other => other,
         }
     }

From 8a1c6e49fb97d44528a451b2cf0c266468ac256d Mon Sep 17 00:00:00 2001
From: ryan <ryan@berri.ai>
Date: Mon, 21 Sep 2026 22:22:12 +0000
Subject: [PATCH 54/55] feat(auth): only allow password-login dashboard
 sessions to call /user/password/change

Password login now stamps login_method=username_password into the UI session key
metadata, and change_password rejects any caller that is not a litellm-dashboard
key carrying that marker with 403 before the user row is read. SSO sessions and
user-associated virtual keys can no longer use the endpoint as a current_password
guessing oracle. The forced-reset session is still minted by the password login
path, so it keeps access to the endpoint

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
 litellm/proxy/auth/login_utils.py             |  6 ++-
 .../password_endpoints.py                     | 23 ++++++++-
 .../proxy/auth/test_login_utils.py            |  6 +--
 .../test_password_endpoints.py                | 49 ++++++++++++++++++-
 ui/litellm-dashboard/src/lib/http/schema.d.ts |  4 +-
 5 files changed, 80 insertions(+), 8 deletions(-)

diff --git a/litellm/proxy/auth/login_utils.py b/litellm/proxy/auth/login_utils.py
index 0dddb16b531..4c2b5d3d0fe 100644
--- a/litellm/proxy/auth/login_utils.py
+++ b/litellm/proxy/auth/login_utils.py
@@ -58,6 +58,7 @@ if TYPE_CHECKING:
 
 BREACH_RECHECK_INTERVAL: Final = timedelta(hours=24)
 PASSWORD_RESET_ALLOWED_ROUTES: Final = ("/user/password/change",)
+PASSWORD_SESSION_METADATA: Final = MappingProxyType({"login_method": "username_password"})
 
 
 def _breach_recheck_due(last_breach_check_at: datetime | None) -> bool:
@@ -431,7 +432,10 @@ async def _sign_in(
                     user_id=user_id,
                     team_id="litellm-dashboard",
                     allowed_routes=list(PASSWORD_RESET_ALLOWED_ROUTES) if password_reset_required else None,
-                    metadata={"password_reset_required": True} if password_reset_required else {},
+                    metadata={
+                        **PASSWORD_SESSION_METADATA,
+                        **({"password_reset_required": True} if password_reset_required else {}),
+                    },
                 )
             else:
                 raise ProxyException(
diff --git a/litellm/proxy/management_endpoints/password_endpoints.py b/litellm/proxy/management_endpoints/password_endpoints.py
index c94399ba25d..03a8b4c4010 100644
--- a/litellm/proxy/management_endpoints/password_endpoints.py
+++ b/litellm/proxy/management_endpoints/password_endpoints.py
@@ -11,9 +11,11 @@ signal is emitted by hand below, with field names only, never values.
 from typing import TYPE_CHECKING, Annotated, Final
 
 from fastapi import APIRouter, Depends, HTTPException
+from pydantic import TypeAdapter
 
 from litellm._logging import verbose_proxy_logger
 from litellm.proxy._types import (
+    UI_TEAM_ID,
     ChangePasswordRequest,
     ChangePasswordResponse,
     CommonProxyErrors,
@@ -21,6 +23,7 @@ from litellm.proxy._types import (
     LitellmTableNames,
     UserAPIKeyAuth,
 )
+from litellm.proxy.auth.login_utils import PASSWORD_SESSION_METADATA
 from litellm.proxy.auth.password_policy import validate_password_not_breached, validate_password_policy
 from litellm.proxy.auth.user_api_key_auth import user_api_key_auth
 from litellm.proxy.management_helpers.audit_logs import create_object_audit_log
@@ -37,6 +40,7 @@ if TYPE_CHECKING:
 router: Final = APIRouter()
 
 _PASSWORD_CHANGED_AUDIT_VALUES: Final = '{"fields_changed": ["password"]}'
+_KEY_METADATA: Final = TypeAdapter(dict[str, object])
 
 
 def _error_detail(message: str) -> HTTPExceptionErrorDetail:
@@ -44,6 +48,13 @@ def _error_detail(message: str) -> HTTPExceptionErrorDetail:
     return detail
 
 
+def _is_password_login_session(user_api_key_dict: UserAPIKeyAuth) -> bool:
+    if user_api_key_dict.team_id != UI_TEAM_ID:
+        return False
+    key_metadata: Final = _KEY_METADATA.validate_python(user_api_key_dict.metadata)
+    return all(key_metadata.get(k) == v for k, v in PASSWORD_SESSION_METADATA.items())
+
+
 def _user_table(
     prisma_client: "PrismaClient | None",
 ) -> "TableActions[prisma_models.LiteLLM_UserTable]":
@@ -63,7 +74,9 @@ async def change_password(
     """
     Change the calling user's own password.
 
-    Requires the current password. The new password must differ from the
+    Only callable with the dashboard session issued by a username/password
+    login; SSO sessions and virtual keys are rejected with 403. Requires the
+    current password. The new password must differ from the
     current one and satisfy the configured password policy
     (`general_settings.password_policy_*`: minimum length, character classes,
     and, when enabled, breached-password screening via haveibeenpwned.com).
@@ -82,6 +95,14 @@ async def change_password(
             detail=_error_detail(CommonProxyErrors.db_not_connected_error.value),
         )
 
+    if not _is_password_login_session(user_api_key_dict):
+        raise HTTPException(
+            status_code=403,
+            detail=_error_detail(
+                "Passwords can only be changed from a dashboard session created by logging in with a password."
+            ),
+        )
+
     user_id: Final = user_api_key_dict.user_id
     if user_id is None:
         raise HTTPException(
diff --git a/tests/test_litellm/proxy/auth/test_login_utils.py b/tests/test_litellm/proxy/auth/test_login_utils.py
index ada231a3e95..3786169c320 100644
--- a/tests/test_litellm/proxy/auth/test_login_utils.py
+++ b/tests/test_litellm/proxy/auth/test_login_utils.py
@@ -2138,7 +2138,7 @@ class TestPasswordResetRequiredSessionMinting:
         result, key_kwargs = await self._login(_prisma_with_user(row))
 
         assert key_kwargs["allowed_routes"] == ["/user/password/change"]
-        assert key_kwargs["metadata"] == {"password_reset_required": True}
+        assert key_kwargs["metadata"] == {"login_method": "username_password", "password_reset_required": True}
         assert result.password_reset_required is True
 
     @pytest.mark.asyncio
@@ -2147,7 +2147,7 @@ class TestPasswordResetRequiredSessionMinting:
         result, key_kwargs = await self._login(_prisma_with_user(row))
 
         assert key_kwargs["allowed_routes"] is None
-        assert not key_kwargs["metadata"]
+        assert key_kwargs["metadata"] == {"login_method": "username_password"}
         assert result.password_reset_required is False
 
     async def _login_with_screen_result(self, mock_prisma_client, breached: bool) -> tuple[LoginResult, dict, dict]:
@@ -2199,7 +2199,7 @@ class TestPasswordResetRequiredSessionMinting:
         result, key_kwargs, _ = await self._login_with_screen_result(mock_prisma_client, breached=True)
 
         assert key_kwargs["allowed_routes"] == ["/user/password/change"]
-        assert key_kwargs["metadata"] == {"password_reset_required": True}
+        assert key_kwargs["metadata"] == {"login_method": "username_password", "password_reset_required": True}
         assert result.password_reset_required is True
 
 
diff --git a/tests/test_litellm/proxy/management_endpoints/test_password_endpoints.py b/tests/test_litellm/proxy/management_endpoints/test_password_endpoints.py
index 581a2ef8df8..c04353fec99 100644
--- a/tests/test_litellm/proxy/management_endpoints/test_password_endpoints.py
+++ b/tests/test_litellm/proxy/management_endpoints/test_password_endpoints.py
@@ -12,7 +12,8 @@ import pytest
 import respx
 from fastapi import HTTPException
 
-from litellm.proxy._types import LitellmTableNames, ProxyErrorTypes, ProxyException, UserAPIKeyAuth
+from litellm.proxy._types import UI_TEAM_ID, LitellmTableNames, ProxyErrorTypes, ProxyException, UserAPIKeyAuth
+from litellm.proxy.auth.login_utils import PASSWORD_SESSION_METADATA
 from litellm.proxy.management_endpoints.password_endpoints import change_password
 from litellm.proxy.utils import hash_password, verify_password
 
@@ -37,7 +38,15 @@ def _make_prisma(user: MagicMock | None) -> MagicMock:
 
 
 def _caller(user_id: str | None = "user-123") -> UserAPIKeyAuth:
-    return UserAPIKeyAuth(user_id=user_id)
+    return UserAPIKeyAuth(user_id=user_id, team_id=UI_TEAM_ID, metadata=dict(PASSWORD_SESSION_METADATA))
+
+
+def _sso_session_caller() -> UserAPIKeyAuth:
+    return UserAPIKeyAuth(user_id="user-123", team_id=UI_TEAM_ID, metadata={})
+
+
+def _virtual_key_caller() -> UserAPIKeyAuth:
+    return UserAPIKeyAuth(user_id="user-123", team_id="team-abc", metadata=dict(PASSWORD_SESSION_METADATA))
 
 
 def _hibp_url_for(password: str) -> str:
@@ -130,6 +139,42 @@ async def test_change_password_rejects_unchanged_password():
     prisma.db.litellm_usertable.update.assert_not_called()
 
 
+@pytest.mark.asyncio
+@pytest.mark.parametrize(
+    "caller",
+    [
+        pytest.param(_sso_session_caller(), id="sso_dashboard_session"),
+        pytest.param(_virtual_key_caller(), id="virtual_key_with_forged_metadata"),
+    ],
+)
+async def test_change_password_rejects_non_password_login_session(caller: UserAPIKeyAuth):
+    """Only the session minted by a password login may change the password, so a
+    stolen virtual key or an SSO session cannot use the endpoint as a
+    current_password guessing oracle."""
+    from litellm.proxy._types import ChangePasswordRequest
+
+    prisma = _make_prisma(_make_user_row(hash_password(CURRENT_PASSWORD)))
+
+    with (
+        patch(  # test-quality-ok: change_password reads proxy_server module globals; no injection seam
+            "litellm.proxy.proxy_server.prisma_client", prisma
+        ),
+        patch(  # test-quality-ok: change_password reads proxy_server module globals; no injection seam
+            "litellm.proxy.proxy_server.general_settings", _POLICY_NO_BREACH_CHECK
+        ),
+    ):
+        with pytest.raises(HTTPException) as exc_info:
+            await change_password(
+                data=ChangePasswordRequest(current_password=CURRENT_PASSWORD, new_password=NEW_PASSWORD),
+                user_api_key_dict=caller,
+            )
+
+    assert exc_info.value.status_code == 403
+    assert "logging in with a password" in exc_info.value.detail["error"]
+    prisma.db.litellm_usertable.find_first.assert_not_called()
+    prisma.db.litellm_usertable.update.assert_not_called()
+
+
 @pytest.mark.asyncio
 async def test_change_password_rejects_session_without_user():
     from litellm.proxy._types import ChangePasswordRequest
diff --git a/ui/litellm-dashboard/src/lib/http/schema.d.ts b/ui/litellm-dashboard/src/lib/http/schema.d.ts
index 93753d29993..84e3270c48b 100644
--- a/ui/litellm-dashboard/src/lib/http/schema.d.ts
+++ b/ui/litellm-dashboard/src/lib/http/schema.d.ts
@@ -17386,7 +17386,9 @@ export interface paths {
          * Change Password
          * @description Change the calling user's own password.
          *
-         *     Requires the current password. The new password must differ from the
+         *     Only callable with the dashboard session issued by a username/password
+         *     login; SSO sessions and virtual keys are rejected with 403. Requires the
+         *     current password. The new password must differ from the
          *     current one and satisfy the configured password policy
          *     (`general_settings.password_policy_*`: minimum length, character classes,
          *     and, when enabled, breached-password screening via haveibeenpwned.com).

From cf7988a2df65f6e775426bde8656cf4840f09f56 Mon Sep 17 00:00:00 2001
From: "berriai-litellm-provider-info-sync[bot]"
 <328147090+berriai-litellm-provider-info-sync[bot]@users.noreply.github.com>
Date: Mon, 21 Sep 2026 22:31:01 +0000
Subject: [PATCH 55/55] chore(prices): sync OpenRouter prices: 3 models

openrouter/~z-ai/glm-flash-latest: max_tokens, max_output_tokens, input_cost_per_token, output_cost_per_token, cache_read_input_token_cost
openrouter/deepseek/deepseek-v4-pro: input_cost_per_token, output_cost_per_token, cache_read_input_token_cost
openrouter/z-ai/glm-5.3-flash: max_tokens, max_output_tokens, input_cost_per_token, output_cost_per_token, cache_read_input_token_cost
---
 ...odel_prices_and_context_window_backup.json | 26 +++++++++----------
 model_prices_and_context_window.json          | 26 +++++++++----------
 2 files changed, 26 insertions(+), 26 deletions(-)

diff --git a/litellm/model_prices_and_context_window_backup.json b/litellm/model_prices_and_context_window_backup.json
index 6b49b1d47a5..beb90c2fb8c 100644
--- a/litellm/model_prices_and_context_window_backup.json
+++ b/litellm/model_prices_and_context_window_backup.json
@@ -43037,21 +43037,21 @@
         "supports_web_search": false
     },
     "openrouter/deepseek/deepseek-v4-pro": {
-        "input_cost_per_token": 8.95578e-07,
+        "input_cost_per_token": 8.92272e-07,
         "input_cost_per_token_cache_hit": 4.4e-08,
         "litellm_provider": "openrouter",
         "max_input_tokens": 1048576,
         "max_output_tokens": 384000,
         "max_tokens": 384000,
         "mode": "chat",
-        "output_cost_per_token": 1.791156e-06,
+        "output_cost_per_token": 1.784544e-06,
         "source": "https://openrouter.ai/api/v1/models",
         "supports_function_calling": true,
         "supports_prompt_caching": true,
         "supports_reasoning": true,
         "supports_response_schema": true,
         "supports_tool_choice": true,
-        "cache_read_input_token_cost": 7.46315e-08,
+        "cache_read_input_token_cost": 7.4356e-08,
         "supports_audio_input": false,
         "supports_pdf_input": false,
         "supports_vision": false,
@@ -68212,13 +68212,13 @@
         "supports_web_search": false
     },
     "openrouter/z-ai/glm-5.3-flash": {
-        "input_cost_per_token": 7.5e-08,
-        "output_cost_per_token": 2.5e-07,
-        "cache_read_input_token_cost": 2e-08,
+        "input_cost_per_token": 1.5e-07,
+        "output_cost_per_token": 5e-07,
+        "cache_read_input_token_cost": 5e-08,
         "litellm_provider": "openrouter",
         "max_input_tokens": 1310720,
-        "max_output_tokens": 102400,
-        "max_tokens": 102400,
+        "max_output_tokens": 943718,
+        "max_tokens": 943718,
         "mode": "chat",
         "source": "https://openrouter.ai/api/v1/models",
         "supports_audio_input": false,
@@ -73252,14 +73252,14 @@
         "supports_web_search": true
     },
     "openrouter/~z-ai/glm-flash-latest": {
-        "cache_read_input_token_cost": 2e-08,
-        "input_cost_per_token": 7.5e-08,
+        "cache_read_input_token_cost": 5e-08,
+        "input_cost_per_token": 1.5e-07,
         "litellm_provider": "openrouter",
         "max_input_tokens": 1310720,
-        "max_output_tokens": 102400,
-        "max_tokens": 102400,
+        "max_output_tokens": 943718,
+        "max_tokens": 943718,
         "mode": "chat",
-        "output_cost_per_token": 2.5e-07,
+        "output_cost_per_token": 5e-07,
         "source": "https://openrouter.ai/api/v1/models",
         "supports_audio_input": false,
         "supports_function_calling": true,
diff --git a/model_prices_and_context_window.json b/model_prices_and_context_window.json
index 6b49b1d47a5..beb90c2fb8c 100644
--- a/model_prices_and_context_window.json
+++ b/model_prices_and_context_window.json
@@ -43037,21 +43037,21 @@
         "supports_web_search": false
     },
     "openrouter/deepseek/deepseek-v4-pro": {
-        "input_cost_per_token": 8.95578e-07,
+        "input_cost_per_token": 8.92272e-07,
         "input_cost_per_token_cache_hit": 4.4e-08,
         "litellm_provider": "openrouter",
         "max_input_tokens": 1048576,
         "max_output_tokens": 384000,
         "max_tokens": 384000,
         "mode": "chat",
-        "output_cost_per_token": 1.791156e-06,
+        "output_cost_per_token": 1.784544e-06,
         "source": "https://openrouter.ai/api/v1/models",
         "supports_function_calling": true,
         "supports_prompt_caching": true,
         "supports_reasoning": true,
         "supports_response_schema": true,
         "supports_tool_choice": true,
-        "cache_read_input_token_cost": 7.46315e-08,
+        "cache_read_input_token_cost": 7.4356e-08,
         "supports_audio_input": false,
         "supports_pdf_input": false,
         "supports_vision": false,
@@ -68212,13 +68212,13 @@
         "supports_web_search": false
     },
     "openrouter/z-ai/glm-5.3-flash": {
-        "input_cost_per_token": 7.5e-08,
-        "output_cost_per_token": 2.5e-07,
-        "cache_read_input_token_cost": 2e-08,
+        "input_cost_per_token": 1.5e-07,
+        "output_cost_per_token": 5e-07,
+        "cache_read_input_token_cost": 5e-08,
         "litellm_provider": "openrouter",
         "max_input_tokens": 1310720,
-        "max_output_tokens": 102400,
-        "max_tokens": 102400,
+        "max_output_tokens": 943718,
+        "max_tokens": 943718,
         "mode": "chat",
         "source": "https://openrouter.ai/api/v1/models",
         "supports_audio_input": false,
@@ -73252,14 +73252,14 @@
         "supports_web_search": true
     },
     "openrouter/~z-ai/glm-flash-latest": {
-        "cache_read_input_token_cost": 2e-08,
-        "input_cost_per_token": 7.5e-08,
+        "cache_read_input_token_cost": 5e-08,
+        "input_cost_per_token": 1.5e-07,
         "litellm_provider": "openrouter",
         "max_input_tokens": 1310720,
-        "max_output_tokens": 102400,
-        "max_tokens": 102400,
+        "max_output_tokens": 943718,
+        "max_tokens": 943718,
         "mode": "chat",
-        "output_cost_per_token": 2.5e-07,
+        "output_cost_per_token": 5e-07,
         "source": "https://openrouter.ai/api/v1/models",
         "supports_audio_input": false,
         "supports_function_calling": true,