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:

  1. Global state pollution: Programmatically registered servers persist globally and are visible to all Codex sessions, including interactive CLI usage
  2. Cleanup burden: Applications must ensure cleanup via codex mcp remove, which can fail if the process crashes unexpectedly
  3. Concurrency issues: Multiple concurrent sessions require careful coordination of unique server names to avoid collisions
  4. 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.

View original on GitHub ↗

This issue has 2 comments on GitHub. Read the full discussion on GitHub ↗