Claude Desktop MCP Not Working? Fixes for Config and HTTP Servers

Your MCP server worked yesterday. Today Claude Desktop shows no tools, a "Server disconnected" banner, or nothing at all, and the only clue is a vague error that points nowhere. It happens to almost everyone who wires up a local server, and the cause is nearly always one of five things: a broken claude_desktop_config.json, a command the app can't find, a server that prints the wrong text to stdout, an HTTP server added the wrong way, or an app that was never fully restarted.

This article walks through each failure in the order you should check them, with the exact JSON, paths and commands to paste. Work from the top and stop the moment your tools show up. Most fixes take under five minutes.

💡 Fast answer: quit Claude Desktop from the tray or menu bar (not just the window), run your config through a JSON validator, replace npx with its absolute path, and add remote servers through Settings, Connectors instead of the config file. That alone fixes the majority of cases.

Check the Basics First

Before you touch a single line of JSON, rule out the boring causes. They account for more failed setups than any real bug.

Quit Claude Desktop Fully

Closing the window is not quitting. On Windows the app keeps running in the system tray, and on macOS it stays alive until you press Cmd+Q. Claude Desktop reads its config only at launch, so every edit you made while it was running is ignored.

Right-click the tray icon (or use the menu bar), choose Quit, wait two seconds, then open the app again. Do this after every change, even a single character.

Open the Right Config File

Don't hunt for the file by hand. Open Settings, pick Developer, and press Edit Config. That opens the exact file the app reads. The usual locations look like this:

💡 If you edit a file and nothing ever changes, you may be editing a copy the app doesn't use. Some packaged Windows installs redirect app data to a different folder. Edit Config always opens the right one.

A minimal setup that works looks like this. If this loads and yours doesn't, the difference between the two files is your bug.

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/you/Documents"]
    }
  }
}

Copy Prompt

Read the Logs Before Guessing

Every local server writes its own log, named mcp-server-NAME.log, next to a general mcp.log. In Settings, Developer each server also shows whether it is running or failed, so you can see which entry is the problem at a glance.

To watch logs live on macOS:

tail -n 40 -F ~/Library/Logs/Claude/mcp*.log

Copy Prompt

And on Windows PowerShell:

Get-Content "$env:APPDATA\Claude\logs\mcp.log" -Tail 40 -Wait

Copy Prompt

Restart the app with the log window open and the error usually scrolls past in the first few seconds. These are the lines worth recognizing:

Fix Broken Config JSON

Claude Desktop is not forgiving about syntax. One stray comma and every server in the file disappears, not only the one you just edited.

Syntax Mistakes That Break Everything

Check this list line by line:

• Trailing commas after the last property in an object or array.
• Comments. JSON has none, so // lines you copied from a tutorial will break the file.
• Smart quotes. Chat apps and word processors turn " into curly quotes that look identical and fail instantly.
• A missing comma between two server entries.
• A wrong top-level name. It must be exactly mcpServers, with that capital S. Variants like mcpservers or servers are silently ignored.
• Numbers in env. Environment values must be strings, so write "PORT": "8080", not "PORT": 8080.
• Deleted sections. If the file already had other top-level settings, keep them when you paste a new mcpServers block.

Here is a typical broken file:

{
  "mcpServers": {
    "notes": {
      "command": "node",
      // path to my server
      "args": ["C:\Users\Ana\notes-server\index.js"],
    }
  }
}

Copy Prompt

And the fixed version:

{
  "mcpServers": {
    "notes": {
      "command": "node",
      "args": ["C:\\Users\\Ana\\notes-server\\index.js"]
    }
  }
}

Copy Prompt

The quickest way to catch all of this at once is to let a parser do the work. Python ships with one:

python -m json.tool claude_desktop_config.json

Copy Prompt

If it prints your file back, the syntax is valid. If it prints an error with a line number, go straight to that line.

Windows Paths and Backslashes

The backslash is JSON's escape character, so C:\Users\Ana is invalid because \U is not a real escape. You have two safe options:

1. Double every backslash: C:\\Users\\Ana\\notes-server\\index.js
2. Use forward slashes: C:/Users/Ana/notes-server/index.js

Windows accepts forward slashes in nearly every case, and they are far harder to get wrong. Spaces in folder names are fine inside a JSON string, but test the path in a terminal first.

Fix Command and Startup Errors

The config is valid, the app restarted, and the server still fails. Now the problem is the process itself.

Why spawn npx ENOENT Happens

ENOENT means "no such file or directory." Claude Desktop launched from the Dock or the Start menu does not read your shell profile, so it never sees the PATH you have in a terminal. If you installed Node through nvm, fnm, asdf or Volta, the binaries live in a folder only your shell knows about. The command works in your terminal and fails inside the app, which is exactly why it feels so confusing.

Use Absolute Paths for Node

Ask your terminal where the binary actually is:

which npx     # macOS
where npx     # Windows

Copy Prompt

Then paste the full path into command. Because npx itself needs to find node, add a PATH entry in env that includes the same folder:

{
  "mcpServers": {
    "filesystem": {
      "command": "/Users/you/.nvm/versions/node/v22.11.0/bin/npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/you/Documents"],
      "env": {
        "PATH": "/Users/you/.nvm/versions/node/v22.11.0/bin:/usr/local/bin:/usr/bin:/bin"
      }
    }
  }
}

Copy Prompt

Run node --version too. Many npx-launched servers need a recent LTS release of Node, and an old system install is a classic hidden cause.

The Windows cmd Wrapper

On Windows, npx is really a batch file called npx.cmd, and launching it directly can fail. Wrap it in cmd /c so the shell resolves it properly:

{
  "mcpServers": {
    "filesystem": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@modelcontextprotocol/server-filesystem", "C:/Users/Ana/Documents"]
    }
  }
}

Copy Prompt

Keep Stdout Clean

This one hits people who write their own server. A stdio server talks to Claude through JSON-RPC messages on stdout, and nothing else is allowed there. One stray console.log("server started") corrupts the stream, and the app drops the connection with an Unexpected token error.

💡 Some libraries print a banner or a deprecation warning on import. If the log shows text you never wrote, run the server in a terminal and watch what appears before the first protocol message.

Fix HTTP and Remote Servers

HTTP servers cause the most confusion, because the config file looks like the place to add them. It isn't.

Config File Runs Local Servers Only

Entries under mcpServers launch a program on your machine and talk to it over stdin and stdout. They do not dial a web address. Adding "url": "https://example.com/mcp" to that block is the single most common HTTP mistake, because the app has no way to use that entry.

Add a Custom Connector

Remote servers go through Connectors. Custom connectors are available on the Pro, Max, Team and Enterprise plans, and on Team or Enterprise an organization owner may need to add the connector first.

1. Open Settings and choose Connectors.
2. Press Add custom connector.
3. Paste the HTTPS address of the server's endpoint, often ending in /mcp.
4. Sign in if the server asks for OAuth.
5. Switch the connector on from the tools menu in a new chat.

Aim for a Streamable HTTP endpoint. A server that only speaks the older SSE transport is a frequent mismatch. When the connector fails, this table narrows it down:

A server bound to localhost is the usual culprit when a custom connector refuses to connect, because the address means something different from wherever the request originates.

Bridge With mcp-remote

When the server is private, local, or needs a header, the mcp-remote package acts as a stdio bridge. Claude launches it like any other local server, and it forwards the traffic to your HTTP endpoint:

{
  "mcpServers": {
    "my-remote": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://example.com/mcp",
        "--header",
        "Authorization:${AUTH_HEADER}"
      ],
      "env": {
        "AUTH_HEADER": "Bearer YOUR_TOKEN"
      }
    }
  }
}

Copy Prompt

Two details matter here. First, write the header with no space after the colon and keep the real value in env. On Windows, spaces inside args can get mangled when npx starts, and this layout sidesteps the bug. Second, mcp-remote has options to force HTTP-only or SSE-only behavior, so check its README when the default negotiation picks the wrong transport. Everything from the earlier sections still applies: restart fully, use absolute paths, read the log.

Test Servers Outside Claude

When you can't tell whether the server or the app is at fault, take the app out of the picture.

Run MCP Inspector

The official MCP Inspector connects to a server and lists its tools in a browser tab:

npx @modelcontextprotocol/inspector node build/index.js

Copy Prompt

For an HTTP server, open the Inspector and pick the matching transport type, then paste the URL. The result splits the problem cleanly:

• Tools appear in the Inspector but not in Claude: the issue is your config, PATH or restart.
• The Inspector fails too: the server is the problem, so fix it there first.

Probe HTTP With curl

For a Streamable HTTP server, send a real initialize request and read the status code:

curl -i -X POST https://example.com/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl-test","version":"0.0.1"}}}'

Copy Prompt

Use PicassoIA Tools Inside Claude

Once connectors work, the payoff is putting them to use. PicassoIA offers an MCP connection so Claude can create pictures and clips for you inside a chat. The connection exposes four models:

Generation jobs are asynchronous. The tool returns a prediction ID right away, and Claude then checks the status until the job succeeds or fails. That design explains most of the "it hangs" reports:

• A job still shows as running: ask Claude to check the existing prediction by its ID. Submitting the same prompt again only starts a second job.
• Failures when many jobs run together: an account runs up to five predictions at once, shared across every connection, so stay at or under five.
• Tools missing after connecting: switch the connector on from the tools menu and open a fresh chat.
• Unsure what your plan allows: ask Claude to look up your account, or check the MCP connections page in your PicassoIA account.

Use Claude Sonnet 5 on PicassoIA

Stuck on a config that looks right and still fails? Hand it to a second pair of eyes. Claude Sonnet 5 runs on PicassoIA and is built for debugging code, and it can read screenshots of error banners.

1. Open the model page. Go to Claude Sonnet 5 on PicassoIA.
2. Fill the prompt. Paste your config, the last 30 lines of the log, your operating system, your Node version, and what you expected to happen. Remove every token first.
3. Attach a screenshot. The image field accepts a picture of the error. Raise max_image_resolution above its 0.5 megapixel default if the text looks blurry after scaling.
4. Set the effort. The default low is fastest. Switch to high when several servers interact or the cause is unclear.
5. Add a system prompt. Something like: "You are an MCP troubleshooting assistant. Return the corrected JSON first, then a short list of causes."
6. Generate and compare. Diff the answer against your file, apply one change at a time, and fully restart the app after each.

💡 Never paste live tokens into any chat window. Replace them with YOUR_TOKEN and put the real value back only in your local file.

For stubborn multi-file problems, Claude Fable 5 and Claude Opus 4.7 are also available in the same category.

Make Your First Image Today

Your servers are running, the tools are visible, and the hard part is behind you. Now spend ten minutes on the fun part. Open PicassoIA Image and write a prompt for a scene you would actually hang on a wall. Refine it with PicassoIA Image Editor Pro, then bring the result to life with PicassoIA Video.

Try the same prompt in three styles, change the camera angle, swap the lighting from dawn to dusk, and compare. The quickest way to get good at this is to run many small experiments and keep the ones that surprise you. When you want more options, browse every model at picassoia.com/en/all-models and see what fits your next project on Picasso IA.