MCP Integration

MCP Integration — Title: MCP Integration

# MCP Integration

Open CLI Codex supports the **Model Context Protocol (MCP)** — but there's one important constraint to know upfront.

## Constraint: only active with the `commandcode` provider

```python
def mcp_is_active() -> bool:
    """MCP only works when the active provider supports it (commandcode)."""
    return bool(_prov().get("mcp_capable"))

MCP only activates when the currently active provider has the mcp_capable flag — right now, only Command Code has this flag in the registry. If you're on another provider (Fireworks, Cohere, Cerebras...), /mcp won't work.

Why there's no default MCP server

# Default MCP servers — empty. Web search is already available via the
# internal `websearch` tool (SearXNG HTML scrape + DDG fallback), so no
# default MCP server is needed.
_DEFAULT_MCP_SERVERS: dict = {}

Web search is already served by the internal websearch tool (see Agent Tools), so MCP doesn't need any default server — you add servers as needed.

MCP server configuration

Stored in config.json, under the mcp_servers key:

{
  "mcp_servers": {
    "<name>": {
      "transport": "http",
      "url": "https://...",
      "headers": { "...": "..." },
      "enabled": true
    }
  }
}

Managing via slash command

/mcp list      # list configured servers + status
/mcp add       # add a new server
/mcp remove    # remove a server
/mcp refresh   # refresh a server's tool cache

How MCP tools are exposed to the model

Each MCP server's tools are merged into the api_tools list sent to the model as function-tools, named following the convention:

mcp__<server_name>__<tool_name>

When the model calls a tool matching this pattern, _dispatch_tool routes the request to _mcp_call_tool(), which forwards it to the correct MCP server via JSON-RPC 2.0 (HTTP transport).

Status & errors

The 03_mcp.py module keeps 3 in-session caches:

Variable	Content
_MCP_TOOL_CACHE	{server_name: [tool_dict, ...]} — tools discovered from each server
_MCP_STATUS	{server_name: "connected"|"error"|"unauthorized"}
_MCP_LAST_ERROR	{server_name: "HTTP 403: ..."} — most recent error detail

/mcp list reads directly from these caches to display connection status.

➡️ See supported providers overall: Providers