{"slug": "mcp-server-configured-but-zero-tools-show-up-here-s-probably-why", "title": "MCP server configured, but zero tools show up? Here's probably why", "summary": "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.", "body_md": "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`\n\nsays nothing is wrong.\n\nIf this has happened to you, welcome — the GitHub issues are full of us:\n\n`npx`\n\non Windows`/doctor`\n\nfails 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.\n\n```\n{\n  \"mcpServers\": {\n    \"Home Assistant (ha-mcp)\": { \"command\": \"npx\", \"args\": [\"-y\", \"ha-mcp\"] }\n  }\n}\n```\n\nThis looks harmless. But at least one major client **silently drops every tool** when an `mcpServers`\n\nkey contains parentheses. Server shows connected, `tools/list`\n\ncompletes, and the UI displays nothing. One user reported chasing this for hours.\n\n**Fix:** rename the key — letters, numbers, hyphens, underscores only.\n\n`npx`\n\non Windows\n\n```\n{ \"command\": \"npx\", \"args\": [\"-y\", \"@modelcontextprotocol/server-filesystem\"] }\n```\n\nGUI apps on Windows frequently fail to spawn `npx`\n\ndirectly. The terminal works; the desktop client doesn't, because GUI processes don't get your shell environment.\n\n**Fix:** wrap it:\n\n```\n{ \"command\": \"cmd\", \"args\": [\"/c\", \"npx\", \"-y\", \"...\"] }\n```\n\n`npx`\n\nworks 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.\n\n**Fix:** use the absolute path to the binary, or a shim the GUI can resolve.\n\nOne unescaped Windows path (`\"cwd\": \"C:\\tools\\my-server\"`\n\n) and the whole config silently fails to parse. Some clients report this; others just show zero servers.\n\n**Fix:** run the file through any JSON validator — `python -m json.tool config.json`\n\n.\n\nUsers report `uv`\n\n-launched servers that keep failing *after* the underlying script was fixed, because the tool runner cached the broken environment. Also: `env`\n\nblocks that reference variables the GUI process doesn't have.\n\n**Fix:** clear the tool runner's cache; inline absolute paths in `env`\n\n.\n\nSo 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:\n\n```\npipx install git+https://github.com/lajiaojiang-ai/mcp-why.git\nmcp-why                    # auto-discover common client configs\nmcp-why --config path/to/claude_desktop_config.json\n```\n\nExample output:\n\n```\n[ERROR] risky_server_name: Server name 'Home Assistant (ha-mcp)' contains parentheses or brackets\n  why: Some clients silently drop every tool when an mcpServers key contains parentheses.\n  fix: Rename the key to letters, numbers, hyphen, or underscore only.\n\n[WARNING] windows_npx: Server 'Home Assistant (ha-mcp)' launches npx directly on Windows\n  why: GUI apps often fail to spawn npx unless wrapped with cmd.exe /c.\n  fix: Use {\"command\":\"cmd\",\"args\":[\"/c\",\"npx\",\"-y\",\"...\"]}.\n```\n\nThere's also an optional `--probe`\n\nthat sends only `initialize`\n\n+ `tools/list`\n\nover stdio (it never calls a tool, and it can't touch your real endpoints — it's read-only diagnostics against config + a handshake).\n\nRepo: [https://github.com/lajiaojiang-ai/mcp-why](https://github.com/lajiaojiang-ai/mcp-why)\n\nIf 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.", "url": "https://wpnews.pro/news/mcp-server-configured-but-zero-tools-show-up-here-s-probably-why", "canonical_source": "https://dev.to/lajiaojiang/mcp-server-configured-but-zero-tools-show-up-heres-probably-why-5a25", "published_at": "2026-08-16 00:28:53+00:00", "updated_at": "2026-08-16 01:11:13.913547+00:00", "lang": "en", "topics": ["developer-tools"], "entities": ["mcp-why", "lajiaojiang-ai", "MCP", "npx", "Windows", "GitHub"], "alternates": {"html": "https://wpnews.pro/news/mcp-server-configured-but-zero-tools-show-up-here-s-probably-why", "markdown": "https://wpnews.pro/news/mcp-server-configured-but-zero-tools-show-up-here-s-probably-why.md", "text": "https://wpnews.pro/news/mcp-server-configured-but-zero-tools-show-up-here-s-probably-why.txt", "jsonld": "https://wpnews.pro/news/mcp-server-configured-but-zero-tools-show-up-here-s-probably-why.jsonld"}}