Category: Claude Code Insider

Last verified: October 8, 2026 (Pacific)

MCP (Model Context Protocol) is how you give Claude hands. Out of the box Claude can talk; with an MCP server connected, it can read your files, query a database, hit an API, or drive a browser. This guide covers the two places you actually wire servers up: the claude_desktop_config.json file for the Claude Desktop app, and the claude mcp add command for Claude Code (the terminal/IDE tool). It ends with the troubleshooting section the official docs skip: path problems, JSON syntax traps, servers that silently never load, and the Windows quirks that cost people an afternoon.

Everything below is checked against the current Claude Code MCP docs and tested commands. If you want the wider picture of how MCP fits into a working setup, see the AI operator’s stack.

What is MCP and what is an MCP server?

MCP transport options at a glance

Transport	Use case	Config location	Works with
stdio	Local tools, CLIs, scripts	claude_desktop_config.json or claude mcp add	Claude Desktop, Claude Code
SSE (HTTP)	Remote servers, cloud services	URL in config	Claude Desktop, Claude Code
Streamable HTTP	Production remote MCP	URL in config	Claude Desktop, Claude Code

MCP is an open standard for connecting AI models to external tools and data. An MCP server is a small program that exposes a set of tools (functions Claude can call) over that protocol. Claude is the client; the server is the thing that actually does the work, like reading a Postgres table or creating a GitHub issue.

There are two transport types you will deal with in practice:

• stdio (local): the server runs as a process on your machine. Claude talks to it over standard input/output. Best for filesystem access, local databases, and custom scripts. This is what most “install this MCP server” instructions mean.
• HTTP (remote): the server lives on the internet at a URL. Best for cloud services (Notion, Sentry, Stripe, GitHub). Often uses OAuth. SSE is the older remote transport and is now deprecated; use HTTP for new remote servers.

The same server can usually be added to both Claude Desktop and Claude Code. The mechanics differ: Desktop uses a JSON file you edit by hand, Claude Code gives you a CLI that writes the config for you.

How do I add an MCP server to Claude Desktop?

For local stdio servers, Claude Desktop still reads a single JSON file — you edit it, fully quit the app, and reopen. The config file remains the source of truth for anything that runs on your own machine. Remote servers are a different story: Claude Desktop now offers an in-app route (Settings > Connectors > Add custom connector) that adds a remote server by URL and handles OAuth for you.

Where is claude_desktop_config.json?

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json (paste that into the File Explorer address bar; it expands to C:\Users\YOU\AppData\Roaming\Claude\)

The fastest way to open it: in Claude Desktop go to Settings > Developer > Edit Config. That button creates the file if it does not exist and opens the folder. If the file is brand new it may be empty or just {}.

The config file structure

Everything lives under a top-level mcpServers object. Each key is a name you choose; each value describes how to launch the server. Here is a complete, working file with a local filesystem server and a remote Notion server:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "C:\\Users\\YOU\\Documents"
      ]
    },
    "notion": {
      "command": "npx",
      "args": ["-y", "@notionhq/notion-mcp-server"],
      "env": {
        "NOTION_TOKEN": "secret_your_token_here"
      }
    }
  }
}

Three fields do all the work:

• command the executable to run (npx, node, python, uvx, or an absolute path to a binary).
• args an array of arguments. Each flag and value is its own array element. "--port 8080" as a single string will not work; use "--port", "8080".
• env an object of environment variables (API keys, tokens). Optional.

After saving, completely quit Claude Desktop (on Windows, right-click the system tray icon and choose Quit; closing the window is not enough) and reopen it. You should see a tools/connector indicator in the chat input. For a full Notion walkthrough including the token, see connecting Notion to Claude with MCP.

How do I add an MCP server to Claude Code (CLI)?

Claude Code does not make you hand-edit JSON. The claude mcp command manages servers for you and writes to the right file. This is the part people get wrong most often, so here is the exact, verified syntax.

claude mcp add

The general form for a local (stdio) server is:

claude mcp add [options] <name> -- <command> [args...]

The -- is load-bearing. Everything before it is for Claude Code; everything after it is the command that launches your server. Real examples:

# Local filesystem server
claude mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem ~/Documents

# Local server with an environment variable
claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY airtable -- npx -y airtable-mcp-server

# Remote HTTP server
claude mcp add --transport http notion https://mcp.notion.com/mcp

# Remote HTTP server with an auth header
claude mcp add --transport http github https://api.githubcopilot.com/mcp/ --header "Authorization: Bearer YOUR_PAT"

Option ordering matters. All flags (--transport, --env, --scope, --header) must come before the server name. Put a flag after the name and you will get a confusing parse error or the flag will be passed to your server instead of to Claude Code.

Scopes: local, project, user

The --scope flag decides where the config is written and who sees it:

• local (the default) loads only in the current project, private to you. Stored in ~/.claude.json keyed by the project path.
• project loads in the current project and is shared with your team. Stored in a .mcp.json file at the project root that you commit to git.
• user loads across all your projects, private to you. Also stored in ~/.claude.json.

# Available across all your projects
claude mcp add --scope user --transport http sentry https://mcp.sentry.dev/mcp

# Shared with your team via .mcp.json in the repo
claude mcp add --scope project filesystem -- npx -y @modelcontextprotocol/server-filesystem .

When the same server name exists at multiple scopes, local wins over project, which wins over user. The whole entry from the winning scope is used; fields are not merged.

claude mcp list, get, and remove

# List every configured server and its connection status
claude mcp list

# Show the full config for one server
claude mcp get github

# Remove a server
claude mcp remove github

claude mcp list is your first diagnostic. It shows each server as connected, pending, or failed. Project-scoped servers from a .mcp.json you have not approved yet show as Pending approval until you run claude interactively and accept them.

Other useful commands

# Add from a raw JSON blob (handy when copying from a server's README)
claude mcp add-json weather '{"type":"stdio","command":"npx","args":["-y","weather-mcp"]}'

# Import everything you already set up in Claude Desktop (macOS / WSL)
claude mcp add-from-claude-desktop

Inside a running Claude Code session, type /mcp to see live server status, tool counts, and to trigger OAuth login for remote servers that need it.

Troubleshooting: the errors the docs skip

Most MCP failures are not exotic. They are paths, quoting, and the app not restarting. Work this list top to bottom.

Server not loading / no tools appear

1. Did you actually restart? Claude Desktop only reads the config at launch. Fully quit (tray icon > Quit on Windows, Cmd+Q on macOS) and reopen. In Claude Code, run claude mcp list to see the real status instead of guessing.
2. Is the command on PATH? The single most common stdio failure is npx, node, python, or uvx not being found by the app. GUI apps often have a narrower PATH than your terminal. Fix it by using an absolute path. Find it with which npx (macOS/Linux) or where npx (Windows), then put that full path in command.
3. Read the logs. Claude Desktop writes per-server logs. macOS: ~/Library/Logs/Claude/. Windows: %APPDATA%\Claude\logs\. Look for mcp-server-NAME.log. The actual error (missing module, bad token, wrong path) is almost always sitting right there.

spawn ENOENT or “command not found”

This means the OS could not find the executable named in command. It is a PATH problem, not a Claude problem. Use the absolute path (see above). On Windows specifically, see the npx note below.

JSON syntax errors (the silent killer)

If claude_desktop_config.json has a single syntax error, Claude Desktop loads zero servers and usually says nothing. The usual culprits:

• Trailing commas. JSON forbids a comma after the last item in an object or array. "args": ["a", "b",] is invalid.
• Smart quotes. If you edited the file in a word processor, curly quotes (the slanted kind) break the parser. Use a code editor and straight quotes only.
• Unescaped Windows backslashes. In JSON, \ is an escape character, so every backslash in a Windows path must be doubled: C:\\Users\\YOU\\Documents. A single backslash silently corrupts the string.

Paste the whole file into any JSON validator before restarting. Thirty seconds there saves an hour of staring.

Claude Code: flag passed to the wrong place

If claude mcp add behaves strangely, you almost certainly put a flag after the server name or forgot the --. Reread the order: claude mcp add [flags] NAME -- COMMAND ARGS. The -- separates Claude Code’s flags from your server’s command.

Windows quirks

• npx needs a wrapper in some setups. If a bare "command": "npx" fails on Windows, launch it through cmd: "command": "cmd" with "args": ["/c", "npx", "-y", "the-server-package"]. This resolves a class of “npx works in my terminal but not in Claude” failures.
• Use the right config root. It is %APPDATA%\Claude\ (which is AppData\Roaming), not AppData\Local. Mixing these up means you are editing a file the app never reads.
• Git Bash mangles paths. If you run commands through Git Bash, it can rewrite paths like /c/Users or absolute paths inside arguments. Prefer PowerShell or cmd for claude mcp add, or pass paths exactly as Windows expects them.
• WSL is a separate world. A server installed inside WSL is not visible to a Windows-native Claude Desktop, and vice versa. Keep both on the same side.

Remote server returns 401 / 403

The server needs authentication. In Claude Code, run /mcp and complete the OAuth flow in your browser. If you hardcoded an Authorization header and it is rejected, the token is wrong for that endpoint; remove the header and let OAuth handle it instead.

Frequently asked questions

What is an MCP server in one sentence?

A small program that exposes tools (functions like read-file or query-database) to Claude over the Model Context Protocol, so Claude can take real actions instead of only producing text.

What is the difference between Claude Desktop and Claude Code for MCP?

Claude Desktop is the chat app and you configure servers by hand-editing claude_desktop_config.json, then restarting. Claude Code is the terminal/IDE tool and you configure servers with the claude mcp add command, which writes the config for you.

Where is the Claude Desktop config file?

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json. Windows: %APPDATA%\Claude\claude_desktop_config.json. The quickest way to open it is Settings > Developer > Edit Config inside the app.

Why is my MCP server not showing up?

In order of likelihood: you did not fully restart the app, the command is not on the app’s PATH (use an absolute path), or there is a JSON syntax error such as a trailing comma, a smart quote, or an unescaped Windows backslash. Check the per-server log in the Claude logs folder for the exact error.

What does the double dash do in claude mcp add?

The -- separates Claude Code’s own flags from the command that launches your server. Flags like --transport and --env go before it; the actual launch command (npx -y some-server) goes after it.

What is the default scope for claude mcp add?

local. The server loads only in the current project and stays private to you. Use --scope user to make it available in every project, or --scope project to share it with your team via a committed .mcp.json.

Is SSE or HTTP the right transport for remote servers?

HTTP. SSE still works but is deprecated. Use --transport http for any new remote server unless its documentation specifically requires SSE.

How do I remove an MCP server?

In Claude Code, run claude mcp remove NAME. In Claude Desktop, delete that server’s entry from the mcpServers object in claude_desktop_config.json and restart the app.

Where to go next

Once your servers connect cleanly, the leverage comes from using them well. For how this fits a daily workflow, read the AI operator’s stack; if you are choosing between coding environments, see Claude Code vs Cursor. And if you want a concrete first server to wire up, the Notion MCP setup is a clean, high-value place to start.

Frequently Asked Questions