MCP Troubleshooting. One error, one fix.
Each page covers one MCP error or symptom: what it means, the fastest fix, fixes per app and operating system, and where to find the logs.
We grow your business with
- CROturn traffic into leads
- SEOrank & get found
- GEOwin generative search
- AEOget cited by AI answers
- AIbuild a website that learns
Fixes are checked against each app's and SDK's documentation on the date shown. Look up any JSON-RPC code with the MCP error code lookup.
MCP Troubleshooting
Connection and startup
Servers that won't start, connect or show their tools.
Could Not Attach to MCP Server: How to Fix It (Claude Desktop on macOS and Windows)
Fix the Claude Desktop pop-up "Could not attach to MCP server". Read the right log, use absolute paths for node and npx, and find why the server exits.
Read the guide →Logging to stdout Breaks My MCP Server: How to Fix It (Python, TypeScript, Java, C#)
Printing to stdout corrupts a stdio MCP server's JSON-RPC stream. Move logs to stderr in Python, TypeScript, Java and C#, and silence noisy libraries.
Read the guide →MCP 401 Unauthorized: How to Fix It (Claude, Claude Code, Cursor, VS Code)
Fix 401 Unauthorized from a remote MCP server. Sign in again, check token audience and scopes, remove redirects that drop the header, and fix discovery.
Read the guide →MCP JSON-RPC Parse Error (-32700): How to Fix It (Claude Desktop, Cursor, Claude Code)
Fix MCP parse errors such as -32700 and "Unexpected token" in client logs. Find stray stdout text, broken framing or bad config JSON, client by client.
Read the guide →MCP OAuth Redirect URI Errors: How to Fix Them (Claude, Claude Code, Cursor, VS Code)
Fix "invalid redirect URI" errors on remote MCP servers. The exact callback URLs Claude, Claude Code, Cursor and VS Code use, and what to register.
Read the guide →MCP Server Disconnected in Claude: How to Fix It (Claude Desktop, Claude Code, claude.ai)
Fix "Server disconnected" for MCP servers in Claude Desktop, Claude Code and claude.ai. Find why the process exited, read the right log and reconnect.
Read the guide →MCP Server Failed to Start on Windows: How to Fix It (Claude Desktop, Cursor, VS Code, Claude Code)
Fix MCP servers that fail to start on Windows. Escape backslashes, handle npx.cmd, set APPDATA, check the MSIX config copy, and find the logs.
Read the guide →MCP Server Node.js Version Errors: How to Fix Them (Claude Desktop, Cursor, Claude Code)
Fix MCP servers that fail because of the wrong Node.js version. Check engines requirements, find which node the client really runs, and pin a supported LTS release.
Read the guide →MCP Server Not Connecting in Claude Desktop: How to Fix It (Windows, macOS, Linux)
Fix a local MCP server that will not connect in Claude Desktop. Check the config file, quit the app fully, read mcp.log and run the server by hand.
Read the guide →MCP Server Works in Inspector but Not in Claude: How to Fix It (Claude Desktop, claude.ai, Claude Code)
Your MCP server passes in the Inspector but fails in Claude. The cause is usually environment, paths, runtime, a redirect or a private hostname.
Read the guide →MCP Tool Call Failed: How to Fix It (Claude, Claude Code, Cursor, VS Code)
Fix MCP tool calls that fail while the server stays connected. Tell protocol errors from tool errors, read isError results and replay the call.
Read the guide →MCP Tools Not Showing in Cursor: How to Fix It (Windows, macOS, Linux)
MCP server added but its tools do not show in Cursor? Check the mcp.json location, the server toggle, MCP Logs, sign-in, and tool count, with steps for each cause.
Read the guide →MCP error -32000: Connection closed: How to Fix It (Claude Desktop, Cursor, Claude Code)
MCP error -32000 Connection closed means the server or stream ended before a reply. Find why it exited, fix the launch command and stop stdout output.
Read the guide →MCP error -32001: Request timed out: How to Fix It (Claude Desktop, Claude Code, Cursor)
Fix MCP error -32001 Request timed out. Learn the 60-second SDK default, how to raise timeouts in Claude Code, and how to speed up slow servers.
Read the guide →Too Many MCP Tools Warning: How to Fix It (VS Code, Cursor, Claude Code)
Fix "Cannot have more than 128 tools per request" in VS Code and tool-limit warnings in Cursor and Claude Code. Trim servers or use tool search.
Read the guide →claude_desktop_config.json Not Loading: How to Fix It (Windows, macOS, Linux)
Claude Desktop ignoring claude_desktop_config.json? Check the file path, JSON syntax, the mcpServers key, a full restart, and the Windows MSIX copy of the file.
Read the guide →spawn npx ENOENT in MCP: How to Fix It (Claude Desktop, Cursor, Claude Code)
Fix the spawn npx ENOENT error when an MCP server will not start. Why the client cannot find npx, and how full paths and env settings solve it.
Read the guide →uvx Not Found (spawn uvx ENOENT) in MCP: How to Fix It (Claude Desktop, Cursor, Claude Code)
Fix "uvx not found" and spawn uvx ENOENT for Python MCP servers. Install uv, find the full uvx path, put it in your config, and pick the right Python version.
Read the guide →
MCP Troubleshooting
Protocol, auth and environment
Version mismatches, sessions, OAuth, CORS, Docker, WSL and paths.
ChatGPT Custom MCP Server Won't Connect or Errors: How to Fix It (ChatGPT)
Fix ChatGPT custom MCP server errors: a missing Add option, unreachable URLs, OAuth 401s, invalid_client, and tool calls that break after server updates.
Read the guide →Claude Code MCP Failed to Connect: How to Fix It (Claude Code)
Fix the Failed to connect status in Claude Code. Read the Issue line, fix stdio commands, tokens and env vars, raise MCP_TIMEOUT, and reconnect from /mcp.
Read the guide →Claude Code MCP Server Not Found or Not Listed: How to Fix It (Claude Code)
Your MCP server is missing from claude mcp list or /mcp? Check scope, .mcp.json location and approval, reserved names, and policies, then confirm with /mcp.
Read the guide →Gemini CLI MCP Server Disconnected or Not Working: How to Fix It (Gemini CLI)
Fix Gemini CLI MCP servers that show Disconnected, find no tools or lose API keys. Covers url vs httpUrl, folder trust, env redaction, OAuth and /mcp list.
Read the guide →MCP "Resource not found" (-32602 or -32002): How to Fix It (Claude Code, Inspector, SDKs)
Fix the MCP "Resource not found" error: why resources/read fails, why the code changed from -32002 to -32602 in 2026-07-28, and how to check URIs and templates.
Read the guide →MCP "SSE transport is deprecated" Warning: How to Fix It (Claude Code, VS Code, Cursor, Gemini CLI, SDKs)
Seeing an MCP SSE transport deprecated warning or a missing SSEServerTransport export? Switch the client config to HTTP and move the server to Streamable HTTP.
Read the guide →MCP "Session not found" (HTTP 404): How to Fix It (Claude Code, VS Code, Python and TypeScript Servers)
Fix the MCP "Session not found" 404: why 2025-era Streamable HTTP sessions expire or vanish, how to reconnect, and when to go stateless or use sticky routing.
Read the guide →MCP CORS Errors on a Remote Server: How to Fix It (Browser Clients, Inspector, Web Apps)
Fix CORS errors when a browser-based MCP client calls your remote server: allow the Mcp-* request headers, expose Mcp-Session-Id, and match your Origin allowlist.
Read the guide →MCP Error -32601 Method Not Found: How to Fix It (Claude Code, Inspector, Python and TypeScript SDKs)
Fix MCP error -32601 Method not found: era mismatches between 2025 and 2026-07-28 peers, methods removed in 2026-07-28, and capabilities a server never registered.
Read the guide →MCP Error -32602 Invalid Params: How to Fix It (Claude Code, Cursor, VS Code, Inspector, SDKs)
Fix MCP error -32602 Invalid params: unknown tool names, arguments that fail the input schema, missing _meta fields in 2026-07-28 requests, and resource not found.
Read the guide →MCP Inspector Won't Connect: How to Fix Connection Errors (Inspector v2)
Fix MCP Inspector connection errors in v2: Node version, the per-launch token, transport not determined from URL, protocol era, 403 host checks and Docker ports.
Read the guide →MCP Protocol Version Mismatch (Unsupported protocol version, -32022): How to Fix It (Claude Code, Inspector, SDKs)
Fix MCP protocol version errors: UnsupportedProtocolVersion -32022, ERA_NEGOTIATION_FAILED and 400 Bad Request between 2026-07-28 clients and 2025-era servers.
Read the guide →MCP Server Command Not Found on macOS (PATH Issues): How to Fix It (Claude Desktop, Cursor, Claude Code)
Fix MCP servers that fail on a Mac because npx, node, uvx or python is not found. Why GUI apps miss your shell PATH, and how absolute paths in the config fix it.
Read the guide →MCP Server Crashes or Fails on Large Responses: How to Fix It (Claude Code, Claude Desktop, Cursor)
Fix MCP tool calls that crash, truncate or get saved to a file when results are big. Covers Claude Code output limits, the 16 MiB cap, pagination and resource links.
Read the guide →MCP Server Not Getting Environment Variables: How to Fix It (Claude, Cursor, VS Code)
Your MCP server works in a terminal but says an API key is missing in the client. Learn why env vars are not inherited and the exact syntax each client expects.
Read the guide →MCP Server in Docker Not Connecting: How to Fix It (Claude, Cursor, VS Code)
Fix an MCP server that runs in Docker but never connects. Covers the -i flag, detached mode, env vars, Docker MCP Toolkit gateway timeouts and where to read logs.
Read the guide →MCP Servers in WSL on Windows Not Working: How to Fix It (Claude Desktop, Claude Code, VS Code, Cursor)
Fix MCP servers that fail when Windows apps meet WSL. Run Linux servers through wsl.exe, use the right path style, pass env vars and pick where the client runs.
Read the guide →VS Code MCP Server Not Starting or Not Showing: How to Fix It (VS Code, GitHub Copilot)
VS Code MCP server won't start or its tools never appear? Check Show Output, Workspace Trust, the servers vs mcpServers format, PATH and Docker flags, then retry.
Read the guide →
FAQ
Common questions
Where do I start when an MCP server fails?
Can you fix our MCP setup for us?
Project Managers who will work with you on your project!
Irina S.hello@eseospace.com
Benjamin G.ben@eseospace.com
David G.david@eseospace.comWork with us
Talk to the team behind your project
Tell us what you need and we’ll match you with the right people.
Book a Discovery Call
Jeanette M.jeanette@eseospace.com
Mark S.mark@eseospace.com
Maryna P.maryna@eseospace.com
Want help with MCP?
Request a free MCP readiness review: which tools to connect first, which servers to trust and what to lock down.
Request a Free Review →
