MCP Servers Not Initializing - Poor Error Messages and Troubleshooting Experience

Summary

MCP servers configured in .claude/settings.json fail to initialize with no helpful error messages. /mcp command only shows "No MCP servers configured" without explaining why.

Environment

• OS: macOS (Darwin 24.6.0)
• Claude Code version: Latest stable
• Provider: Vertex AI
• MCP servers attempted: mermaid, excalidraw, playwright, jira

Steps to Reproduce

1. Create .claude/settings.json with MCP server configurations
2. Create .claude/settings.local.json with "enableAllProjectMcpServers": true
3. Restart Claude Code (fully quit and reopen)
4. Run /mcp command
5. Result: "No MCP servers configured"

Configuration Files

.claude/settings.json:

{
  "mcpServers": {
    "mermaid": {
      "command": "npx",
      "args": ["-y", "mermaid-mcp-server"]
    },
    "excalidraw": {
      "command": "npx",
      "args": ["-y", "excalidraw-mcp"]
    },
    "playwright": {
      "command": "npx",
      "args": ["-y", "@playwright/mcp"]
    },
    "jira": {
      "command": "npx",
      "args": ["-y", "jira-mcp"]
    }
  }
}

.claude/settings.local.json:

{
  "enableAllProjectMcpServers": true
}

Expected Behavior

• MCP servers should initialize on startup
• Clear error messages if servers fail to start
• /doctor command should diagnose MCP issues
• Logs should be accessible showing what went wrong

Actual Behavior

• No servers initialize
• /mcp only says "No MCP servers configured"
• /doctor doesn't help diagnose the issue
• No clear logs or error messages
• Required 5+ full restarts with no progress
• Claude Code assistant made multiple incorrect troubleshooting suggestions

Impact

This is extremely frustrating for users:

• No feedback about what's wrong
• Time-consuming trial and error with restarts
• No way to diagnose the actual problem
• The AI assistant itself doesn't have visibility into the issue

Suggestions

1. Better error messages: Explain WHY servers aren't loading (e.g., "Config file not found", "Server failed to start: [error]", "Permission denied")
2. Diagnostic tools: /doctor should check MCP configuration and report specific issues
3. Logs: Make logs accessible showing MCP server initialization attempts
4. Real-time feedback: Show server status as they attempt to connect
5. AI agent improvement: The assistant should have access to diagnostic information to actually help troubleshoot

Additional Context

User has successfully used MCP servers (Playwright, Jira) in other Claude Code projects with Vertex AI, so the issue is project-specific and configuration-related, but completely opaque to debug.

---
Note: This experience has been extremely draining. The product needs better observability and error handling for MCP servers.