MCP Server Not Working? 8 Fixes That Actually Help

You've edited the config file, restarted Claude Desktop, and asked "what tools do you have?" — and Claude has no idea what you're talking about. Or it did work before, and now it doesn't. Either way, you're not alone. Here are the eight most common MCP server problems and exactly how to fix each one.

Fix 1: Validate your JSON config file

This is the cause of at least half of all "MCP server not showing up" reports. A single misplaced comma, missing bracket, or extra brace breaks the entire config file silently — Claude Desktop just ignores the invalid file without telling you why.

Copy your entire claude_desktop_config.json content and paste it into jsonlint.com. It'll tell you exactly which line has the error. The most common mistakes: trailing comma after the last property, missing comma between server entries, and using single quotes instead of double quotes.

A valid config looks like:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path"]
    }
  }
}

Fix 2: Actually quit Claude Desktop (don't just close the window)

Closing the Claude Desktop window doesn't stop the process. The app keeps running in the background — and the old config is still loaded. You need to fully quit.

Mac: Right-click the dock icon → Quit. Or use Cmd+Q with the app in focus.

Windows: Right-click the system tray icon → Exit. Or use Task Manager to end the Claude process.

Then reopen. This alone fixes the issue roughly 30% of the time.

Fix 3: Check Node.js PATH visibility

Claude Desktop launches as a GUI app, not from a terminal. On Mac especially, GUI apps don't always inherit the full PATH that your terminal has. So even if npx works in your terminal, it might be invisible to Claude Desktop.

Find the full path to npx by running which npx in your terminal. Then use that full path in your config:

{
  "mcpServers": {
    "filesystem": {
      "command": "/usr/local/bin/npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path"]
    }
  }
}

On Apple Silicon Macs (M1/M2/M3), the path is usually /opt/homebrew/bin/npx.

Fix 4: Check the Claude Desktop error logs

Claude Desktop writes MCP-related errors to a log file. This is the most direct way to find out what's actually going wrong.

• Mac: ~/Library/Logs/Claude/mcp*.log
• Windows: %APPDATA%\Claude\logs\

Open the most recent log file and look for error messages near the startup time. Common errors you'll see: "command not found," "ENOENT" (file not found), "invalid API key," or JSON parse errors.

Fix 5: Check that the package name is correct

Package names in the npm registry are case-sensitive and easy to mistype. The official Anthropic packages all follow the pattern @modelcontextprotocol/server-[name]. If you typo'd the package name, npx silently fails.

Verify by running the install command manually in a terminal first:

npx -y @modelcontextprotocol/server-filesystem /tmp

If that works in your terminal, the package name is correct.

Fix 6: Check expired or invalid API tokens

If your server requires an API key (Brave Search, GitHub, Slack, etc.) and the server was working before but stopped recently, your token may have expired. GitHub fine-grained PATs default to 90-day expiry. Brave API keys don't expire by default but can be revoked.

Test your token manually with a curl command to the API. For GitHub:

curl -H "Authorization: Bearer YOUR_TOKEN" https://api.github.com/user

If you get a 401 Unauthorized, the token is expired or invalid. Generate a new one.

Fix 7: Pin your package version

Using npx -y @modelcontextprotocol/server-filesystem without a version always pulls the latest version. If a new version was just published with a breaking change, your server may break on the next Claude Desktop restart.

Pin to the last-known working version:

"args": ["-y", "@modelcontextprotocol/server-filesystem@0.6.2", "/path"]

Check the package's npm page or GitHub releases to find recent version numbers.

Fix 8: Check for port conflicts (remote servers only)

If you're running an SSE or HTTP-based MCP server (rather than a stdio server spawned by Claude Desktop), it needs a free port. If another process is already using that port, the server fails to start silently.

Check what's using a port with:

# Mac/Linux
lsof -i :3000

# Windows
netstat -ano | findstr :3000

Change the server's port in its config or kill the conflicting process.

What if none of these fixes work?

Open a GitHub issue on the specific server's repo. Include: your OS, Node.js version (node --version), the exact error from the log file, and your config (with tokens redacted). The maintainers are generally responsive, especially for official Anthropic servers.