Every agent's model. One place. Codex on DeepSeek, Claude Code on Kimi, from the menu bar.
package library
// References to environment variables in a server's headers and
// environment (#1250). The library writes one as ${NAME} and keeps it as
// written; each agent is given it in the syntax that agent reads, so a
// token can stay in the environment and out of every agent's config. An
// agent that reads no reference where the server has one isn't given the
// server: written as it is, the agent would send "${NAME}" itself, and
// written with the value, the token would be in its file after all.
import (
"encoding/json"
"errors"
"fmt"
"maps"
"os"
"regexp"
"slices"
"strings"
)
// envRef is a reference as the library writes one: ${NAME}.
var envRef = regexp.MustCompile(`\$\{([A-Za-z_][A-Za-z0-9_]*)\}`)
// refSyntax is how an agent spells a reference in a value.
type refSyntax int
const (
// refNone: the agent reads no reference there
refNone refSyntax = iota
// refDollar: ${NAME}, as the library writes it
refDollar
// refOpenCode: {env:NAME}
refOpenCode
// refCursor: ${env:NAME}
refCursor
// refCodex: Codex's own keys, which name the variable; a value can only
// be the variable whole (Authorization's Bearer aside)
refCodex
// refGoose: ${NAME} in a header, each name listed in env_keys; a
// command's variable only through env_keys, under its own name
refGoose
// refDsh: a !!js expression reading process.env (dshRef)
refDsh
)
// envSyntax is how the agent reads a reference in a remote server's
// headers and in a command's environment.
type envSyntax struct{ headers, env refSyntax }
// refsOf is how each agent reads a reference, as its own source or docs
// say. A refNone is an agent magpie found no reference in, so a server
// that has one is left out for it.
func (f *mcpFile) refsOf() envSyntax {
if f.Literal {
return envSyntax{}
}
switch f.Format {
case fmtClaude:
// Claude Code expands ${NAME} (and ${NAME:-default}) in url,
// headers, command, args and env of every scope's servers, the
// user's in ~/.claude.json as well as a project's .mcp.json
// (code.claude.com/docs/en/mcp, "Environment variable expansion";
// 2.1.293's z4t expands the user and local scopes too, and tried:
// a user-scope server got the token, an unset one is warned of and
// sent as written). Toward a remote server it reads Anthropic's,
// the clouds' and the package registries' own credential variables
// as empty. Droid 0.231 expands ${NAME} in env and headers of
// ~/.factory/mcp.json and won't connect with one unset
// (docs.factory.com/cli/configuration/mcp). CodeBuddy Code, and
// WorkBuddy, whose servers its CodeBuddy engine runs, expand ${NAME}
// in command, args, cwd, env, url and headers of every scope's
// servers and warn of one unset (McpConfigEnvExpandService,
// @tencent-ai/codebuddy-code 2.162.0).
return envSyntax{refDollar, refDollar}
case fmtGrok:
// Grok Build expands ${NAME} and ${NAME:-default} in url, command,
// args, env and headers of [mcp_servers.*] as it loads config.toml
// (~/.grok/docs/user-guide/07-mcp-servers.md, 1.0.46)
return envSyntax{refDollar, refDollar}
case fmtCodex:
// codex-rs/config/src/mcp_types.rs (RawMcpServerConfig):
// bearer_token_env_var sends Authorization: Bearer <its value>,
// env_http_headers sends a header whole from a variable, and a
// command's env_vars passes a variable of Codex's own environment
// on by its name; http_headers and env are sent as written
return envSyntax{refCodex, refCodex}
case fmtOpenCode:
// OpenCode puts in {env:NAME} anywhere in its config file as it
// reads it (packages/opencode/src/config/config.ts, load), "" for
// one unset; MiMo Code reads opencode.json the same way
return envSyntax{refOpenCode, refOpenCode}
case fmtCursor:
// Cursor reads ${env:NAME} in url, headers, command, args and env
// (cursor.com/docs/context/mcp, "Config interpolation"; cursor-agent
// 2026.10.01's mcp-agent-exec expands every string of mcp.json the
// same way). A command gets only HOME, LOGNAME, PATH, SHELL, TERM
// and USER of Cursor's own environment besides its env.
return envSyntax{refCursor, refCursor}
case fmtGemini:
// Gemini CLI expands $NAME, ${NAME} and ${NAME:-default} in every
// string of settings.json as it loads the file, and saves the file
// as written (packages/cli/src/config/settings.ts loadSettings ->
// resolveEnvVarsInObject; envVarResolver.ts resolveEnvVarsInString;
// read in the 0.62.0 bundle)
return envSyntax{refDollar, refDollar}
case fmtCrush:
// Crush resolves $NAME and ${NAME} in an MCP server's headers and
// env as it connects (charmbracelet/crush v0.39.3
// internal/config/resolve.go ResolveValue, config.go
// MCPConfig.ResolvedHeaders / ResolvedEnv); an unset one is sent
// empty
return envSyntax{refDollar, refDollar}
case fmtCopilot:
// Copilot CLI: "Supports $VAR, ${VAR}, and ${VAR:-default}
// expansion" for env, "Supports variable expansion" for headers
// (github/docs, copilot cli-command-reference.md); a command
// inherits only PATH (add-mcp-servers.md)
return envSyntax{refDollar, refDollar}
case fmtGoose:
// Goose 1.52.0 crates/goose/src/agents/extension.rs: resolve puts
// ${NAME} into headers (and uri) from envs and env_keys only, never
// straight from its environment; envs are given to a command as
// written. merge_environments reads each env_keys name from the
// environment (upper-cased), else from Goose's keyring.
return envSyntax{refGoose, refGoose}
case fmtPi:
// pi-mcp-adapter 5.1 reads ${NAME}, $env:NAME and {env:NAME} in a
// server's headers and env (utils.ts interpolateEnvVars,
// docs/servers.md); a file pi-mcp-extension reads too is Literal
return envSyntax{refDollar, refDollar}
case fmtPiNative:
// Pi 0.99+ resolves $NAME and ${NAME} in a server's headers and env
// as it connects, and leaves a server with an unset one unconnected
// (pi 1.0.4 dist/core/resolve-config-value.js,
// dist/extensions/mcp/runtime.js createDefaultTransport). OmO
// (senpi 2026.10.10) reads ${NAME} and ${NAME:-default} anywhere in
// its mcp.json (dist/core/extensions/builtin/mcp/config.js
// interpolateConfig); its command gets only HOME, LOGNAME, PATH,
// SHELL, TERM and USER besides its env (docs/mcp.md)
return envSyntax{refDollar, refDollar}
case fmtOmp:
// omp 18.6 expands ${NAME} and ${NAME:-default} in mcp.json as it
// loads it (src/discovery/helpers.ts expandEnvVarsDeep); Qoder CLI
// 1.1.64 expands $NAME, ${NAME} and ${NAME:-default} in settings.json
// and again in a server's headers, url and env as it connects
// (bundle/qodercli.js); AtomCode 5.2.1 expands ${NAME} in a server's
// url, headers, command, args and env, "" for an unset one
// (crates/atomcode-capabilities/src/mcp/config.rs expand_env_vars)
return envSyntax{refDollar, refDollar}
case fmtHermes:
// Hermes reads ${NAME} (and ${env:NAME}) in config.yaml's
// mcp_servers, ~/.hermes/.env loaded first, and won't connect a
// remote server that still has one unset (tools/mcp_tool_config.py
// _interpolate_env_vars, _require_rendered_remote)
return envSyntax{refDollar, refDollar}
case fmtCommandCode:
// Command Code 1.73 reads ${NAME} and ${NAME:-default} in a server's
// headers and env, and refuses one unset (dist/cli.mjs
// resolveEnvPlaceholders)
return envSyntax{refDollar, refDollar}
case fmtDsh:
// DeepSeek Harness evaluates a YAML !!js value of a plugin's config
// as it activates the row, with its own process in reach (dsh
// 0.2.0-rc.2: cordis-plugin-include's entryListSchema reads the
// tag, quoted or not; cordis-plugin-loader's interpolate evaluates
// it all through the config). dsh-mcp-client's README gives a
// command GITHUB_TOKEN: !!js process.env.GITHUB_TOKEN, and a command
// needs it so: it inherits dsh's environment without the
// credential-shaped names (dsh-subprocess scrubbedParentEnv). Tried
// (#1435): the server got the token, and with the variable unset
// dsh left the server out, saying its config is invalid.
return envSyntax{refDsh, refDsh}
}
// None: Claude Desktop gives a command its env as written and only
// HOME, LOGNAME, PATH, SHELL, TERM and USER of its own (2.7032's app.asar
// Jv; ${...} is expanded for organisations' plugin servers only).
// Antigravity parses mcp_config.json and sends what it says
// (agy 1.2.16: no os.Expand on its MCP path; antigravity.google/docs/mcp
// names none). Kimi reads mcp.json with json.loads and passes headers
// and env on (kimi_cli/cli/__init__.py, fastmcp mcp_config.py). Cline's
// settings are plain strings (@cline/core 0.0.90). ZCode expands only
// its plugins' servers, not mcp.servers (zcode.cjs createTransport).
// Zed hands a command its env and a url its headers as written
// (zed-industries/zed 2c99f547: crates/context_server/src/transport/
// stdio_transport.rs command.envs, http.rs build_request).
// Alma
// 0.4.164 JSON.parses mcp.json and hands a command its env and a url
// its headers as written (out/main/index.js createStdioTransport,
// connectRemoteServer). Devin's docs name ${env:NAME} for OAuth
// fields only (extensibility/mcp/configuration.mdx), so its headers
// and env aren't known to read one.
return envSyntax{}
}
// refNames are the variables a value references.
func refNames(v string) []string {
var out []string
for _, m := range envRef.FindAllStringSubmatch(v, -1) {
out = append(out, m[1])
}
return out
}
// hasRef says whether any value of m references a variable.
func hasRef(m map[string]string) bool {
for _, v := range m {
if envRef.MatchString(v) {
return true
}
}
return false
}
// HasEnvRefs says whether the server's headers or environment reference
// a variable.
func (s *Server) HasEnvRefs() bool { return hasRef(s.Headers) || hasRef(s.Env) }
// errNoEnvRef is why an agent that reads no reference isn't given a
// server with one.
var errNoEnvRef = errors.New("it reads no environment variable from its MCP config, so a server with ${NAME} in its headers or environment isn't given to it: written there, the token would be in its file as plain text")
// whole is the variable a value is in whole (${NAME}), or "".
func whole(v string) string {
if m := envRef.FindStringSubmatch(v); m != nil && m[0] == v {
return m[1]
}
return ""
}
// bearerOf is the variable Authorization's value "Bearer ${NAME}" names.
func bearerOf(k, v string) string {
if !strings.EqualFold(k, "Authorization") {
return ""
}
rest, ok := strings.CutPrefix(v, "Bearer ")
if !ok {
return ""
}
return whole(rest)
}
// refsProblem says why the agent can't be given the server's references,
// or nil when it can (or the server has none).
func (f *mcpFile) refsProblem(s *Server) error {
r := f.refsOf()
headers, env := s.Headers, s.Env
if !s.Remote() {
headers = nil
} else {
env = nil
}
if r.headers == refNone && hasRef(headers) || r.env == refNone && hasRef(env) {
return errNoEnvRef
}
if r.headers == refCodex {
for _, k := range slices.Sorted(maps.Keys(headers)) {
v := headers[k]
if envRef.MatchString(v) && whole(v) == "" && bearerOf(k, v) == "" {
return fmt.Errorf("Codex reads a header from a variable only whole (%s: ${NAME}), or as Authorization: Bearer ${NAME}; %s isn't one", k, k)
}
}
}
if r.env == refCodex || r.env == refGoose {
agent := "Codex"
if r.env == refGoose {
agent = "Goose"
}
for _, k := range slices.Sorted(maps.Keys(env)) {
v := env[k]
if envRef.MatchString(v) && whole(v) != k {
return fmt.Errorf("%s passes a variable on only under its own name (%s: ${%s}); %s isn't one", agent, k, k, k)
}
}
}
if r.headers == refGoose || r.env == refGoose {
// Goose reads an env_keys name upper-cased, so a lower-case one
// would be some other variable
for _, n := range gooseKeys(headers, env) {
if n != strings.ToUpper(n) {
return fmt.Errorf("Goose reads a variable's name upper-cased; ${%s} would be %s", n, strings.ToUpper(n))
}
}
}
return nil
}
// gooseKeys are the variables Goose is told to read (env_keys): those the
// headers reference and those a command is given.
func gooseKeys(headers, env map[string]string) []string {
var out []string
for _, m := range []map[string]string{headers, env} {
for _, v := range m {
for _, n := range refNames(v) {
if !slices.Contains(out, n) {
out = append(out, n)
}
}
}
}
slices.Sort(out)
return out
}
// refKeys are the keys of an agent's entry that name the variables the
// server references, magpie's to write only while it references one there.
func (f *mcpFile) refKeys(s *Server) []string {
switch f.Format {
case fmtCodex:
if s.Remote() && hasRef(s.Headers) {
return []string{"bearer_token_env_var", "env_http_headers"}
}
if !s.Remote() && hasRef(s.Env) {
return []string{"env_vars"}
}
case fmtGoose:
if s.Remote() && hasRef(s.Headers) || !s.Remote() && hasRef(s.Env) {
return []string{"env_keys"}
}
}
return nil
}
// toAgent is a value with its references in the agent's syntax.
func toAgent(syntax refSyntax, v string) string {
switch syntax {
case refOpenCode:
return envRef.ReplaceAllString(v, "{env:$1}")
case refCursor:
return envRef.ReplaceAllString(v, "$${env:$1}")
}
return v
}
var (
openCodeRef = regexp.MustCompile(`\{env:([A-Za-z_][A-Za-z0-9_]*)\}`)
cursorRef = regexp.MustCompile(`\$\{env:([A-Za-z_][A-Za-z0-9_]*)\}`)
)
// dshEnvRef is the expression dsh reads a variable whole with.
var dshEnvRef = regexp.MustCompile(`^process\.env\.([A-Za-z_][A-Za-z0-9_]*)$`)
// dshRef is a value with references as the !!js expression dsh evaluates
// to it, or false for one with none. A variable whole is process.env.NAME,
// as dsh-mcp-client's README writes one, so dsh leaves the server out
// while it's unset. In a longer value each variable is
// (process.env.NAME ?? "") and the text around it JSON strings, which
// JavaScript reads the same: what the user wrote is never code, and an
// unset variable is empty rather than "undefined".
func dshRef(v string) (dshJS, bool) {
if n := whole(v); n != "" {
return dshJS("process.env." + n), true
}
ms := envRef.FindAllStringSubmatchIndex(v, -1)
if len(ms) == 0 {
return "", false
}
var parts []string
lit := func(s string) {
if s != "" {
b, _ := json.Marshal(s)
parts = append(parts, string(b))
}
}
at := 0
for _, m := range ms {
lit(v[at:m[0]])
parts = append(parts, `(process.env.`+v[m[2]:m[3]]+` ?? "")`)
at = m[1]
}
lit(v[at:])
return dshJS(strings.Join(parts, " + ")), true
}
// dshPart is one operand of a longer value dshRef writes: a JSON string,
// or a variable with "" in its place while unset.
var dshPart = regexp.MustCompile(`^(?:"(?:[^"\\]|\\.)*"|\(process\.env\.([A-Za-z_][A-Za-z0-9_]*) \?\? ""\))`)
// dshUnref is the value an expression dshRef writes stands for, its
// references as the library writes them; false for any other expression,
// which is dsh's to work out.
func dshUnref(e dshJS) (string, bool) {
s := string(e)
if m := dshEnvRef.FindStringSubmatch(s); m != nil {
return "${" + m[1] + "}", true
}
var b strings.Builder
refs := 0
for i := 0; i == 0 || s != ""; i++ {
if i > 0 {
rest, ok := strings.CutPrefix(s, " + ")
if !ok {
return "", false
}
s = rest
}
m := dshPart.FindStringSubmatchIndex(s)
if m == nil {
return "", false
}
if m[2] >= 0 {
b.WriteString("${" + s[m[2]:m[3]] + "}")
refs++
} else {
var lit string
if json.Unmarshal([]byte(s[:m[1]]), &lit) != nil {
return "", false
}
b.WriteString(lit)
}
s = s[m[1]:]
}
if refs == 0 {
return "", false
}
return b.String(), true
}
// dshRefs is m as dsh's entry has it, a value with a reference as its
// expression; nil stays nil.
func dshRefs(m map[string]string) map[string]any {
if m == nil {
return nil
}
out := make(map[string]any, len(m))
for k, v := range m {
if e, ok := dshRef(v); ok {
out[k] = e
} else {
out[k] = v
}
}
return out
}
// dshUnrefs is a dsh entry's headers or env with each expression dshRef
// writes read back as the value it stands for; any other value, and
// anything but a map, as it is.
func dshUnrefs(v any) any {
m, ok := v.(map[string]any)
if !ok {
return v
}
out := make(map[string]any, len(m))
for k, x := range m {
if e, ok := x.(dshJS); ok {
if s, ok := dshUnref(e); ok {
out[k] = s
continue
}
}
out[k] = x
}
return out
}
// fromAgent is a value the agent has, with its references as the library
// writes them.
func fromAgent(syntax refSyntax, v string) string {
switch syntax {
case refOpenCode:
return openCodeRef.ReplaceAllString(v, "$${$1}")
case refCursor:
return cursorRef.ReplaceAllString(v, "$${$1}")
}
return v
}
// mapTo is m with every value in the agent's syntax; nil stays nil.
func mapTo(syntax refSyntax, m map[string]string) map[string]string {
if m == nil || syntax != refOpenCode && syntax != refCursor {
return m
}
out := make(map[string]string, len(m))
for k, v := range m {
out[k] = toAgent(syntax, v)
}
return out
}
// mapFrom is m with the agent's references as the library writes them.
func mapFrom(syntax refSyntax, m map[string]string) map[string]string {
if m == nil || syntax != refOpenCode && syntax != refCursor {
return m
}
out := make(map[string]string, len(m))
for k, v := range m {
out[k] = fromAgent(syntax, v)
}
return out
}
// codexHeaders splits headers into those Codex sends as written, the
// variable Authorization's bearer token is read from, and the headers it
// reads whole from a variable.
func codexHeaders(h map[string]string) (plain map[string]string, bearer string, fromEnv map[string]string) {
for _, k := range slices.Sorted(maps.Keys(h)) {
v := h[k]
switch {
case !envRef.MatchString(v):
if plain == nil {
plain = map[string]string{}
}
plain[k] = v
case bearerOf(k, v) != "" && bearer == "":
bearer = bearerOf(k, v)
default:
if fromEnv == nil {
fromEnv = map[string]string{}
}
fromEnv[k] = whole(v)
}
}
return
}
// codexEnv splits a command's environment into what Codex sets as written
// and the variables it passes on by name.
func codexEnv(e map[string]string) (plain map[string]string, pass []string) {
for _, k := range slices.Sorted(maps.Keys(e)) {
if v := e[k]; envRef.MatchString(v) {
pass = append(pass, k)
} else {
if plain == nil {
plain = map[string]string{}
}
plain[k] = v
}
}
return
}
// putRef sets k to v in *into, made if need be, unless k is there already
// (a value written out wins over the variable it's read from).
func putRef(into *map[string]string, k, v string) {
if *into == nil {
*into = map[string]string{}
}
if _, ok := (*into)[k]; !ok {
(*into)[k] = v
}
}
// codexEnvVars are the names a Codex entry's env_vars passes on: each a
// name, or a table with one (codex-rs's McpServerEnvVar); Goose's env_keys
// is a list of names too.
func codexEnvVars(v any) []string {
a, _ := v.([]any)
var out []string
for _, x := range a {
switch e := x.(type) {
case string:
out = append(out, e)
case map[string]any:
if n, _ := e["name"].(string); n != "" {
out = append(out, n)
}
}
}
return out
}
// expandRef is a value with each reference replaced by the variable's value
// in magpie's own environment, for magpie to reach the server itself; the
// names it found unset are given too.
func expandRef(v string) (string, []string) {
var unset []string
out := envRef.ReplaceAllStringFunc(v, func(m string) string {
name := m[2 : len(m)-1]
x, ok := os.LookupEnv(name)
if !ok && !slices.Contains(unset, name) {
unset = append(unset, name)
}
return x
})
return out, unset
}
// expandAll is m with every value expanded (expandRef), and the variables
// found unset, sorted.
func expandAll(m map[string]string) (map[string]string, []string) {
var unset []string
out := make(map[string]string, len(m))
for k, v := range m {
x, miss := expandRef(v)
out[k] = x
for _, n := range miss {
if !slices.Contains(unset, n) {
unset = append(unset, n)
}
}
}
slices.Sort(unset)
return out, unset
}