Why Your MCP Server Isn't Connecting to Claude (and 9 Fixes)

If Claude Desktop shows your server but the tools don't appear, or the plug icon is missing entirely, one of these is almost always the cause.

1. Wrong path in the config

claude_desktop_config.json doesn't expand ~. Use the absolute path. /Users/you/projects/..., not ~/projects/....

2. Node not on PATH for GUI apps

Claude Desktop launches with the GUI's environment, not your shell's. If you installed Node with nvm, the binary may not be visible. Use the full path to node and your script, or symlink them somewhere global.

3. Logs going to stdout

Stdout is reserved for the MCP protocol. Any console.log corrupts the stream. Send logs to stderr (console.error) or to a file.

4. Protocol version mismatch

If your SDK is older than the client, the handshake fails silently. Update @modelcontextprotocol/sdk to the latest.

5. The server crashes on startup

Run it manually:

node /absolute/path/to/server.js

If it errors out, fix that first. Claude won't tell you about a crashed process; the plug icon just never appears.

6. Tool schema is invalid JSON Schema

Most clients silently drop tools with bad schemas. Validate yours with a JSON Schema validator before assuming your code is wrong.

7. Tool name has a space or unsupported character

Tool names should match [a-zA-Z0-9_-]+. get user will be rejected. Use get_user.

8. Description is empty or too long

Empty descriptions get filtered. Descriptions over a few thousand characters get truncated and may render as garbage.

9. You forgot to restart Claude

Config changes only load on launch. Quit fully (not just close the window) and reopen.

Diagnose without guessing

Trial and error in Claude Desktop is slow because every iteration costs an app restart. Point PreMan at your server instead. It shows the raw initialize handshake, the tool list, and any protocol errors in plain text. Once it works there, plugging into Claude is a one-line config change.

→ Debug your MCP server in PreMan