How to fix MCP error "spawn npx ENOENT / command not found"?

The AI host application (Claude Desktop, Cursor, etc.) was launched in a graphical desktop environment that does not inherit your terminal's user $PATH, or Node.js is not installed globally. Quick Fix: Replace 'command': 'npx' with the absolute path to your npx binary (e.g. C:/Program Files/nodejs/npx.cmd on Windows or /usr/local/bin/npx on macOS).

How to fix MCP error "JSON-RPC error -32603: Internal error (STDOUT Pollution)"?

The MCP server wrote non-JSON debug strings to standard output (STDOUT) instead of standard error (STDERR). In stdio transport, STDOUT is strictly reserved for JSON-RPC messages; any `console.log()` breaks JSON parsing. Quick Fix: Switch all logging inside your custom MCP server from `console.log()` to `console.error()`. For Python servers, write logs exclusively to `sys.stderr`.

How to fix MCP error "JSON-RPC error -32602: Invalid params"?

The AI model passed arguments with incorrect data types (e.g. string instead of integer or array), or omitted a required parameter defined in inputSchema. Quick Fix: Inspect the tool's inputSchema with tools/list and ensure all required fields match their declared types.

How to fix MCP error "JSON-RPC error -32700: Parse error / Invalid Windows backslashes"?

Single backslashes used in Windows file paths (e.g. 'C:\Projects') violate JSON string escape rules. Quick Fix: Replace single backslashes with forward slashes (e.g. 'C:/Projects') or double-escaped backslashes ('C:\\Projects').

How to fix MCP error "SSE connection closed prematurely / EOF"?

Reverse proxies (Cloudflare, Nginx, ALB) or corporate firewalls terminate idle HTTP streaming connections after 60–100 seconds when keep-alive heartbeats are missing. Quick Fix: Implement a 15-second ping/heartbeat comment (`: keep-alive\n\n`) on the SSE endpoint and disable proxy buffering (`X-Accel-Buffering: no`).

Developer Troubleshooting EngineInstant OS Fixes

MCP Error Decoder

Search exact error strings and stack traces from Claude Desktop, Cursor, and OpenAI Codex CLI. Inspect root causes and copy verified terminal fixes.

Scan Config in Linter

Category:

Protocol & SerializationMedium

Raw .md

JSON-RPC error -32602: Invalid params

Symptom

Server rejects tool invocation stating arguments do not match schema.

Root Cause

The AI model passed arguments with incorrect data types (e.g. string instead of integer or array), or omitted a required parameter defined in inputSchema.

Remediation & Quick Fix

Inspect the tool's inputSchema with tools/list and ensure all required fields match their declared types.

OS Diagnostic Commands:

mac

# Inspect tool schema via MCP inspector:
npx @modelcontextprotocol/inspector

windows

# Inspect tool schema via MCP inspector:
npx @modelcontextprotocol/inspector

linux

# Inspect tool schema via MCP inspector:
npx @modelcontextprotocol/inspector

Verified Configuration Example:

// Ensure payload arguments match required properties
{
  "jsonrpc": "2.0",
  "id": 12,
  "method": "tools/call",
  "params": {
    "name": "query_database",
    "arguments": {
      "limit": 10 // Number, not string "10"
    }
  }
}

Diagnostic Guide

Architecture of Model Context Protocol Failures

MCP server issues typically stem from process isolation mismatches, stdio stream contamination, or environment inheritance limitations. Because the host AI application communicates across child-process stdio pipes or Server-Sent Events (SSE) connections, traditional browser debugging tools cannot directly capture errors.

Stdio vs. Stderr Separation

The primary rule of local MCP servers is that STDOUT belongs exclusively to the JSON-RPC wire protocol. If a server library outputs diagnostic logs, banner messages, or package notices to STDOUT, the host JSON parser crashes with an unrecoverable framing error. All server logging must route to STDERR.

GUI Subprocess Environment Isolation

Desktop GUI hosts (such as Claude Desktop or Cursor) are launched by the desktop window manager, not your shell profile (.bashrc or .zshrc). They inherit a minimal system PATH. Tools installed via nvm, pyenv, or Homebrew often require absolute binary paths in the configuration.