Merge pull request #5293 from modelcontextprotocol/v2/fix/3986-get-env-mask-secrets

fix(everything): get-env masks credential-like values by default

Author: cliffhall

.changeset/get-env-mask-secrets.md

@@ -0,0 +1,5 @@
+---
+"@modelcontextprotocol/server-everything": minor
+---
+
+`get-env` now masks the values of credential-like environment variables (names with a `KEY`, `TOKEN`, `SECRET`, `PASSWORD`, `PASSWD`, `CREDENTIAL`, `AUTH` or `COOKIE` segment) as `"<redacted>"`. Set `GET_ENV_INCLUDE_SECRETS=1` to return every value unmasked.

src/everything/README.md

@@ -13,6 +13,8 @@ This MCP server attempts to exercise all the features of the MCP protocol. It is
 
 A complete list of the registered MCP primitives and other protocol features demonstrated can be found in the [Server Features](docs/features.md) document.
 
+The `get-env` tool returns the server's environment variables, but masks the value of any credential-like name (a `KEY`, `TOKEN`, `SECRET`, `PASSWORD`, `PASSWD`, `CREDENTIAL`, `AUTH` or `COOKIE` segment, such as `OPENAI_API_KEY`) as `"<redacted>"`. To see every value unmasked while debugging, start the server with `GET_ENV_INCLUDE_SECRETS=1` (or `true`). Leave it unset otherwise: with it set, every credential in the server's environment reaches the model's context.
+
 ## Protocol versions
 
 The server serves both protocol eras, over stdio and Streamable HTTP, from one process:

src/everything/__tests__/tools.test.ts

@@ -5,7 +5,8 @@
  * to the client (sampling, elicitation, roots), the task tools, logging,
  * subscriptions and gzip each have their own file.
  */
-import { afterEach, describe, expect, it } from "vitest";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { INCLUDE_SECRETS_VAR, REDACTED } from "../tools/get-env.js";
 import { MCP_TINY_IMAGE } from "../tools/get-tiny-image.js";
 import {
   connect,
@@ -69,18 +70,92 @@ describe("get-sum", () => {
 });
 
 describe("get-env", () => {
-  it("returns the whole server process environment as JSON", async () => {
-    // Characterization: every variable is returned, secrets included. This
-    // is the tool's documented purpose (debugging server configuration).
-    process.env.EVERYTHING_TEST_VAR = "test-value";
-    try {
-      const result = await call("get-env");
-      const env = JSON.parse(textOf(contentOf(result)[0]));
-      expect(env.EVERYTHING_TEST_VAR).toBe("test-value");
-      expect(env.PATH).toBe(process.env.PATH);
-    } finally {
-      delete process.env.EVERYTHING_TEST_VAR;
-    }
+  /** Calls `get-env` and parses the JSON object it returns. */
+  async function getEnv(): Promise<Record<string, string>> {
+    const result = await call("get-env");
+    return JSON.parse(textOf(contentOf(result)[0]));
+  }
+
+  beforeEach(() => {
+    // Mask by default even if the developer's shell sets the opt-in.
+    vi.stubEnv(INCLUDE_SECRETS_VAR, undefined);
+  });
+
+  afterEach(() => {
+    vi.unstubAllEnvs();
+  });
+
+  it("returns every variable name, with non-credential values intact", async () => {
+    vi.stubEnv("EVERYTHING_TEST_VAR", "test-value");
+    const env = await getEnv();
+    expect(env.EVERYTHING_TEST_VAR).toBe("test-value");
+    expect(env.PATH).toBe(process.env.PATH);
+    expect(Object.keys(env).sort()).toEqual(Object.keys(process.env).sort());
+  });
+
+  it.each([
+    "OPENAI_API_KEY",
+    "GITHUB_TOKEN",
+    "AWS_SECRET_ACCESS_KEY",
+    "DB_PASSWORD",
+    "MYSQL_PASSWD",
+    "GOOGLE_APPLICATION_CREDENTIAL",
+    "BASIC_AUTH",
+    "SESSION_COOKIE",
+    "key",
+    "my_Token",
+  ])("masks the value of the credential-like name %s", async (key) => {
+    vi.stubEnv(key, "planted-secret-9f3a1c");
+    const env = await getEnv();
+    expect(env[key]).toBe(REDACTED);
+    expect(JSON.stringify(env)).not.toContain("planted-secret-9f3a1c");
+  });
+
+  it.each([
+    "PWD",
+    "OLDPWD",
+    "KEYBOARD_LAYOUT",
+    "MONKEY",
+    "TOKENIZER_PATH",
+    "AUTHOR_NAME",
+    "PASSWORDLESS",
+  ])(
+    "leaves %s readable: no whole segment is a credential word",
+    async (key) => {
+      vi.stubEnv(key, "plain-value");
+      const env = await getEnv();
+      expect(env[key]).toBe("plain-value");
+    },
+  );
+
+  it.each(["1", "true", "TRUE", " yes ", "on"])(
+    "returns credential values unmasked when GET_ENV_INCLUDE_SECRETS=%j",
+    async (flag) => {
+      vi.stubEnv(INCLUDE_SECRETS_VAR, flag);
+      vi.stubEnv("OPENAI_API_KEY", "planted-secret-9f3a1c");
+      const env = await getEnv();
+      expect(env.OPENAI_API_KEY).toBe("planted-secret-9f3a1c");
+      expect(env[INCLUDE_SECRETS_VAR]).toBe(flag);
+    },
+  );
+
+  it.each(["", "0", "false", "no"])(
+    "keeps masking when GET_ENV_INCLUDE_SECRETS=%j",
+    async (flag) => {
+      vi.stubEnv(INCLUDE_SECRETS_VAR, flag);
+      vi.stubEnv("OPENAI_API_KEY", "planted-secret-9f3a1c");
+      const env = await getEnv();
+      expect(env.OPENAI_API_KEY).toBe(REDACTED);
+    },
+  );
+
+  it("says in its description that credential values are masked", async () => {
+    session ??= await connect();
+    const { tools } = await session.client.listTools();
+    const tool = tools.find((t) => t.name === "get-env");
+    expect(tool?.description).toContain(REDACTED);
+    expect(tool?.description).toContain(INCLUDE_SECRETS_VAR);
+    expect(tool?.inputSchema.properties ?? {}).toEqual({});
   });
 });
 

src/everything/docs/features.md

@@ -31,7 +31,7 @@ Each feature below is marked **both**, **2026-07-28** or **2025-era**. Roots, sa
 
 - `echo` (tools/echo.ts), **both**: Echoes the provided `message: string`. Uses Zod to validate inputs.
 - `get-annotated-message` (tools/get-annotated-message.ts), **both**: Returns a `text` message annotated with `priority` and `audience` based on `messageType` (`error`, `success`, or `debug`); can optionally include an annotated `image`.
-- `get-env` (tools/get-env.ts), **both**: Returns all environment variables from the running process as pretty-printed JSON text.
+- `get-env` (tools/get-env.ts), **both**: Returns all environment variables from the running process as pretty-printed JSON text. Every name is returned, but the value of a credential-like name (one with a `KEY`, `TOKEN`, `SECRET`, `PASSWORD`, `PASSWD`, `CREDENTIAL`, `AUTH` or `COOKIE` segment between underscores, in any case) is replaced with `"<redacted>"`. Set `GET_ENV_INCLUDE_SECRETS=1` (or `true`) in the server's environment to return every value unmasked, for debugging.
 - `get-header-params` (tools/get-header-params.ts), **both**: Returns its `region` argument and the `Mcp-Param-Region` HTTP header it arrived in. Its input and output schemas are plain JSON Schema 2020-12, and `region` carries `x-mcp-header: "Region"`, so a 2026-07-28 Streamable HTTP client mirrors it into that header and the server refuses a call whose header disagrees with the body (`-32020`). The header is `null` on stdio and for a 2025-era client.
 - `get-resource-links` (tools/get-resource-links.ts), **both**: Returns an intro `text` block followed by multiple `resource_link` items. For a requested `count` (1–10), alternates between dynamic Text and Blob resources using URIs from `resources/templates.ts`.
 - `get-resource-reference` (tools/get-resource-reference.ts), **both**: Accepts `resourceType` (`text` or `blob`) and `resourceId` (positive integer). Returns a concrete `resource` content block (with its `uri`, `mimeType`, and data) with surrounding explanatory `text`.

src/everything/docs/instructions.md

@@ -20,6 +20,7 @@ The server serves two protocol eras. A client on protocol version 2026-07-28 con
 ## Constraints & Limitations
 
 - `gzip-file-as-resource`: Max fetch size controlled by `GZIP_MAX_FETCH_SIZE` (default 10MB), timeout by `GZIP_MAX_FETCH_TIME_MILLIS` (default 30s), allowed domains by `GZIP_ALLOWED_DOMAINS`
+- `get-env`: Values of credential-like variable names (`*_KEY`, `*_TOKEN`, `*_SECRET`, `*_PASSWORD` and the like) come back as `"<redacted>"`; the server operator can set `GET_ENV_INCLUDE_SECRETS=1` to return them unmasked
 - Session resources are ephemeral and lost when the session ends; minted resources expire after ten minutes
 - Roots, sampling and logging are deprecated as of protocol version 2026-07-28, as is the HTTP+SSE transport
 

src/everything/docs/structure.md

@@ -168,7 +168,7 @@ src/everything
 - `get-annotated-message.ts`
   - Registers a `get-annotated-message` tool which demonstrates content-level annotations. Emits a primary `text` message with content `annotations` (`priority`, `audience`) that vary by `messageType` (`"error" | "success" | "debug"`), and optionally includes an annotated `image` (tiny PNG) when `includeImage` is true. All tools in this server include tool-level annotations (`readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`).
 - `get-env.ts`
-  - Registers a `get-env` tool that returns the current process environment variables as formatted JSON text; useful for debugging configuration.
+  - Registers a `get-env` tool that returns the current process environment variables as formatted JSON text; useful for debugging configuration. Values of credential-like names are masked as `"<redacted>"` unless `GET_ENV_INCLUDE_SECRETS` is set to a truthy value.
 - `get-header-params.ts`
   - Registers a `get-header-params` tool with JSON Schema 2020-12 input and output schemas whose `region` argument carries `x-mcp-header`; returns the argument and the `Mcp-Param-Region` header it arrived in.
 - `get-resource-links.ts`

src/everything/tools/get-env.ts

@@ -1,11 +1,50 @@
+/**
+ * The `get-env` tool: returns the server process's environment as JSON, for
+ * debugging how a client launched the server.
+ *
+ * A raw dump would put every credential in the server's environment into
+ * model context, on a tool annotated read-only that clients may auto-approve
+ * (#3986, #5130). So by default every variable NAME is returned, but the VALUE
+ * of a credential-looking name is replaced with a placeholder. A name counts
+ * as credential-looking when one of its underscore-separated segments is a
+ * credential word (`OPENAI_API_KEY`, `GITHUB_TOKEN`, `DB_PASSWORD`). Whole
+ * segments, not substrings, so `PWD`, `KEYBOARD` or `MONKEY` stay readable.
+ * The heuristic over-masks some names (`SSH_AUTH_SOCK`) and cannot see a
+ * secret stored under an innocuous name; it is a safer default, not a
+ * guarantee. Setting `GET_ENV_INCLUDE_SECRETS` to a truthy value restores the
+ * full, unmasked dump for debugging. It is read on each call, so it reflects
+ * the environment at call time.
+ */
 import { McpServer, CallToolResult } from "@modelcontextprotocol/server";
 
+/** The placeholder that replaces a masked value. */
+export const REDACTED = "<redacted>";
+
+/** The opt-in that returns every value unmasked. */
+export const INCLUDE_SECRETS_VAR = "GET_ENV_INCLUDE_SECRETS";
+
+/** Name segments that mark a variable as holding a credential. */
+const CREDENTIAL_SEGMENTS = new Set([
+  "KEY",
+  "TOKEN",
+  "SECRET",
+  "PASSWORD",
+  "PASSWD",
+  "CREDENTIAL",
+  "AUTH",
+  "COOKIE",
+]);
+
+/** Values of `GET_ENV_INCLUDE_SECRETS` that turn the opt-in on. */
+const TRUTHY = new Set(["1", "true", "yes", "on"]);
+
 // Tool configuration
 const name = "get-env";
 const config = {
   title: "Print Environment Tool",
   description:
-    "Returns all environment variables, helpful for debugging MCP server configuration",
+    "Returns all environment variables, helpful for debugging MCP server configuration. " +
+    `Values of credential-like names (a KEY, TOKEN, SECRET, PASSWORD, PASSWD, CREDENTIAL, AUTH or COOKIE name segment) are masked as "${REDACTED}" unless ${INCLUDE_SECRETS_VAR} is set to 1 or true in the server's environment.`,
   inputSchema: {},
   annotations: {
     readOnlyHint: true,
@@ -15,11 +54,55 @@ const config = {
   },
 };
 
+/**
+ * Whether an environment variable name looks like it holds a credential:
+ * one of its underscore-separated segments, compared case-insensitively, is
+ * a credential word.
+ *
+ * @param {string} key - The environment variable name.
+ * @returns {boolean} True when the value should be masked.
+ */
+export const isCredentialName = (key: string): boolean =>
+  key
+    .toUpperCase()
+    .split("_")
+    .some((segment) => CREDENTIAL_SEGMENTS.has(segment));
+
+/**
+ * Whether `GET_ENV_INCLUDE_SECRETS` is set to a truthy value
+ * (`1`, `true`, `yes` or `on`, case-insensitively).
+ *
+ * @param {NodeJS.ProcessEnv} env - The environment to read the opt-in from.
+ * @returns {boolean} True when values should be returned unmasked.
+ */
+export const includeSecrets = (env: NodeJS.ProcessEnv): boolean =>
+  TRUTHY.has((env[INCLUDE_SECRETS_VAR] ?? "").trim().toLowerCase());
+
+/**
+ * The environment as the tool returns it: every name, with the value of each
+ * credential-like name masked unless the opt-in is set.
+ *
+ * @param {NodeJS.ProcessEnv} env - The environment to render.
+ * @returns {Record<string, string | undefined>} The (possibly masked) copy.
+ */
+export const maskEnv = (
+  env: NodeJS.ProcessEnv,
+): Record<string, string | undefined> => {
+  if (includeSecrets(env)) return { ...env };
+  return Object.fromEntries(
+    Object.entries(env).map(([key, value]) => [
+      key,
+      isCredentialName(key) ? REDACTED : value,
+    ]),
+  );
+};
+
 /**
  * Registers the 'get-env' tool.
  *
- * The registered tool Retrieves and returns the environment variables
- * of the current process as a JSON-formatted string encapsulated in a text response.
+ * The registered tool returns the environment variables of the current
+ * process as a JSON-formatted string in a text response, with the values of
+ * credential-like names masked unless `GET_ENV_INCLUDE_SECRETS` is set.
  *
  * @param {McpServer} server - The McpServer instance where the tool will be registered.
  * @returns {void}
@@ -30,7 +113,7 @@ export const registerGetEnvTool = (server: McpServer) => {
       content: [
         {
           type: "text",
-          text: JSON.stringify(process.env, null, 2),
+          text: JSON.stringify(maskEnv(process.env), null, 2),
         },
       ],
     };