`claude_desktop_config.json` is the per user JSON file Claude Desktop reads at launch. Its `mcpServers` map gives each server a name and either `command + args + env` for stdio or `url` for remote HTTP.
Imagine a laptop that cannot detect USB devices by itself. To make a device work, you write its name on a sticky note inside a notebook the laptop checks every time it boots up. That notebook is `claude_desktop_config.json`. Each sticky note says: here is the device name, here is how to start it (a command line for something local, or a web address for something remote), and here are any secret passwords it needs. When Claude Desktop launches, it reads the notebook, starts every local entry as a background process, connects to every remote entry, and lists whatever tools each one offers. Change the notebook, restart the laptop, and the new tools show up. There is no other way to add servers: no settings menu, no drag and drop, just the file.
Concept explanation~2 min read
Everything you need to truly understand this topic: intuition, mechanics, step by step explanation, code, formulas, and worked example. Click to expand.
Concept explanation~2 min read
Everything you need to truly understand this topic: intuition, mechanics, step by step explanation, code, formulas, and worked example. Click to expand.
If you have ever added a server to Claude Desktop, you have already met claude_desktop_config.json. If you have not, you might be surprised to learn there is no graphical settings panel for it. Claude Desktop's entire MCP wiring lives in a single JSON file on disk that the app reads at startup, uses to launch subprocesses or open connections, and then surfaces as tools in the chat.
This deep dive covers what the file contains, where it lives on each OS, the two entry shapes, the operational gotchas that trip people up, and why Anthropic shipped MCP wiring as a file rather than a settings dialog.
What the file is and what it controls
claude_desktop_config.json is a per user JSON file that Claude Desktop reads exactly once at startup to discover MCP servers. There is one top level key the app cares about, mcpServers, whose value is a map. Each map entry represents one server: a freely chosen name as the key and a config object as the value.
When Claude Desktop boots, it walks this map, launches a subprocess for every local entry and opens a connection for every remote entry, performs the MCP initialize handshake against each, calls tools/list to fetch available tools, and shows the union in the chat surface. The model then sees all these tools and can invoke them through normal function calling.
The file is the only supported wiring mechanism in 2026. There is no graphical add server dialog inside Claude Desktop. This is an intentional design choice rather than missing polish, and we will return to the reasoning in the design rationale section.
Situations where this technique stops working.
2–4 min · Everything important, quickly.
Real products, models, and research that use this idea.
- Adding the filesystem server: an entry named `fs` with `command: npx` and `args: ["@modelcontextprotocol/server-filesystem", "/Users/me/Documents"]` so the model can read and edit local files during a conversation.
- Adding the GitHub server: `command: docker` or npx, plus `GITHUB_PERSONAL_ACCESS_TOKEN` under `env`, giving Claude the ability to list PRs and create issues.
What an interviewer would ask next. Try answering before peeking at the approach.
QWhy does Claude Desktop require a full restart instead of watching the file for changes?
Reloading would mean tearing down running subprocesses and re handshaking each server, which complicates the trust UX because tools could change mid conversation. A startup only read keeps the trust boundary at session launch.
Red flags & common mistakes
The phrases that signal junior thinking. Click to expand.
Red flags & common mistakes
The phrases that signal junior thinking. Click to expand.
Editing the file and expecting changes to take effect immediately. Claude Desktop reads it only at startup, so a full quit and relaunch is required.
60 second bullets to scan on the way to the call.
The exact file path on macOS and Windows
The one top level key the file uses
Primary sources. Browse if you want the original framing.
Same topic, related formats. Practice these next.