Unclear Whether --session-tunnel is meant for direct use or is hidden for hosts only is not stated.
What
claude mcp serve runs Claude Code as an MCP server, so another program can use its tools. New options appear only when CLAUDE_CODE_REMOTE is true and CLAUDE_CODE_ENVIRONMENT_KIND is empty; ordinary local installs never see them and stay on stdio with raw results.
--transport <transport>(stdio or http, default stdio),--port <port>,--result-format <format>(raw or rendered) and--session-tunnel.- With http the server starts listening on the network.
--portwithout http fails withError: --port only applies to --transport http, and http must come right afterclaude mcp serve. --session-tunnelneeds--transport httpand--port 28471, and reads one line of JSON on standard input withsession_id,session_tokenandapi_base_url. It dials a tunnel that relays tool calls and exits when the token expires or policy refuses. A bad envelope exits withEX_CONFIG.- With
--session-tunnel, Claude Code can also read one JSON line from a file descriptor (a numbered input channel) holdingoauth_tokenandagent_proxy_token. A non-empty sign-in token is installed andCLAUDE_CODE_OAUTH_TOKEN_FILE_DESCRIPTORis cleared. - A relay token can come from
CCR_AGENT_PROXY_TOKEN_FILE_DESCRIPTOR, refused unless it is a descriptor number of 3 or more and the process has no IPC channel. In a tool container with no session id, the proxy uses that oragent_proxy_token, uses the session idtool-container, and is disabled with a logged message if neither is given. - Structured tool output objects are returned only when
CLAUDE_CODE_MCP_SERVE_TOOL_OUTPUTis on, with allow and deny rules fromCLAUDE_CODE_MCP_SERVE_SETTINGS. Otherwise requests are refused with a message that it is not on. - A call can become a request for a person's approval, using
anthropic/permissionAsks,anthropic/returnToolOutputandanthropic/toolHostInterface. New served tools includeRunMonitorCommand,StageFileandPlaceFiles. - As a tool-server daemon, hooks from settings or plugins are dropped with a warning, and in http mode the file watcher does not start. An HTTP hook that cannot be asked on certain events gives a 'Refused, and a retry will be too' message.
Why
This lets remote or hosted setups run Claude Code's tools on a machine through a tunnel. Most users will not see it, since it only appears in cloud-remote sessions.
Names in the bundle--session-tunnelclaude mcp serve
--transport
Recipes modified, high confidence
`<target>` below is an [ad-hoc target](/docs/2026-07-28/tools/inspector/configuration#ad-hoc-targets): a positional stdio command, or `--server-url <url> --transport http`.see the edit
--transport
TUI client modified, high confidence
The TUI also takes the [shared server-selection flags](/docs/2026-07-28/tools/inspector/configuration#shared-server-selection-flags) (`--server-url`, `--transport`, `--header`, `-e`, `--cwd`) plus `--protocol-era` for an ad-hoc server, and…see the edit
--transport
Recipes modified, high confidence
`<target>` below is an [ad-hoc target](/docs/draft/tools/inspector/configuration#ad-hoc-targets): a positional stdio command, or `--server-url <url> --transport http`.see the edit
--transport
TUI client modified, high confidence
The TUI also takes the [shared server-selection flags](/docs/draft/tools/inspector/configuration#shared-server-selection-flags) (`--server-url`, `--transport`, `--header`, `-e`, `--cwd`) plus `--protocol-era` for an ad-hoc server, and the …see the edit
Something disagreesSomething we can check disagrees with this entry, or the writer said they could not settle it.
The writer flagged doubt
Whether `--session-tunnel` is meant for direct use or is hidden for hosts only is not stated.
Anthropic's documentation agrees
--transport on Recipes
Anthropic's release notes agree
Fixed claude mcp serve background Bash results not naming the output file, and its tool description promising a notification that never…
The name it cites is new in this build
New in this build: --session-tunnel