chore(cli): document the real MCP timeout keys

[lukealvoeiro]

Gap

EXT-N100 (F/P2): The MCP docs describe a per-server timeoutMs key in mcp.json and a global mcp.callTimeoutMs setting in settings.json. Neither exists in the CLI. The only timeout keys the CLI reads are the per-server timeout (tool call timeout, ms) and connectTimeout (connect/initialize timeout, ms; added in factory-mono#17204 and previously undocumented). There is no global setting for the call timeout.

Evidence

Docs (before this PR)

• docs/cli/configuration/mcp.mdx:294: "| timeoutMs | number | Per-server override for the MCP tool call timeout in milliseconds. Falls back to the global default when omitted. |"
• docs/cli/configuration/mcp.mdx:483-515 ("MCP call timeout"): "Override the timeout per server with timeoutMs", "You can also set a global default via the mcp.callTimeoutMs setting in settings.json", followed by a resolution order (per-server timeoutMs, then global mcp.callTimeoutMs, then built-in default).
• docs/cli/configuration/settings.mdx:65: "| mcp.callTimeoutMs | Integer (milliseconds) | Built-in default | Global timeout for MCP tool calls. Overridden per-server by timeoutMs in mcp.json. ... |"
• JP mirrors: docs/jp/cli/configuration/mcp.mdx:294, :489-517; docs/jp/cli/configuration/settings.mdx:65.
• Introduced in #1175 (ce83e77, "configurable per-server and global call timeouts") and its review follow-up; the key names never matched the CLI.

Code (factory-mono)

• packages/common/src/settings/schema.ts:1602-1621: McpServerConfigSchema accepts timeout and connectTimeout (positive int, ms). It has no timeoutMs, and zod strips unknown keys silently.
• apps/cli/src/mcp/McpHub.ts:1850: timeout: server.config.timeout ?? MCP_CALL_TOOL_TIMEOUT_MS
• apps/cli/src/mcp/constants.ts:1: MCP_CALL_TOOL_TIMEOUT_MS = 3 * 60 * 1000
• connectTimeout: McpHub.ts:1029,1059 pass it as connectTimeoutMs. Stdio falls back to MCP_STDIO_SERVER_CONNECT_TIMEOUT_MS = 30 s (clients/stdio.ts:116, constants.ts:19). HTTP/SSE fall back to MCP_SERVER_CONNECT_TIMEOUT_MS = 10 s (clients/http/shared.ts:417 -> clients/shared.ts:38, constants.ts:14).
• Nothing in the CLI reads callTimeoutMs.

Live test (source-built CLI, isolated HOME, no network): a mock stdio MCP server whose tool sleeps 6000 ms, called via droid exec --auto high -m custom:mock "call the sleep tool" with a local mock model:

Config	Result	Elapsed
mcp.json "timeoutMs": 1500	slept ok (key ignored)	6069 ms
mcp.json "timeout": 1500	MCP error -32001: Request timed out	1557 ms
settings.json {"mcp":{"callTimeoutMs":1500}}	slept ok, no warning	6115 ms

All runs exited 0.

Why it matters

Users who follow the docs to raise or lower the timeout for slow tools get no effect and no warning, because the documented keys are silently dropped; the tool keeps the 3-minute default. connectTimeout, the fix for slow-starting servers that fail on the 10 s or 30 s connect deadline, was not documented anywhere.

Fix

• EN and JP mcp.mdx: rename timeoutMs to timeout in the schema table and the example, and document connectTimeout with its defaults (30 s stdio, 10 s http/sse). State the built-in 3-minute call timeout, and remove the mcp.callTimeoutMs example and the resolution-order list. The example value is now 600000, because the old 120000 was below the 3-minute default and would have shortened the timeout.
• EN and JP settings.mdx: remove the mcp.callTimeoutMs row.

Validation

• grep -rn "callTimeoutMs\|timeoutMs" docs returns nothing after the change.
• The #mcp-call-timeout anchor and the JP explicit anchor are kept.
• The docs repo has no lint or format tooling; the diff (4 files, +12/-40) was reviewed by hand and the code references were re-read in factory-mono.

Found by the scheduled CLI arguments audit (gap EXT-N100).

[factory-droid]

Droid finished @lukealvoeiro's task —— View job

---

LGTM. No actionable issues found in the MCP timeout documentation changes.

0 inline comments posted