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

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.<name>] 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. See the official MCP documentation for supported header fields.

Examples

Incorrect:

[mcp_servers.catalog]
url = "https://catalog.example.test/mcp"
headers = { "X-Client" = "release-review" }

Correct:

[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

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.