AI AI Tools Guidebook
Troubleshooting

Claude MCP Server Keeps Disconnecting

MCP server connects then drops — network blip, auth expiry, or server crash.

Published: Author: AI Productivity Guide Team 🌐 查看中文版本

You launch Claude Desktop or Claude Code, see “MCP server connected” in the tools list, and a few minutes later the same server greys out as “disconnected.” Click reconnect — it works briefly, then drops again. This is the classic Claude MCP (Model Context Protocol) integration issue, and the root cause is almost always in one of three places: the server process, the OAuth token, or the local config path.

MCP isn’t an HTTP long-poll — it’s Claude spawning a local subprocess (or talking to a remote HTTP MCP) and chatting over stdin/stdout. Any of: subprocess crash, network blip, auth expiry can sever the connection.

Common causes

Ordered by hit rate, highest first.

1. Local MCP server process crashes or gets OOM-killed

stdio-mode MCP servers are Node / Python subprocesses Claude spawns. They can be OOM-killed, panic on uncaught exceptions, or fail to start with the wrong Node version.

How to spot it: Claude Desktop → Help → Open Logs, search for “spawn” or “exit.” Lines like “exited with code 1” or “killed” point here.

2. OAuth token expired and server didn’t auto-refresh

Remote MCP (e.g., official Slack or Linear MCP) uses OAuth. When tokens expire, some implementations don’t auto-refresh — connection looks live but every call returns 401.

How to spot it: Tool calls return “unauthorized” / 401. Going to Settings → MCP → Reconnect fixes it.

3. mcp.json / claude_desktop_config.json has wrong path or perms

The most common local gotcha. The args use relative paths, point to a non-existent file, or live in a directory Claude can’t read.

How to spot it: Logs show ENOENT: no such file or directory or EACCES: permission denied.

4. Node / Python version mismatch

MCP servers usually require Node 18+ or Python 3.10+, but your PATH’s first node is older (e.g., system-stock 14). Claude inherits PATH, subprocess fails.

How to spot it: Terminal which node && node -v — compare to the server’s README.

5. Corporate network blocks SSE

Some remote MCPs use Server-Sent Events. Enterprise proxies / firewalls cut long-lived SSE connections every 30-60 seconds.

How to spot it: Disconnection interval is suspiciously regular (every 30s / 60s) and happens only to remote MCPs.

6. macOS Gatekeeper / Firewall blocks local server’s listen

First launch of a new MCP server prompts macOS “allow network connections.” If you accidentally hit Deny, it silently fails afterward.

How to spot it: System Settings → Network → Firewall → Options shows Claude or the server explicitly blocked.

Shortest path to fix

Step 1: Read the logs first

Claude Desktop:

macOS:   ~/Library/Logs/Claude/mcp*.log
Windows: %APPDATA%\Claude\logs\
Help → Open Logs Folder

Claude Code:

claude --debug
# or in chat: /doctor

Find MCP entries near the most recent disconnect timestamp.

Step 2: Use absolute paths in mcp.json

Edit the config (macOS Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "filesystem": {
      "command": "/Users/you/.nvm/versions/node/v20.10.0/bin/node",
      "args": [
        "/Users/you/code/mcp-filesystem/dist/index.js",
        "/Users/you/Documents"
      ]
    }
  }
}

Key rules:

  • command is the absolute path from which node, not just "node"
  • All paths in args are absolute
  • Escape or quote any spaces in paths

Step 3: Manually run the server to confirm it starts

Copy the command + args from the config into a terminal:

/Users/you/.nvm/versions/node/v20.10.0/bin/node \
  /Users/you/code/mcp-filesystem/dist/index.js \
  /Users/you/Documents

If it crashes in your terminal, Claude can’t run it either. Fix Node version / install deps first.

Step 4: Re-OAuth remote MCPs

Settings → MCP → find the dead server → Disconnect → Connect. After authorizing, the tool should be usable immediately. If not, check whether the target platform’s (Slack/Linear/etc) admin revoked the app authorization.

Step 5: Align versions

node -v          # must be >= 18
python3 -V       # must be >= 3.10
which node

If your system has multiple versions, hardcode the nvm path in command, or set PATH via env:

{
  "command": "node",
  "args": ["..."],
  "env": {
    "PATH": "/Users/you/.nvm/versions/node/v20.10.0/bin:/usr/bin:/bin"
  }
}

Step 6: Network / firewall

sudo /usr/libexec/ApplicationFirewall/socketfilterfw --listapps | grep -i claude

# If needed, reset
sudo /usr/libexec/ApplicationFirewall/socketfilterfw --remove /Applications/Claude.app
# Restart Claude and Allow when prompted

On corporate networks, ask IT to allowlist anthropic.com and your MCP’s specific domain.

Prevention

  • After installing any MCP server, run mcp list (Claude Code) or manually verify in Desktop’s tool list; comment every path change
  • Always absolute paths in mcp.json — never ~ or ./
  • Lock Node version (nvm + .nvmrc) so system updates don’t break it
  • Note remote-MCP token expiry in Notion / wiki; refresh before expiry
  • On macOS, the first time a new MCP starts, read the firewall prompt carefully — don’t accidentally Deny
  • Track mcp.json in git so you can roll back if you break it

Tags: #Claude #Troubleshooting

Related Articles