The first time an MCP server fails, it looks like the model is being stupid. It calls a tool, gets nothing back, and apologizes. It usually is not the model. Here is the loop that finds the actual problem in a few minutes instead of a few hours.
Step one: run it outside the client
Take the install command from the listing and run it in a terminal. If it exits immediately, prints a version and returns, or waits on stdin, you have already learned which transport it expects. The Filesystem server waits on stdin; the Fetch server fetches one URL and exits. A client configured for the wrong one looks like a broken agent.
Step two: read the first line it prints
Servers that speak stdio usually write a startup line to stderr. If that line says it cannot find a key, a path, or a token, you are done — no amount of prompt tuning fixes a missing credential. The Notion server is the classic case: a valid token that has access to zero pages behaves exactly like a dead server.
Step three: call one tool by hand
Use the inspector or a one-line JSON-RPC request to list tools, then call the smallest one. If listing works and calling fails, the problem is arguments, not wiring. This distinction saves the most time, because the error messages are identical from the model's side.
Step four: check the client's config path
Every client reads a different file: Claude Desktop uses one path, Cursor another, and half the tutorials online reference a location that changed two versions ago. The listing on each server page shows the exact `mcpServers` block; paste it rather than retyping it.
Step five: only then suspect the model
If tools list, arguments are right, and results are wrong, you have a genuine reasoning or context problem. That is the point where comparing two servers or two models is worth doing, for example Context7 for version-accurate docs, or one of the code-intelligence packages in the MCP directory when the agent keeps reading the wrong part of a codebase.
The pattern is always the same: eliminate transport, then credentials, then arguments, then context. In that order, ninety percent of MCP bugs die before you touch a prompt.