How to Set Claude Code MCP Startup Timeout

The one-line answer

Use CLAUDE_CODE_MCP_STARTUP_WAIT_MS=5000 claude -p "Run the scheduled check" to allow up to five seconds of first-turn MCP startup waiting. Use CLAUDE_CODE_MCP_STARTUP_WAIT_MS=0 when the job can begin without any MCP server being ready.

Claude Code 2.1.274 introduced this variable on September 17, 2026. The release note defines two things precisely: the value is a millisecond bound on the first non-interactive turn, and 0 means do not wait. It does not publish a default for the new variable. Set it explicitly in unattended jobs so a future default or machine-level environment does not silently change your startup policy.

Non-interactive means a run started with -p or --print, such as a CI check, a cron job, or an SDK-driven task. Interactive terminal sessions are not the target of this switch.

The practical rule is simple:

Those ranges are operating recommendations, not Anthropic defaults. Measure your own servers before standardizing them.

What the startup wait actually controls

Think of the first turn as a train departure and each MCP server as a connecting platform. CLAUDE_CODE_MCP_STARTUP_WAIT_MS decides how long the train stays at the station for connecting passengers. It does not decide how long each passenger may keep trying to reach the station, how long work takes after boarding, or when the whole journey must end.

That narrow scope is the point. Before 2.1.274, operators often reached for MCP_TIMEOUT, which controls a different clock. Now a scheduled job can choose a short first-turn readiness window without pretending every server connection or later tool call has the same deadline.

Four clocks, four different failure decisions

The safest setup names each clock and gives it one job.

There is also MCP_CONNECT_TIMEOUT_MS, a 5,000 ms default for a blocking startup connection batch. It applies to blocking startup behavior such as MCP_CONNECTION_NONBLOCKING=0 or a server marked alwaysLoad: true. Anthropic's environment variable reference explicitly distinguishes it from MCP_TIMEOUT.

For tool calls, a timeout field on one server in .mcp.json overrides MCP_TOOL_TIMEOUT for that server. That is useful when a data warehouse query reasonably needs longer than a ticket lookup. It still does not change the new first-turn wait.

This distinction also explains why 0 is not a universal speed switch. With tool search enabled, if the prompt later needs a server that is still connecting, Claude Code waits inside ToolSearch. With tool search disabled, it uses WaitForMcpServers. Skipping the front-door wait can move the wait deeper into the job.

A runnable slow-server test

You can reproduce the boundary with a local stdio server that delays only its MCP initialization response. Save this as slow-mcp.mjs:

import readline from "node:readline";

const delay = Number(process.env.SLOW_MCP_DELAY_MS || 5000);
const lines = readline.createInterface({ input: process.stdin });
const send = message => process.stdout.write(JSON.stringify(message) + "\n");

lines.on("line", line => {
  const request = JSON.parse(line);
  if (request.method === "initialize") {
    setTimeout(() => send({
      jsonrpc: "2.0",
      id: request.id,
      result: {
        protocolVersion: request.params.protocolVersion,
        capabilities: { tools: {} },
        serverInfo: { name: "slow-ready", version: "1.0.0" }
      }
    }), delay);
  } else if (request.method === "tools/list") {
    send({ jsonrpc: "2.0", id: request.id, result: { tools: [] } });
  }
});

Point Claude Code at it with slow-mcp.json:

{
  "mcpServers": {
    "slow-ready": {
      "type": "stdio",
      "command": "node",
      "args": ["./slow-mcp.mjs"],
      "env": { "SLOW_MCP_DELAY_MS": "5000" }
    }
  }
}

Run it with CLAUDE_CODE_MCP_STARTUP_WAIT_MS=1000 MCP_TIMEOUT=10000 claude -p "Reply with OK." --mcp-config ./slow-mcp.json --strict-mcp-config --output-format stream-json --verbose.

The --strict-mcp-config flag keeps unrelated user and project servers out of the test. The stream format exposes the early system/init event, including each MCP server's name and status. It also exposes mcp_server_errors when a supplied configuration is invalid.

What the local check showed

A pre-auth startup check on Claude Code 2.1.274 used that 5,000 ms server. Because the environment was not logged in, the run stopped at authentication. The measurement covers startup only, which is exactly the boundary under test.

The wall times include Claude Code and npx startup overhead, so they are not values to copy into a service objective. The useful result is categorical: 0 and 1,000 ms released the first-turn gate while the server was pending, and 7,000 ms allowed the same server to report connected. Nothing here measures model latency or total job duration.

Make readiness explicit before business work

A timeout only answers, "How long will we wait?" A production job must also answer, "Which tools are required?"

Use a two-part gate:

1. Before launching the business task, health-check each required remote endpoint or local server command. For configured and approved servers, claude mcp list reports statuses such as connected, needs authentication, or failed to connect.
2. In the Claude Code stream, inspect system/init.mcp_servers. Require the named server to have status: "connected", and reject a non-empty mcp_server_errors entry for that server. Treat cached or optional servers according to an explicit allowlist.

If the required server is pending, terminate the run before accepting any business result. If it is optional, log the degraded mode and continue. This makes the wait setting a policy input, not the policy itself.

Discovery caching deserves special care. A remote server with a cached tool list can appear as pending at initialization and connect on its first tool call. That behavior is useful for optional tools, but it does not satisfy a hard readiness promise. A required-tool gate should demand a live connection or perform its own health check.

Finally, wrap the complete process in a scheduler-level deadline. The startup wait cannot stop a model request, Bash command, hook, or later MCP tool call from consuming the rest of the run window.

The business math is mostly about failure speed

The compute savings are real but easy to exaggerate. Suppose 10,000 monthly jobs would otherwise spend a full 30 seconds waiting and you set a 3-second first-turn budget. The maximum reclaimed capacity is 4,500 runner minutes.

GitHub currently lists a standard 2-core Linux hosted runner at $0.006 per minute and a macOS runner at $0.062 per minute. At those rates, 4,500 minutes represents $27 of Linux time or $279 of macOS time before included minutes. GitHub also rounds each job's usage up to a whole minute, so a 27-second improvement may not change the bill at all if the total run stays in the same billing bucket.

The larger payoff is operational. A job that fails its readiness check in three seconds gives the scheduler time to retry, page the right owner, or switch to a fallback. A job that quietly starts without its database or issue tracker can generate a plausible but incomplete result, which costs more to detect and unwind than the runner time.

If you are also controlling large responses, the Claude Code tool-output limit guide covers the separate output side of the workflow. For unattended installs and network policy, pair this readiness gate with per-command network access.

Seven workflows that benefit most

1. Scheduled finance and operations reports

A finance operator runs a 6 a.m. report that needs a warehouse MCP server. Mark that server required, give its measured cold start a small margin, and stop if it is not connected. The payoff is not merely a faster run. It prevents a polished report built from repository files while the live numbers were unavailable.

2. Automated pull-request risk checks

A platform team runs Claude Code on every high-risk pull request and expects tools from GitHub, an issue tracker, and a security scanner. The gate can require the scanner and GitHub while treating the issue tracker as optional. Developers get a fast, explainable failure instead of a review that silently omitted the most important evidence.

3. Release coordination jobs

A release manager uses a scheduled agent to compare merged work, open incidents, and deployment status. Each source can have a named readiness rule. If the deployment MCP server is down, the job stops before drafting release notes that imply a release is safe.

4. Overnight support triage

A support team lets a job group tickets, inspect account history, and draft replies. The helpdesk and customer-data servers are required; Slack may be optional. A bounded wait keeps the queue moving, while the readiness rule keeps private customer context from being guessed when a source is missing.

5. Incident-response assistants

An on-call engineer starts a non-interactive diagnostic run from an alert. A short startup budget exposes whether logs and metrics are actually reachable. If either required server is unavailable, the wrapper can route to the manual runbook immediately instead of spending the incident window on a partial diagnosis.

6. Autoscaled ephemeral runners

A team launches fresh containers for every agent job. Local stdio servers may pay cold-start costs for package loading, authentication helpers, or schema discovery. Measuring those starts separates an honest seven-second readiness budget from a permanent workaround for an unhealthy server.

7. Multi-tenant agent products

A product serves customers with different MCP connections. One tenant may require Salesforce, another Linear, and another no external tools. A per-run required-server list lets the same orchestration layer choose a short wait for each tenant without making the slowest integration everybody's default.

Three things worth building

1. MCP readiness gate for Claude Code CI

This is the strongest opportunity. The product is a small runner wrapper that reads the required-server policy, starts Claude Code with an explicit wait, records system/init, and returns a machine-readable readiness failure before accepting the agent's result.

The demand is narrow but commercially meaningful: claude code automation shows about 140 US searches a month, a 200% yearly rise in the suggestion data, and a $10.88 CPC. People also ask how to let Claude Code run automatically and how to configure Claude Code with MCP. Those are direct expressions of the setup problem.

The smallest sellable version is a CLI with a policy file, GitHub Actions annotations, and JSON evidence for each run. The catch is distribution. Anthropic can add richer native readiness policies, so the durable value must be cross-run history, alerts, and support for several agent runtimes.

2. Timeout policy linter

This tool would scan shell scripts, CI files, settings, and .mcp.json, then flag mixed-up clocks: a zero startup wait with required tools, a short job deadline paired with a 28-hour tool timeout, or an unbounded optional integration.

The exact keyword mcp server timeout has about 10 US searches a month and a reported yearly trend of -67%. A related search is MCP_TOOL_TIMEOUT, and people ask how to increase the Claude Code timeout. That is enough demand for a feature inside the readiness gate, not enough for a standalone company.

An MVP needs parsers for GitHub Actions, common shell syntax, and Claude Code MCP configuration, plus opinionated fixes. The catch is false confidence: static config cannot know a server's real cold-start distribution without runtime measurements.

3. Scheduled-agent startup telemetry

This product would turn system/init events into a timeline of connection latency, pending states, invalid configs, and degraded runs. Platform teams would pay for trends and alerts across many repositories rather than reading JSONL files by hand.

It shares the 140 monthly searches for claude code automation, while claude code browser automation adds another 40 and also shows a 200% yearly rise in the suggestion data. The broader signal is teams moving Claude Code into repeatable jobs, where startup evidence becomes an operations problem.

The MVP is an event collector, a required-versus-optional server map, and alerts when readiness crosses a service objective. The catch is data sensitivity. MCP names and tool metadata can reveal internal systems, so redaction and self-hosting are part of the product, not enterprise polish for later.

Limits and the honest take

This control solves one small, valuable part of reliable automation. It does not repair a broken MCP server, authenticate an expired connector, shorten a later tool call, or stop the entire Claude Code process.

Do not use 0 for a job whose first useful action requires MCP. It can expose pending at initialization, and the wait may return when the tool is searched for. Do not raise the value until flaky servers look healthy either. HTTP and SSE servers retry transient first-connection failures, but authentication and not-found errors require configuration changes. A longer wait only delays that truth.

Stdio servers also do not automatically reconnect after a mid-session drop. A generous startup window says nothing about their health ten minutes later.

The best policy is strict and boring: a short explicit first-turn wait, named required servers, a status gate, a separate tool timeout, and an outer job deadline. That stack produces useful failures instead of mysterious delays.

On Monday, pick one scheduled Claude Code job, measure its required MCP cold starts, set the smallest honest wait, and make a pending required server fail before the result is trusted. If you want that reliability layer built across your agent workflows, I can help with the production system.