MCP Troubleshooting Updated June 2026

MCP Troubleshooting Guides

Answer-first guides for the most common MCP server errors in Claude Desktop, Cursor, and other MCP clients. Each guide covers one specific real error with the fix in the first paragraph.

If you are not sure which guide to read: check the MCP log file first (~/Library/Logs/Claude/mcp-server-NAME.log on macOS), find the error message, then pick the matching guide below.

Connection and startup errors

MCP Server Not Connecting in Claude Desktop

No tools icon, server silently fails to start. Covers PATH issues, config location, full-quit requirement, and env vars.

Quick fix: replace "npx" with the absolute path from which npx

MCP Server spawn ENOENT — npx, uvx, and Node path errors

spawn ENOENT means the binary was not found. Platform-specific absolute path fixes for macOS, Windows, and Linux.

Quick fix: which npx → use that full path in command field

MCP Config JSON Invalid / Not Loading

A single JSON error silently disables all servers. Trailing commas, Windows backslashes, missing braces, and comments are the most common causes.

Quick fix: python3 -m json.tool your config to find the error

Runtime and stability errors

MCP Tools Not Showing Up in Claude

Hammer icon missing entirely, or fewer tools than expected. Covers the difference between no icon and empty tool list.

Quick fix: read ~/Library/Logs/Claude/mcp-server-NAME.log

MCP Server Timeout / Disconnected

First-run npx timeout, slow initialization, recurring disconnects, and tool call timeouts — each with a specific fix.

Quick fix (first run): run the server command manually once in terminal to pre-cache

Client-specific errors

Cursor MCP Not Working

Cursor uses ~/.cursor/mcp.json (not Claude Desktop's config). Covers config location, format, reload steps, and Output panel debugging.

Quick fix: check ~/.cursor/mcp.json exists and has valid JSON

Diagnosis and tools

How to Debug an MCP Server

Step-by-step debugging: reading logs, testing servers manually, using MCP Inspector, checking environment differences, and isolating to one server.

Quick start: npx @modelcontextprotocol/inspector COMMAND ARGS

Free diagnostic tools

MCP Config Auditor — paste your claude_desktop_config.json or mcp.json, get a per-server report of bare commands, placeholder tokens, JSON errors, and relative paths. 100% client-side.

MCP Server Health Check — sends real MCP protocol messages to any server endpoint and reports response time and tool list. Useful for HTTP/SSE transport servers.

CLI: pip install mcp-config-lint && mcp-config-lint — run it in any terminal to get a config report without opening a browser.

Also useful: MCP Server Setup Guide — Fix Silent MCP Failures (blog) — MCP Server Directory