# codex-mcp-headers Codex HTTP MCP servers must use http_headers instead of ignored headers | | | |---|---| | **Severity** | warning (auto) | | **Autofix** | - | | **Since** | v0.21.0 | | **Repo Types** | codex-project | | **Category** | [OpenAI Codex](codex.md) | ## Why Codex's project `.codex/config.toml` uses `http_headers` for literal HTTP MCP headers and `env_http_headers` for environment-variable names. A server table carrying `headers` loads, but Codex ignores that field, so requests omit headers the author intended to send. This warning checks only `headers` on `[mcp_servers.]` tables with a string `url` and no `command`. It also reports the ignored field when `http_headers` is already present or the server is disabled. Other unknown fields, transport errors, and general server shape validation remain with Codex. JSON MCP files for plugins and other hosts are outside this rule. Verified with the released Codex CLI 0.159.3 offline `mcp get --json` command and its [server configuration parser](https://github.com/openai/codex/blob/rust-v0.159.3/codex-rs/config/src/mcp_types.rs). See the [official MCP documentation](https://developers.openai.com/codex/mcp) for supported header fields. ## Examples Incorrect: ```toml [mcp_servers.catalog] url = "https://catalog.example.test/mcp" headers = { "X-Client" = "release-review" } ``` Correct: ```toml [mcp_servers.catalog] url = "https://catalog.example.test/mcp" http_headers = { "X-Client" = "release-review" } env_http_headers = { Authorization = "CATALOG_AUTHORIZATION" } ``` ## How to fix Move intended literal header values into `http_headers`, merging with any existing table. Use `env_http_headers` when values name environment variables. Remove the ignored `headers` field after reviewing its contents. There is no autofix: moving the values changes which headers Codex sends, and existing canonical fields may need a manual merge. The warning is based on committed configuration; local project trust and user settings do not suppress it. ## Configuration ```yaml rules: codex-mcp-headers: enabled: auto # true | false | auto severity: warning ``` *Run `skillsaw explain codex-mcp-headers` to see this documentation and the rule's effective configuration in your terminal.*