When an MCP server will not connect, check in this order: the command path, the config syntax, environment variables, the client logs, then a standalone test with the MCP Inspector. Most failures are one of the first three. This checklist follows the official MCP debugging guide.
Step 1: read the client log
Every client has a log. In Claude Desktop, logs go to a Logs folder under Library on macOS and under the roaming app data folder on Windows, in files named with an mcp prefix. The debugging guide shows a tail command for macOS. Logs capture connection events, configuration issues, runtime errors and message exchanges.
In Cursor, open the Output panel and choose MCP Logs. In VS Code, run MCP: List Servers and choose Show Output.
Step 2: check the launch command
The guide lists common startup problems:
- A wrong path to the server executable.
- Missing required files.
- Permission problems.
Use an absolute path for the command. A client may start from a different working directory than you expect, since for servers launched from config the directory may be undefined, such as the root folder on macOS. Relative paths like a dot slash data folder will then fail.
Step 3: check the config
Invalid JSON syntax, missing required fields and type mismatches all stop a server loading. A stray trailing comma is enough.
For Claude Code, one specific trap is a JSON entry with a url but no type. It is treated as stdio and skipped, so always set the type.
Step 4: check environment variables
Servers launched over stdio inherit only a limited subset of environment variables, and the set depends on the platform. If your server needs an API key or a PATH entry, put it in the env section of the config. A key exported in your shell may simply not be visible to the process the client starts.
Step 5: test it without the client
Run the server alone with the MCP Inspector. If it works there, the problem is the client config. If it fails there too, the problem is the server. See testing an MCP server with the Inspector.
Step 6: check protocol compatibility and restart
The current guide says to call the discover request to see which protocol versions a server supports. An unsupported version returns a specific error that lists supported versions. Requests missing the required version or capabilities metadata are rejected with an invalid params error, and a server that needs a capability the client did not declare returns a missing capability error.
Finally, restart the client after any config or server code change. For Claude Desktop, fully quit and reopen, since closing the window is not enough. When you share logs and configs for help, sanitise them. The guide lists protecting credentials and masking personal information under debugging security.
Quick check
My server works in the terminal but not in the client. Why?
Usual causes are a relative path, a different working directory, or environment variables the client did not pass. Use absolute paths and set env in the config.
Do I need to restart after editing config?
Yes. Restart the client, and for Claude Desktop quit it fully.
Sources
Last reviewed: 19 October 2026.
