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
- 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"]
}
- Start a Claude Code session
- Call any tool from the
sqlite MCP server (e.g., mcp__sqlite__query)
- 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
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
sqliteMCP server (e.g.,mcp__sqlite__query)Expected Behavior
Impact
Environment