claude-code - 💡(How to fix) Fix MCP: Silent failures make server integration opaque and hard to debug [4 comments, 5 participants]

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. 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:

TL;DR

To improve diagnostics for MCP server failures, implement explicit error logging and feedback mechanisms for config file location issues, protocol version mismatches, and server startup or handshake problems.

Guidance

• Verify config file locations: Ensure that MCP server configurations are placed in standard, expected locations to avoid silent ignores.
• Implement protocol version checks: Log specific errors when protocol version mismatches occur during the initialize handshake to facilitate easier debugging.
• Enhance server startup visibility: Introduce a command or flag (e.g., /mcp or --mcp-debug) to provide real-time status updates on server startup, including success, failure, or timeout reasons.
• Surface --mcp-config failures: On startup, print a summary of loaded versus failed MCP servers, including reasons for failures to improve the feedback loop.

Example

// Example of logging a protocol version mismatch error
if (serverProtocolVersion !== expectedProtocolVersion) {
  console.error(`MCP server handshake failed: server returned protocolVersion "${serverProtocolVersion}", expected "${expectedProtocolVersion}"`);
}

Notes

The provided guidance focuses on enhancing error logging and feedback to address the silent failure issues. Implementing these changes should significantly improve the diagnostics for MCP server failures. However, the exact implementation details may vary based on the specific requirements and constraints of the Claude Code CLI and custom MCP servers.

Recommendation

Apply the suggested workarounds and enhancements to improve error logging and feedback for MCP server failures, as there is no clear indication of a fixed version that addresses these issues. This approach will provide immediate benefits in terms of diagnostics and debugging capabilities.