Skip to content

The agent that grows with you

fix(mcp): an unset ${VAR} env entry counts as absent; set values pass verbatim

Tekniumcaa1ea8d923b
diff --git a/tests/tools/test_mcp_stdio_env_unset_ref.py b/tests/tools/test_mcp_stdio_env_unset_ref.py
index b577f401219..e7d2006b7ed 100644
--- a/tests/tools/test_mcp_stdio_env_unset_ref.py
+++ b/tests/tools/test_mcp_stdio_env_unset_ref.py
@@ -1,21 +1,47 @@
-"""Stdio MCP launch env: an optional ``"VAR": "${VAR}"`` forward never reaches the child literally."""
+"""Stdio MCP launch env: an env entry rendered from one unset ``${VAR}`` counts as absent."""
+import json
+import subprocess
+import sys
from unittest.mock import patch
+USER_ENV = {"OPT_DIR": "${OPT_DIR}", "OPT_ENV": "${env:OPT_ENV}", "EMPTY": "${EMPTY}", "SET_DIR": "${SET_DIR}",
+ "PARTIAL": "${OPT_DIR}/bin", "PLAIN": "x", "XDG_CONFIG_HOME": "${OPT_CONFIG_HOME}",
+ "TERM": "${OPT_TERM}", "RESOLVED_LITERAL": "${ACTUAL_LITERAL}"}
+PARENT = {"PATH": "/usr/bin:/bin", "TERM": "parent-term", "XDG_CONFIG_HOME": "/parent/config", "SET_DIR": "/opt/set",
+ "EMPTY": "", "ACTUAL_LITERAL": "${STILL_UNSET}"}
-def test_unset_whole_placeholder_env_entry_is_dropped():
- """An optional ``"VAR": "${VAR}"`` forward never reaches the child as the literal
- placeholder: unset drops the key, set passes the value, partial refs keep today's text."""
- from tools.mcp_tool_config import _build_safe_env, _interpolate_env_vars
- user_env = {"OPT_DIR": "${OPT_DIR}", "OPT_ENV": "${env:OPT_ENV}", "SET_DIR": "${SET_DIR}",
- "PARTIAL": "${OPT_DIR}/bin", "PLAIN": "x", "XDG_CONFIG_HOME": "${OPT_CONFIG_HOME}"}
- parent = {"PATH": "/usr/bin", "SET_DIR": "/opt/set", "XDG_CONFIG_HOME": "/parent/config"}
- with patch.dict("os.environ", parent, clear=True):
- result = _build_safe_env(_interpolate_env_vars(user_env))
+def _rendered():
+ from tools.mcp_tool_config import _interpolate_env_vars
+ # Load renders once; connect renders again under the owner's scope.
+ return _interpolate_env_vars(_interpolate_env_vars({"command": sys.executable, "env": USER_ENV}))
- assert "OPT_DIR" not in result and "OPT_ENV" not in result
- assert "XDG_CONFIG_HOME" not in result # unset override does not fall back to the parent's value
- assert result["SET_DIR"] == "/opt/set"
+
+def test_unset_whole_ref_counts_as_absent_and_set_values_pass_verbatim():
+ from tools.mcp_tool_config import _build_safe_env
+
+ with patch.dict("os.environ", PARENT, clear=True):
+ result = _build_safe_env(_rendered()["env"])
+
+ assert not {"OPT_DIR", "OPT_ENV", "EMPTY"} & set(result)
+ assert result["XDG_CONFIG_HOME"] == "/parent/config" # as if the line weren't there
+ assert result["SET_DIR"] == "/opt/set" and result["PLAIN"] == "x"
assert result["PARTIAL"] == "${OPT_DIR}/bin"
- assert result["PLAIN"] == "x"
+ assert result["RESOLVED_LITERAL"] == "${STILL_UNSET}" # a set value is data, whatever it looks like
+
+
+def test_child_spawned_through_the_sdk_merge_sees_the_documented_env():
+ from mcp.client.stdio import get_default_environment
+ from tools.mcp_tool_transport import _stdio_launch
+
+ with patch.dict("os.environ", PARENT, clear=True):
+ command, env, _ = _stdio_launch(_rendered())
+ child_env = get_default_environment() | env # what mcp.client.stdio.stdio_client spawns with
+ probe = "import json, os; print(json.dumps(dict(os.environ)))"
+ seen = json.loads(subprocess.run([command, "-c", probe], env=child_env, capture_output=True, text=True,
+ check=True).stdout)
+
+ assert "OPT_DIR" not in seen and "EMPTY" not in seen
+ assert seen["TERM"] == "parent-term"
+ assert seen["RESOLVED_LITERAL"] == "${STILL_UNSET}"
diff --git a/tools/mcp_tool_config.py b/tools/mcp_tool_config.py
index 070d67bb99f..526b3e1875f 100644
--- a/tools/mcp_tool_config.py
+++ b/tools/mcp_tool_config.py
@@ -181,10 +181,19 @@ _CONTEXT_VAR_RESOLVERS = {
"workspaceFolderBasename": _workspace_basename, "pathSeparator": lambda: os.sep, "/": lambda: os.sep}
-def _is_unresolved_ref(value: Any) -> bool:
- """True when *value* is entirely one env ``${VAR}`` / ``${env:VAR}`` placeholder (not a context var)."""
- match = _ENV_VAR_PATTERN.fullmatch(value) if isinstance(value, str) else None
- return match is not None and match.group(1).strip() not in _CONTEXT_VAR_RESOLVERS
+class _RenderedStr(str):
+ """A config string after ``${...}`` rendering, carrying how it resolved, so later steps never
+ guess from text that may itself look like ``${...}``. ``missed``: some env reference was unset
+ (or empty) and kept its placeholder; a re-render (connect renders again under the owner's fresh
+ scope) retries from ``template``, while a fully resolved value is final. ``unset_ref``: the
+ template was one whole env reference that missed."""
+
+ def __new__(cls, text: str = "", template: Optional[str] = None, missed: bool = False, unset_ref: bool = False):
+ rendered = super().__new__(cls, text)
+ rendered.template = text if template is None else template
+ rendered.missed = missed
+ rendered.unset_ref = unset_ref
+ return rendered
def _build_safe_env(user_env: Optional[dict]) -> dict:
@@ -207,13 +216,12 @@ def _build_safe_env(user_env: Optional[dict]) -> dict:
if key in os.environ:
env[key] = os.environ[key]
if user_env:
- # A value that is still a whole ``${VAR}`` here was unset (or empty) at render time: the
- # key is left unset (baseline copy included) so a plugin can forward an optional var
- # without the child seeing the literal placeholder (servers that validate it refuse to start).
+ # An entry rendered from one whole ``${VAR}`` that is unset (or empty) counts as absent, so
+ # a plugin can forward an optional var without the child seeing the literal placeholder.
+ # The key keeps its baseline value, if any: the MCP SDK re-adds its own inherited set
+ # (PATH, HOME, TERM, ...) at spawn anyway, so popping here would not unset it.
for key, value in user_env.items():
- if _is_unresolved_ref(value):
- env.pop(key, None)
- else:
+ if not getattr(value, "unset_ref", False):
env[key] = value
from agent.delegation_context import delegated_child_subprocess_env
return delegated_child_subprocess_env(env)
@@ -546,13 +554,27 @@ def _packaged_npx_entry(command: str, args: list) -> Optional[tuple]:
def _interpolate_env_vars(value):
"""Recursively resolve ``${VAR}`` / Cursor ``${env:VAR}`` placeholders and context vars. Env
refs resolve from the active profile's secret scope when multiplexing (the routed profile's
- value, not another profile's in ``os.environ``). Unset vars keep the literal placeholder."""
+ value, not another profile's in ``os.environ``). Unset (or empty) vars keep the literal placeholder;
+ a templated string comes back as a ``_RenderedStr`` recording how it resolved."""
from agent.secret_scope import get_secret as _get_secret
if isinstance(value, str):
+ if isinstance(value, _RenderedStr) and not value.missed:
+ return value
+ template = getattr(value, "template", value)
+ missed = []
+
def _replace(m):
resolver = _CONTEXT_VAR_RESOLVERS.get(m.group(1).strip())
- return resolver() if resolver is not None else (_get_secret(_env_ref_name(m.group(1)), m.group(0)) or m.group(0))
- return _ENV_VAR_PATTERN.sub(_replace, value)
+ if resolver is not None:
+ return resolver()
+ resolved = _get_secret(_env_ref_name(m.group(1)), None)
+ if not resolved:
+ missed.append(m.group(0))
+ return resolved or m.group(0)
+ text = _ENV_VAR_PATTERN.sub(_replace, template)
+ if text == template and not missed:
+ return value
+ return _RenderedStr(text, template, missed=bool(missed), unset_ref=missed == [template])
if isinstance(value, dict):
return {k: _interpolate_env_vars(v) for k, v in value.items()}
if isinstance(value, list):
diff --git a/website/docs/developer-guide/plugins/index.md b/website/docs/developer-guide/plugins/index.md
index 3de41889644..b612ee737bf 100644
--- a/website/docs/developer-guide/plugins/index.md
+++ b/website/docs/developer-guide/plugins/index.md
@@ -105,9 +105,10 @@ Values declared in portable MCP `env` are visible package data, not a secret
storage mechanism. Do not place credentials in `mcp.json`.
To pass a user's variable through to a stdio server (Hermes otherwise hands MCP
servers a filtered environment), declare it as `"NAME": "${NAME}"`. The value
-comes from the user's shell or profile `.env`; when the variable is unset, Hermes
-leaves `NAME` out of the server's environment rather than passing the literal
-`${NAME}`, so optional variables are safe to forward.
+comes from the user's shell or profile `.env`; when the variable is unset (or
+empty), the entry is treated as if it weren't there: the server doesn't get the
+literal `${NAME}`, and `NAME` keeps whatever value the server would have without
+that line (usually unset). Optional variables are safe to forward.
The current portable subset supports stdio and Streamable HTTP MCP entries.
Portable `streamable-http` entries are routed through Hermes' existing native
diff --git a/website/docs/reference/mcp-config-reference.md b/website/docs/reference/mcp-config-reference.md
index 3613cc9fb54..86b311a1a30 100644
--- a/website/docs/reference/mcp-config-reference.md
+++ b/website/docs/reference/mcp-config-reference.md
@@ -83,7 +83,7 @@ mcp_servers:
GITHUB_PERSONAL_ACCESS_TOKEN: "${env:GITHUB_TOKEN}" # same as "${GITHUB_TOKEN}"
```
-Values resolve from the active profile's secret scope (falling back to the process environment), so put the secret in `~/.hermes/.env`. An unset (or empty) variable keeps its literal placeholder, with two exceptions. A stdio server's `env` entry whose whole value is one reference (`GHIDRA_INSTALL_DIR: "${GHIDRA_INSTALL_DIR}"`) is left out of the server's environment instead, so a config or plugin can forward an optional variable and the server sees it as unset rather than as the text `${GHIDRA_INSTALL_DIR}`; a value that only contains a reference (`"${OPT_DIR}/bin"`) is still passed with the placeholder. And in a remote server's `url` or `headers`: sending a literal `${VAR}` there is a guaranteed 401 that reads as a bad credential, so the connect fails closed instead, with the variable named in the server's status (`MCP server 'name': ${VAR} in url/headers is not set in this profile's .env or secret source`). Fix the profile's `.env` (or its secret source); the next connect attempt renders the reference afresh.
+Values resolve from the active profile's secret scope (falling back to the process environment), so put the secret in `~/.hermes/.env`. An unset (or empty) variable keeps its literal placeholder, with two exceptions. A stdio server's `env` entry whose whole value is one reference to an unset variable (`GHIDRA_INSTALL_DIR: "${GHIDRA_INSTALL_DIR}"`) is treated as if the entry weren't there: the server doesn't get the placeholder, and the variable keeps whatever value the server would have without that line (usually unset; basics such as `PATH`, `HOME` or `TERM` keep the value Hermes passes every server). So a config or plugin can forward an optional variable safely. A variable that is set is always passed as is, even if its value happens to look like `${...}`; a value that only contains a reference (`"${OPT_DIR}/bin"`) is still passed with the placeholder. And in a remote server's `url` or `headers`: sending a literal `${VAR}` there is a guaranteed 401 that reads as a bad credential, so the connect fails closed instead, with the variable named in the server's status (`MCP server 'name': ${VAR} in url/headers is not set in this profile's .env or secret source`). Fix the profile's `.env` (or its secret source); the next connect attempt renders the reference afresh.
### Context variables