Support per-session MCP server configuration via exec options
Resolved 💬 2 comments Opened Jan 20, 2026 by 0xeb Closed Feb 23, 2026
💡 Likely answer: A maintainer (etraut-openai, contributor)
responded on this thread — see the highlighted reply below.
Problem Statement
When using the Codex SDK programmatically, there's no way to register MCP servers that are scoped to a single session. Currently, MCP servers must be registered globally via codex mcp add, which writes to ~/.codex/config.toml. This creates several issues:
- Global state pollution: Programmatically registered servers persist globally and are visible to all Codex sessions, including interactive CLI usage
- Cleanup burden: Applications must ensure cleanup via
codex mcp remove, which can fail if the process crashes unexpectedly - Concurrency issues: Multiple concurrent sessions require careful coordination of unique server names to avoid collisions
- No SDK support: The TypeScript SDK has no API for per-session MCP configuration
Proposed Solution
Add support for session-scoped MCP servers via the exec options:
// TypeScript SDK
const result = await codex.exec({
prompt: "Use my-calc__add to compute 5+3",
mcpServers: [
{ name: "my-calc", url: "http://127.0.0.1:8080/mcp" }
]
});
Or via CLI flags for the underlying process:
codex exec --mcp-server "name=my-calc,url=http://127.0.0.1:8080/mcp" "..."
Benefits
- Session-scoped servers automatically cleaned up when session ends
- No global config pollution
- Safe for concurrent usage without name coordination
- Enables cleaner programmatic MCP integration
Use Case
Applications that spin up ephemeral MCP servers (e.g., for tool augmentation) need those servers available only to specific Codex sessions, not registered globally where they affect other sessions or persist after the application exits.
2 Comments
Thanks for the detailed writeup. Right now MCP servers are only configured via mcp_servers in config, and the TS SDK doesn’t expose any per‑session MCP API.
One workaround on the CLI is to use per‑process config overrides, e.g.
codex exec -c 'mcp_servers.my_calc.url="http://127.0.0.1:8080/mcp"'.This feature request hasn't received any upvotes, so I'm closing it.