How do I use claude mcp add-json <name> - for an MCP server?
The trailing dash in `claude mcp add-json <name> -` makes the command read the server's JSON from stdin.
The string claude mcp add-json <name> - is new in Claude Code 2.1.327, released on November 17, 2026. Its trailing dash tells the command to read the server's JSON from stdin, so tokens can stay off the command line. Run it in your own terminal, pipe the JSON in, and a token never has to appear in the command you type.
This guide is independent and unofficial. It follows Anthropic's changelog and MCP documentation, both read on November 20, 2026.
What the changelog line says
The Claude Code changelog dates version 2.1.327 to November 17, 2026. One line under Added concerns this command. It says the dash form exists "to read the server's JSON from stdin, so tokens can stay off the command line; not available inside a Claude Code session".
Two things follow from that line. The - at the end is the part that sends the command to stdin. And the command belongs in a normal terminal window, not inside a running Claude Code session.
The changelog does not explain how stdin gets its content. Piping from another command or redirecting from a file are ordinary shell habits, and we treat them as such, not as documented Claude Code features.
The command shape you already know
Anthropic's MCP documentation shows add-json with the JSON as a quoted argument:
claude mcp add-json example '{"command":"npx","args":["-y","@example/mcp-server"]}'
The same page explains what to pass: "Pass claude mcp add-json the object inside mcpServers, not the wrapper." If a server's setup instructions show a whole mcpServers block written for another client, such as Claude Desktop, you copy only the inner object.
The <name> placeholder is the label you choose for the server. The documentation says a key with characters other than letters, numbers, hyphens and underscores needs a different name, so stick to those.
Two candidate ways to feed it stdin
Both commands below replace the quoted JSON with a -. Neither is copied from Anthropic's pages.
printf '%s' '{"command":"npx","args":["-y","@example/mcp-server"]}' | claude mcp add-json example -
claude mcp add-json example - < server.json
The first pipes a string in. The second reads a file you saved. For a real token, the file route is the one that keeps the secret out of the command, but the file then holds the token, so keep it out of any folder you commit.
The Claude moves worth stealing, by email
Workflows tested on real jobs, sent only when they are worth it. Free.
Add a server in five steps
Update Claude Code
Update Claude Code, then run claude --version. You need 2.1.327 or later.
Save the inner JSON object
Copy only the object inside mcpServers, as the MCP documentation says, into a file such as server.json. Fix any url entry that has no type.
Leave Claude Code
Open a plain terminal. The changelog says the stdin form is not available inside a Claude Code session.
Run the command with a dash
Use claude mcp add-json example - < server.json, with your own name in place of example.
Confirm it connected
Run claude mcp get example. The documentation says each add-json command prints an Added line on success.
The fixes in step two come from the documentation: a url entry with no type fails, because Claude Code reads an entry with no type as a stdio server. Add "type": "http", "type": "sse" or "type": "ws" to match the endpoint.
Pick the scope before you paste a token
The scope decides which file receives the server. Anthropic's MCP page describes three:
- Local, the default. "A local-scoped server loads only in the project where you added it and stays private to you." It is stored in
~/.claude.json. - Project. Servers go in a
.mcp.jsonfile at the project root, which is made for sharing with a team. - User. Servers are stored in
~/.claude.jsonand are available across all your projects.
The documentation says add-json accepts the --scope flag. Our reading is that the JSON you pass becomes the server's entry in the file for that scope. So a token placed inside the JSON would end up in .mcp.json under project scope, a file the documentation suggests you commit. Keep tokens on local or user scope.
Check it, then remove it if needed
Anthropic's MCP page lists the management commands:
claude mcp list
claude mcp get notion
claude mcp remove notion
Inside a session, /mcp shows server status. When you remove a remote server, "Claude Code also deletes the OAuth tokens and client registration it stored for that server." The page adds that Claude Code doesn't revoke them at the issuing authorization server. For a leaked credential, our API key guide says to revoke first and investigate second.
Where this does not help
- We did not run it. We cannot confirm the behavior or the exact output.
- The documentation page does not describe stdin. The MCP page we read covers the quoted form of
add-json. Only the changelog line mentions the-. - It protects the command line, not the config. We could not confirm where Claude Code keeps a token you pass this way, so check the file for your scope.
- A trusted token can still reach an untrusted server. The MCP page warns: "Verify you trust each server before connecting it." Choosing the right connection type is a separate question, covered in our API vs MCP vs CLI comparison.
- It is new. The changelog entry is days old, so check the changelog again before you build a routine on it.
Once a server is added, Claude decides when to call it. Our guide on making Claude Code wait for an MCP task covers one behavior of long-running calls.
What does the dash do in claude mcp add-json <name> -?
It tells the command to read the server's JSON from stdin instead of from an argument. Anthropic's changelog for Claude Code 2.1.327 describes it that way, so that "tokens can stay off the command line". The changelog does not say more, so test with a harmless server first.
Which Claude Code version added claude mcp add-json <name> -?
Claude Code 2.1.327, dated November 17, 2026 in Anthropic's changelog. Run claude --version to check what you have, and update Claude Code if it is older. Version 2.1.327 is the one the changelog lists for the stdin form.
Can I use claude mcp add-json <name> - inside a Claude Code session?
No. The changelog says the stdin form is "not available inside a Claude Code session". Open a separate terminal window, run the command there, then start or restart Claude Code. Inside a session, /mcp shows the status of servers you already added.
Sources (checked 2026-11-20)
- Claude Code changelog: version 2.1.327, November 17, 2026, the Added line for
claude mcp add-json <name> - - Connect Claude Code to tools via MCP: the
add-jsonexample, themcpServerswrapper note, scopes, the management commands and the trust warning
