1. Quick diagnosis
Auth
401 / 403 from WP.
Transport
Server didn’t spawn.
Schema
Zod validation failure.
Runtime
Tool threw an exception.
2. Auth issues
3. Transport problems
If Claude Desktop says "server didn't connect": check the path in command is absolute, the binary is executable, and Node is on PATH. Tail the host log.
4. Tool execution failures
Wrap tool bodies in try/catch and return a structured isError response. Never throw raw exceptions — the agent will give up.
5. Debugging tips
Use the MCP inspector. Log every JSON-RPC frame to a file in dev. Replay failing sessions from the log to isolate the offending call.