Claude Desktop MCP Configuration: claude_desktop_config.json, Logs, Extensions, and the Difference From Claude Code

If you search for “claude desktop mcp configuration” you get two kinds of answers mixed together: instructions for the Claude Desktop app, which reads a file called claude_desktop_config.json, and instructions for Claude Code, the terminal tool, which reads .mcp.json and ~/.claude.json and has a claude mcp command. The two products share the Model Context Protocol and nothing else about configuration. Copy a snippet from the wrong one and the server silently never appears. This post is the reference for the Desktop side, with the exact file paths, the JSON shape, the menu path, the logs, and a side-by-side table against Claude Code so you can tell at a glance which file you should be editing.

It is the companion to our Claude Code MCP servers guide and the claude mcp add command reference, which cover the terminal product in depth.

The file: claude_desktop_config.json

Claude Desktop starts local MCP servers from one JSON file. Its location is fixed:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

You do not have to find it by hand. In the app, open the Claude menu in your system menu bar (not the settings inside the chat window), choose Settings, go to the Developer tab and click Edit Config. That creates the file if it does not exist and opens it; the official quickstart describes this path. Linux builds of Claude Desktop exist too, and the same Developer tab is the reliable way to locate the file there.

The structure is a single top-level key:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/username/Desktop",
        "/Users/username/Downloads"
      ]
    }
  }
}

Each entry under mcpServers is one server. The key (“filesystem”) is the display name you will see in the app. command is the executable, args is its argument list, and an optional env object sets environment variables for that process, which is where API keys for a server usually go. On Windows the example uses double backslashes in paths (C:\\Users\\username\\Desktop) because this is JSON. Paths must be absolute; relative paths are the single most common reason a server does not start.

Two things the Desktop file does not do, and that trip up people arriving from Claude Code: it has no scopes (there is one file for the whole app), and it does not expand ${VAR} references the way Claude Code’s .mcp.json does. Put the literal value in env, or use a Desktop Extension, covered below, which stores secrets properly.

Restart, then find the server

After saving, quit Claude Desktop completely and reopen it. The servers are launched at startup, so a running app will not pick up an edited file. Once it is back, click the “Add files, connectors, and more” control at the bottom left of the message box, hover Connectors, and choose Manage connectors; your server is listed there with its tools. If it is missing, the app read the file and either found a syntax error or failed to start the process, and the logs will say which.

Where the logs are

• macOS: ~/Library/Logs/Claude
• Windows: %APPDATA%\Claude\logs

mcp.log holds the app’s own MCP connection log, and each server gets a mcp-server-SERVERNAME.log containing its stderr. Many stdio servers write all their logging to stderr, so a busy server log is not necessarily an error log. To follow them live on macOS:

tail -n 20 -f ~/Library/Logs/Claude/mcp*.log

The fastest diagnostic is still to run the server’s command by hand in a terminal, exactly as written in the config, and see whether it starts. If npx is not found, the app is not seeing the same PATH as your shell; on macOS, Node installed through a version manager is the usual culprit, and writing the full path to the node or npx binary in command fixes it. On Windows, a server failing with ${APPDATA} in a path is a documented case: add the expanded APPDATA value to that server’s env block, and make sure npm is installed globally.

Desktop Extensions: the no-JSON route

Anthropic’s support documentation now points most users at Desktop Extensions rather than the JSON file. An extension is a local MCP server packaged as a single installable file (the .mcpb bundle, formerly .dxt) with a manifest.json describing it. In Settings under Extensions you can browse an Anthropic-reviewed directory and click Install, or under Advanced settings use the Extension Developer section’s “Install Extension…” to load a .mcpb file you were given. Fields marked "sensitive": true in the manifest are stored in the operating system’s secure storage instead of a plain text file, which is the main practical advantage over claude_desktop_config.json for anything with an API key. Directory extensions update automatically; privately shared bundles are updated by hand. On Team and Enterprise plans, owners can allow or block public extensions and upload custom ones for one-click install, and machine-level enterprise policies override the in-app controls.

The JSON file still works and is still the right tool for a server you are developing, a one-off command, or a machine where you want to see exactly what runs. Extensions are the right tool for distributing a server to people who should never open a config file.

Remote servers are connectors, not config

claude_desktop_config.json is for local servers: processes the app launches on your machine over stdio. A remote MCP server over HTTP is added as a connector from the app’s Connectors UI, or by an organisation through the connector directory, not by editing the JSON file. If you have a URL rather than a command, you are in the wrong file; this is the mirror image of Claude Code, where claude mcp add --transport http name url handles the remote case from the same command as local ones.

Claude Desktop vs Claude Code: the table

Everything in one place, because this is the comparison the search results never make.

• Config file. Desktop: one file, claude_desktop_config.json. Code: .mcp.json at the project root (project scope), plus ~/.claude.json for user and local scopes.
• Scopes. Desktop: none; the file applies to the whole app. Code: local, project and user, with precedence local > project > user, then plugins and connectors.
• Adding a server. Desktop: edit the JSON or install an extension; restart the app. Code: claude mcp add, claude mcp add-json, or edit the file; no restart of anything but the session.
• Environment variables. Desktop: literal values in env. Code: ${VAR} and ${VAR:-default} expansion in command, args, env, url and headers.
• Remote (HTTP/SSE) servers. Desktop: connectors, not the JSON file. Code: same claude mcp add with --transport http or sse.
• Approval of project servers. Desktop: not applicable. Code: a prompt the first time a project’s .mcp.json is seen, reset with claude mcp reset-project-choices.
• Status and logs. Desktop: Manage connectors in the app, Developer settings, and the mcp*.log files. Code: claude mcp list, claude mcp get name, and /mcp inside a session.
• Sharing with teammates. Desktop: an extension bundle, or an org-managed extension. Code: commit .mcp.json to the repository.

One bridge exists between them: Claude Code can import your Desktop servers with claude mcp add-from-claude-desktop, which reads claude_desktop_config.json and offers each server for import. It is available on macOS and WSL, names are restricted to letters, numbers, hyphens and underscores, and a name that already exists in Claude Code gets a _1 suffix. It is a one-way, one-time copy, not a sync.

A minimal, correct Desktop config for a real server

Most people configuring Desktop by hand want a filesystem server and one server that needs a key. A complete file for that looks like this on macOS:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/me/Projects"]
    },
    "search": {
      "command": "npx",
      "args": ["-y", "some-search-mcp-server"],
      "env": {
        "SEARCH_API_KEY": "paste-the-key-here"
      }
    }
  }
}

Three checks before you restart: the file is valid JSON (a trailing comma after the last server is the classic error), every path is absolute, and every directory you list is one you are comfortable letting Claude read and modify, because the server runs with your account’s permissions and the app will ask you to approve each action but not each file.

Troubleshooting in order

1. Quit and relaunch the app completely; a window close is not a quit.
2. Validate the JSON. One bad character disables every server in the file.
3. Run the command from the config in a terminal and read what it prints.
4. Open mcp.log and the server’s own log in the logs folder for your platform.
5. Replace npx or node with its full path if the app cannot find it.
6. If tools appear but calls fail silently, check the server log for stderr output and restart the app once more.
7. If none of that works, the MCP project’s debugging guide and its Inspector tool let you talk to the server outside Claude entirely.

If you are a developer who lives in both products, the rule of thumb is simple: the Desktop file is a launcher, nothing more, and everything clever (scopes, variable expansion, per-project approval, a CLI) lives on the Claude Code side. Configure Desktop once, by hand or by extension, and do your real MCP work where the tooling is.