How to Debug MCP Servers That Stop Working
How to Debug MCP Servers That Stop Working
You had MCP working yesterday. Today the tools are not showing up. No error message. No crash. Just silence.
This is the most common MCP debugging scenario and it almost always comes down to one of three things: the initialize handshake, the server process, or the transport layer.
Check the Initialize Handshake
Every MCP connection starts with an initialize request from the client to the server. If this handshake fails, nothing works. The server must respond with its capabilities and protocol version.
The fastest way to test this is sending a raw initialize request to your server's stdin and checking if you get a valid JSON-RPC response back. If the server does not respond or sends malformed JSON, you have found your problem.
Claude Desktop Silently Drops Connections
Claude Desktop has a habit of silently disconnecting from MCP servers without telling you. The tools disappear from the interface but there is no error notification. Check the Claude Desktop logs at ~/Library/Logs/Claude/ for connection errors.
A common cause is the server process crashing after initialization. It passes the handshake but dies when handling the first real request. Check if your server process is still running with ps aux | grep your-server-name.
Transport Layer Issues
If you are using stdio transport, make sure your server is not printing anything to stdout that is not valid JSON-RPC. A stray log message or debug print will corrupt the protocol stream and kill the connection.
For SSE transport, verify the port is not blocked and the server is actually listening. A firewall change or port conflict can break things without any obvious error.
Quick Debug Checklist
- Restart Claude Desktop completely - not just close the window
- Kill and restart the MCP server process
- Check server logs for startup errors
- Verify your
claude_desktop_config.jsonhas the correct path and arguments - Test the server manually with a raw initialize request
Fazm is an open source macOS AI agent. Open source on GitHub.