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

Silent failures are a class of behavioral opacity bug that are especially dangerous because they produce confident-looking output on degraded capability. The three scenarios here all share the same structure: the agent believes a tool is available, the user believes it is available, but it is not — and nothing says so.

Two things are missing across all three cases:

1. Named diagnostic events, not just log entries. Log entries get lost; they are not surfaced in the agent's operating context. Each failure type (wrong config location, protocol version mismatch, tool call error) should produce a named event that the agent can reason about. Something like: MCP server [name] failed to connect: protocol version mismatch (server: 2024-11-05, required: 2024-11-15). Proceeding without this server. That message should appear in the session, not only in a log.

2. Capability state is part of context. When an MCP server fails to load, the agent's effective capability set changes. The agent should know that, and so should the user. A session that starts with 3 MCP servers but only 2 connected is operating in a degraded state — that should be visible, not silent.

The 30-second timeout on protocol version mismatch is the most actionable quick fix: the handshake response includes the version, so the mismatch is detectable immediately. No reason to wait 30 seconds before raising the error.

Found 3 possible duplicate issues:

1. https://github.com/anthropics/claude-code/issues/45529
2. https://github.com/anthropics/claude-code/issues/39061
3. https://github.com/anthropics/claude-code/issues/34744

This issue will be automatically closed as a duplicate in 3 days.

• If your issue is a duplicate, please close it and 👍 the existing issue instead
• To prevent auto-closure, add a comment or 👎 this comment

🤖 Generated with Claude Code

This is a perfect example of what we call a "silent bomb" — the server fails in two completely invisible ways before a single tool call is ever made. Wrong config location? Silent. Protocol version mismatch? Silent 30-second timeout with no error message. It's death by a thousand silences.

The pattern we see repeatedly: AI tooling gives developers optimistic feedback (no errors = everything is fine) when the reality is the integration is broken. Traditional debugging tools can't help because there's nothing to debug — the failure is in the absence of behavior, not in incorrect behavior.

We've been building Open Code Review specifically to catch this class of issues. Our checks validate configuration completeness, flag missing required fields, and detect protocol/contract mismatches at the PR level — before code ever reaches production. The thesis is that AI-generated integration code has failure modes that look nothing like traditional bugs.

For anyone dealing with MCP integration issues: npx @opencodereview/cli scan . --sla L1 catches configuration gaps, missing error handling, and silent failure patterns that traditional linters completely miss.

The /mcp logs command suggestion is spot-on. Observability shouldn't be an afterthought for AI tool integrations.

+1 from the operator side of the line.

We maintain NEXO Brain, a stdio MCP server that exposes ~300 tools across four Claude hosts (Claude Code, Codex, Claude Desktop, and the NEXO Desktop runtime). We've hit every failure mode in this thread and the silent-timeout one is by far the most expensive. Three concrete patterns we've landed on that mitigate the current opacity — useful as a stopgap until Claude Code surfaces more diagnostics natively:

1. Write a session-start hook that probes the server and writes a status file. We run mcp__nexo__nexo_startup as the first tool call and persist {installed, protocol_version, handshake_ms, tools_registered} to ~/.nexo/coordination/session-briefing.txt. When the server silently times out, the hook output shows up as "missing" and the agent immediately knows to fall back instead of looping into a 30s stall.

1. Log the handshake from the server side, not the client side. Every MCP server we operate emits a JSONL startup line with protocol_version_client, protocol_version_server, negotiated_version, tools_count, startup_ms. When a version mismatch happens Claude Code reports nothing, but the server log shows the rejected initialize call immediately. This is the single biggest time-saver for the kind of 2024-11-05 vs. 2025-11-25 case described here — the server always knows it was spoken to; the client pretends it wasn't.

1. Ship a doctor tool inside the MCP server. We expose nexo_doctor which the agent can call to self-diagnose: it returns scanned config locations, loaded server registrations, handshake latency, and any quarantined tools. This is a workaround for the "where is it looking?" problem — instead of reverse-engineering Claude Code's config scan order we just teach the server to report what it observes about its own install.

For the specific asks in the issue I'd second (3) (/mcp logs) as the highest-ROI surface. The protocol-version mismatch alone is worth a dedicated error code — an unknown-but-silent 30s wait is the worst debugging experience in the whole MCP stack right now.

— Francisco (maintainer, NEXO Brain)

+1 on MCP servers: playwright ✓ canny ✗ (handshake timeout — run with --mcp-debug for details) - this is related to my #39061 - there needs to be at least some way for MCP server to complain in a way that the complaint makes it to the user that is not the "run in debug mode and review the logs" method.

Related to https://github.com/anthropics/claude-code/issues/16837. There used to be a claude mcp list --debug flag that logged the MCP verbose logs under ~/.claude/debug (and earlier even on the stdout (or stderr, I'm not sure) https://github.com/anthropics/claude-code/issues/7575).

Confirming this on Windows 11 + Claude Code 2.1.123. Just spent ~12 hours
debugging four stdio MCP servers stuck at ✗ Failed to connect in
claude mcp list. Filed the underlying bug as #54786 (cwd field ignored
on Windows).

Discoverability gap that this issue describes was the entire problem:

• claude mcp list says only ✗ Failed to connect
• A 380-line debug runbook ruled out 11 hypotheses across multi-day

sessions before the actual cause surfaced

• The cause appeared in 30 seconds once DEBUG=true claude mcp list was

run — the spawned Python interpreter's stderr (can't open file
'wrong\path\server.py') was the smoking gun all along

Suggestions worth folding in if/when this gets prioritized:

1. Surface the spawned server's stderr as part of the ✗ Failed to connect

line (or at minimum point users at DEBUG=true in the failure message)

1. Document MCP_CONNECTION_NONBLOCKING, CLAUDE_CODE_DEBUG_LOGS_DIR,

CLAUDE_CODE_DEBUG_LOG_LEVEL somewhere user-discoverable. Currently they
show up only in the bundled JS source.

1. The claude mcp list health check appears to send a quick initialize

handshake — when it fails, the only visible artifact is the binary
pass/fail. The captured stderr already exists in the debug logs; piping
the last line into the health-check output would be enough.

DEBUG=true claude mcp list - great, so getting debugging output is possible still (confirmed on 2.1.121 (Claude Code)).

I already see MCP_CONNECTION_NONBLOCKING, CLAUDE_CODE_DEBUG_LOGS_DIR and CLAUDE_CODE_DEBUG_LOG_LEVEL on https://code.claude.com/docs/en/env-vars.

@nratzan the 12-hour debugging session is a painfully recognizable story. We operate ~300 MCP tools across four Claude hosts and the silent-timeout variant of this issue is, by far, the most expensive failure mode to diagnose in production.

Your three suggestions are spot-on, especially #1 (surface stderr in the ✗ Failed to connect line). In our case, adding a self-diagnostic tool (nexo_doctor) inside the MCP server itself was the only reliable workaround — the server can introspect its own health and report it through the tool interface since the transport layer won't.

The cwd bug you filed as #54786 is a good catch. Worth noting that DEBUG=true as @marcindulak confirmed works, but it shouldn't take a debug flag to see why a server failed — that's exactly the UX gap this issue describes.

Thanks for the request. This is the same ask as #39061 (surface MCP startup errors and per-server logs). Consolidating tracking there.

This issue has been automatically locked since it was closed and has not had any activity for 7 days. If you're experiencing a similar issue, please file a new issue and reference this one if it's relevant.