MCP server connection fails silently on VS Code extension startup
Bug Description
When launching Claude Code in VS Code, MCP servers configured in ~/.claude/settings.json sometimes fail to connect silently — no error message, no warning, no indication of failure. Claude proceeds without MCP tools and the user only discovers the failure when they try to use an MCP-dependent feature.
The same MCP server connects reliably from the CLI (claude in terminal), confirming the server itself is healthy. The issue is specific to the VS Code extension's startup MCP handshake.
Steps to Reproduce
- Configure a custom MCP server in
~/.claude/settings.jsonthat connects to backend services on startup (e.g., databases, vector stores) - Open VS Code
- Start a Claude Code session
- Check available tools — MCP tools are missing from the tool list
- Claude proceeds as if no MCP servers are configured
Expected Behavior
- MCP connection failure should surface a visible error or warning to the user
- Ideally, the extension should retry the MCP handshake if the initial attempt fails/times out
Actual Behavior
- MCP tools silently don't load
- No error message shown anywhere (not in output panel, not in notifications, not inline)
- Claude proceeds as if MCP servers don't exist
- The user has no way to know MCP failed without manually checking tool availability
- "Developer: Reload Window" consistently fixes the issue — the server connects successfully on the second attempt
Likely Cause
The MCP server process takes time to initialize (connecting to backend services, loading configs). If the MCP protocol handshake doesn't complete within the extension's startup timeout window, the connection is silently abandoned. On reload, backend services are already warm and the handshake succeeds immediately.
Current Workaround
Reload the VS Code window (Ctrl+Shift+P → "Developer: Reload Window") before starting every session. The second handshake attempt succeeds because backend services are already warm from the first (failed) attempt.
This works but shouldn't be necessary — users shouldn't have to develop rituals to work around silent failures.
Suggested Fixes
- Retry logic — Retry MCP handshake 2-3 times with exponential backoff on failure
- Visible error — Show a VS Code notification when an MCP server fails to connect (e.g., "Failed to connect to MCP server 'claude-memory'. Click to retry.")
- Lazy initialization — Defer MCP server connection to first tool invocation rather than extension startup
- Status indicator — Show MCP server connection status in the status bar so users can see at a glance if servers are connected
Environment
- OS: Windows 11 Pro (10.0.26200)
- VS Code: Latest stable
- Claude Code Extension: Latest
- MCP Server: Custom Python stdio server (connects to FalkorDB + Qdrant on localhost via Docker)
- Note: The exact same
settings.jsonconfig works 100% of the time from the CLI — this is VS Code extension-specific
This issue has 3 comments on GitHub. Read the full discussion on GitHub ↗