MCP client configuration file locations by operating system
Find the exact global or project configuration file without copying another client's path.
There is no operating-system-wide MCP configuration file. The client and the scope determine the location: project files live inside the repository, while user or global files live under the current user's home or application-data directory. Identify both before editing so a valid JSON object does not end up in a file the client never reads.
The quickest cross-platform rule is to preserve the client documentation's path notation. A leading ~ means the current user's home directory on macOS and Linux and in shells that support home expansion. Windows-only application paths may instead use variables such as %APPDATA%. Do not substitute one client's folder or schema for another.
Choose project, local, or user scope deliberately
Choose a project file when teammates should receive the same server definition through version control. Choose a user or global file for a personal server that should appear in every project. Claude Code also has a local scope: it is private to you and limited to the current project, but the data is stored inside ~/.claude.json rather than a project-local settings file.
VS Code user configuration is profile-aware, so opening the file through MCP: Open User Configuration is safer than guessing a physical profile folder. In a remote VS Code window, use MCP: Open Remote User Configuration when the server should run on the remote machine.
Find the file without copying the wrong schema
First name the client and decide whether the server belongs to one project or every project. Second, open the documented file or client command instead of creating a similarly named file by memory. Third, confirm the top-level schema: Cursor, Claude Code, Claude Desktop, and legacy Windsurf examples use mcpServers, while VS Code uses servers. Finally, save and use the client's server list, logs, or status view to confirm that the client loaded the entry.
A common failure mode is treating a correct path as portable between clients. For example, .cursor/mcp.json is invisible to VS Code's native MCP loader, while .vscode/mcp.json is not Cursor's project file. A second failure mode is putting a global definition in a project file and then assuming it should appear in unrelated workspaces.
Verified MCP configuration file locations
Use the table as a location map, not as a compatibility guarantee. These paths match current first-party documentation accessed on August 8, 2026. The project-relative entries work the same way on Windows, macOS, and Linux because they start at the project root; home-relative entries depend on the signed-in user's home directory.
- Cursor - project
- .cursor/mcp.jsonCreate this file at the project root. Cursor documents the same project-relative location for its desktop platforms.
- Cursor - global
- ~/.cursor/mcp.jsonCursor's documented home-relative file makes servers available across projects.
- Claude Code - project
- .mcp.jsonProject-scoped servers are shared through the file at the project root.
- Claude Code - local or user
- ~/.claude.jsonLocal scope is stored under the current project entry; user scope is available across projects in the same file.
- VS Code - workspace
- .vscode/mcp.jsonThe workspace file is shareable. Its top-level server collection is servers, not Cursor's mcpServers.
- VS Code - user profile
- MCP: Open User ConfigurationUse the Command Palette command because each VS Code profile can have its own mcp.json, and remote windows can have a separate remote-user configuration.
- Claude Desktop - macOS
- ~/Library/Application Support/Claude/claude_desktop_config.jsonThe official MCP local-server guide documents Claude Desktop for macOS and Windows, not Linux.
- Claude Desktop - Windows
- %APPDATA%\Claude\claude_desktop_config.jsonUse Edit Config in Claude Desktop's Developer settings to create or open the file.
- Windsurf legacy Cascade
- ~/.codeium/windsurf/mcp_config.jsonCurrent Windsurf documentation limits this file to the legacy Cascade agent; new Devin Local tabs use Devin CLI configuration instead.
Continue with the client-specific setup
After locating the file, use the narrower guide for the client's transport syntax, authentication flow, and validation steps.
Editorial boundary
This page owns MCP client configuration file locations and scope selection. It does not claim that every client accepts the same transport, object shape, authentication method, or reload behavior. Keep those details on the client-specific pages, and consolidate this page into /integrations/mcp-clients if monthly first-party verification can no longer cover Windows, macOS, and Linux workflows.