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.

Related MCP server: my-mcp-server

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

What gets recorded

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

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.