feat: Support environment variable substitution in MCP server headers

[ksprashu]

What would you like to be added?

The Gemini CLI should support environment variable substitution within the headers values of the mcpServers configuration. This would allow users to store sensitive tokens securely in their environment and reference them in the configuration.

Eg:

  {
    "mcpServers": {
      "myApiServer": {
        "httpUrl": "https://api.example.com/",
        "headers": {
          "Authorization": "Bearer $MY_API_TOKEN"
        }
      }
    }
  }

The CLI should replace $MY_API_TOKEN with the value of the MY_API_TOKEN environment variable before sending the request. It should support both $VAR and ${VAR} syntax.

Why is this needed?

Currently, when configuring an MCP server in settings.json, any values in the headers object are treated as literal strings. This means sensitive data, like bearer tokens or API keys, must be hardcoded into the configuration file, which is a security risk.

Additional context

The current alternative is to hardcode the token, which is not secure. Another alternative would be to use a local script as a proxy, but this adds unnecessary complexity for a common use case.

[ksprashu]

I'm noting some inconsistency.
This actually seemed to work in the latest v0.1.15 release
However when I checked the source code, there was no different in this module between 0.1.14 and 0.1.15
Can someone please triage this and confirm?

[DinoChiesa]

Please approve and merge that commit!

[DinoChiesa]

I retro-fitted that commit into my 0.1.17 source tree, and it worked for remote HTTP Servers.

[ksprashu]

Thanks @DinoChiesa for checking this.

I did some investigation on the latest source and Gemini CLI found this.

The key file here is packages/cli/src/config/settings.ts.

When the Gemini CLI starts, it calls the loadSettings function. This function reads your settings.json from the user, workspace, and system directories. As it parses each file, it immediately processes the content to substitute any environment variables.

This is done by the resolveEnvVarsInObject function, which recursively scans through your entire settings object. When it finds a string value, it uses resolveEnvVarsInString to perform the substitution.

Here is the exact code that finds and replaces variables like $GITHUB_PERSONAL_ACCESS_TOKEN:

    1 // packages/cli/src/config/settings.ts
    2
    3 function resolveEnvVarsInString(value: string): string {
    4   const envVarRegex = /\$(?:(\w+)|{([^}]+)})/g; // Find $VAR_NAME or ${VAR_NAME}
    5   return value.replace(envVarRegex, (match, varName1, varName2) => {
    6     const varName = varName1 || varName2;
    7     if (process && process.env && typeof process.env[varName] === 'string') {
    8       return process.env[varName]!;
    9     }
   10     return match;
   11   });
   12 }
   13
   14 function resolveEnvVarsInObject<T>(obj: T): T {
   15   // ... (recursively calls resolveEnvVarsInString on all string values)
   16 }
   17
   18 // In the main loadSettings function:
   19 // ...
   20 // workspaceSettings = resolveEnvVarsInObject(parsedWorkspaceSettings);
   21 // ...

So, by the time your mcpServers configuration is passed to the rest of the application, the Authorization header has already been updated to contain the actual value of your GITHUB_PERSONAL_ACCESS_TOKEN.

Given this, maybe my patch is redundant.

Again, I'd love confirmation before I bring in a PR.