claude mcp add-json From Stdin: Keep Tokens Off the CLI
Since Claude Code 2.1.327, claude mcp add-json <name> - reads the server's JSON from standard input instead of from the command line. The point is the token: a header such as Authorization: Bearer ... no longer appears as a shell argument, so it is not in the command you typed. It does not make the token private on disk, and it will not run from inside a Claude Code session. Both limits are covered below.
Verified against: Claude Code 2.1.327 on 2026-11-18. We ran every command in this article in a scratch home directory, and the outputs are quoted as seen. The MCP and CLI reference pages on code.claude.com (fetched the same day) do not mention the stdin form, so the behavior below comes from the changelog, --help, and our runs. We did not test OAuth servers or --client-secret together with stdin.
The command
printf '%s' '{"type":"http","url":"https://mcp.example.com/mcp","headers":{"Authorization":"Bearer '"$MCP_TOKEN"'"}}' \
| claude mcp add-json my-server -
Better, produce the JSON in a script or a secret manager call so that no literal token is typed anywhere:
my-secret-tool get mcp-token \
| jq -Rc '{type:"http",url:"https://mcp.example.com/mcp",headers:{Authorization:("Bearer "+.)}}' \
| claude mcp add-json my-server -
(my-secret-tool is a placeholder for whatever command prints your token. jq builds the JSON so quotes in the token cannot break it.)
The help text in 2.1.327 describes it as: "Add an MCP server (stdio, SSE, HTTP, or WebSocket) with a JSON string, or - to read it from stdin". The -s, --scope <scope> flag still works (local, user, project; default local).
What we saw
We piped an HTTP server definition with a bearer header into a fresh home directory:
$ printf '%s' '{"type":"http","url":"https://example.com/mcp","headers":{"Authorization":"Bearer TESTTOKEN"}}' | claude mcp add-json demo -
Added http MCP server demo to local config
$ echo $?
0
With -s project it printed Added http MCP server demo2 to project config and wrote .mcp.json in the working directory.
Bad input fails with exit code 1 and a plain message:
| Stdin | Message | Exit |
|---|---|---|
{bad | Invalid configuration: not a JSON object. Check its quotes, commas and braces. | 1 |
| empty line | There is no JSON on stdin. Pipe it in, or pass it as the argument. | 1 |
It refuses to run inside a Claude Code session
Run from a shell that Claude Code itself started (including the Bash tool), the same command stops:
Reading the JSON from stdin is refused inside a Claude Code session, because its permission prompt would not show the server. Run the command outside the session.
Exit code 1, nothing added. The message gives the reason: a permission prompt for the command would show only claude mcp add-json my-server -, not the server you are about to add. In our test we got past it by running the command with a clean environment (env -i), since the session is detected from environment variables. Treat that as an observation, not a supported workaround: the intended place to run it is a normal terminal of your own.
Where the token still lives
Stdin keeps the token out of your shell history and out of the process arguments. It does not encrypt anything. After the run above:
$ claude mcp get demo
demo:
Scope: Local config (private to you in this project)
...
Headers:
Authorization: Bearer TESTTOKEN
In our run, ~/.claude.json held the header in plain text (that file's mode was -rw-------), and with -s project the token went into .mcp.json in the repo directory, also in plain text. If that file is committed, so is the token. For a shared project server, keep the secret out of the file instead: the MCP page documents headersHelper for dynamic headers, and environment variable expansion in .mcp.json. We did not test either here, so check that page before relying on it.
Related 2.1.327 fix: project scope no longer drops other keys
The same release notes say claude mcp add and claude mcp remove with project scope used to delete other top-level keys from .mcp.json, such as $schema or another tool's servers. We started from a file containing $schema, servers and an empty mcpServers, added one server with -s project, and all three keys were still there afterward. We did not run the old version, so we cannot show the bug itself.
FAQ
Which Claude Code version added stdin support for add-json?
2.1.327, per the changelog. claude --help for mcp add-json on 2.1.327 shows the - form.
Does reading from stdin encrypt or hide the token?
No. It only keeps it off the command line. The server entry, headers included, is stored as plain JSON in ~/.claude.json (local and user scope) or .mcp.json (project scope).
Why does it say it cannot run inside a session?
The message says a permission prompt would not show the server. Run it from your own terminal.
Can I still pass the JSON as an argument?
Yes. claude mcp add-json <name> '<json>' is unchanged and is what the docs show.
Does it work with OAuth servers and --client-secret?
We did not test that combination. The documented OAuth example passes --client-secret as a separate flag with the JSON as an argument.