Nine out of ten MCP connection failures are not exotic. They are a typo, a port, or a process that never started. I have tripped over all three, usually in that order. This is the checklist I wish someone had handed me, organized from "check the boring thing first" to "okay now it gets interesting."
1. Start With the Config
Most failures trace back to the config block. Open your mcpServers section and check three words: command, args, env. Is the command spelled exactly as the package expects? Are all required arguments present? Is every environment variable the server needs actually defined? A single missing env value commonly surfaces as a confusing handshake failure. If you are unsure what the block should look like, this config JSON guide explains each key.
2. Did It Start at All?
Next, confirm the server process is actually running. If you launched it manually in a terminal, the app cannot connect unless that terminal stays open. If you used a process manager, verify the process is up. A very common gotcha: you restarted the app but not the server, or vice versa. Both the client and the server need to be freshly started after a config change.
3. Check the Port and Host
For a local server, "connection refused" almost always means a port or host mismatch. The server listens on one port, the config points at another, or one listens on 127.0.0.1 while the other expects a different host. Confirm the exact URL the server advertises matches the url in your config. For remote servers, a firewall or a blocked region can produce the same refusal — testing from a different network sometimes tells you instantly.
4. Read the Handshake Error
If the server is up and reachable but the connection fails anyway, look at the protocol error. In JSON-RPC, failures come back as structured error objects with a code and message, not just an HTTP status. That message usually says exactly what is wrong, like an unsupported protocol version. To read those errors fluently, this MCP and JSON-RPC explainer shows you what a healthy handshake looks like, which makes the failing one obvious.
5. Test the Endpoint Directly
Strip the AI app out of the equation. Point curl straight at the server and see if you get a sensible JSON-RPC response. If curl fails, the problem is the server. If curl works but your app does not, the problem is the app or its config. That single test splits the two halves of the system instantly. For a curl example against a real server, the connection guide includes one.
6. The Silent-Config Trap
Sometimes there is no error at all — the server just does not appear. Nine times out of ten this is a config file saved in the wrong location or in the wrong format (a stray comma will quietly break JSON parsing). Re-save the file by copy-pasting and make sure it is valid JSON before giving up and inspecting anything clever.
7. When All Else Fails
If you have verified the config, the process, the port, and the handshake, and the server still will not connect, check whether your client version supports the protocol version the server speaks. Version mismatches are the last common culprit and are usually resolved by updating one side or the other. If you are still stuck, knowing what an MCP server even is in the first place can reframe the whole problem — our what is an MCP server guide covers the foundation.
Wrapping Up
Connection failures in MCP are rarely deep mysteries. Config first, process second, port third, handshake fourth. Isolate the server with curl, and re-validate your config when things are silent. Follow that order and the vast majority of "MCP not working" reports vanish in a few minutes.