Debugging stdio transport MCP servers

Why stdout corruption happens

In the MCP stdio transport, the protocol framing is newline-delimited JSON (NDJSON). The client reads stdout line by line and parses each line as a JSON-RPC message. When a non-JSON line appears — a startup banner, a log line, a debug print — the client's JSON parser fails and the session enters an undefined state. Depending on the client implementation, this results in:

• Silent connection failure (most common — the client closes the connection without showing an error)
• A JSON parse error in the client log
• The server appearing to connect but all tool calls failing
• The server appearing connected but the tool list being empty

The failure is particularly confusing because it happens during startup — before any tool is called — and the error appears on the client side, not in the server output. The server may be running correctly while the client shows it as disconnected.

// WRONG — corrupts the JSON-RPC stream
console.log('Server starting...');          // stdout — breaks the client
console.log({ tools: registeredTools });    // stdout — breaks the client
process.stdout.write('Ready\n');            // stdout — breaks the client

// CORRECT — stderr is not part of the JSON-RPC transport
console.error('Server starting...');
process.stderr.write('Server starting...\n');

// With a structured logger (pino configured to write to stderr):
import pino from 'pino';
const logger = pino({}, pino.destination(2));  // 2 = stderr fd
logger.info('Server starting');

The rule applies to all output — even a single stray character on stdout during initialization will break the session. Remove all console.log calls, even temporary ones you added for quick debugging.

The DEBUG environment variable pattern

The MCP TypeScript SDK and Node.js ecosystem use the DEBUG environment variable convention (from the debug npm package) to enable verbose logging that writes to stderr. Enable it for built-in SDK logging:

# Enable MCP SDK internal debug logging (writes to stderr)
DEBUG=mcp:* node dist/index.js

# Enable only specific namespaces
DEBUG=mcp:server node dist/index.js
DEBUG=mcp:transport node dist/index.js

# Enable debug logging for your own code too
DEBUG=mcp:*,myserver:* node dist/index.js

In your server code, use the debug package (or a structured logger behind a DEBUG check) for verbose output that's safe to leave in production code — it only emits when DEBUG is set:

import createDebug from 'debug';
const debug = createDebug('myserver:tools');

server.tool('search_documents', schema, async (args) => {
  debug('search called with args: %O', args);  // only emits if DEBUG=myserver:*
  // ...
});

The debug package writes to stderr automatically — it knows it's not a JSON-RPC transport. Set the DEBUG environment variable in your Claude Desktop config temporarily when debugging, then remove it.

Inspecting the live stdio stream with tee

When you need to see the raw JSON-RPC protocol traffic — not just your server logs, but every message exchanged — you can intercept the stdio pipes using tee. This lets you observe the protocol without using the MCP Inspector UI, which is useful in CI or terminal-only environments:

# Create named pipes for interception
mkfifo /tmp/mcp-stdin /tmp/mcp-stdout

# In one terminal: start your server with pipes connected to tee
node dist/index.js \
  < <(tee /tmp/stdin-log.ndjson < /tmp/mcp-stdin) \
  > >(tee /tmp/stdout-log.ndjson > /tmp/mcp-stdout)

# In another terminal: run an MCP client that connects to the pipes
# (or use the MCP SDK test client)

# Format the captured logs with jq for readability
tail -f /tmp/stdout-log.ndjson | jq '.'
tail -f /tmp/stdin-log.ndjson | jq '.'

A simpler approach for one-off debugging: redirect the server output to a file while running the server directly in a terminal, then inspect the output file:

# Run the MCP Inspector which handles the pipes for you
npx @modelcontextprotocol/inspector node dist/index.js
# Then use Inspector's Protocol tab to see all JSON-RPC messages

For most debugging tasks, the MCP Inspector's Protocol tab is simpler than manual pipe interception. Use manual tee/jq interception when you need to capture a long session or automate protocol inspection in a script.

Debugging the initialize handshake

The MCP initialize handshake is the first thing that happens when a client connects. If it fails, no tools are ever sent and the client shows the server as disconnected. The handshake sequence is:

1. Client sends initialize request with protocolVersion, capabilities, and clientInfo
2. Server responds with initialize result (its protocolVersion, capabilities, serverInfo)
3. Client sends initialized notification (no response expected)
4. Client sends tools/list request
5. Server responds with the tool manifest

Failures at each step have distinct causes:

To debug step-by-step: run npx @modelcontextprotocol/inspector node dist/index.js, open the Protocol tab, and watch each message in sequence. The first missing or malformed message identifies the failing step.

Matching config.json to your actual server binary

Most stdio debugging issues in Claude Desktop come from a mismatch between the server configuration in claude_desktop_config.json and what the actual server process needs. Common mismatches:

// claude_desktop_config.json
{
  "mcpServers": {
    "my-server": {
      // WRONG: points to source file (requires tsx to be installed globally)
      "command": "node",
      "args": ["src/index.ts"],

      // CORRECT: points to compiled output
      "command": "node",
      "args": ["/absolute/path/to/my-server/dist/index.js"],

      // ALSO CORRECT: use npx with the package name
      "command": "npx",
      "args": ["my-mcp-server"],

      "env": {
        // Missing env vars here cause the server to crash on startup silently
        "DATABASE_URL": "postgres://localhost/mydb",
        "API_KEY": "your-key-here"
      }
    }
  }
}

Key rules for Claude Desktop config:

• Use absolute paths for args — Claude Desktop doesn't inherit your shell's PATH or working directory. Relative paths fail silently.
• Run npm run build before testing — if the TypeScript source changed but dist/ hasn't been rebuilt, the old binary runs.
• List all required environment variables in env — the server process doesn't inherit your shell environment. A missing DATABASE_URL causes a startup crash that looks like a connection failure.
• Check the log at ~/Library/Logs/Claude/mcp-server-<name>.log — Claude Desktop writes the server's stderr output to this file. The startup error is almost always there.

Reading the Claude Desktop MCP log

Claude Desktop writes each MCP server's stderr output to a per-server log file. This is the most reliable way to diagnose stdio-mode server failures:

# macOS
tail -f ~/Library/Logs/Claude/mcp-server-my-server.log

# Windows (PowerShell)
Get-Content "$env:APPDATA\Claude\logs\mcp-server-my-server.log" -Wait

# Cursor (macOS)
tail -f ~/Library/Logs/Cursor/mcp-server-my-server.log

The log file name matches the key in your config's mcpServers object. If the server never started, the file may not exist or may be empty — check that the path in your config resolves correctly by running the exact command manually in a terminal.

Related pages

• Debug logging for MCP servers
• MCP Inspector tool
• Debugging MCP servers in VS Code
• MCP server stdio transport
• MCP server error handling