From 0c0d88d90b2878e34126737ef9218f9e7e3dec3e Mon Sep 17 00:00:00 2001
From: Gal Zahavi <38544478+galz10@users.noreply.github.com>
Date: Thu, 14 May 2026 14:23:38 -0700
Subject: [PATCH] =?UTF-8?q?docs(extensions):=20clarify=20env=20var=20sanit?=
 =?UTF-8?q?ization=20policy=20for=20MCP=20and=20ext=E2=80=A6=20(#22854)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-authored-by: Jack Wotherspoon <jackwoth@google.com>
Co-authored-by: Jenna Inouye <jinouye@google.com>
---
 docs/extensions/reference.md          | 16 ++++++++++++++++
 docs/extensions/writing-extensions.md |  7 +++++++
 docs/tools/mcp-server.md              | 27 ++++++++++++++++++++++++---
 3 files changed, 47 insertions(+), 3 deletions(-)

diff --git a/docs/extensions/reference.md b/docs/extensions/reference.md
index 274cb61a78..576265f2b1 100644
--- a/docs/extensions/reference.md
+++ b/docs/extensions/reference.md
@@ -210,6 +210,22 @@ To update an extension's settings:
 gemini extensions config <name> [setting] [--scope <scope>]
 ```
 
+#### Environment variable sanitization
+
+For security reasons, sensitive environment variables are filtered out and not
+passed to extensions or MCP servers by default.
+
+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 allowlist them for use within the extension.
+
 ### Custom commands
 
 Provide [custom commands](../cli/custom-commands.md) by placing TOML files in a
diff --git a/docs/extensions/writing-extensions.md b/docs/extensions/writing-extensions.md
index f2dc730c29..0ad0440dff 100644
--- a/docs/extensions/writing-extensions.md
+++ b/docs/extensions/writing-extensions.md
@@ -159,6 +159,13 @@ 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,
+> sensitive environment variables are filtered out and not passed to extensions
+> or MCP servers by default. 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.
diff --git a/docs/tools/mcp-server.md b/docs/tools/mcp-server.md
index d9d8835c8c..e72089b1eb 100644
--- a/docs/tools/mcp-server.md
+++ b/docs/tools/mcp-server.md
@@ -221,8 +221,10 @@ 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*`,
@@ -232,7 +234,8 @@ 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.
 
@@ -247,6 +250,24 @@ specific data with that server.
 > (for example, `"MY_KEY": "$MY_KEY"`) to securely pull the value from your host
 > environment at runtime.
 
+**Example: Passing a GitHub Token securely to the
+[official GitHub MCP server](https://github.com/github/github-mcp-server) via
+`mcp_config.json`**
+
+```json
+{
+  "mcpServers": {
+    "github": {
+      "command": "npx",
+      "args": ["-y", "@github/github-mcp-server"],
+      "env": {
+        "GITHUB_PERSONAL_ACCESS_TOKEN": "$GITHUB_PERSONAL_ACCESS_TOKEN"
+      }
+    }
+  }
+}
+```
+
 ### OAuth support for remote MCP servers
 
 Gemini CLI supports OAuth 2.0 authentication for remote MCP servers using SSE or