Could Not Attach to MCP Server: How to Fix It (Claude Desktop on macOS and Windows)

"Could not attach to MCP server" is a Claude Desktop message that means the app started your server but could not finish connecting to it. The server usually exited early, never answered, or ran with the wrong Node or Python. The fastest fix is to open the server's own log file, mcp-server-SERVERNAME.log, and read the last lines. If it is empty, replace npx or node in your config with absolute paths and restart the app.

Checked against: the MCP debugging guide, the MCP local server guide, TypeScript SDK issue #86 and servers issue #64 on 2 November 2026. The GitHub issues are user reports, not official docs. eSEOspace did not reproduce the error.

What this error means

Claude Desktop launches local servers as child processes over stdio. "Attach" covers the steps after launch: the server must read the client's first request from stdin and reply on stdout.

In TypeScript SDK issue #86, opened in December 2024, a macOS user got "Could not attach to MCP server demo." Their mcp.log showed "Attempting to connect to MCP server demo..." followed by "Connected to MCP server demo!" The server's own log had no output. The reporter closed the issue after a workaround from servers issue #64 worked.

That workaround targets Node version managers. Issue #64 says that with nvm, "the app tries to use an incorrect Node and fails," and recommends installing the package globally and using "absolute paths to both the Node executable and server script."

Quick fix

1. Open the logs. Run tail -n 20 -F ~/Library/Logs/Claude/mcp*.log on macOS, or type "$env:AppData\Claude\logs\mcp*.log" in PowerShell on Windows. Both commands come from the MCP debugging guide.
2. Run the command by hand. Copy command and args from claude_desktop_config.json into a terminal. Fix any error you see.
3. Use absolute paths. Put the full path to node (from which node) in command and the full path to the server's script in args.
4. Add environment variables. If the server needs keys, set them in env. The debugging guide says stdio servers inherit only a limited set of variables.
5. Remove stdout output from the server. Use stderr for logs.
6. Quit and reopen Claude Desktop from the menu bar or tray, not the window's close button.

Example from the nvm workaround pattern (paths will differ on your machine):

{
  "mcpServers": {
    "puppeteer": {
      "command": "/Users/username/.nvm/versions/node/v22.11.0/bin/node",
      "args": [
        "/Users/username/.nvm/versions/node/v22.11.0/lib/node_modules/@modelcontextprotocol/server-puppeteer/dist/index.js"
      ]
    }
  }
}

The Puppeteer server in that example now sits in the MCP project's servers-archived repository, described as "no longer maintained." Use the same pattern with your own server.

Fix by client / OS

Claude Desktop on macOS

Apps started from the Dock do not load your shell profile. Tools from nvm, Homebrew or uv may be missing from the app's PATH. Use which to find full paths. See the macOS PATH guide.

Claude Desktop on Windows

A MATLAB Answers thread reports this pop-up together with "Unable to connect to extension server" for a desktop extension. Try disabling and re-enabling the extension, and check that any log or data folder it uses is writable. For JSON configs, use double backslashes in paths and see failed to start on Windows.

Desktop extensions

Claude's help article says extension logs are under Settings > Desktop app, then Manage next to Extensions. It also suggests restarting Claude Desktop to refresh the extension registry. A bug report on SAP's Fiori MCP extension describes a server that exited after initialize under the app's built-in Node runtime and worked when pointed at a system Node. Treat that as one report.

Where to find the logs

Folders: ~/Library/Logs/Claude (macOS), %APPDATA%\Claude\logs (Windows), ~/.config/Claude/logs (Linux). An empty server log plus a "connected" line in mcp.log points to a server that exits silently or runs under a different runtime than you expect.

If it still fails

• Test in the Inspector. Run npx @modelcontextprotocol/inspector node /full/path/to/server.js, as shown in the Inspector docs. If tools list there, the problem is the Claude Desktop environment. Read works in Inspector but not in Claude.
• Look for -32000 or -32001. Those mean the connection closed or timed out. See Connection closed and Request timed out.
• Check the Node version. See MCP Node version errors.

Look up any code in the logs with the MCP error code lookup. For a fleet of laptops that all need the same servers, an MCP readiness audit can produce a tested standard config.

Frequently asked questions