[DOCS] Headless MCP startup docs omit `MCP_CONNECTION_NONBLOCKING` and `--mcp-config` wait behavior

Documentation Type

Missing documentation (feature not documented)

Documentation Location

https://code.claude.com/docs/en/headless

Section/Topic

Non-interactive -p startup behavior when MCP servers are loaded, especially MCP_CONNECTION_NONBLOCKING=true and how --mcp-config connections affect startup time

Current Documentation

The headless docs currently say:

Add the -p (or --print) flag to any claude command to run it non-interactively. All CLI options work with -p, including: --continue for continuing conversations --allowedTools for auto-approving tools * --output-format for structured output

Add --bare to reduce startup time by skipping auto-discovery of hooks, skills, plugins, MCP servers, auto memory, and CLAUDE.md.

| MCP servers | --mcp-config <file-or-json> |

The CLI and MCP docs add only:

--mcp-config | Load MCP servers from JSON files or strings (space-separated)

MCP_TIMEOUT | Timeout in milliseconds for MCP server startup

Configure MCP server startup timeout using the MCP_TIMEOUT environment variable (for example, MCP_TIMEOUT=10000 claude sets a 10-second timeout)

No current page documents MCP_CONNECTION_NONBLOCKING, and the existing -p / --mcp-config docs do not explain the MCP connection wait behavior for headless startup.

What's Wrong or Missing?

Changelog v2.1.89 says:

Added MCP_CONNECTION_NONBLOCKING=true for -p mode to skip the MCP connection wait entirely, and bounded --mcp-config server connections at 5s instead of blocking on the slowest server

A. MCP_CONNECTION_NONBLOCKING is undocumented

No current https://code.claude.com/docs/en/env-vars entry or headless example tells users that MCP_CONNECTION_NONBLOCKING=true exists or that it changes -p startup by skipping the MCP connection wait entirely.

B. Headless --mcp-config wait semantics are undocumented

The docs explain that --mcp-config loads MCP servers and that MCP_TIMEOUT controls MCP startup timeout, but they do not explain the -p-specific behavior change from v2.1.89: headless startup now uses a bounded wait for --mcp-config server connections instead of blocking on the slowest server.

That leaves scripted users guessing about why claude -p with MCP starts faster, how long it waits before proceeding, and when they should use MCP_CONNECTION_NONBLOCKING=true instead of relying on the default behavior.

Suggested Improvement

Update the headless, CLI, MCP, and env-var docs together:

1. Add MCP_CONNECTION_NONBLOCKING to https://code.claude.com/docs/en/env-vars with a short description that it applies to -p mode and skips the MCP connection wait.
2. In https://code.claude.com/docs/en/headless, document what happens when claude -p is launched with MCP servers, including that --mcp-config no longer blocks indefinitely on the slowest server.
3. In https://code.claude.com/docs/en/cli-reference or https://code.claude.com/docs/en/mcp, clarify the bounded-wait behavior introduced in v2.1.89 and how it relates to the existing MCP_TIMEOUT setting.
4. Add one script-oriented example, for example:

MCP_CONNECTION_NONBLOCKING=true claude -p --mcp-config ./mcp.json "Summarize the repo"

If the docs team does not want to hardcode the current 5-second value, the docs should still say that -p now uses a short bounded wait instead of waiting for the slowest MCP server.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

| Page | Line(s) | Context |
|------|---------|---------|
| https://code.claude.com/docs/en/headless | 25-29, 37-55 | -p docs list CLI options, recommend --bare for startup speed, and mention --mcp-config, but not MCP connection-wait behavior |
| https://code.claude.com/docs/en/cli-reference | 70, 80 | CLI flag table lists --mcp-config and --print without explaining headless MCP wait semantics |
| https://code.claude.com/docs/en/env-vars | 170-172 | Env vars page documents MCP batch-size and timeout controls, but not MCP_CONNECTION_NONBLOCKING |
| https://code.claude.com/docs/en/mcp | 339-345 | MCP docs mention MCP_TIMEOUT only, not the -p-specific nonblocking and bounded-wait behavior |

Total scope: 4 pages affected

Source: Changelog v2.1.89

Changelog entry:

Added MCP_CONNECTION_NONBLOCKING=true for -p mode to skip the MCP connection wait entirely, and bounded --mcp-config server connections at 5s instead of blocking on the slowest server