Published on npm

@turingspark/mcp-debug

A CLI proxy that sits between your MCP client and server, logging every JSON-RPC message in both directions with timing information. Works with any MCP server — no code changes required.

View on npm →Quick Start

$ npm install -g @turingspark/mcp-debug

What mcp-debug does

When an MCP tool returns unexpected output, fails silently, or takes longer than expected, mcp-debug shows you the exact bytes on the wire so you can diagnose the problem without guessing.

📋

Full message log

Every request and response logged — initialize handshake, tool calls, notifications.

⏱

Per-call latency

Response time shown on every call. Spot slow tools immediately.

🚨

Error flagging

Protocol errors and tool-level errors surfaced with an ERROR label automatically.

🖥

Web dashboard

Visual log browser at localhost:8101. Browse sessions and inspect payloads.

Quick Start

Install globally or run with npx — no config required.

# Install globally npm install -g @turingspark/mcp-debug # Or run directly with npx npx @turingspark/mcp-debug [options] -- <server> [server-args]

CLI flags

Flag	Description
--verbose	Log full JSON payloads for every message
--port <n>	Dashboard port (default: 8101)
-- <cmd> [args]	Server command and args — canonical form, handles paths with spaces
--cmd "<cmd>"	Alternative for simple commands without spaces in paths

Output legend

→	Request sent from debug proxy to server
←	Response received from server
ERROR	Response contains a JSON-RPC error object or isError: true
[Nms]	Latency for that call in milliseconds

Examples

Three real scenarios showing what you see on the wire.

Example 1 — Hello World

Listing a directory

The simplest way to see mcp-debug in action. Uses mcp-server-filesystem to list a local directory — one tool call, a clean response, and the full initialize handshake visible from the start.

npx @turingspark/mcp-debug \ --verbose --port 8101 \ -- mcp-server-filesystem /tmp/mcp-test-dir

[mcp-debug] Proxying: mcp-server-filesystem /tmp/mcp-test-dir

[mcp-debug] Dashboard: http://localhost:8101

[mcp-debug] Session: session_1774190205017_gpgq4n

-> initialize id=1

{ "method": "initialize", "params": { ... } }

<- initialize id=1 [105ms]

{ "result": { "serverInfo": { "name": "secure-filesystem-server" } } }

-> tools/call id=2

{ "params": { "name": "list_directory", "arguments": { "path": "..." } } }

<- tools/call id=2 [4ms]

{ "result": { "content": [{ "text": "[FILE] README.md [FILE] hello.txt" }] } }

mcp-debug logs the full initialize handshake before your first tool call — you can confirm protocol version and server capabilities upfront. The 4ms response time is visible immediately.

Example 2 — Chained Calls

Listing then reading a file

Most real workflows involve multiple tool calls in sequence. mcp-debug logs both calls with their own IDs and latencies, keeping the full conversation traceable.

-> tools/call id=2

{ "params": { "name": "list_directory" } }

<- tools/call id=2 [3ms]

{ "result": { "content": [{ "text": "[FILE] README.md ..." }] } }

-> tools/call id=3

{ "params": { "name": "read_file", "arguments": { "path": ".../README.md" } } }

<- tools/call id=3 [3ms]

{ "result": { "content": [{ "text": "# README " }] } }

Each call gets its own incrementing ID — id=2 for the list, id=3 for the read. Straightforward to match requests to responses when scanning a longer session log.

Example 3 — Error Handling

Catching an auth failure

When a server rejects a request, the error is often swallowed by the client and surfaces as a vague failure. mcp-debug shows the full JSON-RPC error envelope so you can see exactly what the server returned.

# no GITHUB_TOKEN set in environment npx @turingspark/mcp-debug \ --verbose --port 8101 \ -- mcp-server-github

-> tools/call id=2

{ "params": { "name": "create_repository", ... } }

<- tools/call (error) id=2 [210ms] ERROR

{

"error": {

"code": -32603,

"message": "Authentication Failed: Requires authentication"

}

The ERROR label appears automatically on any response containing a JSON-RPC error object. Without mcp-debug, your client would receive this silently. With it, you have the exact code and message to write a targeted handler.

Web UI — same session

MCP Debug web UI showing the authentication error in the Messages tab

MCP Debug Timeline tab showing the auth failure sequence

Claude Desktop Config

The -- separator form maps naturally to Claude Desktop's args array. Use this pattern to wrap any existing MCP server with mcp-debug for a debugging session:

{ "mcpServers": { "filesystem-debug": { "command": "npx", "args": [ "@turingspark/mcp-debug", "--verbose", "--", "mcp-server-filesystem", "/path/with spaces/my-project" ] } } }

The -- form is the canonical pattern for anything non-trivial. It handles paths with spaces correctly, requires no custom parsing, and maps cleanly to argv arrays in all MCP client configs.

Stop guessing. Start seeing.

Add mcp-debug to any MCP workflow and get full visibility into every message in seconds.

View on npm →

npx @turingspark/mcp-debug -- <your-server>