A developer spends an afternoon editing ~/.cursor/mcp.json to fix a misbehaving server, with no visible change, and is also surprised to see servers in chat that the project file never mentions. The project's .cursor/mcp.json defines a server under the same name. What is happening?

The principle — Cursor reads MCP configuration from two places and combines them. A project file at .cursor/mcp.json and a global file at ~/.cursor/mcp.json are merged, and if the same server name appears in both, the project-level config takes priority.

Why the key is correct — Merging accounts for both symptoms at once. The servers appearing in chat that the project file never mentions are the global entries, which survive because nothing in the project shadows them. The fruitless afternoon is the collision: the project entry with the matching name wins, so edits to the global copy of that one server change nothing observable. The fix is to edit the project file, or to rename one entry so the two stop colliding, and then restart Cursor, since the configuration is read at startup.

Why the others are wrong — Exclusive selection, where one file is used and the other ignored, would have hidden the global servers entirely, which is the opposite of what was seen. Giving the global file precedence would have made the edits take effect, so the observation itself rules it out and a cache theory only delays the diagnosis. And the entries are not loaded side by side under generated names; sharing a name is precisely what causes one to shadow the other.

Remember this — Commit .cursor/mcp.json so a team gets the same servers, and keep personal ones global. When an edit appears to do nothing, check whether the other file defines a server with the same name before changing anything else.

Sources — Cursor's MCP integrations documentation.