Where Claude Desktop’s MCP config lives, what goes in it, the three ways to add a server, and how to fix the common failures — plus how to put a policy gate in front of every tool call.
QUICK ANSWERQuick answer: ~/Library/Application Support/Claude/claude_desktop_config.json on macOS, %APPDATA%\Claude\claude_desktop_config.json on Windows. Top-level key is mcpServers.
| Scope | Path | Notes |
|---|---|---|
| macOS | ~/Library/Application Support/Claude/claude_desktop_config.json | Created by Settings → Developer → Edit Config if it doesn’t exist yet. |
| Windows | %APPDATA%\Claude\claude_desktop_config.json | Use escaped backslashes in any Windows paths inside the file, e.g. C:\\Users\\you\\Desktop. |
One global file — Claude Desktop has no per-project scope. Open it via the menu-bar Claude menu → Settings → Developer → Edit Config.
A top-level mcpServers object, one entry per server. The JSON file configures local stdio servers; remote servers are added as custom connectors through the UI instead.
| Key | What it does |
|---|---|
command | Executable to launch the server. GUI apps don’t inherit your shell PATH — a full path is the safe choice. |
args | Array of arguments passed to the command. All file paths must be absolute. |
env | Environment variables for the server process, e.g. API keys. |
{
"mcpServers": {
"filesystem": {
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-filesystem",
"/Users/username/Desktop",
"/Users/username/Downloads"
]
}
}
} Remote MCP servers (streamable HTTP, OAuth) are added as custom connectors: Settings → Connectors → Add custom connector. They don’t go in the JSON file.
| Transport | Status | How to declare it |
|---|---|---|
| stdio | Supported | Declare command + args in claude_desktop_config.json. Runs as a local child process. |
| Streamable HTTP | Supported | Via custom connectors in the UI (Settings → Connectors), including OAuth-protected servers. |
| SSE | Deprecated | Legacy remote connectors; prefer streamable HTTP. |
Settings → Developer → Edit Config opens claude_desktop_config.json. Add an entry under mcpServers, save, then fully quit and relaunch Claude Desktop — servers load at startup only.
One-click local server install via .mcpb desktop extension bundles (formerly .dxt) — no JSON editing. Managed under Settings → Extensions.
Remote MCP servers are added under Settings → Connectors → Add custom connector, with OAuth handled in the UI.
Restart the app fully (quit, not just close the window), validate the JSON syntax, and make sure every file path in args is absolute, not relative.
Claude Desktop launches as a GUI app and doesn’t inherit your shell PATH. Use the full path to npx or node — which npx in a terminal gives it to you.
Check the logs: ~/Library/Logs/Claude/ on macOS, %APPDATA%\Claude\logs\ on Windows. mcp.log covers connections; mcp-server-NAME.log captures that server’s stderr. Tail with tail -f ~/Library/Logs/Claude/mcp*.log.
Add an expanded APPDATA value to the server’s env block, and make sure npm is installed globally.
Claude Desktop reads the config at startup only. Every edit needs a full quit and relaunch.
A standard filesystem MCP in Claude Desktop. Every read and write hits the upstream directly, with no audit trail and no path restrictions.
{
"mcpServers": {
"filesystem": {
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-filesystem",
"/Users/username/Desktop"
]
}
}
} Register the filesystem MCP in PolicyLayer, mint a grant, point Claude Desktop at the proxy URL via mcp-remote. PolicyLayer evaluates every call against the grant’s policy before it reaches the upstream.
{
"mcpServers": {
"filesystem": {
"command": "npx",
"args": [
"-y", "mcp-remote",
"https://proxy.policylayer.com/mcp/<server-uuid>/",
"--header", "Authorization: Bearer <grant-token>"
]
}
}
} The <server-uuid> appears on each server's detail page. The <grant-token> shows once at mint time. See the Quick start for the full setup walk-through — and if you operate under SOC 2, HIPAA, GDPR or similar, the compliance hub maps how gateway-mediated MCP traffic evidences each framework.
Allow reads and directory listings. Allow writes, but deny any write into common credential paths.
{
"version": "1",
"default": "deny",
"tools": {
"read_file": {},
"list_directory": {},
"write_file": {
"deny_if": [
{
"conditions": [
{ "path": "args.path", "op": "regex", "value": "^/Users/[^/]+/(\\.ssh|\\.aws|secrets)" }
]
}
]
}
}
} See Writing policies for the policy format, operators, and quota shapes.
On macOS: ~/Library/Application Support/Claude/claude_desktop_config.json. On Windows: %APPDATA%\Claude\claude_desktop_config.json. Settings → Developer → Edit Config opens it, creating the file if needed.
Yes — fully quit and relaunch. Claude Desktop only loads MCP servers at startup, so closing the window is not enough.
Yes, as custom connectors: Settings → Connectors → Add custom connector, with OAuth handled in the UI. The JSON config file is for local stdio servers; a remote server can also be bridged into it with the mcp-remote package.
Almost always PATH: GUI apps don’t inherit your shell environment, so npx or node may not resolve. Use absolute paths for the command and any file arguments, then check ~/Library/Logs/Claude/mcp*.log for the actual error.
Desktop extensions bundle a local MCP server into a one-click install — no JSON editing or Node setup. They are managed under Settings → Extensions, and enterprises can deploy them centrally.
Route your MCP traffic through PolicyLayer. Every tool call is checked against your policy before it runs: allow, deny, or require approval. Per-identity grants. Full audit log. Live in minutes.
Instant setup, no code required.
46,500+ MCP servers and 515,000+ tools scanned and risk-classified.