Claude MCP Setup: Connect a Server to Claude Desktop (2026)

You edited the config, restarted Claude, and… nothing. No MCP server, no error, just the same empty connectors list. You’re not doing it wrong — the tutorials just skip the part where it breaks. Let’s fix it.

I lost most of an evening to this. I had pasted a server into my Claude MCP config exactly like the README said, relaunched the app, and got an empty tools list with zero explanation. The happy-path guides all stop at “restart Claude and you’re done.” Mine wasn’t done.

By the end of this guide you’ll have a working Claude MCP config you can copy, and — more importantly — a troubleshooting tree for when the server still won’t appear. We’ll cover Python and Node servers, the different file paths on macOS and Windows, the errors that actually show up in practice, how to use the same server in Cursor or VS Code, and one quick safety check before you connect anything.

How Claude Desktop loads MCP servers

Before you fix anything, it helps to know what Claude is actually doing when it starts. MCP (Model Context Protocol — an open standard that lets AI apps call external tools through one common interface) servers are launched by Claude Desktop, not by you.

When the app starts, it reads one file, claude_desktop_config.json, finds every entry under mcpServers, and runs each one as a small background process. It then talks to that process over JSON-RPC and lists whatever tools the server offers. If the config is wrong, Claude silently skips the server — there’s no popup telling you why. That silence is the whole problem this post solves.

The diagram shows the chain: config file in, server process started, tools out. Each link can break independently, which is exactly why “it’s not showing up” has more than one cause. To open the file yourself, use Settings → Developer → Edit Config — clicking Edit Config opens claude_desktop_config.json in your default editor and creates it if it doesn’t exist. If you’ve never met MCP before, my complete guide to what an MCP server is covers the concept first.

The config that works — Python & Node, macOS & Windows

Here’s a config that connects on the first try. The file lives at ~/Library/Application Support/Claude/claude_desktop_config.json on macOS and %APPDATA%\Claude\claude_desktop_config.json on Windows. Start with the official filesystem server, which runs through Node:

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

The command is the executable Claude runs, and args are passed to it. Swap the path at the end for a folder you actually want Claude to read. A Python server you wrote yourself looks almost identical — you just point command at your interpreter or uv:

{
  "mcpServers": {
    "my-python-server": {
      "command": "uvx",
      "args": ["my-mcp-server"]
    }
  }
}

There’s one Windows-specific trap worth flagging before you save. On Windows, Claude Desktop often can’t find npx or uvx on its PATH, so the server fails instantly. The reliable fix is to give the full path to the executable instead of relying on PATH:

{
  "mcpServers": {
    "filesystem": {
      "command": "C:\\Program Files\\nodejs\\npx.cmd",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "C:\\Users\\you\\Documents"]
    }
  }
}

Common mistake: a trailing comma after the last entry. JSON doesn’t allow it, the file fails to parse, and Claude loads zero servers — not just the broken one. When in doubt, paste the file into a JSON validator before saving.

Once the file is saved, the rest is mechanical. Follow these six steps and you’ll either be connected or know exactly which step failed.

Step five is the one most people skip: a normal window close doesn’t reload the config. You have to fully quit Claude — from the system tray on Windows or with Cmd-Q on macOS — and start it again.

Claude MCP not showing up — the troubleshooting tree

If the server still isn’t there, work down this list in order. I’ve hit every one of these myself, and they’re roughly ranked by how often they’re the real cause.

First, confirm you actually restarted the app, not just the window. This is the single most common cause. Quit it completely and reopen it.

Second, check the JSON parses. One missing brace or trailing comma silently kills the whole file. Run it through any JSON linter.

Third, on Windows, suspect PATH. If you used a bare npx and the server never starts, open a fresh terminal and run where npx and where node. If they resolve, switch the config to that full path as shown above. NVM-managed Node installs are a frequent offender here because Claude doesn’t inherit your shell environment.

Fourth, if you see the message “This extension is disabled globally by the user,” that’s not your config at all — it’s the desktop extension allowlist. Desktop extensions can be switched off by a system or organization policy. On a managed or work machine, an organization owner has to enable the allowlist before extensions appear; check Settings and, if needed, ask your admin. This one fooled me for an hour because the config was perfect.

Fifth, check the logs. Claude writes Claude MCP logs you can tail:

# macOS
tail -n 50 -f ~/Library/Logs/Claude/mcp*.log

The logs name the failing server and usually print the underlying error — ENOENT (command not found), a Python traceback, or a JSON parse error. Reading the log is faster than guessing, and it’s the step the happy-path tutorials never mention.

Sixth, if everything parses but a tool call fails the moment you use it, suspect relative paths in your args. Claude launches the server from its own working directory, not the folder you’re sitting in, so a path like ./data resolves somewhere you don’t expect. Use absolute paths for any file or folder you pass to a server, and the intermittent “works sometimes” failures disappear.

Finally, if the server simply vanished after working yesterday, confirm Claude Desktop updated overnight. A version bump occasionally resets which extensions are enabled, and re-toggling the server in Settings brings it back.

Using MCP beyond Claude — Cursor, VS Code, ChatGPT

The same Claude MCP server works in other clients too, and this is where MCP earns its “USB-C for AI tools” nickname — one server, many hosts. Each client just reads a different config file. Yes, this works on a MacBook, and yes, it works with the other major assistants.

Cursor uses its own JSON file with the identical mcpServers shape — a global one at ~/.cursor/mcp.json or a per-project .cursor/mcp.json. You can paste the exact block from above with no changes.

VS Code has had native MCP support since version 1.99 in early 2026, surfaced through GitHub Copilot Chat. Project servers go in a committed .vscode/mcp.json so your team shares them, while servers that need a personal API key belong in your user settings instead of the repo. ChatGPT and Claude Code also speak MCP, each through their own connector setup.

The takeaway: learn the config once and you can give any of these tools the same powers. Only the file location and a little wrapper syntax change between them — the command, args, and env keys stay the same everywhere, which is the whole point of a shared protocol.

Is it safe? What an MCP server can actually see

Quick gut-check before you connect a stranger’s server, because the honest answer is “it depends on what you grant it.” A local MCP server runs as a process on your machine with your permissions, so the filesystem server can read every file under the folder you pointed it at — choose that path deliberately, not your whole home directory.

A remote server is different: you’re sending requests to someone else’s endpoint, so it sees whatever data you pass and whatever a leaked token unlocks. Only connect servers from sources you trust, give them the narrowest scope that works, and keep secrets in environment variables rather than pasted into the config.

That’s the five-second version; the full security checklist lives in the build guide. Treat a third-party MCP server the way you’d treat any package you npm install — useful, but worth a glance first.

Conclusion

You now have the config that connects and the tree that fixes your Claude MCP setup when it doesn’t. The recipe is short: valid JSON under mcpServers, the full executable path on Windows, a genuine full restart, and the logs when all else fails. That’s the difference between an empty connectors list and a working one.

So which server are you connecting first — and did it show up on the first restart, or did one of these fixes save you? Tell me in the comments.

Read next: Once you can connect servers, the obvious next step is to build your own — Build an MCP Server in Python: Production-Ready in 2026 walks through typed tools and OAuth from scratch.

Related: What Is an MCP Server? Complete Guide for Developers (2026) · Official docs: connecting local MCP servers.