Codex CLI 0.151.0 adds mcp_optional_startup_grace_ms, a top-level config.toml setting for the initial MCP tool catalog. Codex waits 1,000 milliseconds by default for optional MCP servers. Increase the value when valid tools are missing from the first turn because their servers initialize slowly. Set it to 0 only when you want Codex to wait for every optional server's own startup_timeout_sec.
Our position is that most teams should keep the default until measurements show a real discovery problem. A larger grace period makes the first catalog more complete, but it puts slow integrations back on the startup path.
What changed in Codex CLI 0.151.0
Codex can connect to local stdio MCP servers and remote Streamable HTTP servers. Each enabled server initializes, reports capabilities, and returns a tool list. Codex combines those lists with its built-in tools before the model starts working.
Waiting for every server produces a complete catalog, but one unavailable integration can delay the first turn. Proceeding immediately stays responsive, but a slow optional server may miss the initial catalog.
Version 0.151.0 makes that tradeoff configurable. The new setting controls how long initial tool discovery waits for optional servers as a group. OpenAI documents these semantics:
- Default value:
1000milliseconds. - Any non-negative integer is accepted.
- A positive value creates a bounded shared grace period.
- A value of
0disables the shared grace and waits according to each server'sstartup_timeout_sec.
The setting applies at startup and when MCP configuration refreshes. Changing it resets cached startup deadlines.
This is not a connection timeout and it does not make a server faster. It controls how long Codex waits while assembling the initial optional-tool snapshot.
The two timeouts solve different problems
The names are easy to confuse:
mcp_optional_startup_grace_ms = 2500
[mcp_servers.internal_docs]
command = "uvx"
args = ["internal-docs-mcp"]
startup_timeout_sec = 15
required = false
mcp_optional_startup_grace_ms is global. It limits how long optional servers may hold up the initial catalog. In this example, Codex gives optional discovery a shared 2.5-second window.
startup_timeout_sec belongs to one server. It controls how long that server may take to initialize before Codex treats startup as failed. Its documented default is 10 seconds.
The server can therefore have a 15-second initialization timeout while the initial catalog waits only 2.5 seconds. That is useful when the integration may become available later but should not block immediate work. It also explains why increasing only startup_timeout_sec may not make a slow optional tool appear in the first catalog.
The required field changes the contract. An enabled server with required = true must initialize, or Codex fails startup or resume. Leave it false for convenience integrations that are useful but not necessary for the task.
How to configure Codex MCP startup grace
First, upgrade and confirm the active version:
npm install -g @openai/codex@0.151.0
codex --versionOpen ~/.codex/config.toml for a user-wide setting, or add .codex/config.toml inside a trusted repository for project-specific behavior. The CLI and IDE extension share the same configuration layers.
Start with a modest measured increase:
mcp_optional_startup_grace_ms = 3000
[mcp_servers.github]
url = "https://example.internal/mcp"
required = false
startup_timeout_sec = 10
tool_timeout_sec = 60
Restart Codex, then inspect live MCP state:
/mcpConfirm that the expected server is active and its tools are listed. Then ask Codex to run one harmless read-only operation. A tool appearing in configuration does not prove that initialization and tools/list succeeded.
For a one-off experiment, use a CLI configuration override instead of editing the file:
codex -c mcp_optional_startup_grace_ms=3000Run the same test several times. Local stdio processes vary on cold package downloads, while remote HTTP servers vary with authentication and network latency.
If your agent workflow depends on several internal systems, Axentia's AI agent development service can help define which integrations belong on the critical path and which should remain optional.
A practical measurement method
Measure before raising the grace. For each optional server, record the time from Codex launch to the server becoming active and returning its tool list. Test warm and cold starts separately.
A small shell loop can capture total CLI startup behavior, although server-level logs provide the better breakdown:
for run in 1 2 3 4 5; do
/usr/bin/time -p codex --version >/dev/null
doneFor the actual MCP path, enable server-side timestamps around process start, initialization, and tools/list. For HTTP servers, add request timing at the gateway. Never print bearer tokens or complete environment blocks into shared logs.
Choose a grace close to the 95th percentile for integrations that should normally be ready on the first turn. Add a small margin, then cap the value. If most optional servers finish within 700 ms and one occasionally needs eight seconds, a global eight-second grace is the wrong fix. Optimize or reclassify that server.
We recommend tracking four outcomes:
- Time until the first prompt can run.
- Percentage of launches with the expected tools in the initial catalog.
- MCP initialization failures by server and transport.
- First-turn failures caused by a missing tool.
The target is not a perfectly complete catalog. It is the shortest wait that makes the tools required for normal first-turn work reliably available.
Troubleshoot missing MCP tools in order
A missing tool is not automatically a grace-period problem. Check the stages in sequence.
1. Confirm the server is configured
codex mcp list
codex mcp show internal_docsIf the server is absent or disabled, changing the grace cannot help. Fix the configuration layer first. Remember that project .codex/config.toml files load only for trusted projects.
2. Inspect the live session
Use /mcp in the Codex interface. If the server is active and tools are visible, the catalog is healthy. Test a read-only call before changing timeouts.
If the server is active but exposes no tools, inspect its tools/list response and any allow or deny lists. enabled_tools can restrict the catalog, while disabled_tools is applied afterward.
3. Separate startup from authentication
A remote server may start quickly but fail OAuth or bearer-token resolution. A stdio server may launch but miss an environment variable. These failures need credential or process fixes, not more waiting.
4. Increase the grace in small steps
Try 2,000 ms, then 3,000 or 5,000 ms. Repeat the same clean-start test. If the server still misses the catalog despite logs showing fast initialization, capture the version, transport, timing, and /mcp state for a reproducible issue.
Our MCP adoption analysis explains the broader cost of accumulating integrations without clear ownership. Startup latency is one operational symptom of that sprawl.
When to set the value to zero
This configuration is valid:
mcp_optional_startup_grace_ms = 0
It does not mean "wait zero milliseconds." OpenAI's schema says zero disables the shared grace, causing optional servers to use their configured startup_timeout_sec instead.
Use zero in a controlled workflow where the initial model turn must see every enabled optional tool and longer startup is acceptable. A dedicated repository-maintenance environment with a stable set of local servers may fit that pattern.
Do not use zero on developer machines with many remote or occasionally unavailable servers. With the default 10-second per-server timeout, startup can become noticeably slower. Mark genuinely essential servers as required, and keep convenience servers behind a bounded grace.
Production limits and tradeoffs
The new setting improves control, not observability. It does not provide a latency histogram, explain why a server missed the snapshot, or guarantee when late tools become useful to an already-running model turn. Teams still need server logs and a functional tool call.
The setting is global within a resolved configuration. You cannot assign separate shared grace periods to fast and slow servers. Per-server startup_timeout_sec controls failure timing, not separate catalog grace budgets.
Finally, a longer wait can hide an unhealthy integration. If a local server downloads packages on every start or a remote server performs slow authentication, raising the grace treats the symptom. Fix repeatable cold-start work, cache dependencies, and monitor the endpoint before expanding the startup budget.
When this setting is not worth changing
Leave the default alone when /mcp consistently shows the tools you use, the first prompt starts promptly, and missing-tool errors are rare. Configuration churn without a measured failure adds another variable to every developer environment.
It is also not the right fix for tools excluded by allow lists, an invalid command, a wrong URL, expired OAuth, missing environment variables, or a server that returns an empty tool list.
For teams new to the protocol, our MCP server guide covers the client, server, transport, and tool-discovery boundaries before you tune startup timing.
FAQ
What is the default mcp_optional_startup_grace_ms value?
Codex CLI 0.151.0 defaults mcp_optional_startup_grace_ms to 1,000 milliseconds. That is the shared window used while collecting tools from optional MCP servers for the initial catalog. Required servers have a different contract, and individual servers retain their own startup_timeout_sec setting.
Why are Codex MCP tools missing on the first turn?
The server may initialize after the optional startup grace expires, but timing is only one cause. The server can also be disabled, unauthenticated, excluded by tool filters, misconfigured, or returning an empty list. Check codex mcp list, /mcp, server logs, and one read-only call before increasing the grace.
Should mcp_optional_startup_grace_ms be set to zero?
Usually not. Zero disables the shared grace and makes Codex wait according to each optional server's startup_timeout_sec. Use it only when a complete initial catalog matters more than startup latency and every enabled server is controlled. A measured positive limit is safer for mixed local and remote integrations.
Tune the catalog, not the symptom
mcp_optional_startup_grace_ms gives Codex teams a useful control over first-turn readiness. Start at 1,000 ms, measure which tools miss the catalog, and raise the value only enough to cover healthy startup variation. Required integrations should fail clearly. Optional integrations should not make every session wait for their worst day.
If you need help designing a reliable MCP-backed agent workflow, book a call with Axentia. We can profile tool discovery, separate required dependencies from optional context, and build the checks that prove an integration is ready.