Support per-session MCP server configuration via exec options
Resolved 💬 2 comments Opened Jan 20, 2026 by 0xeb Closed Feb 23, 2026
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.
This issue has 2 comments on GitHub. Read the full discussion on GitHub ↗