The diagnosis, in order
Follow these checks in order: the first one you find is almost always the cause.
- Validate the JSON. It's the most frequent error. Copy the contents of the configuration file into an AI chat (in the browser) and ask: "is this JSON valid? fix it." One comma too many or a missing brace prevents all the servers from loading, not just the new one.
- Restart the app completely. Assistants read the configuration only at startup. Closing the window isn't enough: actually quit (including from the icon in the tray, if it stays active) and reopen. It's the fix that solves half of the "I don't see the server" cases.
- Check Node.js. Open the terminal and type
node --version. If it doesn't respond with a number, Node isn't installed or isn't in the system path: install it from the official site and reopen the terminal and the app. - Check the path. The server's or folder's path must be exact and absolute. Copy it from the folder's properties instead of typing it by hand; on Windows you need double backslashes in the file.
A concrete example
Luca's filesystem server doesn't show up in Claude Desktop. Instead of reinstalling everything at random, he follows the order. First check: he pastes the file into a chat and asks whether the JSON is valid. The AI points out a missing comma after another server's block. He adds it, saves, and restarts Claude completely.
On restart the server appears. Time lost: three minutes, instead of an afternoon suspecting Node, the permissions, the server. The lesson is the order: the problem was the most common of all (broken JSON), and starting there found it immediately. Had he started by reinstalling Node, he would have fixed nothing.
When it does NOT work (and how to fix it)
If the server doesn't show up at all
After validating the JSON and restarting, if it's still not there, check that the entry is written in the right place in the file (inside mcpServers, or servers in VS Code) and that the name isn't duplicated. To see what's really happening, open the server with the official tool MCP Inspector (npx @modelcontextprotocol/inspector), which shows the messages exchanged and the errors.
If you get "command not found"
The computer can't find the server's command (usually npx or node). It means Node isn't installed or isn't in the system path. Reinstall Node.js, and after installation close and reopen both the terminal and the assistant, so they recognize the new command.
If the server starts and closes immediately
Sometimes the server starts and crashes. Common causes: a Node version too old for that server, or the server printing messages where it shouldn't and breaking communication. Update Node to the latest stable version, and try the server with the MCP Inspector: the error shown there tells you what's wrong.
A tip from someone who actually uses it
When you add a new server, connect them one at a time and immediately verify that it works before adding the next. That way, if something breaks, you know exactly which entry is the culprit. Adding five servers together and then discovering that "nothing works" forces you to dismantle everything to find the error: an apparent saving that becomes a hunt for the culprit.
Frequently asked questions
Where do I find the error messages?
Two places: the MCP Inspector (npx @modelcontextprotocol/inspector), which opens the server in a window and shows every exchange, and the app's own logs (serious assistants keep a record of server errors, usually reachable from the developer settings). Starting there beats trying at random.
I changed the file but nothing happens, why?
Almost always because the complete restart is missing. The configuration is read at startup: until you actually quit the app and reopen it, the changes have no effect. It's the first thing to recheck every time "nothing changes."
Sometimes is the problem a bug in the app and not mine?
Yes, it happens. There have been known regressions where an app update broke the connection to servers for everyone, regardless of the configuration. If you've checked JSON, Node, path, and restart and it still doesn't work, look for whether others are reporting the same problem after a recent update: in that case you wait for the fix, it's not your fault.