You need to add an MCP server to Claude Desktop. Which file do you edit and what goes in it?

Attempt it

You edit claude_desktop_config.json, a per user JSON config that Claude Desktop reads at startup to discover MCP servers. On macOS it lives at ~/Library/Application Support/Claude/claude_desktop_config.json; on Windows at %APPDATA%\Claude\claude_desktop_config.json. The file has one top level key, mcpServers, which maps a chosen server name to either a local stdio entry (command + args + optional env) or a remote entry (url). After saving, you must fully quit and relaunch Claude Desktop for the new server's tools to appear in the chat surface.

Your answer

Quick reference

TL;DR

`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.

Memory aid

Sign in for the mnemonic that makes this stick. See Pro pricing.

Easy to grasp

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.

Key concepts

Claude Desktop stdio transport MCP configuration

Detailed answer & concept explanation

~6 min read

Everything you need to truly understand this topic: intuition, mechanics, step by step explanation, code, formulas, and worked example. Click to expand.

Everything you need to truly understand this topic: intuition, mechanics, step by step explanation, code, formulas, and worked example.

Sign in for 5 free unlocks/day or go Pro for unlimited. See Pro pricing.

Quick scan · 2–4 min

Everything important, quickly.

3 min: name the file and its per OS path, describe the `mcpServers` schema with the two entry shapes, explain the startup only read model, and close with the secrets hygiene consideration.

Real-world examples

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.
Adding a remote MCP server hosted on Cloudflare Workers: a single `url` field pointing at the streamable HTTP endpoint, with OAuth handled through a browser flow on first connection.

Interviewer follow-ups

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?

Sign in or go Pro to see the approach for this follow-up.

QWhat happens if two entries expose tools with the same name?

Sign in or go Pro to see the approach for this follow-up.

QHow would you share an MCP server config across a team without leaking secrets?

Sign in or go Pro to see the approach for this follow-up.

Don't say this

Red flags and common mistakes that signal junior thinking. Click to expand.

Most common mistake

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.

Sign in or go Pro to see all red flags and common mistakes. See Pro pricing.

60-second cheat sheet

The night-before-the-interview bullets. Scan these on the way to the call.

Sign in for 5 unlocks/day or go Pro for unlimited revision sheets. See Pro pricing.

References

Primary sources. Skim if you want the original framing.