How to debug an MCP connection

Check config, process, permissions, then a tool call. Do not reinstall the client first.

See whether the client shows connected. If not, inspect command, args, cwd and PATH. A wrong npx package name, or Node missing from a GUI app PATH, is the usual cause.

Connected but tools fail: read server logs and the first tool error. A stdio server that dies on boot often looks like a timeout. Run the same command in a terminal.

Permission failures get blamed on “MCP is broken”. A path outside the allow list, a key missing from env, or a remote OAuth prompt will fail the first tool. Try a read-only call.

If it still fails, keep one filesystem or fetch server to prove the client. The install snippet on a detail page is a start; swap in your paths and secrets.