Codex http_headers_helper: send the Sume API key without storing it
Codex's http_headers_helper runs a local command that prints header JSON, so a Sume API key can come from a secret manager instead of config.toml.
Set http_headers_helper on the Sume server in ~/.codex/config.toml to a local command that prints a JSON object of header names and values, for example {"x-api-key": "..."} fetched from a secret manager. Codex's reference describes the key as a local command that prints a JSON object of header names (read 2026-10-02), and Sume accepts a key in x-api-key or an Authorization: Bearer header.
Four ways Codex can send a header
The Codex reference lists several HTTP options for a server. They differ in where the secret lives.
| Key | What the Codex docs say | Where the key lives |
|---|---|---|
http_headers | Static header name-value pairs | In config.toml, as text |
env_http_headers | Headers mapped to environment variables | In the shell environment |
bearer_token_env_var | Environment variable for the bearer token | In the shell environment |
http_headers_helper | Local command that prints a JSON object of header names | In the secret manager |
auth | Authentication method, oauth or chatgpt | Not a key route |
[mcp_servers.sume]
url = "https://mcp.sume.com/mcp"
http_headers_helper = "/usr/local/bin/sume-mcp-headers"
tool_timeout_sec = 90
# /usr/local/bin/sume-mcp-headers (chmod 700)
#!/bin/sh
printf '{"x-api-key": "%s"}' "$(my-secret-tool get sume-api-key)"Why use a helper over an env var
An environment variable is simple, but it is visible to every process the shell starts. A helper keeps the key in a store with its own access control and reads it only when Codex needs headers. Sume's docs say to rotate a key that appears in logs or chat history, and a helper that never prints the key to stdout outside the JSON line makes that less likely (OAuth and API keys).
Replace my-secret-tool with your own tool; the snippet is a shape, not a product. If the key could contain a double quote or a backslash, build the JSON with a tool that escapes it rather than printf.
What stays the same
The helper only changes where the header comes from. An API-key session still sees the full hosted tool set, paid tools need an idempotency_key, and dry_run and max_spend_usd are the preview and cap (MCP tools and gates). Pair the helper with the per-server approval settings if you want prompts on the paid tools.
Keep tool_timeout_sec above Sume's 55-second jobs_wait hold; Codex's documented default is 60 seconds.
Limits
Check the connection with mcp_health and tools_list, the read-only first calls in the MCP quickstart.
- The Codex page I read does not say how often the helper runs, so test it by checking
mcp_healthafter a restart. - A helper that fails or prints invalid JSON should be treated as a connection failure; check the helper by running it by hand.
- Sume's OAuth path is separate and does not use this key.
Sources
Related posts
More in Integrations
- Codex enabled_tools: allowlist only read-only Sume MCP tools
Codex's enabled_tools setting limits which tools a Sume MCP server exposes. Here is an allowlist of Sume's read tools, and why it matters most for API keys.
- Codex MCP required = true: fail fast when the Sume server is down
Codex's required = true makes startup fail if an enabled MCP server cannot initialize. When to set it for Sume, and how the 1000 ms grace and 10 s timeout work.
- Codex MCP per-tool approval_mode: always prompt on Sume generate_video
In Codex config.toml, tools.<tool>.approval_mode overrides the server default, so generate_video can prompt while jobs_status runs without asking.
- Convex HTTP action as a Sume webhook receiver: raw body, no retry
A Convex httpAction reads the raw body with request.text() and is not retried by Convex, so Sume's 10 delivery attempts and a job_id dedupe do the work.
Written by Sume