MCP Server Timeout / Disconnected in Claude Desktop

Types of timeout / disconnect errors

There are three distinct failure modes that all look like "timeout" in the Claude UI:

1. Initialization timeout — the server process started but did not complete the MCP handshake (initialize + initialized messages) within Claude Desktop's timeout window
2. Transport disconnect — the stdio pipe between Claude Desktop and the server closed unexpectedly (server crashed, exited, or was killed)
3. Tool call timeout — the server is running but a specific tool call took too long to return a response

The log file will tell you which one you have. Check it before proceeding:

# macOS
tail -50 ~/Library/Logs/Claude/mcp-server-SERVERNAME.log

# Windows
Get-Content "$env:APPDATA\Claude\logs\mcp-server-SERVERNAME.log" -Tail 50

First-run npx timeout (most common)

When you use npx -y @modelcontextprotocol/server-NAME, npx downloads the package from npm the first time. This can take 30–90 seconds on a slow connection — long enough for Claude Desktop to time out the server connection.

Fix: pre-warm the server by running its command manually in a terminal first:

# Run manually to trigger the download
/usr/local/bin/npx -y @modelcontextprotocol/server-filesystem /tmp

# Wait for it to start (it will print something or just hang listening)
# Then stop it:
^C

The package is now in npx's local cache. Claude Desktop will start it instantly on the next attempt.

Initialization timeout from slow startup

Some MCP servers perform network calls during initialization — connecting to a database, fetching an OAuth token, or validating credentials against a remote API. If those calls hang or are slow, the server times out before it can respond to Claude Desktop's initialize request.

Signs in the log:

Connecting to database...
(then nothing — the server hung waiting for the connection)

Fixes:

• Database servers (postgres, redis, sqlite): test the connection outside Claude first — psql postgresql://user:pass@host/db. If the connection itself is slow or failing, fix that first.
• Firewall / VPN: some servers try to reach external services during init. If you are on a VPN that blocks outbound connections, this will hang.
• OAuth-dependent servers (Google Drive, Notion): if the OAuth token has expired, the server will try to refresh it during init and may hang. Delete the token file and re-authenticate manually.

Recurring disconnects after initial connection

If the server connects successfully but disconnects after minutes or hours, these are the most likely causes:

• External connection timeout: database or API connection was idle too long and the remote closed it. The server did not handle the reconnection and crashed.
• Expired OAuth token: Google Drive, Notion, and similar servers hold OAuth tokens. When the token expires and auto-refresh fails, the server crashes. Delete token.json and re-authorize.
• Memory limit: the OS killed the server process due to memory pressure. Check Activity Monitor (macOS) or Task Manager (Windows) to see if the server process was using excessive RAM.
• Unhandled exception in the server: a bug in the server code triggered on a specific operation. Check the log for a stack trace immediately before the disconnect.

Tool call timeouts

If the server is connected and tools are visible but specific tool calls time out, the issue is in the tool's execution, not the server startup. Common causes:

• Large file operations: the filesystem server reading a very large directory or file
• Slow database queries: a query that takes more than 30 seconds
• Browser automation: Playwright or Puppeteer waiting for a page that never loads (check the URL, or add a timeout in server config if it supports one)
• Network requests: the fetch or brave-search server calling an API that is rate-limited or slow

These are harder to fix without modifying the server. The practical workaround is to use more targeted tool calls (fetch a specific URL instead of a broad search, query a specific record instead of a full table scan).

Reading the logs for timeout errors

The log will contain one of these patterns:

# Initialization timeout (Claude Desktop side)
Server initialization timed out

# Transport disconnect
Server process exited with code 1
Server process exited unexpectedly

# Crash before disconnect
Error: connect ECONNREFUSED 127.0.0.1:5432
UnhandledPromiseRejectionWarning: ...

# npx download in progress (this is fine, just slow)
npm warn exec The following package was not found and will be installed

FAQ