{ "version": "1.0", "generatedAt": "2026-10-19T02:46:21.055Z", "dataRefreshedAt": "2026-10-15T14:34:37.103Z", "count": 16, "fixes": [ { "slug": "mcp-server-not-showing-in-cursor", "title": "MCP server not showing in Cursor (or showing a red dot)", "clients": [ "Cursor" ], "error": "No tools available • Client closed • red status dot next to the server in Cursor's MCP settings", "cause": "Cursor only reads ~/.cursor/mcp.json (global) or .cursor/mcp.json in the project root. A wrong file location, a typo in the mcpServers key, invalid JSON, or a command that crashes on start all leave the server missing or red.", "steps": [ { "title": "Put the config in the right place", "text": "Global: ~/.cursor/mcp.json. Per project: <project>/.cursor/mcp.json. The top-level key must be mcpServers.", "code": "{\n \"mcpServers\": {\n \"playwright\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@playwright/mcp@latest\"]\n }\n }\n}" }, { "title": "Run the command yourself", "text": "Copy the exact command and args into a terminal (e.g. npx -y @playwright/mcp@latest). If it errors there, it will error in Cursor too.", "code": null }, { "title": "Check the MCP log", "text": "Open the Output panel (Cmd/Ctrl+Shift+U) and choose MCP Logs from the dropdown to see the real error.", "code": null }, { "title": "Toggle and reload", "text": "Open Customize in the sidebar, find the server under MCP, and toggle it off and on. You can also run \"Developer: Reload Window\".", "code": null } ], "relatedServers": [ "playwright", "github", "context7" ], "sources": [ "https://cursor.com/docs/context/mcp", "https://modelcontextprotocol.io/docs/tools/debugging" ], "url": "https://plugolis.com/fixes/mcp-server-not-showing-in-cursor/" }, { "slug": "mcp-server-not-showing-in-claude-desktop", "title": "MCP server not showing in Claude Desktop", "clients": [ "Claude Desktop" ], "error": "No hammer/tools icon appears, or \"Could not attach to MCP server\" / \"MCP server failed\" in Claude Desktop", "cause": "Claude Desktop reads claude_desktop_config.json only at startup. Editing the wrong file, invalid JSON, or not fully quitting the app (it keeps running in the tray/menu bar) are the usual causes.", "steps": [ { "title": "Edit the right file", "text": "macOS: ~/Library/Application Support/Claude/claude_desktop_config.json. Windows: %APPDATA%\\Claude\\claude_desktop_config.json. Easiest path: Settings → Developer → Edit Config.", "code": "{\n \"mcpServers\": {\n \"filesystem\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@modelcontextprotocol/server-filesystem\", \"/Users/you/Desktop\"]\n }\n }\n}" }, { "title": "Fully quit and restart", "text": "Quit from the menu bar/tray (Cmd+Q on macOS), not just close the window, then reopen.", "code": null }, { "title": "Read the logs", "text": "macOS: ~/Library/Logs/Claude/mcp*.log. Windows: %APPDATA%\\Claude\\logs\\.", "code": "tail -n 50 -f ~/Library/Logs/Claude/mcp*.log" }, { "title": "Use absolute paths", "text": "Paths in args (folders, scripts) must be absolute; ~ and relative paths are not expanded.", "code": null } ], "relatedServers": [ "filesystem", "memory", "fetch" ], "sources": [ "https://modelcontextprotocol.io/docs/develop/connect-local-servers", "https://modelcontextprotocol.io/docs/tools/debugging" ], "url": "https://plugolis.com/fixes/mcp-server-not-showing-in-claude-desktop/" }, { "slug": "spawn-npx-enoent", "title": "Fix \"spawn npx ENOENT\" when starting an MCP server", "clients": [ "Claude Desktop", "Cursor", "Windsurf" ], "error": "Error: spawn npx ENOENT", "cause": "The app launched the server without your shell's PATH, so it cannot find npx. This is common with nvm, fnm, Volta, or Homebrew installs, because GUI apps do not load ~/.zshrc / ~/.bashrc.", "steps": [ { "title": "Confirm Node is installed", "text": "Run node -v and which npx (macOS/Linux) or where npx (Windows).", "code": "which npx\n# e.g. /Users/you/.nvm/versions/node/v22.11.0/bin/npx" }, { "title": "Use the absolute path to npx", "text": "Replace \"npx\" with the full path from the previous step.", "code": "{\n \"mcpServers\": {\n \"memory\": {\n \"command\": \"/Users/you/.nvm/versions/node/v22.11.0/bin/npx\",\n \"args\": [\"-y\", \"@modelcontextprotocol/server-memory\"]\n }\n }\n}" }, { "title": "Or pass PATH explicitly", "text": "Add an env.PATH that includes the Node bin folder, so npx can also find node.", "code": "\"env\": { \"PATH\": \"/Users/you/.nvm/versions/node/v22.11.0/bin:/usr/local/bin:/usr/bin:/bin\" }" }, { "title": "Restart the client", "text": "Fully quit and reopen the app so it re-spawns the server.", "code": null } ], "relatedServers": [ "memory", "filesystem", "sequential-thinking" ], "sources": [ "https://modelcontextprotocol.io/docs/develop/connect-local-servers", "https://modelcontextprotocol.io/docs/tools/debugging" ], "url": "https://plugolis.com/fixes/spawn-npx-enoent/" }, { "slug": "windows-npx-mcp-cmd-c", "title": "MCP servers fail on Windows with npx (use cmd /c)", "clients": [ "Claude Desktop", "Cursor", "VS Code" ], "error": "spawn npx ENOENT • 'npx' is not recognized • Connection closed (Windows only)", "cause": "On Windows, npx is a npx.cmd batch script, which cannot be spawned directly without a shell. Clients that spawn the command directly fail.", "steps": [ { "title": "Wrap npx with cmd /c", "text": "Make cmd the command and pass /c npx … as args.", "code": "{\n \"mcpServers\": {\n \"github\": {\n \"command\": \"cmd\",\n \"args\": [\"/c\", \"npx\", \"-y\", \"@modelcontextprotocol/server-filesystem\", \"C:\\\\Users\\\\you\\\\Desktop\"]\n }\n }\n}" }, { "title": "Escape backslashes", "text": "In JSON every Windows path backslash must be doubled: C:\\\\Users\\\\you.", "code": null }, { "title": "Add APPDATA if npm cannot find its cache", "text": "Some setups need APPDATA passed through.", "code": "\"env\": { \"APPDATA\": \"C:\\\\Users\\\\you\\\\AppData\\\\Roaming\\\\\" }" } ], "relatedServers": [ "filesystem", "desktop-commander", "playwright" ], "sources": [ "https://modelcontextprotocol.io/docs/develop/connect-local-servers", "https://nodejs.org/api/child_process.html#spawning-bat-and-cmd-files-on-windows" ], "url": "https://plugolis.com/fixes/windows-npx-mcp-cmd-c/" }, { "slug": "mcp-env-vars-not-passed", "title": "MCP server can't see my API key (env vars not passed)", "clients": [ "Claude Desktop", "Cursor", "Claude Code", "VS Code" ], "error": "401 Unauthorized • \"API key is required\" • \"Missing environment variable\"", "cause": "MCP clients start servers with a minimal environment. Variables exported in your shell profile are usually not inherited, so the key has to be put in the server's env block (or passed with the client's CLI flag).", "steps": [ { "title": "Add an env block next to command/args", "text": "Keys go inside the server entry, not at the top level.", "code": "{\n \"mcpServers\": {\n \"brave-search\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@brave/brave-search-mcp-server\"],\n \"env\": { \"BRAVE_API_KEY\": \"your-key\" }\n }\n }\n}" }, { "title": "Claude Code: use -e", "text": "Pass variables with --env/-e when adding the server.", "code": "claude mcp add brave -e BRAVE_API_KEY=your-key -- npx -y @brave/brave-search-mcp-server" }, { "title": "VS Code: use inputs for secrets", "text": "VS Code's mcp.json supports ${input:…} prompts so you don't hardcode keys.", "code": "{\n \"inputs\": [{ \"type\": \"promptString\", \"id\": \"brave-key\", \"description\": \"Brave API key\", \"password\": true }],\n \"servers\": {\n \"brave\": { \"command\": \"npx\", \"args\": [\"-y\", \"@brave/brave-search-mcp-server\"], \"env\": { \"BRAVE_API_KEY\": \"${input:brave-key}\" } }\n }\n}" }, { "title": "Restart and avoid committing keys", "text": "Restart the client. Add project-level config files that contain keys to .gitignore.", "code": null } ], "relatedServers": [ "brave-search", "firecrawl", "github" ], "sources": [ "https://docs.claude.com/en/docs/claude-code/mcp", "https://code.visualstudio.com/docs/copilot/customization/mcp-servers", "https://modelcontextprotocol.io/docs/develop/connect-local-servers" ], "url": "https://plugolis.com/fixes/mcp-env-vars-not-passed/" }, { "slug": "mcp-json-config-syntax-error", "title": "MCP config JSON syntax errors (trailing commas, comments, quotes)", "clients": [ "Claude Desktop", "Cursor", "Windsurf" ], "error": "Unexpected token } in JSON at position … • \"Failed to parse MCP config\" • servers silently missing", "cause": "MCP config files are strict JSON: no trailing commas, no comments, double quotes only, and backslashes must be escaped. One error disables every server in the file.", "steps": [ { "title": "Validate the file", "text": "Run it through a JSON parser.", "code": "python3 -m json.tool ~/.cursor/mcp.json\n# or\nnode -e \"JSON.parse(require('fs').readFileSync(process.argv[1]))\" ~/.cursor/mcp.json" }, { "title": "Remove trailing commas and comments", "text": "The last item in an object or array must not end with a comma; delete any // comments.", "code": null }, { "title": "Merge into a single mcpServers object", "text": "When adding a second server, put it inside the same mcpServers object. Don't paste a second top-level block.", "code": "{\n \"mcpServers\": {\n \"memory\": { \"command\": \"npx\", \"args\": [\"-y\", \"@modelcontextprotocol/server-memory\"] },\n \"fetch\": { \"command\": \"uvx\", \"args\": [\"mcp-server-fetch\"] }\n }\n}" } ], "relatedServers": [ "memory", "fetch", "time" ], "sources": [ "https://modelcontextprotocol.io/docs/develop/connect-local-servers", "https://cursor.com/docs/context/mcp" ], "url": "https://plugolis.com/fixes/mcp-json-config-syntax-error/" }, { "slug": "cursor-too-many-mcp-tools", "title": "Too many MCP tools: tool limits in Windsurf, Cursor and VS Code", "clients": [ "Windsurf", "Cursor", "VS Code" ], "error": "Tool limit warnings, or the agent ignoring tools from a server you enabled", "cause": "Agents work best with a limited set of tools, and some clients enforce a hard cap. Windsurf's docs say Cascade has a limit of 100 total tools at any given time. Cursor's and VS Code's current MCP docs don't publish a fixed number, but both let you switch tools off. Big servers like GitHub or AWS can expose dozens of tools each, so a few servers add up quickly.", "steps": [ { "title": "Disable servers you are not using", "text": "Cursor: Customize → MCP, toggle the server off. Windsurf: the MCPs section of the Cascade panel's ... menu shows tool counts per server, with a toggle for each.", "code": null }, { "title": "Turn off individual tools", "text": "VS Code: click Configure Tools in the chat input and untick tools. Windsurf: list tool names in the server's disabledTools array.", "code": "{\n \"mcpServers\": {\n \"github\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@modelcontextprotocol/server-github\"],\n \"disabledTools\": [\"create_repository\"]\n }\n }\n}" }, { "title": "Use server-side toolsets", "text": "Some servers let you load only a subset. GitHub's server supports GITHUB_TOOLSETS.", "code": "\"env\": { \"GITHUB_PERSONAL_ACCESS_TOKEN\": \"…\", \"GITHUB_TOOLSETS\": \"repos,issues,pull_requests\" }" } ], "relatedServers": [ "github", "aws", "playwright" ], "sources": [ "https://docs.windsurf.com/windsurf/cascade/mcp", "https://cursor.com/docs/context/mcp", "https://code.visualstudio.com/docs/copilot/customization/mcp-servers", "https://github.com/github/github-mcp-server" ], "url": "https://plugolis.com/fixes/cursor-too-many-mcp-tools/" }, { "slug": "spawn-uvx-enoent", "title": "Fix \"spawn uvx ENOENT\" for Python MCP servers", "clients": [ "Claude Desktop", "Cursor" ], "error": "Error: spawn uvx ENOENT", "cause": "Python servers such as fetch, git, time, and many awslabs servers launch with uvx, which comes from uv. Either uv isn't installed, or it lives in ~/.local/bin, which GUI apps don't have on their PATH.", "steps": [ { "title": "Install uv", "text": "Use the official installer.", "code": "curl -LsSf https://astral.sh/uv/install.sh | sh\n# Windows (PowerShell):\npowershell -ExecutionPolicy ByPass -c \"irm https://astral.sh/uv/install.ps1 | iex\"" }, { "title": "Use the absolute path", "text": "Find it with which uvx and put it in the config.", "code": "{\n \"mcpServers\": {\n \"fetch\": { \"command\": \"/Users/you/.local/bin/uvx\", \"args\": [\"mcp-server-fetch\"] }\n }\n}" }, { "title": "Restart the client", "text": "", "code": null } ], "relatedServers": [ "fetch", "git", "time", "aws" ], "sources": [ "https://docs.astral.sh/uv/getting-started/installation/", "https://modelcontextprotocol.io/docs/develop/connect-local-servers" ], "url": "https://plugolis.com/fixes/spawn-uvx-enoent/" }, { "slug": "mcp-error-32000-connection-closed", "title": "\"MCP error -32000: Connection closed\": what it means and how to fix it", "clients": [ "Claude Desktop", "Claude Code", "Cursor" ], "error": "McpError: MCP error -32000: Connection closed", "cause": "The server process exited before it finished the handshake. Common reasons: a missing dependency, wrong Node version, missing API key, bad args, or Windows npx without cmd /c. The real error is in the server's stderr.", "steps": [ { "title": "Run the exact command in a terminal", "text": "The crash message shows up immediately.", "code": "npx -y @modelcontextprotocol/server-filesystem /path/that/exists" }, { "title": "Test with the MCP Inspector", "text": "The Inspector starts the server and shows its stderr and protocol messages.", "code": "npx @modelcontextprotocol/inspector npx -y @modelcontextprotocol/server-memory" }, { "title": "Check common culprits", "text": "Windows → use cmd /c. Keys → env block. Node → node version.", "code": null } ], "relatedServers": [ "everything", "filesystem", "memory" ], "sources": [ "https://modelcontextprotocol.io/docs/tools/debugging", "https://modelcontextprotocol.io/docs/develop/connect-local-servers" ], "url": "https://plugolis.com/fixes/mcp-error-32000-connection-closed/" }, { "slug": "mcp-error-32001-request-timed-out", "title": "\"MCP error -32001: Request timed out\"", "clients": [ "Claude Desktop", "Claude Code", "Cursor" ], "error": "McpError: MCP error -32001: Request timed out", "cause": "The client gave up waiting. On first run, npx/uvx may still be downloading the package. Slow tools (browser automation, big crawls) can also go over the default timeout.", "steps": [ { "title": "Pre-install the package", "text": "Run the command once in a terminal so the download is cached.", "code": "npx -y @playwright/mcp@latest --help" }, { "title": "Raise the timeout (Claude Code)", "text": "Claude Code reads MCP_TIMEOUT (startup) and MAX_MCP_OUTPUT_TOKENS.", "code": "MCP_TIMEOUT=30000 claude" }, { "title": "Pin a version", "text": "Using @latest makes npx check the registry every launch. Pinning a version avoids that.", "code": null } ], "relatedServers": [ "playwright", "firecrawl", "chrome-devtools" ], "sources": [ "https://docs.claude.com/en/docs/claude-code/mcp", "https://modelcontextprotocol.io/docs/tools/debugging" ], "url": "https://plugolis.com/fixes/mcp-error-32001-request-timed-out/" }, { "slug": "mcp-stdout-not-valid-json", "title": "\"Unexpected token … is not valid JSON\" from a custom MCP server", "clients": [ "Claude Desktop", "Cursor", "Claude Code" ], "error": "SyntaxError: Unexpected token 'S', \"Server sta\"... is not valid JSON", "cause": "With the stdio transport, stdout is reserved for JSON-RPC messages. Any console.log / print() to stdout corrupts the stream.", "steps": [ { "title": "Log to stderr instead", "text": "Node: use console.error. Python: print(..., file=sys.stderr) or the logging module.", "code": "// Node\nconsole.error(\"Server started\");\n\n# Python\nimport sys\nprint(\"Server started\", file=sys.stderr)" }, { "title": "Silence noisy dependencies", "text": "Libraries that print banners or progress bars to stdout must be silenced or redirected.", "code": null } ], "relatedServers": [ "everything", "sequential-thinking" ], "sources": [ "https://modelcontextprotocol.io/specification/2025-06-18/basic/transports", "https://modelcontextprotocol.io/docs/tools/debugging" ], "url": "https://plugolis.com/fixes/mcp-stdout-not-valid-json/" }, { "slug": "mcp-server-wrong-node-version", "title": "MCP server crashes because the client uses an old Node version", "clients": [ "Claude Desktop", "Cursor" ], "error": "SyntaxError: Unexpected token '?' • ReferenceError: fetch is not defined • ERR_REQUIRE_ESM", "cause": "With nvm installed, a GUI app may pick up an old system Node (e.g. v16) instead of your nvm default. Modern MCP servers need Node 18+ and often 20+.", "steps": [ { "title": "Check which Node the client sees", "text": "Temporarily set command to node with args [\"-v\"] and read the log, or compare /usr/local/bin/node -v with node -v.", "code": null }, { "title": "Point at a modern Node directly", "text": "Use the absolute npx path from your nvm version and put its bin folder first in PATH.", "code": "{\n \"command\": \"/Users/you/.nvm/versions/node/v22.11.0/bin/npx\",\n \"args\": [\"-y\", \"@upstash/context7-mcp\"],\n \"env\": { \"PATH\": \"/Users/you/.nvm/versions/node/v22.11.0/bin:/usr/bin:/bin\" }\n}" }, { "title": "Or upgrade the system Node", "text": "Install a current LTS from nodejs.org so every app gets it.", "code": null } ], "relatedServers": [ "context7", "playwright", "chrome-devtools" ], "sources": [ "https://github.com/nvm-sh/nvm", "https://modelcontextprotocol.io/docs/develop/connect-local-servers" ], "url": "https://plugolis.com/fixes/mcp-server-wrong-node-version/" }, { "slug": "claude-code-mcp-server-not-found", "title": "Claude Code: MCP server added but not available (\"No MCP servers configured\")", "clients": [ "Claude Code" ], "error": "No MCP servers configured • server missing from /mcp in another folder", "cause": "claude mcp add defaults to local scope, which only applies to the current project directory. Open a different folder and the server is gone.", "steps": [ { "title": "Pick the right scope", "text": "-s user for every project, -s project to share through .mcp.json in the repo.", "code": "claude mcp add -s user context7 -- npx -y @upstash/context7-mcp\nclaude mcp list" }, { "title": "Put -- before the server command", "text": "Everything after -- is the server command; flags placed after it go to the server, not to Claude.", "code": "claude mcp add -s user -e GITHUB_PERSONAL_ACCESS_TOKEN=ghp_xxx github -- docker run -i --rm -e GITHUB_PERSONAL_ACCESS_TOKEN ghcr.io/github/github-mcp-server" }, { "title": "Check status inside Claude", "text": "Run /mcp to see connection state and authenticate remote servers.", "code": null } ], "relatedServers": [ "context7", "github", "serena" ], "sources": [ "https://docs.claude.com/en/docs/claude-code/mcp" ], "url": "https://plugolis.com/fixes/claude-code-mcp-server-not-found/" }, { "slug": "vscode-mcp-servers-key", "title": "VS Code ignores my MCP config (\"servers\" vs \"mcpServers\")", "clients": [ "VS Code" ], "error": "Server does not appear in the MCP: List Servers view; config copied from Cursor/Claude does nothing", "cause": "VS Code's .vscode/mcp.json uses a top-level servers key, not mcpServers like Cursor and Claude Desktop.", "steps": [ { "title": "Rename the key", "text": "Use servers in .vscode/mcp.json.", "code": "{\n \"servers\": {\n \"playwright\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@playwright/mcp@latest\"]\n }\n }\n}" }, { "title": "Start the server", "text": "Run MCP: List Servers from the Command Palette, select the server, and choose an action (start/restart).", "code": null }, { "title": "Enable its tools in chat", "text": "Click Configure Tools in the chat input and make sure the server's tools are switched on.", "code": null } ], "relatedServers": [ "playwright", "github", "chrome-devtools" ], "sources": [ "https://code.visualstudio.com/docs/copilot/customization/mcp-servers" ], "url": "https://plugolis.com/fixes/vscode-mcp-servers-key/" }, { "slug": "github-mcp-bad-credentials", "title": "GitHub MCP server: \"Bad credentials\" / 401 errors", "clients": [ "Claude Desktop", "Cursor", "VS Code", "Claude Code" ], "error": "401 Bad credentials • \"GITHUB_PERSONAL_ACCESS_TOKEN not set\"", "cause": "The token is missing, expired, or lacks scopes. With Docker, the variable also has to be forwarded into the container (-e GITHUB_PERSONAL_ACCESS_TOKEN) and set in the env block.", "steps": [ { "title": "Create a token with the right access", "text": "Fine-grained or classic PAT with repo access for the repos you need.", "code": null }, { "title": "Forward the variable into Docker", "text": "Both parts are required.", "code": "{\n \"mcpServers\": {\n \"github\": {\n \"command\": \"docker\",\n \"args\": [\"run\", \"-i\", \"--rm\", \"-e\", \"GITHUB_PERSONAL_ACCESS_TOKEN\", \"ghcr.io/github/github-mcp-server\"],\n \"env\": { \"GITHUB_PERSONAL_ACCESS_TOKEN\": \"ghp_your_token\" }\n }\n }\n}" }, { "title": "Make sure Docker is running", "text": "If Docker Desktop is stopped, the server exits with \"Connection closed\".", "code": null } ], "relatedServers": [ "github" ], "sources": [ "https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens", "https://github.com/github/github-mcp-server" ], "url": "https://plugolis.com/fixes/github-mcp-bad-credentials/" }, { "slug": "windsurf-mcp-config-not-loading", "title": "Windsurf: MCP server not loading in Cascade (mcp_config.json location)", "clients": [ "Windsurf" ], "error": "Server missing from Cascade's MCP list or shown as errored after editing mcp_config.json", "cause": "Windsurf's current docs put mcp_config.json at ~/.config/devin/mcp_config.json (macOS/Linux) or %APPDATA%\\devin\\mcp_config.json (Windows). Older guides point at ~/.codeium/windsurf/. The file applies only to the legacy Cascade agent; the default Devin Local agent reads the Devin CLI config instead. The usual JSON, PATH, and Windows npx problems also apply.", "steps": [ { "title": "Open the file from Windsurf", "text": "In the Cascade panel, click the ... (Actions) menu, then Open MCP config file in the MCPs section. Use a top-level mcpServers key.", "code": "{\n \"mcpServers\": {\n \"context7\": { \"command\": \"npx\", \"args\": [\"-y\", \"@upstash/context7-mcp\"] }\n }\n}" }, { "title": "Check which agent you are using", "text": "If the tab runs the Devin Local agent, configure MCP in the Devin CLI config files, not mcp_config.json.", "code": null }, { "title": "Apply the PATH/Windows fixes", "text": "See spawn npx ENOENT and Windows cmd /c.", "code": null } ], "relatedServers": [ "context7", "magic", "firecrawl" ], "sources": [ "https://docs.windsurf.com/windsurf/cascade/mcp" ], "url": "https://plugolis.com/fixes/windsurf-mcp-config-not-loading/" } ] }