Where the MCP config file lives

• Local scope is the default, claude mcp add writes to ~/.claude.json scoped to the current project, not to .mcp.json. Add --scope project to share with your team, or --scope user for all your projects.
• MCP local scope (~/.claude.json) is not the same file as general local settings (.claude/settings.local.json). The docs call this out because people conflate them constantly.
• Project servers from .mcp.json need approval. They show as ⏸ Pending approval (run claude to approve) until you run claude interactively and accept.
• A cloned repo cannot approve its own servers. Until you trust the workspace, a committed enableAllProjectMcpServers is ignored and the server stays pending.
• Check status with claude mcp get <name> rather than guessing.
• In claude mcp add, -- separates Claude's own flags from the server command. Everything after it is passed through untouched.

• The in-app Edit Config button has been reported to open the wrong file, so people edit something that is never read. If your change has no effect, open the path above directly and confirm you are looking at the same file.
• Restart the app fully after editing. Closing the window is not enough on macOS, quit it.

• Same JSON shape as Claude Desktop, so an mcpServers block copies across unchanged.
• Project config wins where both exist, useful for pinning a server to one repo.

• VS Code uses `servers`, not `mcpServers`. This is the single most common reason a config pasted from a README silently does nothing. Everything else about the entry is the same.

• The file is not created on first launch. You have to make it yourself, directories included.
• Cmd+Shift+P → "Windsurf: Configure MCP Servers" opens it without hunting for the path.

The server does not appear at all

Wrong file, or the wrong root key

Confirm the exact path for your client above. In VS Code, check you used servers and not mcpServers. In Claude Code, run claude mcp get <name>, if it says pending approval, run claude and approve it.

It appears but will not connect

The command cannot run

Run the command and args yourself in a terminal. npx -y <package> should start and wait. If it errors there, it will error in the client. This isolates the problem in seconds.

Works locally, fails for teammates

Scope

You almost certainly used local scope, which is the default. Re-add with --scope project so it lands in .mcp.json, and commit that file.

Auth failures against a hosted server

Missing or unexpanded environment variable

Confirm the variable is exported in the environment the client launches from, a GUI app does not inherit your shell profile. Restart the client fully after changing it.

Everything works but the model picks the wrong tool

Too many servers

Every server adds tool definitions to the context window, and a bloated tool list measurably degrades tool selection. Three to five is the working recommendation. Remove what you are not using.

Breaks only on native Windows

POSIX path assumptions

Many servers assume POSIX paths, shell hooks and file watchers. WSL is the supported path in 2026, if a server misbehaves only on native Windows, try it under WSL before debugging further.