fix(server): warn that a declared MCP server's env reaches the claude command line (#691)

[edspencer]

A follow-up to #701 (#691 step 6), which merged while this was being written. Not a re-do of it — one finding it does not cover, plus the test that proves the finding is real.

The finding

mcp-servers.ts keeps a resolved credential out of every surface Paddock owns: the boot log, error messages, the Settings API. That is complete and it holds. It is still not the whole story, because of what the engine does with the record afterwards:

// @herdctl/core, runner/runtime/cli-runtime.js
const mcpServers = transformMcpServers(options.agent.mcp_servers);
const mcpConfig = JSON.stringify({ mcpServers });
args.push("--mcp-config", mcpConfig);        // ← env values and all

A process argument is not private on Linux. /proc/<pid>/cmdline is world-readable with no hidepid (this box included — checked /proc/mounts), and ps prints it. So on the CLI runtime every declared server's env — the API token a user carefully passed by env:VAR_NAME reference so it would not be written to a file — is legible to any local user for the lifetime of each claude invocation.

The SDK runtime does not do this. It hands the same record to the SDK in-process, and the stdio server it spawns receives the value in its environment, where /proc/<pid>/environ is owner-only. That is exactly what Claude Code itself does, so there is nothing to fix on that path.

Which one runs is driveMode: session (the default) is the SDK, batch is the CLI.

Observed, not inferred

test/integration/declared-mcp-argv.test.ts drives a real turn through the real CLI runtime with a server declared in paddock.config.yaml whose token comes from an env:VAR_NAME reference, and reads the token back out of the spawned process's argv. The fake claude now records --mcp-config and --allowedTools alongside the flags it already recorded (test/bin/claude, ~5 lines).

It is a characterisation test, and the header says so: it pins behaviour Paddock does not want and cannot fix from here. If that assertion ever starts failing, that is good news — the engine has learned to pass --mcp-config as a file path (the Claude CLI accepts one) — and the right response is to delete the test and the warning, not to "fix" it.

The same test pins the other half in the opposite direction: mcp__notion__* reaches the same argv, which is what makes an attached server callable at all rather than silently refused. Both halves of step 6 are now observable end-to-end, on a real spawn, in one test.

What this changes

Nothing about what is attached, and nothing about what is logged for an instance that declares no env values. declaredMcpNotices grows an optional driveMode, and when it is passed:

• driveMode: batch + a declared server with env → warning naming the server;
• driveMode: session + the same → the same text as an info note, because one project pinning driveMode: batch for itself brings the exposure back and the instance-level default does not say so;
• no env values, or no driveMode passed → nothing, so every existing caller and test is unchanged.

Names only, never a value — the notice goes through the same discipline as the rest of the module, asserted in the unit test.

Refusing to attach the server instead would break the feature for exactly the deployments most likely to need it (a container, a server, an instance somebody else runs). So this takes step 5's posture towards what the engine's schema cannot carry: pass it, and refuse to be silent about it.

Why not upstream instead

It probably should be, and this does not block that: the Claude CLI's --mcp-config accepts a file path, so cli-runtime.js could write the JSON to a mode-0600 temp file and pass the path. Worth an issue on edspencer/herdctl alongside #445; I have not filed one. Until it exists, an instance on batch deserves to know.

Note the exposure is not specific to declared servers — a host server inherited under claude.mcpServers: host with an env block is passed the same way. This warns only about the declared ones, because those are the ones a user was told to hand a token to.

Tests

Server 1846 → 1849 (+3, +1 file), web 941 unchanged. env -u NODE_ENV npm test green; every fixture synthetic, the token exists only in the two files that assert on it, and nothing here starts an MCP server.

npm run typecheck fails on reapChatSession in herdctl.ts — @herdctl/core@5.29.1 installed against a declared ^5.31.0, present on main untouched, and it also blocks local E2E. CI installs fresh.

🤖 Generated with Claude Code

[cloudflare-workers-and-pages]

Deploying paddock with    Cloudflare Pages

Latest commit:	d31d71c
Status:	✅  Deploy successful!
Preview URL:	https://3e7daec2.paddock-7u2.pages.dev
Branch Preview URL:	https://feat-691-mcp-argv-exposure.paddock-7u2.pages.dev

View logs