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