mcp server doctor

    1

    Diagnose and fix broken MCP server connections, transport errors, and configuration gaps in AI clients.

    $11

    Secure checkout via Stripe

    Money-back guarantee

    Converts to your local currency at checkout

    Security scanned

    Works with the AI Agents you already use

    Claude CodeClaude CodeCursorCursorCodex CLICodex CLIMuseMuseDotsDots+21 more

    mcp server doctor

    Example session with this skill installed

    My MCP server works in the terminal but Claude Desktop shows 'Server transport closed unexpectedly'. Here is my config: {"mcpServers": {"my-server": {"command": "node", "args": ["server.js"]}}}

    • Read your context and instructions
    • Compiled the mcp server doctor

    The server is failing because the client cannot find the node executable or the server file due to a relative path and missing environment context. This matches pattern F-02 (Command not found) or F-04 (Path resolution failure).

    1. Diagnosis

    Your server is failing because the client process does not inherit your shell's PATH or working directory, preventing it from locating node or server.js.

    2. Evidence

    • Config: "command": "node" relies on the system PATH, which is often restricted in GUI applications.

    Config: "args": ["server.js"] uses a relative path. Clients spawn processes without knowledge of your project root.

    • Handshake: Reached No protocol traffic at all, confirming the process never successfully spawned.

    3. The fix

    Update your claude_desktop_config.json to use absolute paths for both the executable and the script.

    {
  "mcpServers": {
    "my-server": {
      "command": "/usr/local/bin/node",
      "args": ["/absolute/path/to/server.js"],
      "env": {
        "PATH": "/usr/local/bin:/usr/bin:/bin"
      }
    }
  }
}

    Using absolute paths removes the dependency on the host's shell environment.

    4. Verification

    1. Isolate: Run npx @modelcontextprotocol/inspector /usr/local/bin/node /absolute/path/to/server.js.
    2. Observe: Confirm the inspector opens a browser window and lists your tools.
    3. Client Check: Fully quit Claude Desktop (Cmd+Q) and restart.
    4. Log Check: Verify the client log shows connected for my-server.

    5. If that was not it

    F-01 (Stdout Pollution): The server might be printing non-JSON text on startup. Run node server.js 1>stdout.log and check if stdout.log contains anything other than JSON.

    F-05 (Permission Denied): Ensure the node binary and the script have read/execute permissions for the user running the IDE.

    Next steps

    • Run which node in your terminal to get the absolute path for the config.
    • Replace /absolute/path/to/server.js with the full path from your home directory.

    Connects securely to your tools. The creator never sees your data.

    About this skill

    Debug MCP servers without the guesswork. This skill stops you from wasting hours on server code when the real culprit is a missing environment variable or a polluted stdout stream. It provides a technical audit of your Model Context Protocol setup by analyzing logs and configs against a library of documented failure patterns.

    What it does

    • Diagnose connection failures by identifying why servers won't start, time out, or close unexpectedly.
    • Trace handshake breaks to pinpoint exactly where the protocol negotiation failed between the client and server.
    • Detect stdout pollution which is the primary cause of JSON-RPC parse errors in stdio transports.
    • Validate client configurations for common syntax errors, path issues, and environment gaps across major IDEs.
    • Isolate server logic from client-specific behavior using protocol inspector commands.

    How it works

    1. Analyze symptoms by comparing error codes and log fragments against the failure-patterns.md reference.
    2. Reconstruct the handshake using the parse_mcp_log.py script to find the exact protocol break point.
    3. Audit the environment to find discrepancies between your terminal and the IDE's spawned process.
    4. Generate the fix including corrected JSON configs or code changes to move diagnostics to stderr.
    5. Verify with commands that prove the server works in isolation before reconnecting to the client.

    Frameworks & tools

    Works with TypeScript and Python MCP SDKs. Supports Claude Desktop, Cursor, VS Code, Zed, and Windsurf. Uses npx @modelcontextprotocol/inspector for isolation testing.

    Why this beats prompting it yourself

    Generic LLMs often mistake environment-level spawn errors for internal logic bugs. This skill uses a specific diagnostic ladder and specialized regex scripts to identify the "silent" failures that standard prompts miss.

    Use cases

    • Fix "Connection closed" or error -32000 messages in Claude Desktop.
    • Debug why a server works in the terminal but shows no tools in Cursor.
    • Resolve JSON-RPC parse errors caused by library banners or logging statements.
    • Correct mcpServers configuration blocks for Windows path escaping or env expansion.

    Known limitations

    Cannot inspect your local filesystem or run servers directly. Relies entirely on pasted logs and configs. Does not perform design reviews of tool schemas unless they cause protocol failures.

    Find more skills like this on the Claude Skills Marketplace, the Codex Skills Marketplace and the Gemini Skills Marketplace, or browse Claude Skills for LLM Ops.

    Requires logs for confident diagnosis. Cannot access local files or network. Does not recommend 3rd-party servers. Focuses on connectivity over business logic.

    How to use

    1. 1

      Connect your agent to the Agensi MCP

      Copy the prompt and paste it into Claude, ChatGPT, Cursor or any agent that supports MCP. It sets up the connection for you. Manual setup

    2. 2

      Sign in to Agensi

      Your agent shows a sign-in link. Sign in and click Allow.

    3. 3

      Ask for what you need

      Your agent loads this skill and uses it on your task. It always asks before buying a skill.

    Reviews

    No reviews yet

    Be one of the first to try it. Every listed skill goes through the trust checks below.

    Security scanned

    Checked by our 8-point scan before listing

    Fresh listing

    Recently published to Agensi

    Money-back guarantee

    Doesn't do what its page promises? You get your money back.

    Trust & safety

    Security scan

    Security scan passed 2 days ago

    Software
    @modelcontextprotocol/inspectorNode.js

    Permissions

    Terminal / Shell
    Network Access
    Read Files
    Write Files
    Listed2 days ago

    What's inside

    Frequently Asked Questions

    The Doctor specializes in identifying "silent" failures, such as stdout pollution from console logs or environment variable mismatches between your terminal and IDE, which standard LLMs often misdiagnose as code logic errors.

    It supports all major MCP-enabled clients including Claude Desktop, Cursor, VS Code (via extensions), Zed, and Windsurf, covering both TypeScript and Python SDK implementations.

    You will receive the diagnostic agent skill, a library of documented MCP failure patterns, and specialized scripts designed to parse logs and isolate server logic from client behavior.

    Yes, while it specializes in protocol-level errors, it can identify when a JSON-RPC parse error is caused by a malformed tool schema or a missing required field in the server's initialization response.

    For security and privacy, the skill does not have direct access to your local files; it works by analyzing the logs, configuration snippets, and error codes you provide during the diagnostic session.

    New in LLM Ops