MCP_TIMEOUT ignored in GitHub Actions — forces slow pre-install workaround

Environment

• Claude Code Action: anthropics/claude-code-action@v1
• Claude Code version installed by action: 2.1.90
• Runner: ubuntu-latest
• MCP servers: figma-developer-mcp, mongodb-mcp-server (via --mcp-config)

What's Wrong

MCP_TIMEOUT is completely ignored when running Claude Code through claude-code-action in GitHub Actions. MCP servers configured via --mcp-config with npx commands never start — they time out silently and no tools are registered.

What Should Happen

Setting MCP_TIMEOUT=120000 (or any value) should give MCP servers enough time to download via npx and initialize before Claude starts.

What We Tried

We exhausted every approach we could find:

1. Step-level env: on the action step — ignored

```yaml

• uses: anthropics/claude-code-action@v1

env:
MCP_TIMEOUT: 120000
```

1. settings input with {"env": {"MCP_TIMEOUT": "120000"}} — ignored

1. GITHUB_ENV in a prior step (echo "MCP_TIMEOUT=120000" >> "$GITHUB_ENV") — ignored

1. Project-level .claude/settings.json with {"env": {"MCP_TIMEOUT": "120000"}} checked into the repo — ignored (the action uses the SDK, which doesn't seem to read project settings)

1. MCP_CONNECTION_NONBLOCKING=true — skips the wait entirely, but then Claude never sees the MCP tools at all

In every case, MCP servers configured via --mcp-config with npx fail to start. The run completes in ~45 seconds — well under the 120s timeout we set — confirming the timeout value is not being respected.

Evidence from binary analysis

We confirmed from the Claude Code binary that MCP_TIMEOUT is read as:

function vNT() {
  return parseInt(process.env.MCP_TIMEOUT || "", 10) || 30000;
}

The value is read from process.env at connection time, but it never reaches the subprocess when invoked through claude-code-action.

Desired approach

MCP servers should start via npx on demand — no pre-install overhead:

- name: Run Claude Code
  uses: anthropics/claude-code-action@v1
  with:
    claude_args: |
      --mcp-config '{"mcpServers":{"mongodb":{"command":"npx","args":["-y","mongodb-mcp-server","--readOnly"],"env":{...}}}}' 

With a respected MCP_TIMEOUT=120000, npx would have time to download and start the server. No wasted time on runs that don't need MCP tools.

Current workaround

The only thing that works is pre-installing MCP servers globally before the action runs:

- name: Pre-install MCP servers
  run: npm install -g figma-developer-mcp mongodb-mcp-server

- name: Run Claude Code
  uses: anthropics/claude-code-action@v1
  with:
    claude_args: |
      --mcp-config '{"mcpServers":{"figma":{"command":"figma-developer-mcp","args":["--stdio"],...}}}'

This adds 35-40 seconds to every GitHub Actions run, even when MCP tools aren't needed. It defeats the purpose of on-demand npx initialization.

What would fix this

1. Respect MCP_TIMEOUT — pass it through to the Claude CLI subprocess so npx-based servers have time to download and start
2. Or: lazy MCP initialization — don't block startup on MCP connections; connect servers in the background and make tools available when ready (mid-conversation)

Related issues

• #16837 — MCP_TIMEOUT not respected beyond 60s
• #7575 — same
• #41792 — documents MCP_CONNECTION_NONBLOCKING but it's unusable since tools never appear
• #40207 — Claude sends SIGTERM to healthy MCP servers

Better workaround: cache MCP servers

Caching the npm global install between runs reduces the overhead from 35-40s to ~3-4s (cache restore):

- name: Get MCP server versions
  id: mcp-versions
  run: |
    FIGMA_V=$(npm view figma-developer-mcp version)
    MONGO_V=$(npm view mongodb-mcp-server version)
    echo "key=mcp-servers--figma-developer-mcp@${FIGMA_V}--mongodb-mcp-server@${MONGO_V}" >> "$GITHUB_OUTPUT"

- name: Cache MCP servers
  id: mcp-cache
  uses: actions/cache@v4
  with:
    path: |
      /usr/local/lib/node_modules/figma-developer-mcp
      /usr/local/lib/node_modules/mongodb-mcp-server
      /usr/local/bin/figma-developer-mcp
      /usr/local/bin/mongodb-mcp-server
    key: ${{ steps.mcp-versions.outputs.key }}

- name: Install MCP servers
  if: steps.mcp-cache.outputs.cache-hit != 'true'
  run: npm install -g figma-developer-mcp mongodb-mcp-server

Cache auto-busts when either package publishes a new version. Still a workaround though — MCP_TIMEOUT should just work.