[BUG] MCP servers start before settings.local.json env vars are applied (race condition)

Preflight Checklist

• [x] I have searched existing issues and this hasn't been reported yet
• [x] This is a single bug report (please file separate reports for different bugs)
• [x] I am using the latest version of Claude Code

What's Wrong?

When Claude Code starts, MCP servers are launched in parallel before environment variables from settings.local.json env field are fully applied to the process environment. This causes MCP servers that use ${VAR} interpolation in their env block (in .mcp.json) to receive empty/undefined values instead of the actual secrets.

The behavior is non-deterministic — servers launched earlier in the startup sequence fail, while servers launched later (after env vars are loaded) succeed. The order of failure is consistent across restarts, suggesting a timing issue rather than random behavior.

What Should Happen?

All environment variables from settings.local.json (and settings.json) env field should be fully loaded and applied before any MCP servers are started. The ${VAR} interpolation in .mcp.json should always resolve correctly.

Steps to Reproduce

1. Define multiple passwords in .claude/settings.local.json:

{
  "env": {
    "PASSWORD_A": "secret_a",
    "PASSWORD_B": "secret_b",
    "PASSWORD_C": "secret_c"
  }
}

1. Configure 3 MCP servers in .mcp.json using ${VAR} interpolation:

{
  "mcpServers": {
    "server_a": {
      "command": "npx",
      "args": ["-y", "@liangshanli/mcp-server-mysql"],
      "env": {
        "MYSQL_HOST": "host_a",
        "MYSQL_PASSWORD": "${PASSWORD_A}"
      }
    },
    "server_b": {
      "command": "npx",
      "args": ["-y", "@liangshanli/mcp-server-mysql"],
      "env": {
        "MYSQL_PASSWORD": "${PASSWORD_B}"
      }
    },
    "server_c": {
      "command": "npx",
      "args": ["-y", "@liangshanli/mcp-server-mysql"],
      "env": {
        "MYSQL_PASSWORD": "${PASSWORD_C}"
      }
    }
  }
}

1. Start Claude Code (claude)
2. Try to use each MCP server — first 1-2 servers fail with authentication errors (password received as empty or literal ${VAR}), the last server works
3. Manually reconnect failed servers via /mcp → they work immediately (env vars are now loaded)

Observed Behavior

| Server | On startup | After /mcp reconnect |
|--------|-----------|----------------------|
| server_a | Access denied (password not interpolated) | Works |
| server_b | Access denied (password not interpolated) | Works |
| server_c | Works (env vars loaded by this time) | Works |

Error Messages/Logs

MCP error -32603: Access denied for user 'myuser'@'x.x.x.x' (using password: YES)

The "using password: YES" confirms a password was sent, but it was either empty or the literal string ${VAR} rather than the resolved value.

Workaround

After Claude Code starts, manually reconnect affected MCP servers via /mcp dialog. At that point env vars are fully loaded and ${VAR} interpolation works correctly.

Claude Model

Opus 4.6

Is this a regression?

I don't know

Claude Code Version

2.1.79

Platform

Anthropic API (Max subscription)

Operating System

Linux (Ubuntu 24.04, kernel 6.8.0-106-generic)

Terminal/Shell

bash

Additional Information

Related issues:

• #27190 — /doctor doesn't check settings.json env field (similar env loading order issue)
• #18692 — claude mcp add expands ${VAR} placeholders (related env var handling)

Root cause hypothesis: MCP server startup is initiated before or concurrently with loading/applying the env field from settings files. The fix would be to ensure env vars are fully resolved and set in process.env before any MCP server processes are spawned.

---

🤖 Generated with Claude Code