MCP Server Disconnected? Here's the Actual Fix (2026)

Your MCP server was working five minutes ago. Now Claude Desktop, Claude Code, or Cursor just shows "disconnected" and gives you nothing else to go on. No stack trace, no line number, just a status dot that turned red. Here's what is actually happening and how to fix it.

MCP servers run as a subprocess of your AI client, not as some remote service you can curl. That single fact explains almost every disconnect you'll ever see. When you see "disconnected," one of four things happened: the process never started, it started and then crashed, its stdout got polluted with something that isn't valid JSON-RPC, or there's a mismatch between the transport your client expects and the one your server actually speaks. That's the whole list. Once you know which of the four you're dealing with, the fix is usually five minutes, not an afternoon of guessing.

The Model Context Protocol defines two transports that matter for local development: stdio and Streamable HTTP (which replaced the older HTTP+SSE transport). Almost every MCP server you run locally, whether it's one you wrote or one you installed from npm or PyPI, uses stdio. That means your AI client spawns your server as a child process and talks to it by writing JSON-RPC messages to the child's standard input and reading JSON-RPC messages back from its standard output.

That's the entire mechanism. There's no socket, no port, no HTTP handshake to inspect in your browser's network tab. Which is exactly why "disconnected" feels like a black box: the failure is happening at the process and stream level, somewhere between your operating system spawning a subprocess and two programs agreeing on a message format. Every real cause of an MCP disconnect traces back to one of those two mechanics breaking down.

Before you touch any client config, try running your server's exact start command directly in a terminal, completely outside of Claude Desktop, Claude Code, or Cursor. This single step eliminates half of all MCP disconnect reports, because it immediately tells you whether the bug is in your server or in how the client is invoking it.

If it throws an error or a traceback right there in your terminal, you have your answer, and it has nothing to do with MCP as a protocol. Fix that bug first, then move on. If it starts cleanly and just sits there waiting (that's normal for a stdio server with no client attached), the bug is more likely in how your client is spawning or talking to the process, which is what the rest of this guide covers.

This shows up as an immediate disconnect, often within a second of the client trying to connect. Usually the command in your config is wrong in a way your shell would have silently forgiven but a GUI application launching a subprocess will not.

A relative path like ./server.py or server.js works fine when you run it from your project folder in a terminal, because your shell's current working directory is that folder. Your AI client is not launching from that folder. It's launching from wherever its own process happens to run from, usually your home directory or the application bundle's own location, so a relative path resolves to a completely different (and nonexistent) file.

The same problem hits interpreters and package runners. npx, python, and uv being available in your terminal doesn't mean the GUI app sees them. On macOS in particular, GUI applications launched from Finder or Spotlight do not inherit your shell's PATH the way a Terminal.app session does, because they never load your .zshrc or .bash_profile. A command that resolves perfectly in your terminal can produce a plain "command not found" style spawn failure when the same string is handed to posix_spawn by a desktop app.

Use full, absolute paths for both the command and the script argument. If you're not sure where an interpreter actually lives, ask your shell directly rather than assuming.

This is the cause that gets almost everyone at least once, and it's the least intuitive if you haven't hit it before. With stdio transport, stdout is reserved entirely for JSON-RPC messages between your server and the client. Nothing else is allowed to touch it. Any print() statement, any library that logs to stdout by default, any startup banner your framework prints for you, corrupts the stream. The client either disconnects immediately or behaves in ways that look completely unrelated to the actual cause, because from its perspective it just received garbage where it expected a JSON object.

The frustrating part is that this bug is invisible when you test your server in isolation with a simple script, and only shows up once a client is actually parsing the stream character by character.

In Node, console.log writes to stdout and console.error writes to stderr. In Python, print() defaults to stdout unless you redirect it. If you're using a logging library instead of raw print statements, check its default output stream before assuming it's safe. Python's logging module defaults to stderr when you call basicConfig() with no handler, which is safe, but plenty of third-party loggers and ORMs default to stdout for their query logs.

This also catches people indirectly, when a dependency you didn't write logs to stdout on its own initialization. If your server works fine when you test it manually but disconnects only when the AI client runs it, and you've already ruled out path and environment issues, a dependency writing to stdout is one of the first things worth grepping your node_modules or site-packages for.

Related to cause 1, but specifically about environment variables rather than the command path itself. If your server reads an API key, a database URL, or any other secret from an environment variable, remember that the process spawning your server does not automatically inherit your shell's full environment the way a terminal session does. GUI applications on macOS and Windows launch with a minimal environment set by the OS, not the one built up by your .zshrc, .bashrc, or direnv configuration.

You almost always need to declare those variables explicitly inside the server's config block, even if the exact same variable is already exported in your shell profile.

The failure mode here is subtly different from a spawn failure. The process actually starts (you'll often see the client briefly show "connecting" before it flips to "disconnected"), then your server code hits a missing environment variable, throws, and exits. If your server silently fails a second or two after startup, with no obvious spawn error, a missing environment variable it expected to just be there is the first thing to check.

Working directory assumptions cause a similar failure. If your server reads a config file, a .env file, or a SQLite database using a relative path like ./data.db, that path resolves relative to whatever working directory the client happened to launch the process from, which is often not your project folder at all. Use absolute paths for any file your server reads at startup, not just for the command itself.

Less common than the first three, but worth ruling out, especially if you're connecting to a remote or self-hosted MCP server rather than a local one. Your config might specify a url field, which tells the client to expect a Streamable HTTP (or the older SSE) server, when your actual server is only implemented for stdio, or the reverse: a command and args pair when the server you're pointing at only listens on a port.

Double check which transport your server actually implements against what your config is asking for. Mixing these up produces a disconnect that looks identical to every other cause on the surface, no useful error message, just a red status dot, so it's easy to burn time debugging path issues or stdout pollution on a server that was never going to connect over stdio in the first place.

Once you've ruled out the obvious (the manual run test from earlier in this guide), the next step isn't to keep tweaking your client config and reconnecting. It's to isolate the server from the client entirely using a tool built for exactly this.

The four root causes above are the same regardless of which AI client you're using, but where you go to look for evidence differs quite a bit between them.

One Windows-specific wrinkle worth knowing about if you support users on it: Claude Desktop's config file location on Windows moved after a recent MSIX packaging update. If the Edit Config button in the app doesn't seem to match what you're actually editing, check the real file path directly rather than trusting the shortcut, and if you're specifically debugging under WSL2, treat that as a separate troubleshooting pass since it introduces its own networking and process-spawning failure modes on top of everything covered here.

Run MCPConfigCheck against your config before working through this list manually. It catches a number of the most common config-level mistakes automatically, in your browser, before you go digging through client logs.