The file that came back had one key. $schema was gone. The servers object was gone. notes was gone. claude mcp add --scope project had exited 0, and the line it printed said the server had been added.
That is what Claude Code 2.1.308 did on 18 November 2026. claude --version printed 2.1.308 (Claude Code). Each command ran with HOME and CLAUDE_CONFIG_DIR pointed at a new directory, from a project directory that held only .mcp.json. No interactive session was started. No model call was made. The stdio commands were /bin/true and /bin/false, so a later start would exit immediately. This run did not leave a server process behind. The operator home was not the home these commands used.
What was in the file
The project file was valid JSON, and it had four top-level keys. $schema was https://example.invalid/mcp.schema.json. servers held one entry, other-tool, whose command was false. notes was the string keep-me. mcpServers held keep-stdio, type stdio, command /bin/false, and an empty args array.
That is a file more than one tool can share. Claude Code’s project scope reads mcpServers. Another client can keep its own map under servers. A schema URL is there for the editor. None of those extra keys is a server Claude Code will load. They are still part of the file you committed, and a later add does not ask whether you meant to keep them.
The MCP page, fetched the same day, says a project-scoped server lives in .mcp.json at the project root, and that adding one creates or updates that file with the appropriate configuration structure. The example under that sentence is a file whose only top-level key is mcpServers. The page does not say an update deletes every other top-level key. It does not say a top-level servers object is replaced. The word a reader will trust is “updates.”
The write that exits 0
From the directory that held the four-key file:
claude mcp add --scope project --transport stdio probe-stdio -- /bin/true
The exit code was 0. The text was:
Added stdio MCP server probe-stdio with command: /bin/true to project config
File modified: <project>/.mcp.json
There are two spaces between /bin/true and to. The second line names the file. It does not name a key that left.
The file after that command held only mcpServers. keep-stdio was still there, with the same type, the same command, and the same empty args array. It did not gain an env key. probe-stdio had been added beside it: type stdio, command /bin/true, empty args, and env set to an empty object. $schema, servers, and notes were not in the file. The copy that went in ended with a newline. The copy that came out ended on } (byte 0x7d). The mode stayed 664, which is the mode the fixture already had. A file created where none existed was mode 644. The rewrite of an existing file did not chmod it. It also did not leave a .mcp.json backup beside the project. The only backup files from these runs sat under the disposable config directory, and they were copies of .claude.json.
claude mcp list then printed both names and exited 0:
Checking MCP server health…
probe-stdio: /bin/true - ⏸ Pending approval (run `claude` to approve)
keep-stdio: /bin/false - ⏸ Pending approval (run `claude` to approve)
It did not print other-tool. That name had never been under mcpServers, and the key that held it was no longer in the file. A wrapper that searches the output for probe-stdio, or that treats exit 0 as success, will accept the run. The diff is the check that fails.
The same class of write came from add-json. The argument was a single server object, not a patch of the file:
claude mcp add-json --scope project json-stdio '{"type":"stdio","command":"/bin/true","args":[]}'
Exit 0. The result held keep-stdio and json-stdio under mcpServers, and nothing else. Passing JSON on the command line does not mean the command merges that JSON into the document you already have. It means one more entry in the object that gets written back.
A top-level servers map is not mcpServers
A second file had no mcpServers key. It had $schema, a top-level servers object for other-tool, and notes. That is the shape a later release note describes as the case that should stop.
claude mcp add --scope project --transport http shared-server https://example.invalid/mcp
Exit 0. The line was Added HTTP MCP server shared-server with URL: https://example.invalid/mcp to project config. The URL was never contacted. The command writes the entry. It does not open it. The file that remained was:
{
"mcpServers": {
"shared-server": {
"type": "http",
"url": "https://example.invalid/mcp"
}
}
}
other-tool was not copied into mcpServers. The schema URL was not kept. This host did not stop, and it did not print a warning that the previous document had been replaced. The success line is the same shape as an add against a file that was already in Claude Code’s format.
A missing .mcp.json is a different write, and it is the one the docs describe. The same stdio add, in a directory that had no file yet, created one. The created file contained only mcpServers and the new server, including env as an empty object, and it was mode 644. Creating that file is not the defect. Replacing a file that already had other keys is.
The command writes ./.mcp.json in the working directory. It does not write the project file under CLAUDE_CONFIG_DIR. If you run the add from the wrong directory, you create or rewrite a different .mcp.json, and the file you meant to edit stays as it was. Run it from the project root, then read that root’s file. Do not infer the target from the config directory.
Remove uses the same write-back
claude mcp remove --scope project keep-stdio, against the four-key file, exited 0. The line was Removed MCP server keep-stdio from project config. The file became twenty-two bytes:
{
"mcpServers": {}
}
The last byte was }. The server was gone, and so were the three keys that were never servers. Remove is not a narrower edit than add. Both read mcpServers, change that object, and write a file whose only top-level key is mcpServers. If keep-stdio was the only entry, the object you get back is empty. The other tool’s servers map is not consulted on the way out.
That matters if you use remove to retire one shared server and expect the rest of a committed file to stay. On this binary, a successful remove is a rewrite. The name in the success line is the name that left mcpServers. It is not a list of the keys that left the file.
The refusals leave the bytes
Four failures left the project file alone. The exit code is the split, not the presence of a message.
A file whose contents were the two words not json made add exit 1. The message was .mcp.json is malformed (not valid JSON, or mcpServers is not an object). Those two words were still the file.
Add of a name already under mcpServers exited 1 with MCP server keep-stdio already exists in .mcp.json. The four top-level keys were still there, including the trailing newline the fixture had been written with. A duplicate name is a refusal before the write. It is not evidence that a new name would have kept $schema.
Remove of a name that was not in the file exited 1 with No MCP server named "not-there" in .mcp.json. The file was unchanged. A missing name does not become an empty mcpServers object. Only a name the command can find is removed, and only that success path rewrites the document.
claude mcp add-json --scope project dash-stdio -, with the server JSON on stdin, exited 1. The message was Invalid configuration: : Invalid input. The colon pair is what the binary printed. There is no server name between them. The four-key file was unchanged. On this binary, - is not a stdin marker. It is a bad JSON argument. If a wrapper treats any add-json failure as “the server was already configured,” it will leave the file alone, which is the safe side of this particular bug, and it will also fail to add the server.
The pattern on these commands is narrow. Exit 1 meant the project file was not rewritten. Exit 0 meant it was. Do not invert that. A failed add is not the case that drops keys. The successful one is.
Local scope is a different file
The same page puts project scope in .mcp.json at the project root, and local scope in ~/.claude.json under the project path. That split held.
claude mcp add --scope local --transport stdio local-stdio -- /bin/true
Exit 0. The line said the server was added to local config, and the file it named was the disposable .claude.json, with the project path in brackets. The project directory still had no .mcp.json after the command. Default scope is local. If you omit --scope, you do not touch the file in the repository. If you pass --scope project, you do, and the success line is not a diff of that file.
User scope was not required to see the split. It is stored in the same ~/.claude.json as local scope, and it is available in every project. It is still not .mcp.json. A review that only greps the repository will miss a local or user server. A review that only reads claude mcp list will miss a key that project scope just deleted. Those are different checks. Run the one that matches the file you intend to commit.
What list will not tell you
claude mcp list health-checks configured servers and prints a pending-approval line for a project server you have not approved. The page says you approve those by running claude in the project, and that a cloned repository cannot approve its own servers until the workspace is trusted. That approval step is real, and it is not a review of the file’s other keys.
After the successful add, both probe-stdio and keep-stdio were pending. other-tool was absent because it was never a Claude Code server, and because the key that held it had been deleted. Pending approval does not mean the rest of .mcp.json survived. It means the names now under mcpServers have not been accepted for use. A script that waits for Pending approval and then commits the working tree will commit the stripped file.
The page also says claude mcp get shows the same pending state. This run used list, not get, for the post-add check. Get was not needed to see that the dropped key was gone. The file on disk was enough.
The release that names this write
Claude Code 2.1.327 is dated 17 November 2026 in the changelog. Two sentences in that release describe the write this run observed. This host was not upgraded. claude --version still printed 2.1.308, which that changelog dates to 22 October 2026. The 2.1.308 entry is “Bug fixes and reliability improvements.” It does not mention .mcp.json.
One 2.1.327 sentence says claude mcp add --scope project now stops, instead of overwriting the file, when .mcp.json lists its servers at the top level with no mcpServers key. The second file in this run was that case. 2.1.308 overwrote it and exited 0. The note says stop. It does not say the foreign servers entries are imported into mcpServers. A later binary that stops is not a binary that merges. If you need those entries, copy them yourself before you retry the add on a release that refuses the overwrite.
The other sentence says project-scoped claude mcp add and claude mcp remove no longer delete other top-level keys from .mcp.json, such as $schema or another tool’s servers. Those are the keys this run lost, on add and on remove. The note names add and remove. It does not name add-json. This run did not install 2.1.327, so it does not show whether that release also keeps the keys when the command is add-json. On 2.1.308, add-json with a JSON argument dropped the same keys that add dropped.
The same release adds claude mcp add-json <name> - so the server JSON can be read from stdin and a token can stay off the command line. The note says that form is not available inside a Claude Code session. This run was the CLI, not a session, and - still exited 1 before any write. A wrapper pinned to 2.1.308 should not pass - and expect a quiet success. Pass a JSON argument only if you are going to diff the file afterward, or keep the edit out of project scope until you have read the file back.
Do not treat the 17 November note as a description of the binary claude --version printed here. The note is the reason to check the version before you trust a project-scoped add. The observed write is the reason to diff the file on 2.1.308 even when the command exits 0.
Diff the file before you commit
Point HOME and CLAUDE_CONFIG_DIR at a directory you can throw away. Put the .mcp.json you mean to keep in an otherwise empty project directory, and run the add from that directory.
export HOME=<disposable-home>
export CLAUDE_CONFIG_DIR=<disposable-home>/.claude
cd <project>
cp <known-file> .mcp.json
claude mcp add --scope project --transport stdio probe-stdio -- /bin/true
Then compare the file with the copy you started from. On 2.1.308, a zero exit and an Added line are compatible with a file that has lost every key outside mcpServers. claude mcp list will not restore them. There is no project-file backup next to .mcp.json to restore them from either. If the name you added is already present, the command exits 1 and the file stays. That refusal is not a test of the rewrite. Use a name that is not in mcpServers. If the file is not JSON, add exits 1 and the bytes stay. That refusal is not a test of the rewrite either.
Before you commit a project file that another tool also writes, diff it after every project-scoped add, remove, or add-json. If $schema or a servers map has to survive, write the server entry under mcpServers yourself, or run the command on a copy and put the dropped keys back before you commit. Do not treat the success line as a statement that the rest of the file is intact.
On this build, the keys beside mcpServers survive a refusal. They do not survive the command that says it modified the file.
Sources
- Claude Code 2.1.308,
claude --versionoutput2.1.308 (Claude Code), Linux x86_64, 18 November 2026. Project add, remove, add-json, and list ran withHOMEandCLAUDE_CONFIG_DIRset to disposable directories. No interactive session was started. - Connect Claude Code to tools via MCP, project scope section, fetched 18 November 2026. It says add creates or updates
.mcp.jsonand shows a file whose only top-level key ismcpServers. - Claude Code changelog, fetched 18 November 2026. Version 2.1.308 is dated 22 October 2026. Version 2.1.327 is dated 17 November 2026 and describes the stop, the key-preserving fix, and
claude mcp add-json <name> -. This host was not upgraded to that release.