docs(extensions): clarify env var sanitization policy for MCP and ext…

docs/extensions/reference.md

@@ -209,6 +209,16 @@ To update an extension's settings:
 gemini extensions config <name> [setting] [--scope <scope>]
 ```
 
+#### Environment Variable Sanitization
+
+For security reasons, the host's `process.env` is aggressively stripped before the extension or its MCP servers are spawned. 
+
+Extensions **will not** inherit the user's full shell environment variables. They will only have access to:
+1. Standard safe variables (e.g., `HOME`, `PATH`, `TMPDIR`).
+2. Variables explicitly declared and requested in the `gemini-extension.json` manifest via the `settings` array (using the `envVar` property).
+
+If your extension requires specific environment variables (like an API key, custom host, or config path), you **must** declare them in the `settings` array so the CLI can whitelist and inject them into the extension's isolated process.
+
 ### Custom commands
 
 Provide [custom commands](../cli/custom-commands.md) by placing TOML files in a

docs/extensions/writing-extensions.md

@@ -159,6 +159,8 @@ When a user installs this extension, Gemini CLI will prompt them to enter the
 `sensitive` is true) and injected into the MCP server's process as the
 `MY_SERVICE_API_KEY` environment variable.
 
+> **Important (Environment Variable Sanitization):** For security reasons, the host `process.env` is aggressively stripped before the extension or its MCP servers are spawned. Extensions will *only* have access to environment variables that are explicitly declared in the `settings` array using the `envVar` property, plus a few standard safe variables. Do not expect host environment variables to be available otherwise.
+
 ## Step 4: Link your extension
 
 Link your extension to your Gemini CLI installation for local development.

docs/tools/mcp-server.md

@@ -219,8 +219,9 @@ spawning MCP server processes.
 #### Automatic redaction
 
 By default, the CLI redacts sensitive environment variables from the base
-environment (inherited from the host process) to prevent unintended exposure to
-third-party MCP servers. This includes:
+environment (inherited from the host process). This prevents the accidental leakage
+of sensitive host environment variables (like AWS keys or GitHub tokens) to arbitrary
+third-party MCP servers that might execute malicious code or log your environment. This includes:
 
 - Core project keys: `GEMINI_API_KEY`, `GOOGLE_API_KEY`, etc.
 - Variables matching sensitive patterns: `*TOKEN*`, `*SECRET*`, `*PASSWORD*`,
@@ -230,7 +231,7 @@ third-party MCP servers. This includes:
 #### Explicit overrides
 
 If an environment variable must be passed to an MCP server, you must explicitly
-state it in the `env` property of the server configuration in `settings.json`.
+state it in the `env` property of the server configuration in `settings.json` (or `mcp_config.json` if configuring standard MCP clients or remote skills).
 Explicitly defined variables (including those from extensions) are trusted and
 are **not** subjected to the automatic redaction process.
 
@@ -242,6 +243,22 @@ specific data with that server.
 > Instead, use environment variable expansion (e.g., `"MY_KEY": "$MY_KEY"`) to
 > securely pull the value from your host environment at runtime.
 
+**Example: Passing a GitHub Token securely via `mcp_config.json`**
+
+```json
+{
+  "mcpServers": {
+    "github": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-github"],
+      "env": {
+        "GITHUB_TOKEN": "$GITHUB_TOKEN"
+      }
+    }
+  }
+}
+```
+
 ### OAuth support for remote MCP servers
 
 The Gemini CLI supports OAuth 2.0 authentication for remote MCP servers using