# mcp-debug-claude-desktop

**Filed as [anthropics/claude-code#83908](https://github.com/anthropics/claude-code/issues/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](BUG_REPORT.md).

## Quick start

```bash
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`:

```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](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

```bash
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](PROTOCOL.md#redaction) before attaching anything.

## Requirements

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

MIT — see [LICENSE](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.