mcp-debug-claude-desktop: Instructions file for Claude Code

CLAUDE.md — mcp-debug-claude-desktop

Guidance for working in this repository. Read this fully before writing code. It contains measurements that are expensive to repeat and hypotheses that are already refuted — re-testing them is wasted work.

What this project is

A minimal, self-contained reproduction of a bug in Claude Desktop's MCP client: with several chats open, tool calls are lost — some are never sent to the server, and at least one response that the server demonstrably wrote to stdout never reached the client. In every case the user is told the server is unresponsive or has crashed, which it is not.

The deliverable is a public GitHub repository that Anthropic can clone and run in a few minutes, plus a bug report written from its output.

This repo contains no journal, no domain logic, no product. Its only job is to make one protocol-level question answerable: where does the message go?

Origin — what has already been measured

The bug was found on 2026-08-04 while operating an unrelated personal MCP server (ai-journal-mcp, a private journaling server). That server already carries structured instrumentation, which is how the following is known. Do not re-derive any of it.

The incident

Environment of that incident: Claude Desktop 1.24012.11 (macOS 26.5.2, arm64), Node v25.9.0, @modelcontextprotocol/sdk 1.29.0 — one version below the one this repository pins. The controlled runs of 2026-08-04 reproduced the same behaviour on 1.30.0.

Three searches were submitted in three chats, in this order: pidtest-delta, pidtest-echo, pidtest-foxtrot. The complete server log for that window of time — both server processes, every line:

{"ts":"13:02:43.044","pid":24774,"kind":"session","msg":"start","ppid":24769,"version":"0.1.55"}
{"ts":"13:02:43.347","pid":24801,"kind":"session","msg":"start","ppid":24796,"version":"0.1.55"}
{"ts":"13:03:59.407","pid":24774,"phase":"start","rpc_id":3,"tool":"search_journal","args":"query=\"pidtest-foxtrot\""}
{"ts":"13:04:00.797","pid":24774,"phase":"end","rpc_id":3,"status":"ok","ms":1391}
{"ts":"13:04:00.798","pid":24774,"phase":"sent","rpc_id":3,"ms":0,"bytes":2371,"blocked":false}
{"ts":"13:08:10.909","pid":24774,"phase":"start","rpc_id":4,"tool":"get_time"}
{"ts":"13:08:10.923","pid":24774,"phase":"end","rpc_id":4,"status":"ok","ms":14}
{"ts":"13:08:10.923","pid":24774,"phase":"sent","rpc_id":4,"ms":0,"bytes":160,"blocked":false}