MCP troubleshooting · local agent setup
MCP Server Not Connecting? Fix Missing Modules, PATH, and Stale Configs
Diagnose an MCP server that appears installed but disconnects immediately because its runtime, dependency tree, working directory, executable path, or saved client configuration is wrong.
The short answer
“Added successfully” only proves that an MCP configuration entry was written. It does not prove the configured process can start. Check the client status and logs, then verify the exact command outside the client. For Web2MD, reinstall the latest global package and rerun web2md-mcp-setup so stale temporary paths and incomplete dependency trees are replaced with an absolute Node and server path.
Why this workflow is different
Desktop and GUI clients often run with a different PATH and working directory from the terminal where setup was tested. A configuration may point to a deleted temporary checkout, a source file without installed dependencies, a relative executable unavailable to the GUI, or an environment that omits a required package. The visible symptom is usually generic—connection closed—even though the actionable error is one line earlier in the server log.
Typical inputs
- •MCP client logs containing connection closed, module not found, or file not found
- •The saved server command, arguments, scope, and absolute paths
- •The Node runtime and dependency tree used by the configured process
- •Claude Code, Cursor, Codex, Claude Desktop, or another stdio MCP host
Useful outcomes
- ✓A server command that starts in the same environment as the MCP client
- ✓Removal of stale temporary paths and incomplete local checkouts
- ✓A repeatable status check before asking the agent to call a tool
- ✓A support-ready diagnosis containing the first process error, not only the final disconnect message
Evidence behind this workflow
These findings define the page because they describe observed failure patterns and real selection criteria—not a profession name added to generic product copy.
An anonymized Web2MD client log repeated the same missing SDK import 39 times, then later failed because the configured /private/tmp server path no longer existed.
Why it matters: Automatic retries do not repair a broken executable path or dependency tree; setup must replace the saved command with a durable packaged path.
Source: Observed Web2MD client log, 6–15 Nov 2026
A public MCP issue shows “installed successfully” followed by missing-module failures when the client starts the server outside the expected dependency environment.
Why it matters: The first runtime error and working directory are more useful than the client’s final “connection closed” message.
Source: Model Context Protocol issue #1836Claude Code documentation separates adding a server from checking its connection status and inspecting the saved configuration.
Why it matters: A reliable setup flow must include add, verify, use, and repair—not stop after the add command succeeds.
Source: Claude Code MCP quickstart
A practical workflow
- 1
Capture the exact failure
Open the MCP client log and save the first runtime error, configured command, and timestamp. Do not diagnose from “connection closed” alone.
- 2
Remove the stale Web2MD setup
Reinstall with npm i -g web2md-mcp-server@latest, then rerun web2md-mcp-setup. The setup command replaces old entries in supported clients.
- 3
Verify the client status
Restart the client and inspect its MCP status or tool list. The server should initialize and list tools without an immediate transport close.
- 4
Verify the browser bridge separately
If public convert_url works but agent_convert fails, the MCP process is healthy; troubleshoot Chrome, extension sign-in, native host registration, and the cold restart next.
How to choose a webpage-to-Markdown tool
Test tools against the pages and operating constraints in the real pipeline. A strong benchmark uses representative sources and checks failure behavior, not only a clean demo article.
- Find the first process error
What to check: Read upward from “connection closed” until you find the first missing module, missing file, permission, runtime, or authentication error.
Where Web2MD fits: For Web2MD, a missing SDK import or missing dist/index.js means the saved server installation is incomplete or stale; it is not a Chrome extraction failure.
- Verify the saved executable
What to check: Inspect the exact command and arguments stored by the client. Confirm every absolute path still exists and is not inside a temporary directory.
Where Web2MD fits: web2md-mcp-setup resolves the current Node executable and packaged dist/index.js to absolute paths for GUI clients that do not inherit the shell PATH.
- Verify dependencies beside the entry point
What to check: Run the configured command directly and confirm its production dependencies are installed in the package tree it actually loads.
Where Web2MD fits: Install web2md-mcp-server@latest globally rather than pointing clients at a copied dist file or an incomplete source checkout.
- Restart the right processes
What to check: Restart the MCP client after changing its config, and fully quit Chrome when the native messaging host changed.
Where Web2MD fits: The setup summary tells you which clients were configured. Chrome requires a cold restart before it reads a new native host manifest.
Where it is useful
Module not found
The configured entry point exists but its dependency tree does not. Reinstall the packaged server instead of copying only dist/index.js.
Configured file no longer exists
The client points to /tmp, a deleted checkout, or an old package version. Replace it with a durable packaged absolute path.
Works in Terminal, fails in a desktop app
The GUI has a different PATH or working directory. Use an absolute runtime and entry-point path, then restart the app.
Server works, browser conversion fails
Separate transport health from browser bridge health. Check Chrome, extension sign-in, native messaging, and whether the page requires the browser path.
Start with the right Web2MD workflow
Frequently asked questions
Why does an MCP server say it installed successfully but fail to connect?
The install command may only have written a configuration entry. The client still has to launch that command in its own runtime, PATH, working directory, and environment. Inspect the first process error in the log and run the exact saved command directly.
How do I fix Cannot find module @modelcontextprotocol/sdk/server/mcp.js?
The entry point is running without its production dependency tree. For Web2MD, install the latest web2md-mcp-server package globally and rerun web2md-mcp-setup. Do not configure a copied dist/index.js from a temporary or incomplete source checkout.
Why does the MCP server work in Terminal but not Claude Desktop or Cursor?
GUI applications may not inherit your shell PATH or working directory. Configure an absolute runtime and server entry-point path, ensure dependencies live beside that package, and restart the desktop client.
What if the configured MCP path points to /tmp or /private/tmp?
Treat it as temporary and replace it. Temporary directories can be cleaned or replaced, leaving a valid-looking configuration that points to a file that no longer exists.
How can I tell whether MCP or Agent Bridge is broken?
Call a tool that does not need Chrome, such as convert_url. If tool listing and public conversion work but agent_convert fails, the MCP server is healthy and the remaining problem is the extension, native host, Chrome restart, or browser authorization path.