codex mcp add: add --header flag for streamable HTTP servers
Maintainers usually reply within 1 day
Nobody has claimed this yet.
Assessment
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Newbie friendliness
- 76/100
Research direction
Start in codex-rs/cli/src/mcp_cmd.rs near the existing --bearer-token-env-var argument, then trace how codex mcp add writes server settings into config.toml. The issue identifies http_headers as the destination field. Done means repeatable --header values are saved there and can configure a server with a required non-bearer header.
Written by the indexing model from the issue text.
Description
What variant of Codex are you using?
CLI
What feature would you like to see?
Use case
I'm trying to connect MCP servers that require non-bearer HTTP headers (e.g. X-MCP-Lockdown: true). For clients like claude code, I can do this via:
claude mcp add my-server --transport http --header "X-MCP-Lockdown: true" https://example.com/mcp
For Codex, codex mcp add has no --header flag. The only way to set static headers today is by manually editing ~/.codex/config.toml via http_headers — which was added in #5241. This makes it impossible to construct a fully self-contained setup command for servers that require non-bearer headers.
Suggestion
Add a --header "Name: Value" flag (repeatable) to codex mcp add, analogous to claude code's implementation. Example:
codex mcp add my-server \
--url https://example.com/mcp \
--header "X-MCP-Lockdown: true"
This would write the values into http_headers in config.toml, just as --bearer-token-env-var writes into bearer_token_env_var.
Affected servers
Servers that currently can't be fully configured via CLI due to required non-bearer headers include github-mcp-server (X-MCP-Lockdown) and others.
The --header flag could be added at line 352 of codex-rs/cli/src/mcp_cmd.rs, alongside the existing --bearer-token-env-var argument, and the parsed values written into the http_headers map in the server config — the same field added in #5241.
Additional information
No response
- Dominant language
- Rust
- Stars
- 130k
- Forks
- 20.5k
- Avg merge
- 1m
- Merged PRs (30d)
- 997
Getting set up
- No Dockerfile or Docker Compose file
- No pull request template
- Read the contributing guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
More from openai/codex
-
bug CLI config mcp
Difficulty 2/5 1-3 hours Newbie friendliness 82/100
Maintainers usually reply within 1 day
-
app bug context windows-os
Difficulty 2/5 1-3 hours Newbie friendliness 74/100
Maintainers usually reply within 1 day
-
bug CLI TUI windows-os
Difficulty 2/5 1-3 hours Newbie friendliness 68/100
Maintainers usually reply within 1 day
-
app bug
Difficulty 2/5 1-3 hours Newbie friendliness 67/100
Maintainers usually reply within 1 day
-
app-server documentation
Difficulty 2/5 1-3 hours Newbie friendliness 82/100
Maintainers usually reply within 1 day
Similar issues
-
documentation priority:p2 type:chore
Difficulty 2/5 1-3 hours Newbie friendliness 73/100
Maintainers usually reply within 1 day
-
dispatch:sol-high documentation
Difficulty 1/5 1-3 hours Newbie friendliness 85/100
carrick-sh/carrick#768 · 1 comment ·
Maintainers usually reply within 1 day
-
correctness postgres tursopg
Difficulty 2/5 1-3 hours Newbie friendliness 76/100
tursodatabase/turso#10442 ·
Maintainers usually reply within 1 day
-
Difficulty 1/5 Under an hour Newbie friendliness 82/100
ankitects/anki#5864 · 1 reaction ·
Maintainers usually reply within 2 days
-
area: config effort: S good first issue P3 type: bug
Difficulty 2/5 1-3 hours Newbie friendliness 70/100
ferenyl/azuredevopstui#63 ·