claude-code - 💡(How to fix) Fix [DOCS] `CLAUDE_CODE_SHELL_PREFIX` docs omit stdio MCP argument-preservation guidance [1 participants]

Documentation Type

Unclear/confusing documentation

Documentation Location

https://code.claude.com/docs/en/env-vars

Section/Topic

CLAUDE_CODE_SHELL_PREFIX in Environment variables, plus the stdio MCP server startup guidance in MCP configuration

Current Documentation

The env vars page currently says:

CLAUDE_CODE_SHELL_PREFIX | Command prefix that wraps shell commands Claude Code spawns: Bash tool calls, hook commands, and stdio MCP server startup commands. Useful for logging or auditing. Example: setting /path/to/logger.sh runs each command as /path/to/logger.sh <command>

The MCP docs currently say:

claude mcp add [options] <name> -- <command> [args...]

and later:

Command arrays must match exactly - both the command and all arguments in the correct order

What's Wrong or Missing?

The docs say that CLAUDE_CODE_SHELL_PREFIX wraps stdio MCP startup commands, but they do not explain the argument-forwarding contract for that wrapper.

That omission matters because stdio MCP servers are configured as exact command/argument arrays, and v2.1.128 fixed a bug where those arguments could be corrupted when the prefix was set and an argument contained spaces or shell metacharacters.

Today the docs do not tell readers:

• whether the original stdio command and its arguments are preserved as separate argv entries
• how a logging/auditing wrapper should safely re-exec the wrapped command
• that rebuilding the command as a shell string can break MCP server startup or exact serverCommand matching

Suggested Improvement

Add a short note to CLAUDE_CODE_SHELL_PREFIX and cross-reference it from the stdio MCP section.

Suggested content:

When CLAUDE_CODE_SHELL_PREFIX wraps a stdio MCP server startup command, the original command and arguments should be forwarded without flattening or re-quoting them. If your wrapper re-executes the command, pass the original argv through exactly.

Example wrapper guidance:

#!/usr/bin/env bash
# log the command here if needed
exec "$@"

Also add a warning not to use eval, $*, or unquoted expansions for wrappers that may handle arguments containing spaces or shell metacharacters.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

Total scope: 2 pages affected

Relevant release note: v2.1.128 fixed corrupted stdio MCP arguments when CLAUDE_CODE_SHELL_PREFIX was set and an argument contained spaces or shell metacharacters.