[Bug]: MCP auto-execute (require_approval "never") hijacks client-side tool_use from agentic clients like Claude Code, breaking all non-MCP tools with "Error executing tool"

[luyufan498]

What happened?

A model configured with an MCP tool reference using require_approval: "never" (so the proxy auto-executes it server-side) is deployed behind an agentic client that sends its own tools in the same request, such as Claude Code sending Read/Bash/Edit. The auto-execute loop takes over the entire tool_use turn and tries to execute every tool_use block the model emits, including the client's own non-MCP tools. Those tools are not in the MCP server map, so the proxy raises a KeyError that gets swallowed into Error executing tool: '<tool_name>' and fed back to the model. The model retries, fails again, and eventually gives up. From the client's perspective all of its native tools (Read, Bash, etc.) are broken for any request routed to that model

What I expected: when require_approval: "never" is set, the proxy should auto-execute only the MCP tools it injected. A tool_use whose name does not resolve to a known MCP server should be passed through to the client unchanged so the client can execute it locally, the way a normal tool_use turn works when no MCP tool is present

User Flow

Before a fix

1. A user creates a virtual key and a team in the LiteLLM proxy UI, then registers an HTTP MCP server (say image_understand) and grants the team access to it
2. The user attaches the MCP tool to a model via the model's LiteLLM Params, e.g. {"tools": [{"type": "mcp", "server_url": "litellm_proxy/mcp/image_understand", "require_approval": "never"}]}
3. The user points an agentic client (Claude Code) at POST /v1/messages on the proxy, using that model and that virtual key. The client sends its own tools (Read, Bash, Edit, ...) alongside whatever the proxy injects
4. The model decides to call Read on a local file. The proxy's auto-execute loop intercepts that tool_use, fails with Error executing tool: 'Read', and returns the error text to the model instead of handing the tool_use back to the client
5. The model retries with Bash, gets Error executing tool: 'Bash', and eventually stops with a message saying the tools are unavailable. The user sees tool call failures and the client's native tooling is dead for that model

After a fix

1. Same setup as above: MCP server registered, team granted access, MCP tool attached to the model with require_approval: "never"
2. The user points Claude Code at POST /v1/messages with that model and key, sending its own tools
3. The model calls Read on a local file. The proxy recognizes Read is not one of its MCP tools, returns the tool_use block to the client in the response, and lets the client execute it locally
4. When the model calls the injected MCP tool (image_understand), the proxy auto-executes it server-side as before and feeds the result back
5. Both the client's native tools and the injected MCP tool work in the same turn

Proof the bug occurs

I verified the root cause by reading the current main branch (v1.98.0-dev.2). I was not able to capture a full Claude Code trace against my own proxy in time for this report, so the proof below is the code path plus the user-visible symptom. I can add a full end-to-end curl reproduction if the maintainers want one

Config / setup: a model with an MCP tool attached via LiteLLM Params

{"tools": [{"type": "mcp", "server_url": "litellm_proxy/mcp/image_understand", "require_approval": "never"}]}

Version or commit: v1.98.0-dev.2 on main

Commands and their full output

The auto-execute loop in litellm/llms/anthropic/experimental_pass_through/messages/mcp_handler.py extracts every tool_use block without checking whether it belongs to an MCP server

# line 38-40
def _extract_tool_use_blocks(response):
    return tuple(block for block in _get_response_content(response) if block.get("type") == "tool_use")

# line 139-158 (abridged)
for _ in range(MAX_MCP_TOOL_USE_ITERATIONS):
    if _get_stop_reason(response) != "tool_use":
        break
    tool_use_blocks = _extract_tool_use_blocks(response)
    if not tool_use_blocks:
        break
    tool_results = await LiteLLM_Proxy_MCP_Handler._execute_tool_calls(
        tool_server_map=tool_server_map,
        tool_calls=list(tool_use_blocks),
        ...
    )

tool_server_map is built only from the injected MCP tools (in _process_mcp_tools_without_openai_transform). When _execute_tool_calls looks up a client-side tool name that is not in that map, it throws KeyError

# litellm/responses/mcp/litellm_proxy_mcp_handler.py line 675
server_name = tool_server_map[tool_name]

That KeyError is caught by the broad except at line 891-905 and turned into the user-visible error string

# line 891-905 (abridged)
except Exception as e:
    ...
    tool_results.append({
        "tool_call_id": tool_call_id,
        "result": f"Error executing tool: {e}",
        "name": tool_name,
    })

So a model emitting tool_use for Read produces Error executing tool: 'Read', which matches what I observed in the proxy spend logs and what Claude Code surfaced as "tool call failed"

The symptom from the agentic client side (Claude Code talking to the proxy over /v1/messages): the model attempts Read on a file that exists, gets Error executing tool: 'Read' back, tries Bash, gets Error executing tool: 'Bash', then tells the user it cannot read files or run commands. A plain curl client that sends no tools of its own works perfectly against the same model, because then every tool_use resolves to an MCP tool. This is why the bug is specific to agentic clients that bring their own tools

What part of LiteLLM is this about?

Proxy

What LiteLLM version are you on ?

v1.98.0-dev.2

Twitter / LinkedIn details

No response

[LH-kevin]

I’m interested in working on this.

I traced the current /v1/messages MCP loop and found one control-flow detail I’d like to confirm before implementing.

For a response containing both:

• an MCP-owned tool_use (present in tool_server_map), and
• a client-owned tool_use such as Read (not present in tool_server_map),

would you prefer:

1. fail/pass through the entire mixed tool_use response to the client without auto-executing any tool in that response, or
2. support partial execution, where LiteLLM executes only the MCP-owned tool while preserving the client-owned tool for the caller?

I’m asking because PR #33631 previously avoided partial execution for mixed approval modes: an Anthropic follow-up needs a tool_result for every tool_use in the preceding assistant turn, so executing only a subset can leave an invalid tool_use / tool_result sequence unless additional state/reassembly logic is introduced.

I can keep the fix focused and add a mocked regression test for MCP + client-owned tool_use once the intended mixed-turn behavior is confirmed.

[ArjunPakhan]

Hi @luyufan498 , I would like to take this up!

I will implement the pass-through approach (Option A): if the model emits any tool_use block that is not present in tool_server_map (i.e. client-native tools like Read/Bash), the proxy will bypass server-side auto-execution for that turn and pass the complete response back to the client. This guarantees Anthropic API schema compliance while restoring client-side tool execution for agentic frameworks like Claude Code.

I will submit a PR with unit/mock regression tests shortly.

[luyufan498]

Thanks for picking this up. One important clarification on the desired behavior from our side:

The pass-through approach (Option A) doesn't fit our enterprise use case. What we actually need is partial execution (Option B), but with invisible injected tools:

Scenario: In enterprise deployments we want to attach hidden capabilities to a model at the gateway level — e.g. image recognition, OCR, RAG lookups. End users talk to the model with zero special configuration: they never see the injected tools, never configure them, and the gateway's injected tool_use blocks are executed server-side with the results fed back into the conversation. Meanwhile the client's own native tools (Read/Bash/etc.) must keep working exactly as before.

So the required semantics are:

1. Injected (gateway/MCP-owned) tool_use → executed by the proxy, results returned into the turn.
2. Client-owned tool_use → passed through untouched for the client to execute locally.
3. The client should never observe the injected tools at all (no extra configuration, no visible tool definitions).

Regarding the Anthropic schema concern (every tool_use in an assistant turn needs a matching tool_result): this is solvable via message reassembly — execute the injected subset, append their tool_results as an interleaved assistant+user turn (the same pattern Anthropic uses for server-side/background tools), then return the final turn to the client with only its own tool_use blocks outstanding. From the client's perspective there is no schema violation because the injected tool_use never appears in the turn it sees.

I'd suggest making this configurable: strict pass-through for plain clients, partial-execution mode for gateway-injected hidden tools. Happy to help test once a PR lands.

[ArjunPakhan]

Hi @luyufan498, thanks for outlining this enterprise scenario!

That makes complete sense for gateway-level hidden tools. Option A (this PR) serves as the foundational safety pass-through: it immediately fixes the server-side KeyError crash and restores client-side tool execution (Read, Bash, Edit) for agentic clients without introducing stateful turn-reassembly risks.

Supporting Option B (partial execution via message reassembly) requires tracking interleaved assistant/user turns server-side to strip injected tool_use/tool_result blocks from the turn returned to the client.

I propose we merge this PR as Phase 1 to unblock agentic clients and resolve the crash, and then implement Option B as a dedicated feature flag (e.g. mcp_partial_execution: true or require_approval: "partial") in a follow-up PR.

I'd be happy to collaborate on testing Option B once Phase 1 lands!

[ArjunPakhan]

PR Update

All 68 CI checks are now passing green:

• Linting & Type Discipline Gate: Resolved LIT002 violations via explicit inline annotations (type_discipline_gate passed cleanly).
• Codecov Patch Coverage: Passed at >72% with added unit test coverage for both client-side tool passthrough and server-side MCP auto-execution (tests/test_mcp_client_tool_passthrough.py).
• Formatting: Cleaned and verified via ruff.

The PR is fully tested, passing, and ready for maintainer review/merge when available!
@luyufan498

[ArjunPakhan]

Hey just checking in #37438
The PR is fully tested, passing, and ready for maintainer review/merge when available!

[Griffures]

Just got hit by this. Had to unleash LLM on source code to trace it back. +1 from me, then.