Diagnose MCP client configs, local process startup, and stdio handshakes before tools fail to load.
Wellknown found it in public sources; nobody has proven control of it yet. Claiming takes one click if the repository is under your GitHub account, or a small file on your domain otherwise. Verified owners get the badge, 15-minute checks, status alerts, edits that outrank crawled data, and a ranking boost.
Agents can do it too: POST https://wellknown.network/api/v1/claims with {"agent":"mcp-server-doctor","method":"well_known_file"} — machine-readable steps at claim.json, guide at /docs/claim.
Everything here was measured by our prober or read from a registry. Nothing is self-reported.
Attributed to the source that supplied each field. Treated as claims, not facts.
# mcp-server-doctor Diagnose the **MCP client-to-server boundary**: configuration discovery, process launch, and the stdio JSON-RPC handshake that must succeed before tools can load. `mcp-server-doctor` is a dependency-free Python CLI for people who configure local Model Context Protocol servers in Claude, Cursor, Copilot, VS Code, or another agent client and then see missing commands, hidden startup failures, or empty tool lists. It statically checks client configuration and can launch a configured local stdio process to verify `initialize`, `notifications/initialized`, and advertised capability listing such as `tools/list`. > This is not a generic MCP server test client. It focuses on failures that happen **before tool invocation**: locating client config, resolving the executable and working directory, starting the process, preserving JSON-RPC stdout framing, and completing the stdio handshake. ## Why This Exists MCP adoption is moving quickly across AI coding tools, IDEs, and desktop assistants. The painful part is still local setup: - Config files live in different places across clients. - `npx`, `uvx`, Docker, Python, and absolute-path commands fail differently. - A server can show as configured but still expose no tools. - Tokens often get pasted into config files during troubleshooting. - Server logs accidentally written to stdout can break JSON-RPC. This tool gives developers and maintainers a fast preflight check for the exact boundary where an MCP client tries to start and discover a local server. | In scope | Out of scope | | --- | --- | | Client config discovery and validation | Testing whether individual MCP tools are semantically correct | | Command, package, environment, cwd, and shell-wrapper checks | Acting as an interactive MCP tool runner | | Local process startup and stdio JSON-RPC framing | Dynamic testing of remote HTTP or OAuth transports | | Initialize and advertised capability listing | Security approval for calling a discovered t…
Mapped onto the structured taxonomy from declared text and observed tool names. Confidence shown for derived entries.
Every source is kept verbatim. Field changes are logged as events.