Debugging MCP Servers: A Developer Guide

Debugging MCP Servers: A Developer Guide

Building Model Context Protocol (MCP) servers unlocks autonomous agent workflows, but debugging them introduces a unique engineering hurdle: MCP servers run as isolated child processes communicating over strict JSON-RPC 2.0 message pipes.

When a standard web app fails, errors print visibly to terminal logs or browser developer tools. When an MCP server fails, the client host (Claude Desktop, Cursor, Codex CLI) often exhibits silent disconnections, unresponsive tool loops, or vague Process exited with code 1 messages.

This guide provides an end-to-end troubleshooting methodology for diagnosing, debugging, and hardening MCP servers in both TypeScript and Python.

1. The Number One Bug: Standard Stream (stdio) Poisoning

The overwhelming majority of MCP crashes during local development stem from stdio protocol pollution.

The Mechanism

In stdio transport mode, stdin and stdout are strictly reserved for newline-delimited JSON-RPC framing:

• ▸Client -> Server (stdin): JSON-RPC requests (tools/list, tools/call)
• ▸Server -> Client (stdout): JSON-RPC responses ({ "jsonrpc": "2.0", "result": ... })

If your server code—or any third-party library imported by your server—emits plain text, debug logs, or deprecation notices to stdout via console.log() or print(), the client's JSON parser chokes:

SyntaxError: Unexpected token 'D', "Database c"... is not valid JSON

The host immediately terminates the transport session, severing all agent tool access.

The Fix: Standardize on stderr

All human logging, diagnostic tracing, and error telemetry must be routed exclusively to stderr.

TypeScript / Node.js

// FATAL: Corrupts the stdio JSON-RPC stream
console.log("Connecting to PostgreSQL...");

// CORRECT: stderr is safely captured by client host logs
console.error("[MCP-Server] Connecting to PostgreSQL...");
process.stderr.write("[DEBUG] Fetching user records\n");

To guard against rogue third-party packages writing to stdout, redirect global output early in your server entrypoint:

// server.ts (top of file)
const originalStdoutWrite = process.stdout.write.bind(process.stdout);

// Override console.log to route to stderr
console.log = (...args: unknown[]) => {
  console.error("[Redirected stdout]", ...args);
};

Python / FastMCP

import sys
import logging

# FATAL: Corrupts stdio stream
print("Server initialized")

# CORRECT: Direct print to stderr
print("[DEBUG] Server initialized", file=sys.stderr)

# RECOMMENDED: Configure standard logging to stderr
logging.basicConfig(
    stream=sys.stderr,
    level=logging.INFO,
    format="%(asctime)s - %(name)s - %(levelname)s - %(message)s"
)
logger = logging.getLogger("mcp-server")
logger.info("Server listening safely")

2. Interactive Testing with the MCP Inspector

Never test new MCP servers directly inside heavy LLM desktop clients. Use the official MCP Inspector, an interactive web harness designed to inspect raw JSON-RPC traffic, discover tools, and trigger manual tool invocations without burning API tokens.

Launching the Inspector

Run the inspector directly via npx:

# Testing a Node.js / TypeScript MCP server
npx @modelcontextprotocol/inspector node dist/index.js

# Testing with tsx during live development
npx @modelcontextprotocol/inspector npx tsx src/index.ts

# Testing a Python server (uv-managed)
npx @modelcontextprotocol/inspector uv run python server.py

Passing Environment Variables and Arguments

If your server requires credentials, pass arguments and flags after --:

npx @modelcontextprotocol/inspector node dist/index.js --db-path ./data.db

To inject environment variables:

DATABASE_URL="postgres:///dev" npx @modelcontextprotocol/inspector node dist/index.js

What to Verify in Inspector

1. ▸Initialize Handshake: Look at the notification stream. Confirm negotiated protocol version (2024-11-05) and declared capabilities (tools, resources, prompts).
2. ▸Tools List: Check the Tools tab. Verify parameter schemas, required attributes, and descriptions.
3. ▸Manual Tool Execution: Run tool calls with valid and boundary inputs. Validate that output returns cleanly formatted content blocks.
4. ▸Notifications: Verify whether dynamic notifications (such as resource updates) fire without unhandled rejections.

3. Attaching Live Debuggers (Breakpoints and Step-Through)

When printf-debugging to stderr is insufficient, attach full IDE debuggers with step-through execution and memory inspection.

Debugging TypeScript in VS Code / Cursor

Add a dedicated launch configuration to .vscode/launch.json:

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Debug MCP Server (Node)",
      "type": "node",
      "request": "launch",
      "runtimeExecutable": "npx",
      "runtimeArgs": ["tsx", "src/index.ts"],
      "console": "internalConsole",
      "outputCapture": "std",
      "env": {
        "DEBUG": "true",
        "NODE_ENV": "development"
      }
    },
    {
      "name": "Attach to MCP Inspector Process",
      "type": "node",
      "request": "attach",
      "port": 9229,
      "restart": true
    }
  ]
}

To run your server through the MCP Inspector with a Node debugger listening on port 9229:

npx @modelcontextprotocol/inspector node --inspect=9229 dist/index.js

Now click Attach to MCP Inspector Process in your IDE to hit breakpoints inside tool handlers in real time.

Debugging Python MCP Servers with debugpy

In your Python server, you can dynamically attach debugpy:

import debugpy
import sys

# Enable remote debugging if DEBUG_MODE is set
if "--debug" in sys.argv:
    debugpy.listen(("localhost", 5678))
    print("[DEBUG] Waiting for debugger attach on port 5678...", file=sys.stderr)
    debugpy.wait_for_client()

Attach to port 5678 using the standard Python VS Code debug configuration.

4. Understanding MCP JSON-RPC Errors

Errors in MCP operate on two distinct levels: Protocol-level errors and Tool-execution errors. Conflating them breaks agent self-healing.

Protocol Errors vs Tool Errors

Standard JSON-RPC 2.0 Error Codes

When writing custom low-level dispatchers, adhere to standardized error codes:

export const McpErrorCodes = {
  ParseError: -32700,     // Invalid JSON received by server
  InvalidRequest: -32600, // Payload is not a valid Request object
  MethodNotFound: -32601, // Method does not exist / not declared
  InvalidParams: -32602,  // Tool arguments failed schema validation
  InternalError: -32603   // Unhandled internal server exception
} as const;

Proper Tool Error Handling Pattern

Never let an internal database timeout or filesystem exception throw an unhandled promise rejection. Wrap handlers to return a structured error block:

server.setRequestHandler(CallToolRequestSchema, async (request) => {
  const { name, arguments: args } = request.params;

  if (name === "query_records") {
    try {
      const records = await db.query(args.filter);
      return {
        content: [
          {
            type: "text",
            text: JSON.stringify(records, null, 2)
          }
        ]
      };
    } catch (err: any) {
      // Return tool failure so the LLM can adjust parameters or self-heal
      return {
        isError: true,
        content: [
          {
            type: "text",
            text: `Database query failed: ${err.message}. Please refine your search filter.`
          }
        ]
      };
    }
  }

  throw new McpError(
    ErrorCode.MethodNotFound,
    `Unknown tool requested: ${name}`
  );
});

5. Client Log Locations and Forensic Auditing

When a server works in the MCP Inspector but fails in your agent host, check client execution logs.

Claude Desktop Logs

Claude logs every child process invocation and captures stderr:

• ▸macOS: ~/Library/Logs/Claude/mcp.log and ~/Library/Logs/Claude/mcp-server-{name}.log
• ▸Windows: %APPDATA%\Claude\logs\mcp.log and %APPDATA%\Claude\logs\mcp-server-{name}.log
• ▸Linux: ~/.config/Claude/logs/mcp.log

Tailing live logs during testing:

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

# Windows PowerShell
Get-Content -Path "$env:APPDATA\Claude\logs\mcp.log" -Wait -Tail 30

Cursor IDE Logs

In Cursor:

1. ▸Open the Command Palette (Ctrl+Shift+P / Cmd+Shift+P).
2. ▸Type Output: Focus on Output View.
3. ▸Select MCP or Cursor Tab from the output dropdown channel.
4. ▸Review the raw child-process spawn command and environment variables.

OpenAI Codex CLI Logs

Codex CLI outputs process traces when launched with verbose debugging:

# Run codex with full transport tracing enabled
DEBUG=mcp:* codex exec "Inspect recent logs"

6. Common Failure Modes and Solutions

Issue A: "Command not found: npx / node / uv"

• ▸Cause: GUI applications (like Claude Desktop on macOS) do not inherit shell profile environment variables (.zshrc, .bash_profile, PATH). System PATH in GUI apps defaults to /usr/bin:/bin:/usr/sbin:/sbin.
• ▸Solution: Use absolute paths for the command binary in client configs:

{
  "mcpServers": {
    "my-server": {
      "command": "/Users/username/.nvm/versions/node/v20.10.0/bin/node",
      "args": ["/Users/username/projects/my-server/dist/index.js"]
    }
  }
}

Issue B: "Zod Schema Type Coercion Mismatch"

• ▸Cause: LLMs occasionally send numbers as strings ("limit": "10" instead of 10) or pass boolean flags as "true".
• ▸Solution: Use z.coerce in Zod schemas:

const QueryParamsSchema = z.object({
  query: z.string().min(1),
  limit: z.coerce.number().int().positive().default(20),
  includeArchived: z.coerce.boolean().default(false)
});

Issue C: Zombie MCP Processes

• ▸Cause: When client hosts restart or crash, spawned child processes can remain alive in the background holding file locks or ports.
• ▸Solution: Handle SIGTERM and SIGINT cleanly:

const cleanup = async () => {
  console.error("[MCP] Terminating server cleanly...");
  await server.close();
  process.exit(0);
};

process.on("SIGINT", cleanup);
process.on("SIGTERM", cleanup);

Summary Checklist for Production MCP Servers

Before deploying your server to production clients:

1. ▸ Audit stdout: Ensure zero calls to console.log or unformatted print(). All logging routes to stderr.
2. ▸ Test with Inspector: Verified initialize, tool lists, and manual invocations in @modelcontextprotocol/inspector.
3. ▸ Schema Coercion: Handled stringified numbers and booleans in parameter schemas.
4. ▸ Graceful Errors: Handled tool execution errors with isError: true instead of crashing the process.
5. ▸ Absolute Paths: Configured absolute binary paths for GUI client compatibility.
6. ▸ Signal Handling: Implemented SIGINT and SIGTERM handlers to eliminate orphaned processes.