mcp-debug-claude-desktop

Filed as anthropics/claude-code#83908.

A minimal instrumented MCP server for answering one question: when a tool call goes missing in Claude Desktop, where does it go?

Claude Desktop reports lost tool calls as "the local MCP server may be unresponsive, crashed, or not running." This repository checks that claim instead of believing it. For every message it records whether bytes arrived on stdin, whether they parsed, whether a handler ran, whether a response was written, and whether that write went through.

What it found

A tool call is dispatched only if its chat is the active chat at the moment of dispatch — which happens 5–45 seconds after you submit. Open a different chat in that window and the call is discarded: nothing reaches the server, no retry, no log entry anywhere in the client. Four minutes later the user is told the local server has crashed.

Ruled out with the measurement that refuted each: server crash, back-pressure, the approval dialog, deferred tool loading, Electron background throttling. Details in BUG_REPORT.md.

Quick start

npm install
npm run build
npm run test:backpressure     # verify the instrument before trusting it

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "mcp-debug": {
      "command": "/absolute/path/to/node",
      "args": ["/absolute/path/to/mcp-debug-claude-desktop/dist/server.js"]
    }
  }
}

Both paths absolute; command is the output of which node. Restart Claude Desktop, use a tool, then npm run analyse:

rpc_id  method / tool             stdin    parsed  handler   stdout        verdict
0       initialize                245 B    yes     —         162 B ok      complete
2       tools/call echo           108 B    yes     0 ms      87 B ok       complete

pid      ppid     requests  responses  blocked  role
37265    37257    10        10         0        active — 8 tool call(s)
37270    37266    2         2          0        handshake only — no tool call ever

  4 of 12 expected tool calls never reached any server process.

PROTOCOL.md is the full reproduction procedure.

The tools

Tool	Purpose
ping	Smallest round trip. Returns a per-process sequence number — an unbroken sequence proves the server never restarted
echo	Returns its text argument, so each chat is identifiable in the capture
sized_echo	Returns size_kb kilobytes of filler
slow_echo	Returns after delay_ms, separating a slow handler from a lost message

What gets recorded

One JSON object per line in captures/. Never to stdout — stdout is the protocol channel.

Record	Contents
session	pid, ppid, argv, node version, start time
raw	Bytes in both directions, before any parsing
parsed	The JSON-RPC message those bytes became
unparseable	Bytes that never became a message
handler	Start and end of each tool handler
write	The synchronous result of process.stdout.write(), with writableNeedDrain
blocked	Emitted immediately when a write does not go through
flushed	When the write completed, and how long it waited
lifecycle	stdin end/close/error, stdout EPIPE, signals

Two details the measurement depends on. stdin is teed through a PassThrough, with the capture listener registered before the transport's, so no byte is consumed before it is recorded. process.stdout.write is replaced, not wrapped — a wrapper's own buffer would report success while the real stdout was blocked, and the blocked record is written synchronously, because a client that stopped reading never fires drain.

Verifying the instrument

npm run test:backpressure

Runs the server against a consumer that never reads, and asserts the detector fires: 24 tool calls, 24 blocked writes, 1 delivered. An instrument that has never triggered cannot be trusted when it stays silent.

Layout

src/server.ts            the MCP server and its four tools
src/capture.ts           the capture file and the record formats
src/wire.ts              stdin tee and the stdout replacement
src/analyse.ts           npm run analyse
src/test/backpressure.ts npm run test:backpressure
samples/                 a small capture, plus the reference run behind the report
issues/                  the reports as submitted

Privacy

The tools are synthetic: they return fixed strings, filler, or their own arguments. captures/ is gitignored; the committed samples have paths replaced. Claude Desktop's own logs are different — they contain organisation and conversation UUIDs, and claude_desktop_config.json may contain API keys. See PROTOCOL.md before attaching anything.

Requirements

Node ≥ 20. One dependency, @modelcontextprotocol/sdk, pinned to 1.30.0.

MIT — see LICENSE.

---

I am currently looking for a new position; if this is the kind of work you need, you can reach me at sascha.rose@gmail.com.