MCP config file locations: where each coding agent reads its servers

Cursor merges the user and project files, and the project entry wins when the same server name appears in both. A committed entry can therefore replace a personal one. Cursor resolves ${env:NAME}, ${userHome}, and ${workspaceFolder} in command, args, env, url, and headers.

User-scope and local-scope servers both live in ~/.claude.json, and a local entry sits under that project’s path, so use claude mcp add --scope user instead of editing the file by hand. General Claude Code settings live in a different file, ~/.claude/settings.json. The claude mcp add command defaults to local scope, which is private to you in the current project. Pass --scope user or --scope project for the other two, and project scope writes .mcp.json at the project root. When one server name is defined in several scopes, local beats project and project beats user, and the fields are not merged. Write type on every entry that has a url: Claude Code reads an entry with no type as a stdio server, so a url without a type is a configuration error. In interactive sessions, Claude Code asks you to approve the servers in a project .mcp.json. Editing .mcp.json takes effect after you restart the session.

The documented file covers local servers that the app starts, which is why the table lists stdio only. Settings, Developer, Edit Config opens the file and creates it if it is missing. Quit Claude Desktop fully and reopen it after editing, because closing the window is not enough. Use absolute paths to the server and to the runtime it needs, and on Windows write path separators as double backslashes or forward slashes.

The file is TOML and the top-level table is mcp_servers, not mcpServers: each server gets a [mcp_servers.<name>] table. The project file is read only for trusted projects, and project files rank above the user file. The Codex app, CLI, and IDE extension share this configuration. For an HTTP server, bearer_token_env_var stores a variable name instead of the token.

Windsurf’s documentation now sits under the Devin Desktop name. It describes two mcp_config.json files: the Open MCP config file action opens one in the Devin configuration directory, and the editor’s MCP discovery uses a separate file under ~/.codeium/windsurf/. We could not confirm from the documentation how the two relate, so check which one your installation reads before you edit. Rig’s project-scope link for Windsurf writes .windsurf/mcp.json, a path the cited documentation does not describe, so confirm that your version reads it. Remote servers need a serverUrl or url field. The documentation says references such as ${env:NAME} are interpolated in command, args, env, serverUrl, url, and headers.

VS Code’s own format keeps servers under servers, not mcpServers, so rename the key when you copy a snippet from a Cursor or Claude Code file. VS Code also documents a portable format, .mcp.json in the workspace root or ~/.copilot/mcp-config.json for your user, which uses mcpServers. The Add Server flow in the current documentation lists .vscode/mcp.json and the user-profile mcp.json as deprecated destinations and prefers the portable ones, while the configuration reference still documents them. VS Code can prompt for a secret when a server first starts. Declare an inputs entry with type set to promptString and password set to true, then write ${input:your-id} in env. These prompts belong to VS Code’s own format, and the migration documentation lists ${input:...} variables among the fields that do not carry over to .mcp.json.

The CLI reads project definitions from the working directory up to the repository root, and they take precedence over the user file. When .github/mcp.json and .mcp.json sit in the same directory, .mcp.json wins. Workspace servers also require the folder to be trusted. The tools field lists the tools to allow, and ["*"] allows all. The documented types are local (or stdio), http (streamable-http is accepted as an alias), and sse.

command is an array rather than a string. The environment key is environment, not env, and enabled switches the server on. This is the layout in the classic OpenCode documentation, which puts servers directly under mcp. The v2 pages group servers under mcp.servers and use disabled in place of enabled, so check which version you run.

Rig’s Link action, on the Connections screen, writes an entry named rig into the config of Cursor, Claude Code, Codex, Windsurf, VS Code, GitHub Copilot CLI, OpenCode, and Pi. Claude Desktop is not on that list. Every entry starts a stdio launcher, not an HTTP URL:

• command is ~/Library/Application Support/Rig/bin/rig-mcp on a Mac, as an absolute path, and %APPDATA%\Rig\bin\rig-mcp.cmd on Windows. The path contains a space, so it sits alone in command.
• args is empty.
• env carries RIG_MCP_TOKEN and RIG_MCP_URL, which defaults to http://127.0.0.1:47823/mcp.

Rig rewrites the launcher on every start, so the path in your config stays valid. It also rewrites the configs it linked on every start. Four layouts show how the shapes differ, and the GitHub Copilot CLI and Pi entries carry extra fields of their own. Each layout below uses a placeholder token.

Cursor, in .cursor/mcp.json. Windsurf’s entry has the same fields, and Claude Code’s adds "type": "stdio":

A client needs a restart or reload before it lists a new server. These are the steps Rig’s own link hints give, plus the Claude Desktop step from the documentation:

• Cursor: approve the MCP prompt when it appears.
• Claude Code: start a new session.
• Codex, GitHub Copilot CLI, and OpenCode: restart the client, then run /mcp to check that rig is listed.
• VS Code: reload the window.
• Windsurf: reload the MCP settings.
• Claude Desktop: quit fully and reopen.

An env or headers value that holds a token is a credential in a file. Treat these files like the .env files in the env example checklist, including what to do when one leaks.

What the Rig hub token is. A random 24-byte hex string that Rig generates and keeps in its own mcp.json settings file, ~/Library/Application Support/Rig/mcp.json on a Mac. The hub listens on 127.0.0.1:47823 unless you change the port, takes the token as an Authorization: Bearer header, and answers a wrong one with a 401. There is one hub-wide token, plus an optional project-scoped token for each project.

What a token allows. Whatever the MCP access mode allows. read offers read-only tools, control adds starting, stopping, and ports, and full offers everything. A fresh install defaults to control, and writes wait for an Approve click in Rig. A project-scoped token cannot use the group start and stop tools or read the screen frame, and its kill_port frees only that project’s own port. See the MCP tools overview and Project-scoped MCP.

Project scope. Rig’s project-scope links use the project-scoped token, never the hub token. Rig refuses to write if git already tracks the file, because an exclude rule does not hide a tracked file. After writing, it appends the path to .git/info/exclude. That file belongs to your clone and does not travel with the repository, and Rig skips the step outside a git repository. Project-scoped MCP tokens explains when to prefer them.

Rotation. Rotating the token in Rig creates a new hub token and a new token for each project that had one. Rig rewrites your linked user-scope configs straight away and your project-scope files the next time it starts, so a project file keeps its old token, and gets a 401, until you restart Rig or link that project again. A copy of the old token anywhere else stops working.

Any other server. A project-scope file is shared the moment it is committed. Commit it only when every value in it is safe for anyone who can read the repository. Where a client supports references, write the variable name and keep the value in your shell: ${env:NAME} in Cursor and Windsurf, ${NAME} in Claude Code, ${input:id} prompts in VS Code, and bearer_token_env_var for an HTTP server in Codex. The MCP config generator writes the snippet for each client, rewrites ${NAME} references into each client’s own syntax, and warns when a value looks like a token.