Claude MCP Config Files: Locations, Examples and JSON Pitfalls

Updated

Most MCP setup problems come down to two things: a file in the wrong place or JSON that does not parse. Here is where each client looks and what a valid entry looks like.

A Claude MCP config is a JSON file that tells the client which servers to start and how. Claude Desktop reads claude_desktop_config.json, but only for local servers that run on your computer; remote servers are added in the app as custom connectors instead. Cursor reads .cursor/mcp.json or ~/.cursor/mcp.json, and VS Code reads a workspace .mcp.json. If a server does not show up, check the file location first and the JSON syntax second.

Claude Desktop: local servers only

The file lives here:

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

It holds an mcpServers object; each key is a server name. A local server entry, using the SpeedyIndex npm package as the example:

{
  "mcpServers": {
    "speedyindex": {
      "command": "npx",
      "args": ["-y", "speedyindex-mcp"],
      "env": { "SPEEDYINDEX_API_KEY": "your-key" }
    }
  }
}

The package needs Node.js 18+. Restart Claude Desktop after every edit. A remote server URL does not belong in this file: in Claude you open Plugins → Add → Add custom connector, paste the URL and sign in. The step-by-step remote connector setup for https://mcp.speedyindex.com/mcp shows that path with a short video.

Cursor and VS Code

Cursor uses .cursor/mcp.json for one project or ~/.cursor/mcp.json for all projects. A remote server needs only a url:

{"mcpServers":{"speedyindex":{"url":"https://mcp.speedyindex.com/mcp"}}}

Cursor signs in with OAuth on first connect. Turn the server on in settings and expand the tool call of a test prompt to see a real response.

VS Code reads a workspace .mcp.json; the HTTP entry adds a type field:

{"mcpServers":{"speedyindex":{"type":"http","url":"https://mcp.speedyindex.com/mcp"}}}

The same can be done with the command “MCP: Add Server” → HTTP → paste the URL. “MCP: List Servers” shows what VS Code loaded.

JSON pitfalls that break a config

JSON is strict, and config files are often edited by hand or pasted from documents. The usual causes:

  • Trailing commas. {"a": 1,} is not valid JSON; remove the comma before } or ].
  • Smart quotes. Text copied from a word processor may contain curly quotes instead of ".
  • Single backslashes. In a JSON string, a Windows path is written "C:\\Users\\name\\tools"; a single backslash starts an escape sequence.
  • Unquoted values. Keys and string values, including API keys in env, must be in double quotes.
  • Encoded URLs. The server address is written as is. https%3A%2F%2Fmcp.speedyindex.com%2Fmcp is a percent-encoded string, not a URL a client can open.

Pasting the file into a JSON escape or validation tool before saving catches most of these in seconds.

MistakeSymptomFix
Trailing commaServer not listed after restartDelete the comma before the closing brace or bracket
Curly quotesFile fails to parseReplace with straight double quotes
Single backslash in a pathCommand cannot be found or file fails to parseEscape each backslash as \\
Unquoted env valueFile fails to parseWrap the value in double quotes
Percent-encoded server URLConnection failsUse the plain URL
Remote URL in claude_desktop_config.jsonServer not available in ClaudeAdd it as a custom connector instead

Keep keys out of chats

A local server reads its key from env; for the SpeedyIndex package that is SPEEDYINDEX_API_KEY. A remote server signs in through its own page: for SpeedyIndex a sign-in page opens and you paste the API key from your account there, and the server keeps it only inside an encrypted token. In neither case does the key belong in a chat message. Config files with real keys should stay out of shared repositories.

Video: adding the SpeedyIndex connector in Claude. YouTube

Verifying the setup

Claude Desktop: restart, then check that the server is available. Claude (web or desktop) with a custom connector: turn it on in a chat via “+” → Connectors. Claude Code: claude mcp add --transport http --scope user speedyindex https://mcp.speedyindex.com/mcp, then /mcp → Authenticate, then claude mcp list. Cursor: confirm the switch in settings. VS Code: “MCP: List Servers”.

Then ask something read-only. With SpeedyIndex, “What is my SpeedyIndex balance?” returns tokens and credits when the connection works. Claude asks for approval before tool calls; an approval prompt means the server is reachable, not that the config is wrong. Background on how clients and servers talk is on modelcontextprotocol.io.

Related: URL encoding and Google indexing

FAQ

Where is claude_desktop_config.json on macOS?

At ~/Library/Application Support/Claude/claude_desktop_config.json. It is for local servers; remote ones are added as custom connectors.

Why does my server not appear in VS Code?

Check that the file is named exactly .mcp.json in the workspace and parses as JSON, then run “MCP: List Servers”.

Should the server URL be URL-encoded?

No. Percent-encoding is for data inside URLs, such as query values. The server address goes into the config exactly as published.