MCP: Silent failures make server integration opaque and hard to debug

Summary

MCP server failures are currently silent or cryptic, making it very hard to diagnose why a server isn't working. Several related pain points:

---

Issues

1. Wrong config file location is silently ignored

Current behavior: If an MCP server is defined in ~/.claude/mcp/canny.json (a subdirectory) or .claude/settings.local.json, it is silently ignored. No error, no warning, no hint. The server simply doesn't appear.

Expected behavior: Warn the user if a file that looks like an MCP config is found in a non-standard location, or at least document clearly which file locations are scanned.

---

2. Protocol version mismatch causes a silent 30-second timeout

Current behavior: When a custom MCP server responds with an older protocolVersion (e.g. 2024-11-05) during the initialize handshake, Claude Code silently discards the response and waits ~30 seconds before timing out. No error is shown to the user.

Expected behavior: Log a specific error like:

MCP server "canny" handshake failed: server returned protocolVersion "2024-11-05", expected "2025-11-25"

This would have saved hours of debugging. The mismatch is easy to fix once you know it's the cause.

---

3. No visibility into MCP server startup or handshake

Current behavior: There is no way to see what happened during server startup — did the process launch? Did it crash? Did the handshake succeed or fail?

Expected behavior:

• /mcp or a new /mcp logs command should show per-server status: starting, connected, failed (reason), timed out
• Optionally: a --mcp-debug flag that streams server stderr and protocol messages to the terminal

---

4. --mcp-config failures are not surfaced

Current behavior: When --mcp-config <file> is passed and the server fails to start or handshake, there is no feedback. The tools just don't appear.

Expected behavior: On startup, print a summary of MCP servers loaded vs. failed, e.g.:

MCP servers: playwright ✓  canny ✗ (handshake timeout — run with --mcp-debug for details)

---

Impact

Users building or debugging custom MCP servers have no feedback loop. The combination of silent config location failures + silent protocol mismatches means a server can "fail" in two completely invisible ways before a single tool call is ever made.

Environment

• Claude Code CLI
• macOS (darwin 25.2.0)
• Custom stdio MCP server (TypeScript/tsx)