feat(mcp): add HTTP headers helper support

[mom-oai]

Internal Intake Note

This is a draft PR for an external contribution from Dennis Henry / Okta.

Per the Codex contribution guidelines, external code contributions are by invitation only. This PR should be treated as an intake/review thread until a Codex maintainer confirms that this change aligns with the intended MCP auth direction and should proceed.

Current branch state:

• External fork branch: dennishenry/codex:mcp_headers_helper
• Commit: a27251e (feat: add headersHelper support for codex)
• GitHub reports this branch cannot automatically merge into main
• Compare shows 29 files changed, with 1,395 additions and 37 deletions

Summary

Adds support for configuring an MCP streamable HTTP headers helper. The helper is a command that returns a JSON object of HTTP headers, allowing Codex to dynamically provide request headers for MCP servers that require externally generated auth headers.

The change wires http_headers_helper through:

• MCP config parsing and schema generation
• CLI add/list/get/login flows
• App-server MCP request processing
• MCP auth status and OAuth discovery/login paths
• rmcp-client default header construction
• External agent config migration from headersHelper

Notable Behavior

• Adds CLI flags for streamable HTTP MCP servers:
  • --http-headers-helper
  • --http-headers-helper-arg
  • --http-headers-helper-cwd
• Skips automatic OAuth discovery during codex mcp add when a headers helper is configured, so the helper is not run during add.
• Runs the helper when building default headers for MCP/OAuth flows.
• Requires helper output to be a JSON object with string values.
• Adds limits for helper stdout size, stderr size, header count, header value size, and timeout.
• Omits helper stderr from error messages to avoid leaking secrets.
• Restricts http_headers_helper to local streamable HTTP MCP servers.

Testing

The branch includes tests covering:

• Config parsing and serialization
• Config editing
• CLI add/list/get behavior
• OAuth discovery with helper-provided headers
• Helper execution, relative cwd resolution, invalid output, oversized output, and stderr redaction
• External .mcp.json migration from headersHelper

Review Requested

Please confirm:

• Whether this contribution was invited / should be accepted for review
• Whether this approach matches the desired MCP auth model
• Who should be the primary OpenAI maintainer for review
• Whether the external contributor should rebase and resolve merge conflicts before detailed review

[github-actions]

Thank you for your submission, we really appreciate it. Like many open-source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution. You can sign the CLA by just posting a Pull Request Comment same as the below format.

---

I have read the CLA Document and I hereby sign the CLA

---

_{You can retrigger this bot by commenting recheck in this Pull Request. Posted by the CLA Assistant Lite bot.}