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

A developer has released mcp-why, a command-line tool that diagnoses why MCP servers show zero tools in clients. The tool identifies common configuration failures, such as server names with parentheses, npx launch issues on Windows, and unescaped paths, which official tools often miss. The developer created the tool after encountering these issues and reading through GitHub threads.

You add an MCP server to your config. The JSON is valid. The client even says "connected." And then: zero tools . No error. No hint. The official /doctor says nothing is wrong. If this has happened to you, welcome — the GitHub issues are full of us: npx on Windows /doctor fails to detect MCP configuration errorsAfter reading through these threads, the failures cluster into a handful of causes — and none of them are the MCP server's fault. They're client config failures that official tools don't diagnose. Here's the field guide. { "mcpServers": { "Home Assistant ha-mcp ": { "command": "npx", "args": "-y", "ha-mcp" } } } This looks harmless. But at least one major client silently drops every tool when an mcpServers key contains parentheses. Server shows connected, tools/list completes, and the UI displays nothing. One user reported chasing this for hours. Fix: rename the key — letters, numbers, hyphens, underscores only. npx on Windows { "command": "npx", "args": "-y", "@modelcontextprotocol/server-filesystem" } GUI apps on Windows frequently fail to spawn npx directly. The terminal works; the desktop client doesn't, because GUI processes don't get your shell environment. Fix: wrap it: { "command": "cmd", "args": "/c", "npx", "-y", "..." } npx works in your terminal because your shell loads NVM. GUI apps don't load your shell profile, so the binary simply isn't on their PATH. The 182-reaction issue above is exactly this. Fix: use the absolute path to the binary, or a shim the GUI can resolve. One unescaped Windows path "cwd": "C:\tools\my-server" and the whole config silently fails to parse. Some clients report this; others just show zero servers. Fix: run the file through any JSON validator — python -m json.tool config.json . Users report uv -launched servers that keep failing after the underlying script was fixed, because the tool runner cached the broken environment. Also: env blocks that reference variables the GUI process doesn't have. Fix: clear the tool runner's cache; inline absolute paths in env . So I wrote a tiny local CLI that reads MCP client configs and reports exactly these failure classes — with the reason and a suggested fix for each: pipx install git+https://github.com/lajiaojiang-ai/mcp-why.git mcp-why auto-discover common client configs mcp-why --config path/to/claude desktop config.json Example output: ERROR risky server name: Server name 'Home Assistant ha-mcp ' contains parentheses or brackets why: Some clients silently drop every tool when an mcpServers key contains parentheses. fix: Rename the key to letters, numbers, hyphen, or underscore only. WARNING windows npx: Server 'Home Assistant ha-mcp ' launches npx directly on Windows why: GUI apps often fail to spawn npx unless wrapped with cmd.exe /c. fix: Use {"command":"cmd","args": "/c","npx","-y","..." }. There's also an optional --probe that sends only initialize + tools/list over stdio it never calls a tool, and it can't touch your real endpoints — it's read-only diagnostics against config + a handshake . Repo: https://github.com/lajiaojiang-ai/mcp-why https://github.com/lajiaojiang-ai/mcp-why If it saved you from one more hour of staring at a valid-looking config, that's the whole point. Star it if it's useful, open an issue if it's wrong.