MCP server configured, but zero tools show up? Here's probably why

The MCP server has been configured, but it appears that no tools are available. Despite the server showing as connected, and the client confirming the connection, there are no tools or errors indicated. The official /doctor tool reports no issues. This problem has been experienced by many users, as evidenced by the numerous comments on GitHub. Some of the possible causes for this issue include:

1. Parentheses or brackets in the server name: Some clients may silently drop all tools when the `mcpServers` key contains parentheses. To resolve this, rename the key using only letters, numbers, hyphens, and underscores.

2. Using `npx` on Windows: The command `npx` may not work correctly on Windows when used directly. GUI applications often fail to spawn `npx` unless it is wrapped with `cmd.exe /c`. To fix this, use the command format `{ "command": "cmd", "args": [ "/c", "npx", "-y", ... ] }`.

3. NVM (or any version manager) paths: `npx` works in the terminal because the shell loads the version manager. GUI applications do not load the shell profile, so the binary is not found on the PATH. To resolve this issue, use the absolute path to the binary or a shim that the GUI can resolve.

4. JSON configuration errors: Even if the JSON looks fine, a single unescaped Windows path can cause the entire config to silently fail to parse. To fix this, run the file through a JSON validator, such as `python -m json.tool config.json`.

5. Stale caches and environment drift: Users have reported issues with UV-launched servers that continue to fail even after fixing the underlying script, due to the tool runner caching the broken environment. Additionally, env blocks that reference variables unavailable to the GUI process can cause problems. To address these issues, clear the tool runner's cache and use inline absolute paths in the environment.

To help diagnose these common issues, a small local CLI tool called `mcp-why` has been created. It can be installed using `pipx install git+https://github.com/lajiaojiang-ai/mcp-why.git` and run with the command `mcp-why --config path/to/claude_desktop_config.json`. The tool scans through common client configurations and reports the failure classes along with suggested fixes. For more information, visit the GitHub repository at https://github.com/lajiaojiang-ai/mcp-why.