Environment Variables & Secrets

Environment variable management for MCP servers requires discipline. The ${VAR} syntax in settings.json resolves at server startup from the shell environment where Gemini CLI was launched. This means your shell profile (.bashrc, .zshrc, .env) must have the values set before you start Gemini. A common failure mode: developer adds a new MCP server config, pushes it to the team, but nobody else has the required environment variables set. The server silently fails to connect.

For team environments, document required environment variables in GEMINI.md alongside the MCP server configuration. Create a .env.example file listing every variable MCP servers need, with placeholder values. Better yet, use a secrets manager (1Password CLI, Doppler, HashiCorp Vault) and source secrets into your shell before launching Gemini CLI. The pattern: eval $(op signin) && gemini ensures credentials are fresh and scoped to the session.

# .env.example — document every MCP server secret
GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxx
DATABASE_URL=postgresql://user:pass@localhost:5432/mydb
INTERNAL_API_KEY=sk-xxxxxxxxxxxxxxxx

# Launch pattern with 1Password CLI
eval $(op signin) && \
  export GITHUB_TOKEN=$(op read "op://Dev/GitHub/token") && \
  export DATABASE_URL=$(op read "op://Dev/Postgres/url") && \
  gemini

# Or use direnv with .envrc (auto-loads per directory)
# .envrc
export GITHUB_TOKEN=$(op read "op://Dev/GitHub/token")
export DATABASE_URL="postgresql://localhost:5432/myproject"