mcp_servers.<id>.startup_timeout_sec

Values

Any number of seconds. The config reference describes it as “Override the default 10s startup timeout for an MCP server.”

Key	What it does	Default
startup_timeout_sec	Seconds Codex waits for the server to start	10
startup_timeout_ms	Same setting in milliseconds, listed in the docs as an alias	n/a (alias)

Set it per server, inside that server’s block:

[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]
startup_timeout_sec = 30

When to change it

Raise it when a server is slow to boot, and the two big cases are both npx-shaped:

1. npx cold starts. First run downloads the package before the server begins answering. On Windows this regularly blows past 10 seconds. #2555 is a long thread of Windows 11 users hitting MCP client for context7 failed to start: request timed out with Context7 via npx.
2. A lot of servers at once. In #6020 (still open) all ten of the reporter’s servers fail the initialize handshake together. A bigger startup window is the first cheap thing to try before rearranging the whole config.

30 is a sane bump. Go to 60 on a slow machine or when antivirus scans every node process.

Gotchas

• The docs don’t say exactly what the window covers — process launch, the initialize handshake, tool listing, or all three. From the error strings in the issues (“request timed out”, “handshaking with MCP server failed”), it at least spans the handshake.
• The docs also don’t say which key wins if you set both startup_timeout_sec and startup_timeout_ms. Pick one and delete the other.
• A timeout bump won’t fix program not found. That means Codex can’t locate the command at all, and on Windows the usual answer is launching npx through cmd, as users tried in #2555.
• This key only covers startup. Slow tool calls after boot hit tool_timeout_sec instead, which defaults to 60 seconds.

Related settings

• mcp_servers.<id>.tool_timeout_sec: the per-tool-call timeout, default 60 seconds. Startup and tool calls time out independently.
• mcp_servers.<id>.required: per the config reference, setting it to true makes Codex fail startup entirely if that enabled server can’t initialize. Worth knowing before you point it at a flaky server.
• mcp_servers.<id>.enabled: turn a misbehaving server off without deleting its block while you debug.