Skip to content

MCP stdio servers hang indefinitely when child process fails to initialize #35287

@HerbHall

Description

@HerbHall

Problem

When a stdio-based MCP server fails to start (missing database file, npm package error, expired credential), Claude Code waits indefinitely for the MCP initialization handshake. There is no timeout, health check, or error detection. The user must manually cancel the session.

Reproduction

  1. Configure a stdio MCP server with an invalid path:
    "sqlite": {
      "type": "stdio",
      "command": "cmd",
      "args": ["/c", "npx", "-y", "mcp-sqlite", "C:/nonexistent/path/db.sqlite"]
    }
  2. Start a Claude Code session
  3. Call any tool from the sqlite MCP server (e.g., mcp__sqlite__query)
  4. Observe: the tool call hangs indefinitely with no error message

Expected Behavior

  • Startup timeout (e.g., 10-15s): if the MCP server doesn't complete the initialization handshake within a timeout, report an error and mark the server as unavailable
  • Tool call timeout: if a tool call doesn't return within a configurable timeout, return an error rather than hanging
  • Health detection: if the stdio process exits unexpectedly, detect the pipe closure and report it immediately

Impact

  • Any workflow or skill that calls MCP tools can hang the entire session
  • Automated agent workflows (dispatchers, background agents) get stuck permanently
  • User has no indication that the tool is hung vs. processing slowly

Environment

  • Claude Code 2.1.x on Windows 11 (MSYS/bash shell)
  • Affects all stdio MCP servers (memory, sequential-thinking, gitlab, context7, sqlite, etc.)
  • HTTP-based MCP servers (like Synapset) are not affected -- they timeout normally

Metadata

Metadata

Assignees

No one assigned

    Labels

    area:mcpbugSomething isn't workingplatform:windowsIssue specifically occurs on WindowsstaleIssue is inactive

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions