一个LiteLLM 自定义护栏，使OpenAI Codex CLI能够与不理解Codex的MCP工具格式的模型提供者合作。

问题所在

Codex CLI 通过非标准的 type: "namespace" 工具对象将其 MCP（模型上下文协议）服务器发送给模型。OpenAI 的 /v1/responses 端点能够理解该对象。而像 OpenRouter 这样的提供者则不理解。这些工具会被无声投放，永远无法到达模型，因此助手的行为就像没有工具一样。

一份法典请求如下：

修复

该护栏将每个命名空间平整成普通的type: "function"工具，名为mcp__ __ ，然后请求离开代理：

模型看到一个标准工具可以调用，工具调用则以同样的扁平名称返回。

为什么是护栏而不是第二个代理？ 因为 LiteLLM 自定义护栏可以从你已经运行的代理内部重写原始的 /v1/responses 请求主体。在 async_pre_call_hook 中变异 data 会一直传播到上游请求。这一点已在 litellm 1.105 的实验中得到验证。

litellm-guardrail-codex-mcp

A LiteLLM Custom Guardrail that lets OpenAI Codex CLI work with model providers that do not understand Codex’s MCP tool format.

The problem

Codex CLI sends its MCP (Model Context Protocol) servers to the model using a non-standard type: "namespace" tool object. OpenAI’s /v1/responses endpoint understands it. Providers such as OpenRouter do not. The tools are silently dropped and never reach the model, so the assistant behaves as though it has no tools at all.

A Codex request looks like this:

{
  "model": "claude-sonnet-4.5",
  "tools": [
    {
      "type": "namespace",
      "name": "mcp__filesystem",
      "tools": [
        { "name": "read_file", "description": "Read a file", "parameters": { "...": "..." } }
      ]
    }
  ]
}

The fix

This guardrail flattens each namespace into ordinary type: "function" tools named mcp____ before the request leaves the proxy:

{
  "tools": [
    {
      "type": "function",
      "name": "mcp__filesystem__read_file",
      "description": "Read a file",
      "parameters": { "...": "..." }
    }
  ]
}

The model sees a standard tool it can call, and its tool call comes back under that same flattened name.

Why a guardrail and not a second proxy? Because a LiteLLM custom guardrail can rewrite the raw /v1/responses request body from inside the proxy you already run. Mutating data in async_pre_call_hook propagates all the way to the upstream request. This was verified empirically against litellm 1.105.1 for both streaming and non-streaming requests: the mock upstream received mcp__filesystem__read_file as a type: "function" tool. No extra hop, no extra process, and /chat/completions traffic stays untouched.

Installation

uv pip install litellm-guardrail-codex-mcp

The guardrail module path is litellm_guardrail_codex_mcp.CodexMCPNamespaceGuardrail.

Configuration

Merge this into your LiteLLM proxy config (see examples/config.example.yaml):

guardrails:
  - guardrail_name: codex-mcp-namespace-compat
    litellm_params:
      guardrail: litellm_guardrail_codex_mcp.CodexMCPNamespaceGuardrail
      mode: [pre_call, post_call]
      default_on: true

Two settings here are mandatory:

Optional settings