How to Fix “Error Executing MCP Tool: Not Connected”

“Error Executing MCP Tool: Not Connected” means your host client does not currently have a usable connection to the selected MCP server. It does not, by itself, prove that the server is stopped. A process can print a startup message and still fail before the client completes initialization.

Use this order:

Confirm the intended MCP server is enabled and marked connected in the host.
Read the host’s MCP logs and the server’s startup output.
Verify the command, arguments, environment, working directory, and runtime from the host’s environment.
Confirm both sides support the configured transport and initialization handshake.
Retry once, then verify the status and logs again.

1. What “Not Connected” means

Model Context Protocol (MCP) is an open standard for connecting AI applications to external tools and data. An MCP host launches or contacts a server, negotiates a transport, and completes initialization before tools can be called. “Not connected” is a connection-state symptom: the client cannot currently use a working connection to the selected server.

The same wording has appeared with different servers and clients, including GitHub, Sequential Thinking, and Context7 combinations. In several reports, the server printed that it was running on stdio while the client still could not use its tools. That distinction matters: process started is not the same as MCP handshake completed.

2. Fast recovery checklist

Open the host’s MCP or integrations panel.
Select the exact server entry you intended to use.
Enable it if disabled and check whether the UI says connected.
Use Retry connection or reconnect once.
Run the tool again and note whether the error changes.
If retry times out or the error returns, continue with logs instead of repeatedly retrying.

One Roo Code report describes enabling a disabled server or retrying as a successful recovery in that case. A separate Cline report describes retry timing out, so a retry is a useful check, not a guaranteed fix.

3. Read the logs before changing configuration

Record the host version, server version, operating system, launch command, exit status, standard error, and whether the process remains alive. Look in the host’s MCP/integration logs first; they show what the application actually launched, which can differ from a command that works in your terminal.

What to look for

Immediate exit: missing executable, package, argument, runtime, or environment variable.
Repeated restart: the host launches the server, it exits, and the host tries again.
Startup text but no connection: the process is alive, but transport or initialization may not complete.
Timeout: the host cannot complete its connection within its wait period.
Protocol text on the wrong stream: diagnostic output sent to stdout can corrupt stdio communication; use stderr for human-readable logs when the server documentation requires it.

Do not treat a line such as “running on stdio” as proof of a completed handshake. Sequential Thinking and Context7 reports document that exact mismatch between manual startup output and the client’s “Not connected” state.

4. Verify the launch configuration

Check the configuration in the host application, not only a shell profile. GUI applications may have a different PATH, working directory, Node/Python installation, home directory, or environment than your terminal.

Configuration checklist

Item	Check	Typical symptom
Command	Use the executable path supported by the server documentation. Confirm it exists for the host process.	Process exits immediately or never appears.
Arguments	Check spelling, required flags, and package name.	Usage text, module-not-found error, or silent exit.
Environment	Confirm API tokens, configuration variables, and PATH entries are visible to the host.	Authentication or startup failure.
Working directory	Use a directory that exists and contains any required files.	Relative paths fail only in the GUI client.
Runtime	Verify the Node, Python, or other runtime version required by the server.	Syntax, dependency, or engine-version errors.
Package version	Compare the configured package/version with the server’s own instructions.	Arguments or protocol behavior do not match.

Reproduce the exact command

Copy the command, arguments, environment variables, and working directory from the host configuration and run them manually. Capture both output streams and the exit code. For a shell command, the pattern is:

your-mcp-command --required-argument 2>server.log
status=$?
printf 'exit status: %s\n' "$status"
cat server.log

Replace the placeholder with the documented server command. Avoid printing secrets into shared logs.

5. Check transport and initialization

The client and server must use a transport that both support. For local servers, this is often stdio; hosted servers may use another transport documented by that implementation. Verify:

The host configuration selects the transport expected by the server.
The server reads protocol messages from the expected stream.
Human-readable diagnostics are not mixed into protocol output.
The initialization handshake is implemented by both versions.
The host is not launching a different binary or package than the one you inspected.

The GitHub MCP issue lists protocol implementation, stdio compatibility, and initialization as investigation points. That report does not establish any one item as a universal cause. Treat these as targeted checks based on your logs, not as assumptions.

6. Retry safely and collect a useful report

Stop duplicate manually launched copies of the server.
Restart or reconnect the server from the host once.
Wait for the host to show a connected state.
Invoke a simple tool, if the server provides one.
If it fails, save the host and server versions, operating system, exact configuration with secrets removed, startup output, and the first connection error.

Repeated retries can hide the first failure under a stream of timeout messages. One clean retry gives you a useful comparison while preserving the original evidence.

7. Common errors and fixes

Symptom	Likely cause	Fix
Server is enabled but says “Not connected”	Startup succeeded but initialization did not complete.	Read host and server logs; verify transport, protocol streams, and handshake compatibility.
“Command not found” or “module not found”	The host cannot see the executable, package, or runtime.	Use an absolute path where supported, fix PATH for the host process, and verify the package name.
Works in a terminal, fails in the desktop app	Different environment, working directory, permissions, or runtime.	Compare the host’s effective command and environment with the terminal session.
Retry times out	The server is hung, repeatedly crashing, or the client is waiting on an incompatible transport.	Stop duplicate processes, inspect stderr and exit status, then check transport and handshake settings.
Token appears valid but connection still fails	Authentication is only one part of startup; process, transport, or protocol can still fail.	Verify the full launch path and initialization logs. Do not assume token validity isolates the problem.
Startup banner appears, tools remain unavailable	Human-readable startup output is not proof of a completed MCP connection.	Check whether the host received and accepted initialization responses.
Only one package version fails	Version-specific arguments or protocol behavior.	Follow that package’s documentation; consider pinning a version only when logs or documented compatibility point to it.

8. Reliability and performance considerations

Keep the process stable

Use the documented runtime and package version.
Give the host one authoritative server entry instead of duplicate entries.
Keep required credentials available to the launching process.
Send diagnostics to the correct stream and rotate verbose logs.
Record restarts and exit codes so a transient failure is distinguishable from a repeatable one.

Reduce connection delays

Remove unnecessary startup work from the server before initialization.
Use a local, deterministic working directory.
Check for dependency downloads or network calls that block startup.
After changing configuration, perform one clean reconnect and measure whether the host reaches connected state.

Security and cost

Keep tokens out of screenshots, issue reports, and copied logs. Redact secrets before sharing configuration. The supplied reports provide no prevalence, success-rate, uptime, or cost statistics for this error, so do not use a percentage to judge whether a remedy will work.

9. Or skip the browser setup

If your MCP workflow mainly needs website screenshots, ScreenshotNeo provides an MCP server for Claude, Cursor, and any MCP client, with take_screenshot, get_page_info, and capture_pdf tools. You can also call its HTTP API directly. See the ScreenshotNeo API and MCP documentation.

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);

ScreenshotNeo removes cookie banners, newsletter popups, and chat widgets before capture. Bot checks, blank pages, failed loads, timeouts, and cache hits are not billed, and response headers identify the page verdict and billing status. It supports configurable waits, headers, cookies, user agents, selectors, device presets, full-page capture, PDFs, custom CSS and JavaScript, signed links, async webhooks, bulk capture, and more. The Free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000 shots.

Create a free ScreenshotNeo account and connect your MCP client or make the first API call.

10. FAQ

Does “Not connected” mean the server is down?

No. It means the host cannot currently use a working connection. The process may be alive while initialization or transport negotiation is failing.

Will retrying always fix it?

No. A retry can clear a stale or disabled connection, but reports also describe retries timing out. If it returns, inspect logs and configuration.

Should I replace the server package immediately?

No. First verify the command, package name, runtime, environment, transport, and handshake. Change versions only when the server documentation or your logs identify a compatibility issue.

What information should I include in a bug report?

Include host and server versions, operating system, launch configuration with secrets removed, exit status, standard error, transport, and the first failure after a clean reconnect.

Can an MCP server print normal logs?

Follow that server’s transport instructions. For stdio servers, protocol data and human-readable diagnostics generally must remain on their expected separate streams; mixed output can prevent initialization.