Skip to main content
Glama
mcp-debug-claude-desktop

mcp-debug-claude-desktop

by rsascha

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

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.

Available Tools

4 tools
echoA

Returns its text argument unchanged. Use a different text per chat window to tell the windows apart in the capture.

Inputs: text (required).

pingA

Smallest possible round trip. Returns a fixed string and the sequence number of this call.

Inputs: no named parameters.

sized_echoA

Returns size_kb kilobytes of filler. For probing buffer and message size effects.

Inputs: size_kb (required).

slow_echoA

Returns its text argument after delay_ms milliseconds. Separates a slow handler from a lost message.

Inputs: text (required), delay_ms (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.2/5.0

    Scored across 4 tools

    Disambiguation5/5

    Each tool has a distinct, non-overlapping purpose: ping for round-trip verification, echo for text return, sized_echo for size effects, and slow_echo for delay effects. There is no ambiguity between them.

    Naming Consistency4/5

    Names are clear and follow a consistent style: all lowercase with underscores. The echo variants (sized_echo, slow_echo) follow a clear adjective_echo pattern, though ping and echo are simpler bare verb forms.

    Tool Count5/5

    Four tools is an ideal size for a debug server, covering essential test scenarios without bloat. Each tool earns its place.

    Completeness4/5

    The set covers basic connectivity, text echo, size testing, and latency testing. A potential gap is error injection or message corruption testing, but for the stated debug purpose, coverage is solid.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      A Machine Context Protocol server that enables Claude AI to interact with tools through a structured communication interface, following standard MCP patterns with server initialization and stdio transport.
      2,530 npm
      2
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      A Model Context Protocol server that allows integration with Claude Desktop by creating and managing custom tools that can be executed through the MCP framework.
      -
    • A
      license
      Not graded
      quality
      D
      maintenance
      A Node.js/TypeScript MCP server template with sample tools (ping and system_info) that demonstrates how to build custom tools for Claude Desktop using stdio transport.
      6 npm
      ISC