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%2Fmcpis 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.
| Mistake | Symptom | Fix |
|---|---|---|
| Trailing comma | Server not listed after restart | Delete the comma before the closing brace or bracket |
| Curly quotes | File fails to parse | Replace with straight double quotes |
| Single backslash in a path | Command cannot be found or file fails to parse | Escape each backslash as \\ |
| Unquoted env value | File fails to parse | Wrap the value in double quotes |
| Percent-encoded server URL | Connection fails | Use the plain URL |
| Remote URL in claude_desktop_config.json | Server not available in Claude | Add 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.