Model Context Protocol (MCP) relies on a clean, bi-directional JSON-RPC 2.0 transport running over standard input and output (stdio) or Server-Sent Events (SSE).
Because communication occurs through raw pipes, even a minor misconfiguration—such as a single debugging print statement or a missing environment variable—causes the client to drop the connection immediately.
If you are staring at a red status circle, a Connection closed alert, or an Exit code 1 crash in Cursor, Claude Desktop, or Windsurf, this playbook covers the 5 most common failure modes and how to resolve them.
The 5 Most Common MCP Failure Modes
Failure Symptom Most Likely Root Cause Immediate Fix
Exit Code 1 / Red Dot Non-login shell cannot locate node, npx, or uvx Use absolute executable path (/opt/homebrew/bin/npx)
Connection Closed Server printed debug text to stdout instead of stderr Route all logs to stderr or silence logging
spawn ENOENT Relative binary name executed on Windows without .cmd Specify npx.cmd on Windows platforms
EACCES / Permission Denied File or SQLite database is locked or lacks permissions Run chmod +x or inspect database file ACLs
Client Fails on Boot Trailing comma in config JSON or unescaped backslashes Validate JSON syntax with a linter
- Stdout Stream Contamination (The Silent Killer) The Problem
In the Model Context Protocol specification, stdout is strictly reserved for JSON-RPC messages.
If a server script contains:
javascript
// BROKEN: This destroys the JSON-RPC framing!
console.log("Server initialized successfully on port 8080");
or in Python:
python
BROKEN: Prints to stdout by default!
print("Connected to database")
The AI client (Cursor or Claude) attempts to parse "Server initialized successfully..." as a JSON-RPC message, fails with a parse error, and closes the connection immediately.
The Fix
Redirect all logging strictly to stderr:
javascript
// CORRECT (Node.js):
console.error("Debug info: Server initialized");
python
CORRECT (Python):
import sys
sys.stderr.write("Debug info: Connected to database\n")
- Missing Binary Paths (spawn ENOENT) The Problem
Desktop apps (Claude Desktop, Cursor) run as GUI window manager processes. They do not automatically inherit your shell's interactive $PATH defined in ~/.zshrc or ~/.bashrc. As a result, binaries installed via NVM, Homebrew, or Cargo are missing from the path.
The Fix
Find the absolute path using which in your terminal:
bash
which npx
Output: /opt/homebrew/bin/npx
which uvx
Output: /Users/username/.cargo/bin/uvx
And specify the absolute path in your MCP config:
json
{
"mcpServers": {
"sqlite-tools": {
"command": "/opt/homebrew/bin/uvx",
"args": ["mcp-server-sqlite", "--db-path", "/absolute/path/data.db"]
}
}
}
- Windows CMD Execution Quirks (.cmd vs .exe) The Problem
On Windows, npx is not a standalone binary—it is a shell script wrapper named npx.cmd. Calling "command": "npx" in Windows Cursor or Claude can trigger an immediate spawn ENOENT crash.
The Fix
Explicitly specify npx.cmd and escape backslashes on Windows:
json
{
"mcpServers": {
"github-tools": {
"command": "C:\Program Files\nodejs\npx.cmd",
"args": ["-y", "@modelcontextprotocol/server-github"]
}
}
}
- Environment Variable Stripping The Problem
When testing a server in your terminal:
bash
export GITHUB_PERSONAL_ACCESS_TOKEN="ghp_xxx"
npx @modelcontextprotocol/server-github
It works fine. But when configured in Cursor or Claude, it immediately crashes with Exit code 1. This happens because MCP clients do not inherit environment variables from your active shell.
The Fix
Explicitly declare required variables inside the "env" object of your configuration:
json
{
"mcpServers": {
"github-tools": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"],
"env": {
"GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_your_actual_token_here"
}
}
}
}
- Skip Manual JSON Editing Entirely
Instead of manually editing hidden JSON files and risking trailing-comma syntax crashes, you can use the open-source AIStoreHub CLI
:
bash
1. Install CLI
pip install aistorehub
2. Add verified MCP servers directly to Cursor or Claude
aistorehub add github --client cursor
aistorehub add sqlite --client claude
The CLI automatically locates your active IDE configuration, checks for existing backups, validates environment variables, and safely merges the server without corrupting your JSON file.
Original deep-dive published at AIStoreHub: Fixing MCP Connection Closed & Exit Code 1 Errors
.
Post 2: Claude Desktop Setup & Config Guide
Instructions: Paste this into dev.to/new
for your second post:
markdown
title
:
Claude Desktop MCP Setup Guide: Fixing "spawn npx ENOENT" & Config Crashes
published
:
true
description
:
A complete guide to configuring Model Context Protocol (MCP) in Claude Desktop across macOS and Windows, resolving path errors and automating server installs.
tags
:
claude, ai, mcp, programming
canonical_url
:
https://aistorehub.in/blog/claude-desktop-mcp-setup-troubleshooting-guide
Anthropic's release of the Model Context Protocol (MCP) turned Claude Desktop into an autonomous developer environment.
With MCP servers enabled, Claude Desktop can read and write files directly, query PostgreSQL and SQLite databases, inspect GitHub repos, and invoke internal APIs—all without copy-pasting raw text back and forth.
However, configuring Claude Desktop manually remains error-prone. Because Claude Desktop runs as a GUI application, it does not inherit your interactive shell's $PATH, leading to errors like spawn npx ENOENT or silent crashes when a JSON comma is misplaced.
Here is the exact configuration schema, config file locations across operating systems, and fixes for the top Claude MCP errors.
Where is claude_desktop_config.json Located?
Claude Desktop stores all registered server configurations in a single JSON file named claude_desktop_config.json.
By default, this file resides in hidden system directories:
Operating System Exact File Location Quick Terminal Shortcut
macOS ~/Library/Application Support/Claude/claude_desktop_config.json open ~/Library/Application\ Support/Claude
Windows %APPDATA%\Claude\claude_desktop_config.json explorer %APPDATA%\Claude
Linux (Proton / Wine) ~/.config/Claude/claude_desktop_config.json xdg-open ~/.config/Claude
Note: If this file does not exist yet in your directory, you can create it manually as valid JSON.
Official Claude MCP Config Schema
Claude Desktop expects a top-level object containing a mcpServers dictionary. Each key in this dictionary represents a unique server name:
json
{
"mcpServers": {
"sqlite-analytics": {
"command": "uvx",
"args": [
"mcp-server-sqlite",
"--db-path",
"/Users/username/data/analytics.db"
]
},
"github-tools": {
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-github"
],
"env": {
"GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_your_token_here"
}
}
}
}
3 Strict Rules to Avoid Claude Crashes:
Never Leave Trailing Commas: Standard JSON parsers reject trailing commas after the last item. A trailing comma will prevent Claude Desktop from launching tools.
Double-Escape Windows Backslashes: On Windows, file paths must use double backslashes (C:\Users\name) or forward slashes (C:/Users/name).
Use Absolute Executable Paths: If npx or uvx fails with spawn ENOENT, replace "command": "npx" with the absolute path (/usr/local/bin/npx or C:\Program Files\nodejs\npx.cmd).
How to Verify Your Servers are Working
Completely close Claude Desktop (ensure all background processes are quit).
Relaunch Claude Desktop.
Look at the bottom-right corner of the chat input box. You should see a hammer (🛠️) icon.
Click the hammer icon to see the list of active tools registered by your MCP servers.
1-Click Setup with the AIStoreHub CLI
To avoid manual JSON editing and path troubleshooting, you can install and configure verified MCP servers in Claude Desktop with 1 command:
bash
Install the open-source CLI
pip install aistorehub
Configure servers in Claude Desktop automatically
aistorehub add github --client claude
aistorehub add sqlite --client claude
The CLI automatically handles OS-specific path resolution, backs up your config before modifications, and validates JSON syntax.
Original guide published at AIStoreHub: Claude Desktop MCP Setup & Troubleshooting
.
