MCP Installation Errors: How to Fix the 12 Most Common Issues (2026)

Table of Contents

1. Why MCP Installs Fail
2. Before You Debug: 3 Quick Checks
3. The 12 Most Common MCP Install Errors
4. Where to Find the Logs
5. How to Prevent MCP Install Errors
6. Frequently Asked Questions

Why MCP Installs Fail

MCP installs look like they should "just work" — you paste a config block, restart the client, and a new tool appears. In practice, the install pipeline crosses three brittle boundaries: a JSON parser inside the client, a package manager pulling code from the internet, and a long-running subprocess that has to register its tools over stdio. Any one of them can silently swallow an error.

The good news is that 90% of failures fall into 12 recognisable patterns. Once you've seen each one, diagnosis takes seconds. This guide is that catalog — paired with the fix, the diagnostic command, and the prevention rule for each.

Before You Debug: 3 Quick Checks

Run these three checks before reading the error catalog. They eliminate 50% of "broken MCP" reports.

1. Did you fully restart the client? MCP configs are read only at client startup. Closing the window isn't enough — quit the app entirely (Cmd-Q on macOS, system-tray right-click-Quit on Windows) and relaunch. For Claude Code, type /quit and run claude again. For VS Code-based clients, Cmd-Shift-P > Reload Window.

2. Is your JSON valid? A single missing comma will silently disable every MCP in the file. Paste your config into jsonlint.com — if it doesn't parse, fix the error, save, and restart.

3. Can the install command run on its own? Open a terminal and run the exact command from your config — e.g. npx -y @modelcontextprotocol/server-filesystem ~/Documents. If it works there but not in the client, the problem is the client's config (path or env vars). If it fails there too, the package itself or your environment is broken.

If all three pass and the MCP still isn't working, walk through the catalog below.

The 12 Most Common MCP Install Errors

1. "Could not load MCP server"

Symptom: Client UI shows the server as red or missing. Log says "Could not load MCP server" or similar.

Cause: 9 times out of 10, a JSON syntax error in the config file. Missing comma between server entries is the most common.

Fix: Paste the config into jsonlint.com to find the syntax error. Save, then fully restart the client.

Prevention: Use the Skiln Config Generator or a JSON-aware editor like VS Code that highlights syntax errors as you type.

2. "npx: command not found"

Symptom: Log shows spawn npx ENOENT or "npx: command not found" when the client tries to start the server.

Cause: Node.js isn't installed, or it's installed but not on the PATH visible to the MCP client.

Fix: Install Node.js 18+ from nodejs.org. After install, fully quit your terminal AND the MCP client. Relaunch both. The new PATH only applies to processes started after the install.

Prevention: Test node --version and npx --version in a fresh terminal before installing your first MCP. Both should print a version number.

3. Server connects but no tools appear

Symptom: Client shows the server as connected (green / 0 tools).

Cause: Most often, the client UI hasn't refreshed yet. Sometimes the MCP failed to enumerate tools because of a config error in the server itself.

Fix: Wait 5-10 seconds and refresh the MCP panel. If still empty, check the server's log for an enumeration error. Most MCPs print "Registered N tools" on successful startup; absence of that line means the server didn't initialise correctly.

Prevention: Test a server independently in the terminal first — if npx -y @scope/mcp-name shows tool registration on startup, the client will too.

4. "Permission denied" on Filesystem MCP

Symptom: Filesystem MCP fails with "EACCES: permission denied" or "ENOENT: no such file or directory".

Cause: The path in your args either doesn't exist or your user account doesn't have read/write permission.

Fix: Replace the path with one you know exists and own — ~/Documents or ~/Desktop are safe defaults. On Windows, use forward slashes or escaped backslashes (e.g. C:/Users/yourname/Documents or C:\\Users\\yourname\\Documents).

Prevention: Use absolute paths. Tilde-prefixed paths (~/Documents) only work in some clients — when in doubt, expand them to the full home path before pasting into config.

5. "401 Unauthorized" on API-backed MCPs

Symptom: Server starts, tools appear, but calls return "401 Unauthorized" or "invalid_token".

Cause: API key in the env block is missing, expired, malformed, or doesn't have the right scopes.

Fix: Regenerate the token with the scopes the MCP's README specifies. For GitHub MCP, that's typically repo, read:org, and read:user. For Slack MCP, that's chat:write, channels:read, users:read. Paste the new token into the env block (no quotes around the value) and restart.

Prevention: Store API keys in a password manager and document which MCP uses which key. Rotate every 90 days.

6. "spawn ENOENT" for uvx-based MCPs

Symptom: Log says spawn uvx ENOENT when the MCP starts.

Cause: The MCP is a Python server and needs uvx (from the uv Python package manager). uv isn't installed.

Fix: Install uv from astral.sh/uv. On macOS, brew install uv. On Windows, the installer script. Restart your terminal AND the MCP client.

Prevention: When installing a Python-based MCP for the first time, the install instructions on Skiln explicitly call out the uvx prerequisite — pay attention to it.

7. MCP works in one client, fails in another

Symptom: Identical config works in Claude Desktop but fails in Claude Code (or Cursor, or Windsurf).

Cause: Each client looks at a different config file path. You may have edited the wrong one.

Fix: Use the table in our desktop install guide to find the right path for each client. Copy the working config from one client into the right file for the other.

Prevention: When testing a new MCP, paste the config into the simplest client (Claude Desktop) first. Once it works there, copy to other clients knowing the JSON itself is correct.

8. Server starts then crashes within seconds

Symptom: Server appears briefly in the UI, then disappears. Log shows the server exiting with a non-zero code soon after launch.

Cause: Almost always a misconfigured environment variable or missing dependency the MCP needs at startup. Some MCPs validate config on boot and exit if it's malformed.

Fix: Read the log for the actual error. Common ones: missing required env var, malformed connection string, unreachable backend (database down). Fix the upstream issue.

Prevention: Read the MCP's README before installing — the "Required environment variables" section is usually the first thing to copy-paste.

9. "Module not found" or version mismatch

Symptom: Log shows "Cannot find module" or "package version X required but Y installed".

Cause: You have a globally-installed older version of the MCP package, and it's shadowing the npx-fetched latest. Or you pinned an old version that's no longer compatible with the current MCP protocol.

Fix: Uninstall the global version (npm uninstall -g @modelcontextprotocol/server-X). Remove any version pin from your config (use @latest or no version specifier). Restart.

Prevention: Never install MCP servers globally. Always use npx -y so each run pulls the latest.

10. Tools appear but throw errors when called

Symptom: Server connects, tools enumerate, but actually calling a tool returns an error from the MCP.

Cause: Tool-level errors usually mean the MCP's backend is unreachable or misconfigured at call time — wrong DB connection, expired OAuth, network issue.

Fix: Read the specific tool error. "Connection refused" means the backend is down. "Permission denied" usually means missing API scope. "Schema mismatch" usually means the MCP's expectation of the backend changed in an update.

Prevention: Test each MCP's first tool call right after install — don't wait until you need it mid-workflow.

11. SSL/TLS errors on Windows or corp networks

Symptom: Server fails to start with "self signed certificate in certificate chain" or "unable to verify certificate".

Cause: You're behind a corporate proxy that re-signs HTTPS traffic with a custom root certificate. Node.js / npx don't trust it by default.

Fix: Set NODE_EXTRA_CA_CERTS=/path/to/your/corp-root.pem in the MCP server's env block. Your IT team can supply the cert file.

Prevention: If you work behind a proxy regularly, set NODE_EXTRA_CA_CERTS as a system-wide environment variable so every MCP picks it up automatically.

12. Claude can see the tool but won't use it

Symptom: The MCP is connected, the tool is visible, but Claude won't call it even when asked.

Cause: Tool descriptions matter. If the MCP's tool description is vague or doesn't match what you're asking for, Claude won't pick it up. This isn't really an install error — it's a discoverability issue.

Fix: Phrase your request to match the tool's described purpose. If you have multiple MCPs that could serve a request, name the MCP explicitly ("use the GitHub MCP to..."). Some MCPs let you edit tool descriptions in their config — clearer descriptions = higher use rate.

Prevention: Test each new MCP with explicit prompts ("Use the X MCP to do Y") for the first few uses so you learn its actual capabilities before relying on Claude's autodiscovery.

Where to Find the Logs

Tail the log while you restart the client. The startup sequence is verbose and will tell you exactly which server failed and why.

How to Prevent MCP Install Errors

Six habits eliminate most MCP install pain:

1. Use a JSON-aware editor. VS Code, Cursor, or Sublime — anything that highlights syntax errors as you type.
2. Restart the client after every config change. Not the window — the whole app.
3. Never install MCPs globally. Always npx -y (or uvx) so each launch pulls the right version.
4. Document your API keys. Track which MCP uses which token, with renewal dates.
5. Test in a terminal first. Run the install command outside the client to confirm the package works before debugging client config.
6. Use the Skiln Config Generator. It builds the JSON for you, eliminating syntax errors entirely.

Frequently Asked Questions

Why does my MCP server install fail silently?

Silent failures almost always trace to one of three things: a JSON syntax error in your config (the client ignores invalid configs), the MCP's runtime (Node.js or Python) isn't installed or isn't on PATH, or the client wasn't fully restarted after the config change. Check the client's log file — every major MCP client logs the underlying error, even when the UI doesn't show it.

Where are MCP server logs stored?

Claude Desktop logs to ~/Library/Logs/Claude/mcp-server-NAME.log on macOS and %APPDATA%\Claude\logs\ on Windows. Claude Code prints MCP errors inline when you run /mcp. Cursor logs to the Output panel under 'MCP Logs'. Windsurf logs to ~/.codeium/windsurf/logs/. Cline logs to the VS Code Output panel under 'Cline'.

How do I know if an MCP server is actually broken or if my install is wrong?

Run the install command directly in your terminal — e.g. npx -y @modelcontextprotocol/server-filesystem ~/Documents. If the server starts and prints Filesystem MCP server running on stdio, the package itself works and your problem is config-related. If it crashes, the package or your environment is broken.

Can I use the same MCP config across multiple clients?

The JSON shape is identical across Claude Desktop, Claude Code, Cursor, and Windsurf — only the file path differs. You can copy your mcpServers block from one client's config to another's without changes. The Skiln Config Generator exports a single block usable across all of them.

What's the difference between npx and uvx install commands?

npx runs Node-based MCPs (the most common type). uvx runs Python MCPs and requires uv (the modern Python package manager) to be installed first. Install uv from astral.sh/uv if you're seeing spawn uvx ENOENT errors. After installing, restart your terminal AND your MCP client.

Do MCP servers need to be installed globally?

No — and you shouldn't install them globally. npx -y downloads and runs the package in a temporary location, which keeps your system clean and ensures you always get the latest version. Global installs cause version drift between MCPs and are the #1 cause of 'Module not found' errors.

How do I update an MCP server to the latest version?

If you used npx -y, you're already getting the latest version on every startup — restart the client to pull the newest release. If you pinned a specific version (e.g. @modelcontextprotocol/server-github@1.2.3), update the version in your config and restart. Some MCPs publish breaking changes in minor versions, so check the changelog before updating production setups.

What should I do if none of these fixes work?

Open an issue on the MCP server's GitHub repo with: (1) your client name and version, (2) your config block (redact API keys), (3) the exact error from the client log, (4) the output of running the install command directly in your terminal. Most maintainers respond within a day. Browse our full MCP troubleshooting guide for additional debugging patterns.

Last updated: June 04, 2026 · Companion to the MCP Server Troubleshooting Guide and the Desktop Install Guide.