Whose Environment Expands That Variable? Fingerprinting Your Effective Managed MCP Policy

The effective policy is the file multiplied by the environment

I deliberately wrote the test configuration the way people actually write these: tenant name as a variable, internal tool directory as a variable, a development binary allowed relative to the home directory, and a sandbox domain denied through a variable. Four of the six entries contain a variable, four distinct variables are referenced, and zero references carry a default.

{
  "allowManagedMcpServersOnly": true,
  "env": { "TENANT": "acme", "TOOLS_DIR": "/opt/acme/bin" },
  "allowedMcpServers": [
    { "serverUrl": "https://mcp.${TENANT}.example.com/*" },
    { "serverUrl": "https://api.githubcopilot.com/*" },
    { "serverCommand": ["${TOOLS_DIR}/company-mcp", "--config", "/etc/company/mcp.json"] },
    { "serverCommand": ["${HOME}/bin/dev-mcp"] }
  ],
  "deniedMcpServers": [
    { "serverUrl": "https://*.${SANDBOX_DOMAIN}/*" },
    { "serverName": "dangerous-server" }
  ]
}

I resolved that one file against three environments and judged seven servers. CI has every variable set. The workstation is missing TENANT and SANDBOX_DOMAIN. The third case is a user who points HOME at their own working directory.

Three of seven verdicts — 42.9% — flip between CI and the workstation. One (14.3%) flips between CI and the redirected-HOME case. You can review that JSON, approve it, and still have a different policy in force depending on where it runs — which means a diff review is not, on its own, a safety check.

Looking back, what I had been relying on without noticing was the closed property: values written in the file were the values that took effect. That was never a design decision on my part. It happened to hold. Now that it doesn't, the guarantee has to be rebuilt deliberately.

An unresolved variable fails in opposite directions

This is the part that ran against my expectations. An undefined variable collapses to an empty string, but whether that tightens or loosens depends entirely on which list it sits in.

On the workstation, SANDBOX_DOMAIN is undefined, so the deny entry https://*.${SANDBOX_DOMAIN}/* becomes https://*./*. I measured that innocuous-looking pattern against two host-normalization implementations.

The same unresolved variable produced total lockout and total pass-through. Which way it lands depends on details of the matching implementation, which means the person writing the entry cannot predict it. In the verdict table above, tenant-mcp and github were blocked on the workstation because my harness lands on the first row.

In an allowlist the same collapse produces a string that matches nothing, and the entry is quietly voided. The documentation notes that a server blocked by policy disappears from /mcp and claude mcp list with no warning. To the user it simply looks broken, and nothing surfaces the undefined variable as the cause.

Compressed into something worth remembering: an unresolved variable makes an allowlist too strict and a denylist too permissive, and both happen in silence.

You can move the rule, not just the target

The second reversal took some rewiring. When I imagined how an allowlist gets circumvented, I pictured tampering with the thing being matched — the server config. What actually works is tampering with the matcher.

In the third environment the user points HOME at /tmp/mine. The allowlist entry ${HOME}/bin/dev-mcp therefore expands to /tmp/mine/bin/dev-mcp. The target of the permission relocates to wherever the user says. That is why shadow is allowed only in that column — and why dev-tool, the binary the entry was written for, falls outside the allowance at the same time.

No rule has to be broken. The rule's address just gets rewritten. Under the old resolution source, closed inside the settings file, this path did not exist. With resolution moved to the startup environment, it does. The documentation's advice to keep enforcement entries literal was describing exactly this.

Defaults stop the silence but do not restore enforcement

The first fix that comes to mind is a default value. Write ${TENANT:-invalid.example} and an undefined variable no longer becomes an empty string, so the pattern never collapses into an accidental wildcard. Failures caused by unresolved references do disappear.

That turned out to be half a fix. Under the new order, the startup environment is consulted before the managed-settings env, so a user who sets TENANT overrides both the default and the value in the file. Here are the effective-policy fingerprints for the defaulted configuration across three environments.

Missing variables no longer change the fingerprint. Substituted values still do. When I rewrote every enforcement target as a literal, all four environments I tried — including one that set the variables to empty strings — produced the same fingerprint, 03d2bb7397763c07.

So my conclusion is this. A default is an observability tool, not an enforcement tool. Values you genuinely want to vary per environment, like a tenant name, are fine as variables. Values that define the boundary between allowed and denied belong in literals. The riskiest property of this configuration format is that both are written with the same syntax.

Check the effective policy by fingerprint before startup

If reading the file cannot tell you the effective policy, then print the resolved state in a form you can compare. That is what the preflight below does: expand, report findings, canonicalize the effective policy, and reduce it to a short sha256 fingerprint. Compare fingerprints between CI and a workstation and the drift is immediately visible.

#!/usr/bin/env node
// mcp-policy-preflight.mjs — resolve the effective policy, fingerprint it, surface environment drift
// usage: node mcp-policy-preflight.mjs <managed-settings.json> [--json]
import { readFileSync } from "node:fs";
import { createHash } from "node:crypto";
 
const REF = /\$\{([A-Za-z_][A-Za-z0-9_]*)(?::-([^}]*))?\}/g;
const [file, ...flags] = process.argv.slice(2);
if (!file) { console.error("usage: mcp-policy-preflight.mjs <managed-settings.json> [--json]"); process.exit(2); }
 
const cfg = JSON.parse(readFileSync(file, "utf8"));
const sources = [["startup", process.env], ["settings.env", cfg.env ?? {}]];
const findings = [];
 
function expandValue(raw, where) {
  return String(raw).replace(REF, (whole, name, dflt) => {
    const found = sources.find(([, m]) => m?.[name] !== undefined);
    if (found) {
      const value = String(found[1][name]);
      if (value === "") findings.push({ level: "error", code: "EMPTY", where, name, detail: `${found[0]} is an empty string` });
      // present in both sources with different values: meaning depends on the environment
      const other = sources.find(([o, m]) => o !== found[0] && m?.[name] !== undefined);
      if (other && String(other[1][name]) !== value)
        findings.push({ level: "warn", code: "SHADOWED", where, name, detail: `${found[0]}="${value}" shadows ${other[0]}="${other[1][name]}"` });
      return value;
    }
    if (dflt !== undefined) { findings.push({ level: "info", code: "DEFAULTED", where, name, detail: `using default "${dflt}"` }); return dflt; }
    findings.push({ level: "error", code: "UNRESOLVED", where, name, detail: "not present in any resolution source" });
    return "";
  });
}
 
function resolveEntry(entry, where) {
  if (entry.serverUrl !== undefined) return { serverUrl: expandValue(entry.serverUrl, where) };
  if (entry.serverCommand !== undefined) return { serverCommand: entry.serverCommand.map(a => expandValue(a, where)) };
  return { ...entry };
}
 
const effective = {};
for (const key of ["allowedMcpServers", "deniedMcpServers"]) {
  if (!cfg[key]) continue;
  effective[key] = cfg[key].map((e, i) => {
    const where = `${key}[${i}]`;
    const resolved = resolveEntry(e, where);
    // an enforcement field containing a variable can be steered by the user's environment
    const raw = e.serverUrl ?? (e.serverCommand ? e.serverCommand.join(" ") : "");
    if (REF.test(raw)) { REF.lastIndex = 0;
      findings.push({ level: "warn", code: "USER_STEERABLE", where, name: "-", detail: "enforcement field contains a variable" }); }
    return resolved;
  });
}
 
// fingerprint: canonicalize the effective policy so environments can be compared
const canon = JSON.stringify(effective, (k, v) =>
  Array.isArray(v) && v.every(x => x && typeof x === "object")
    ? [...v].map(x => JSON.stringify(x)).sort() : v);
const fingerprint = createHash("sha256").update(canon).digest("hex").slice(0, 16);
 
const errors = findings.filter(f => f.level === "error");
if (flags.includes("--json")) {
  console.log(JSON.stringify({ fingerprint, findings, effective }, null, 2));
} else {
  console.log(`effective policy fingerprint: ${fingerprint}`);
  for (const f of findings) console.log(`  [${f.level}] ${f.code} ${f.where} ${f.name} — ${f.detail}`);
  if (!findings.length) console.log("  no findings");
}
process.exit(errors.length ? 1 : 0);

The REF.lastIndex = 0 right after REF.test(raw) matters because a global regular expression remembers where it stopped. Omit it and every entry after the first gets skipped. I lost a couple of detections that way before catching it.

Running the original configuration in a complete environment and an incomplete one:

$ HOME=/root TENANT=acme TOOLS_DIR=/opt/acme/bin SANDBOX_DOMAIN=sandbox.example.com \
    node mcp-policy-preflight.mjs policy.json
effective policy fingerprint: 8e135e9e5af52776
  [warn] USER_STEERABLE allowedMcpServers[0] - — enforcement field contains a variable
  [warn] USER_STEERABLE allowedMcpServers[2] - — enforcement field contains a variable
  [warn] USER_STEERABLE allowedMcpServers[3] - — enforcement field contains a variable
  [warn] USER_STEERABLE deniedMcpServers[0] - — enforcement field contains a variable
exit=0
 
$ env -u TENANT -u SANDBOX_DOMAIN HOME=/home/dev node mcp-policy-preflight.mjs policy.json
effective policy fingerprint: 5a72a0ce0f10f8bc
  ...
  [error] UNRESOLVED deniedMcpServers[0] SANDBOX_DOMAIN — not present in any resolution source
exit=1

The fingerprints split into 8e135e9e5af52776 and 5a72a0ce0f10f8bc. That mismatch is the fact a file review could not surface. Across ten runs on Node.js v22.22.3 the script averaged 42ms (40ms minimum, 52ms maximum), short enough to sit in a pre-session hook without being felt.

The order I settled on for wiring it into operations:

1. Run it with --json in the distributing CI job and record the fingerprint as an artifact
2. Run the same script before a session starts on the workstation and compare against the recorded value
3. Treat UNRESOLVED and EMPTY as hard stops, since both exit non-zero already
4. Keep every USER_STEERABLE entry on a list of candidates to rewrite as literals
5. When a fingerprint changes, separate environment drift from an intentional edit before letting it through

Step 3 is deliberately unforgiving. An unresolved variable leads to a failure whose direction cannot be predicted, and stopping to look is cheaper than discovering it later.

How much belongs in a variable

Having measured it, here is the line I drew.

For the default values themselves I chose things that are guaranteed not to match, like invalid.example, rather than a working value. A configuration that fails loudly is easier to operate than one that quietly passes while a variable is missing.

Constraining outbound traffic is a neighbouring problem, and I wrote that one up in Tightening outbound traffic from the Claude Code sandbox with strictAllowlist. In both cases what changed my confidence was having a way to confirm at startup that what I wrote is actually in force.

One thing worth doing today

If your Managed MCP allowlist or denylist contains even one variable reference, resolve that configuration twice: once with every variable set, once with one of them missing. If a single server's verdict changes, that entry is a candidate for a literal. The preflight above is ready to run as-is.

Until I measured this, I assumed that reading the distributed JSON told me what was in force. The effective policy is not the settings file. It is the settings file multiplied by the environment. Being able to compare that product as a short fingerprint on every run turned out to be the most useful change I made here.