claude-code - 💡(How to fix) Fix [DOCS] MCP stdio docs omit session environment variables

Documentation Type

Missing documentation (feature not documented)

Documentation Location

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

Section/Topic

CLAUDECODE and CLAUDE_CODE_SESSION_ID entries in Environment variables, plus the "Option 3: Add a local stdio server" section in MCP configuration.

Current Documentation

The environment variables reference currently says:

CLAUDECODE | Set to 1 in subprocesses Claude Code spawns (Bash and PowerShell tools, tmux sessions, hook commands, status line commands). Use to detect when a script is running inside a subprocess spawned by Claude Code

It also says:

CLAUDE_CODE_SESSION_ID | Set automatically in Bash and PowerShell tool subprocesses and in hook command subprocesses to the current session ID. Matches the session_id field in the hook JSON input. Updated on /clear. Use to correlate scripts and external tools with the Claude Code session that launched them

The MCP page's stdio server section documents a different injected variable:

Claude Code sets CLAUDE_PROJECT_DIR in the spawned server's environment to the project root, so your server can resolve project-relative paths without depending on the working directory.

What's Wrong or Missing?

The v2.1.154 changelog says stdio MCP server subprocesses now receive CLAUDE_CODE_SESSION_ID and CLAUDECODE=1 in their environment, but the current documentation does not mention this MCP coverage.

That leaves two gaps:

A. The environment variable reference omits stdio MCP servers

CLAUDECODE lists Bash and PowerShell tools, tmux sessions, hook commands, and status line commands. CLAUDE_CODE_SESSION_ID lists Bash and PowerShell tool subprocesses and hook command subprocesses. Neither entry tells readers that stdio MCP server subprocesses receive the same variables.

B. The MCP stdio setup docs only mention CLAUDE_PROJECT_DIR

The main MCP page tells server authors about CLAUDE_PROJECT_DIR, but does not tell them they can also read CLAUDE_CODE_SESSION_ID for correlation or CLAUDECODE=1 to detect that the process was launched by Claude Code.

Suggested Improvement

Update the CLAUDECODE and CLAUDE_CODE_SESSION_ID entries to include stdio MCP server subprocesses.

Suggested CLAUDECODE addition:

Also set to 1 in stdio MCP server subprocesses launched by Claude Code.

Suggested CLAUDE_CODE_SESSION_ID addition:

Also set automatically in stdio MCP server subprocesses, so local MCP servers can correlate their logs, traces, or external side effects with the Claude Code session that launched them.

Also add a short note to the MCP stdio server section near the CLAUDE_PROJECT_DIR paragraph:

In Claude Code v2.1.154 and later, stdio MCP server subprocesses also receive CLAUDE_CODE_SESSION_ID and CLAUDECODE=1. Use CLAUDE_CODE_SESSION_ID to correlate server logs with the launching Claude Code session, and CLAUDECODE to detect that your server is running under Claude Code.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

Total scope: 2 pages affected

Version context: v2.1.154 changelog entry:

Stdio MCP server subprocesses now receive CLAUDE_CODE_SESSION_ID and CLAUDECODE=1 in their environment