mcp-context-cost 0.19.0 → 0.20.0

package/README.md

@@ -85,8 +85,9 @@ project, and no **value** an entry carries — an env var, a header — is ever
 output. Only their names are.
 
 A remote entry — `url`, or the client's own spelling of it — is probed before anything is
-launched, and reported as measured, **auth-walled** or **unreachable** depending on what it
-answers; an auth-walled row makes the total above it a floor rather than a number. The probe,
+launched, and reported as measured, **auth-walled**, **protocol-mismatch** or
+**unreachable** depending on what it answers; an auth-walled or protocol-mismatch row makes
+the total above it a floor rather than a number. The probe,
 what each verdict quotes, and why it exists at all are in
 [METHODOLOGY §who pays the number](docs/METHODOLOGY.md#who-pays). Nothing here opens a
 browser.
@@ -101,7 +102,10 @@ Not every client puts every tool definition in context on every request, so the
 is not automatically your bill. Which client reads the config decides it, and for Claude Code
 so does how that client is configured **on this machine** — three environment variables and a
 per-server `alwaysLoad` pin, which `audit` reads rather than assumes, from the shell it runs
-in *and* from the `env` block of Claude Code's own settings files. No other client's posture
+in *and* from the `env` block of Claude Code's own settings files. It also reads what an
+organisation deploys: the managed MCP file that takes exclusive control of the server list
+where it exists, and the allow/deny lists that filter what loads — a clean deny is applied to
+the session's claims, an allowlist is reported and never subtracted. No other client's posture
 is readable from a file this opens, so for those the report gives what the vendor is on record
 with, or says there is nothing on record, and claims neither as a measurement.
 
@@ -180,6 +184,13 @@ npx -y mcp-context-cost audit --config .mcp.json --budget 20000
 # exits 1 when the stack exceeds the budget, so a PR adding a 25K-token server fails
 ```
 
+The budget is denominated in **sessions**, because a context window belongs to one session:
+for claude-code that is the files one session loads together — both its configs, or the
+managed file alone where one is deployed, minus anything `deniedMcpServers` removes — and for
+every other client one file is one session. Per-file totals are still reported as file facts;
+the gate reads the costliest session. The baseline diff below stays per file, because a
+baseline pins a file artifact.
+
 The budget is an absolute ceiling. What a reviewer actually wants to know is what *this pull
 request* did, so record a baseline and diff against it:
 
@@ -256,7 +267,7 @@ does, and the percentile that decides are in
 
 ```
   suggest — descriptions at or above the 90th percentile of measured tools
-  (baseline 2026-09-07: 1,430 tools across 87 measured servers):
+  (baseline 2026-09-09: 1,433 tools across 87 measured servers):
     stub · wordy — 345 tokens: description 321 (p92), schema 14
       rewriting the description toward the measured median (27) would recover ≈294 tokens on every request
     1 of 2 tools sit inside the distribution — no advice where nothing is measurably unusual.
@@ -316,7 +327,7 @@ answers a question no client asks: **what did this server cost last month?**
 [results/regressions.md](results/regressions.md) reports each server's most recent movement —
 dated to when it happened, separated into *shipped more tools* versus *same tools, rewritten*,
 and compared only within one isolation. The ecosystem ratchets upward: of the servers whose
-cost has moved at all, 13 moved up against 5 that moved down. Method:
+cost has moved at all, 15 moved up against 5 that moved down. Method:
 [cost movement](docs/METHODOLOGY.md#cost-movement).
 
 If you publish a server, the same measurement is available as a badge, so your users can see
@@ -385,7 +396,7 @@ number is *not*, config policy, failure taxonomy, frozen color bands, known dive
 | `src/audit/` | client-config discovery (10 clients; JSON with comments, TOML, YAML), the remote probe, the per-stack report, and the baseline diff |
 | `src/cli.ts` | `audit` (measure your own stack), `verify` (re-derive any published number), `measure` |
 | `spec/fixtures/` | golden vectors shared by the TypeScript and bash implementations |
-| `tools/` | the scripts that call a network API — the Claude divergence run, the adoption reading, the registry scan — kept out of the package so the library stays offline |
+| `tools/` | the scripts that call a network API — the Claude divergence run, the registry scan — kept out of the package so the library stays offline |
 | `upstream/` | `badge.sh` + bash tests — the self-serve badge recipe, carried here |
 | `servers.yaml` | 107 curated candidates with live install metrics and provenance |
 | `results/` · `badges/` | measurements, leaderboard, history series, shields endpoint JSONs |
@@ -423,7 +434,7 @@ repository), then in your README:
 A badge says what your server costs today; it does nothing about the release
 that adds 1,200 tokens to every user's context next month. Across the servers
 measured here most costs hold steady from sweep to sweep, but when a cost does
-move it usually moves up: the [movement report](results/regressions.md) has 13
+move it usually moves up: the [movement report](results/regressions.md) has 15
 servers ratcheting upward against 5 that got cheaper, and none of those
 maintainers had a check that would have said so first. `measure` takes the same
 gate flags `audit` does, so your own CI can be that check:
@@ -461,25 +472,6 @@ Point the link at the measurement behind the number — for servers in this swee
 `https://athakur3.github.io/mcp-context-cost/servers/<name>.html`; otherwise the
 methodology page. A badge nobody can audit is decoration.
 
-How many projects outside this repository actually display it is a dated reading rather
-than a guess — [docs/adoption.md](docs/adoption.md), regenerated by `npm run adoption`,
-which publishes the queries it ran and every file it examined. A zero there means the
-search ran and found none; if it could not run, it says that instead of publishing a zero.
-
-## Development
-
-```bash
-npm test                        # TS suite incl. golden fixtures + dispute drills
-npx tsc --noEmit                # typecheck
-./upstream/tests/badge-test.sh  # bash suite — byte-identical to the TS reference
-npm run sweep:all -- --docker   # full curated sweep (Docker isolation)
-```
-
-Notable engineering choices: the MCP client is a deliberate raw-wire implementation
-rather than the SDK (schema-parsing can reorder keys, which would corrupt canonical bytes);
-sweep servers run in credential-free Docker containers with recorded isolation; the badge
-color bands are frozen against the observed distribution of the first full sweep.
-
 ## Status
 
 Active. Every row carries the date of its own most recent measurement. Two
@@ -489,8 +481,8 @@ date as the date it means, and don't take the cadence on trust — the build his
 public, one click each:
 [re-sweep runs](https://github.com/athakur3/mcp-context-cost/actions/workflows/resweep.yml)
 and [self-badge runs](https://github.com/athakur3/mcp-context-cost/actions/workflows/self-badge.yml).
-See [ROADMAP.md](ROADMAP.md) for what's next — contributions welcome, especially new
-`servers.yaml` entries; [CONTRIBUTING.md](CONTRIBUTING.md) says what an entry needs, the
+What changed, and why, is in [CHANGELOG.md](CHANGELOG.md); contributions welcome, especially
+new `servers.yaml` entries — [CONTRIBUTING.md](CONTRIBUTING.md) says what an entry needs, the
 order of steps that leaves a pull request green, and where its number comes from.
 
 MIT © 2026

package/dist/audit/audit.d.ts

@@ -6,6 +6,7 @@ import type { ConfiguredServer, LoadedConfig } from './config.js';
 import type { RemoteProbe } from './remote.js';
 import { type DeferralVerdict, type ToolSearchEnv, type ToolSearchSource } from './deferral.js';
 import { type AuditDiff, type IncreaseGate } from './diff.js';
+import { type DenyVerdict, type McpPolicyEvaluation, type UnevaluatedEntry } from './mcp-policy.js';
 export declare const DEFAULT_CONTEXT_WINDOW = 200000;
 /**
  * A server's status in a report: the measurement statuses, plus two that only
@@ -99,6 +100,15 @@ export interface AuditConfigResult {
     suggestions?: ConfigSuggestions | undefined;
     /** Present only when `--changed` ran with a usable capture index. */
     captureVerdicts?: ServerCaptureVerdict[] | undefined;
+    /** Set on the managed MCP file's own row (see managedMcpPath in config.ts). */
+    managed?: true | undefined;
+    /**
+     * Set on a claude-code config that is measured here but does not load in a
+     * session, because a managed MCP file has exclusive control. The value is
+     * that file's path. The measurement stands — it is a fact about this file —
+     * and every session-level claim belongs to the managed file instead.
+     */
+    suppressedByManagedMcp?: string | undefined;
     /**
      * Whether this client loads the total up front or defers it, and — when the
      * client decides that by a threshold — which side of it this stack is on.
@@ -138,7 +148,7 @@ export interface BudgetFit {
  * need, and dropping by weight will sometimes name the one you cannot live without. That
  * caveat is printed with the result rather than left implied.
  */
-export declare function planBudgetFit(config: AuditConfigResult, limit: number): BudgetFit;
+export declare function planBudgetFit(config: Pick<AuditConfigResult, 'servers' | 'totalTokens'>, limit: number): BudgetFit;
 export interface AuditReport {
     methodologyVersion: string;
     encoding: 'o200k_base';
@@ -175,6 +185,49 @@ export interface AuditReport {
         /** Present only when over budget: the arithmetic of getting back under it. */
         fit?: BudgetFit | undefined;
     };
+    /**
+     * What each session loads, one row per session scope — for claude-code the
+     * files one session reads together (the managed file alone where deployed),
+     * with denylist removals already applied and named. Config rows above stay
+     * file facts; this is the session fact, and it is what `--budget` gates.
+     */
+    sessions?: {
+        client: string;
+        sources: string[];
+        totalTokens: number;
+        contextShare: number;
+        deniedTokens?: number | undefined;
+    }[] | undefined;
+    /**
+     * Present when the managed MCP file exists on this machine. `exclusive`
+     * means a claude-code session loads only its servers; `disabled` that it is
+     * deployed with an empty server map, so no MCP server loads at all;
+     * `unreadable` that it exists and could not be read, so which servers a
+     * session loads cannot be said. `suppressed` names the claude-code configs
+     * measured here that do not load under it. Source:
+     * code.claude.com/docs/en/managed-mcp.md, read 2026-09-09.
+     */
+    managedMcp?: {
+        path: string;
+        state: 'exclusive' | 'disabled' | 'unreadable';
+        error?: string | undefined;
+        suppressed: string[];
+    } | undefined;
+    /**
+     * Claude Code's MCP allowlist/denylist, as read from the settings files this
+     * audit opens, evaluated over the claude-code session's servers. Deny
+     * matches are applied — those servers are left out of the session-level
+     * sums, never out of a file's own total; allow verdicts are reported and
+     * never applied (mcp-policy.ts says why the two differ). Absent when no read
+     * settings file sets either list.
+     */
+    mcpPolicy?: {
+        denied: (DenyVerdict & {
+            tokens: number | null;
+        })[];
+        denyUnevaluated: UnevaluatedEntry[];
+        allow?: McpPolicyEvaluation['allow'];
+    } | undefined;
     /** Present only when a divergence run was supplied (`--claude`). */
     claudeDivergence?: {
         model: string;

package/dist/audit/audit.js

@@ -19,6 +19,7 @@ import { identify } from '../core/capture-index.js';
 import { evaluateDeferral, BAND_PRECISION, PUBLISHED_WIRE_TO_CLIENT_RATIO, SHELL_SOURCE, } from './deferral.js';
 import { formatDiff, formatGate } from './diff.js';
 import { signed } from '../core/format.js';
+import { evaluateMcpPolicy, } from './mcp-policy.js';
 export const DEFAULT_CONTEXT_WINDOW = 200_000;
 const TRIM_TOOL_COUNT = 3;
 function buildSuggestions(pool, baseline) {
@@ -159,6 +160,39 @@ function measuredOk(m) {
  * together — not for adding one client's servers to another's.
  */
 const ONE_SESSION_PER_CLIENT = new Set(['claude-code']);
+function composeSessions(built, opts) {
+    const scopes = new Map();
+    for (const cfg of built) {
+        const key = deferralScopeKey(cfg.client, cfg.source);
+        const group = scopes.get(key);
+        if (group)
+            group.push(cfg);
+        else
+            scopes.set(key, [cfg]);
+    }
+    const out = new Map();
+    for (const [key, group] of scopes) {
+        const isCc = ONE_SESSION_PER_CLIENT.has(group[0].client);
+        const sessionCfgs = isCc && opts.managedActive ? group.filter((c) => c.managed) : group;
+        const denied = isCc ? (opts.deniedNames ?? new Set()) : new Set();
+        const all = sessionCfgs.flatMap((c) => c.servers);
+        const servers = all.filter((s) => !denied.has(s.name));
+        out.set(key, {
+            client: group[0].client,
+            group,
+            sessionCfgs,
+            sources: sessionCfgs.map((c) => c.source),
+            servers,
+            totalTokens: servers.reduce((a, s) => a + (s.tokens ?? 0), 0),
+            deniedTokens: all.filter((s) => denied.has(s.name)).reduce((a, s) => a + (s.tokens ?? 0), 0),
+            skippedRows: sessionCfgs.flatMap((c) => c.skipped
+                .filter((s) => !denied.has(s.name))
+                .map((s) => ({ source: c.source, name: s.name, status: s.status }))),
+            sharedSum: sessionCfgs.reduce((a, c) => a + (opts.shared.get(c) ?? 0), 0),
+        });
+    }
+    return out;
+}
 /** Which configs share a deferral verdict. */
 function deferralScopeKey(client, source) {
     return ONE_SESSION_PER_CLIENT.has(client) ? client : `${client}\0${source}`;
@@ -169,31 +203,26 @@ function deferralScopeKey(client, source) {
  * print it once and a `--json` consumer can see which files it spans.
  */
 function attachDeferral(configs, contextWindow, opts) {
-    const scopes = new Map();
-    for (const cfg of configs) {
-        const key = deferralScopeKey(cfg.client, cfg.source);
-        const group = scopes.get(key);
-        if (group)
-            group.push(cfg);
-        else
-            scopes.set(key, [cfg]);
-    }
     const verdicts = new Map();
-    for (const [key, group] of scopes) {
+    for (const [key, comp] of opts.sessions) {
+        // The composition already speaks the managed file's exclusivity and the
+        // denylist: what reaches evaluateDeferral is what the session loads, and
+        // suppressed configs still share the verdict object so their rows can
+        // point at it.
         verdicts.set(key, 
         // Computed against the same context window the share uses, so any
         // threshold moves with `--context` instead of being pinned to 200,000.
         evaluateDeferral({
-            client: group[0].client,
-            sources: group.map((c) => c.source),
-            servers: group.flatMap((c) => c.servers.map((s) => ({
+            client: comp.client,
+            sources: comp.sources,
+            servers: comp.servers.map((s) => ({
                 name: s.name,
                 tokens: s.tokens ?? 0,
                 claudeTokens: s.claudeTokens,
                 ...(s.alwaysLoad ? { alwaysLoad: true } : {}),
-            }))),
-            skippedCount: group.reduce((a, c) => a + c.skipped.length, 0),
-            sharedMeasurements: group.reduce((a, c) => a + (opts.shared.get(c) ?? 0), 0),
+            })),
+            skippedCount: comp.skippedRows.length,
+            sharedMeasurements: comp.sharedSum,
         }, { contextWindow, env: opts.env, settings: opts.settings, divergence: opts.divergence }));
     }
     return configs.map((cfg) => ({
@@ -222,6 +251,38 @@ export function buildReport(configs, measured, opts = {}) {
     // the other client's entry just the same.
     const collapsed = collapsedKeys(configs);
     const shared = new Map();
+    // The managed MCP file, when present, decides what a claude-code session
+    // loads (config.ts: managedMcpPath). Detected before the build, so every
+    // claude-code row can say which side of that fact it is on.
+    const managedCfg = configs.find((c) => c.client === 'claude-code' && c.managed);
+    const otherCc = configs.filter((c) => c.client === 'claude-code' && !c.managed);
+    const managedState = managedCfg
+        ? managedCfg.error
+            ? 'unreadable'
+            : managedCfg.servers.length
+                ? 'exclusive'
+                : 'disabled'
+        : undefined;
+    const managedActive = managedState === 'exclusive' || managedState === 'disabled';
+    // The claude-code session's servers, managed-aware — taken at the config
+    // level because policy entries match argv and URL, which built rows drop.
+    const ccSessionServers = managedActive
+        ? managedState === 'exclusive'
+            ? managedCfg.servers
+            : []
+        : otherCc.flatMap((c) => c.servers);
+    const policy = evaluateMcpPolicy(ccSessionServers.map((s) => ({
+        name: s.name,
+        transport: s.transport,
+        argv: s.argv,
+        url: s.url,
+    })), (opts.settings ?? []).map((s) => ({
+        scope: s.scope,
+        source: s.source,
+        state: s.state,
+        policy: s.mcpPolicy,
+    })));
+    const deniedNames = new Set(policy.denied.map((d) => d.server));
     for (const cfg of configs) {
         if (cfg.error) {
             problems.push(`${cfg.source}: ${cfg.error}`);
@@ -377,12 +438,21 @@ export function buildReport(configs, measured, opts = {}) {
                     verdict: identify(s.canonicalSha256, opts.captureIndex),
                 }))
                 : undefined,
+            ...(cfg.managed ? { managed: true } : {}),
+            ...(managedActive && cfg.client === 'claude-code' && !cfg.managed
+                ? { suppressedByManagedMcp: managedCfg.source }
+                : {}),
         };
         built.push(result);
         shared.set(result, sharedHere);
     }
     built.sort((a, b) => b.totalTokens - a.totalTokens);
-    const results = attachDeferral(built, contextWindow, { ...opts, shared });
+    const sessions = composeSessions(built, {
+        shared,
+        managedActive: managedActive ? managedState : undefined,
+        deniedNames,
+    });
+    const results = attachDeferral(built, contextWindow, { ...opts, shared, sessions });
     const report = {
         methodologyVersion: METHODOLOGY_VERSION,
         encoding: 'o200k_base',
@@ -392,6 +462,32 @@ export function buildReport(configs, measured, opts = {}) {
         emptyConfigs,
         problems,
     };
+    report.sessions = [...sessions.values()].map((s) => ({
+        client: s.client,
+        sources: s.sources,
+        totalTokens: s.totalTokens,
+        contextShare: s.totalTokens / contextWindow,
+        ...(s.deniedTokens > 0 ? { deniedTokens: s.deniedTokens } : {}),
+    }));
+    if (managedCfg && managedState) {
+        report.managedMcp = {
+            path: managedCfg.source,
+            state: managedState,
+            ...(managedCfg.error ? { error: managedCfg.error } : {}),
+            suppressed: managedActive ? otherCc.map((c) => c.source) : [],
+        };
+    }
+    if (policy.sources.length) {
+        const ccServers = built.filter((b) => b.client === 'claude-code').flatMap((b) => b.servers);
+        report.mcpPolicy = {
+            denied: policy.denied.map((d) => ({
+                ...d,
+                tokens: ccServers.find((s) => s.name === d.server)?.tokens ?? null,
+            })),
+            denyUnevaluated: policy.denyUnevaluated,
+            ...(policy.allow ? { allow: policy.allow } : {}),
+        };
+    }
     if (opts.divergence) {
         report.claudeDivergence = {
             model: opts.divergence.model,
@@ -412,23 +508,28 @@ export function buildReport(configs, measured, opts = {}) {
         };
     }
     if (typeof opts.budget === 'number') {
-        // The worst config is the gate: passing because your *lightest* client fits
-        // would be a green check on a session you don't run.
-        const worst = results[0];
+        // The worst SESSION is the gate — decided 2026-09-09. A context window
+        // belongs to one session, and for claude-code a session loads two files
+        // together (or the managed file alone, minus what the denylist removed);
+        // gating the worst file passed a budget the session it belongs to blows.
+        // Passing because your *lightest* client fits would still be a green check
+        // on a session you don't run, so the costliest one is the gate.
+        const worst = [...sessions.values()].toSorted((a, b) => b.totalTokens - a.totalTokens)[0];
         // A total is only a ceiling to compare against if it is the whole cost. A
-        // server that failed to start contributes 0, so the stack reads lighter
+        // server that failed to start contributes 0, so the session reads lighter
         // than it is and the budget passes on a number that is missing a server —
-        // exactly the PR the README says this gate catches. The server-level gate
-        // (core/server-diff.ts) already refuses this; so does this one now. Every
-        // skipped row counts: an auth-walled endpoint is a working server the
+        // exactly the PR the README says this gate catches. Every skipped row of
+        // every session counts: an auth-walled endpoint is a working server the
         // session pays for with its credential, and an unreachable one is a cost
-        // this could not establish, not a cost of zero.
-        const unestablished = results.flatMap((c) => c.skipped.map((s) => `${c.source}: ${s.name} (${s.status})`));
+        // this could not establish, not a cost of zero. What no session loads — a
+        // config the managed file suppresses, a server the denylist removed — is
+        // nobody's bill, so it does not count.
+        const unestablished = [...sessions.values()].flatMap((s) => s.skippedRows.map((r) => `${r.source}: ${r.name} (${r.status})`));
         const over = (worst?.totalTokens ?? 0) > opts.budget;
         report.budget = {
             limit: opts.budget,
             worstTotal: worst?.totalTokens ?? 0,
-            worstSource: worst?.source ?? '(none)',
+            worstSource: worst ? worst.sources.join(' + ') || '(none)' : '(none)',
             over: over || unestablished.length > 0,
             // Named so the reader knows which way the number is wrong: the total
             // understates by however much these cost, which nobody knows.
@@ -808,12 +909,36 @@ export function formatReport(report) {
     const lines = [];
     lines.push(`mcp-context-cost audit · methodology ${report.methodologyVersion} · ${report.encoding} · context window ${n(report.contextWindow)}`);
     const showClaude = !!report.claudeDivergence;
+    // The managed MCP file with no server rows of its own still owns the session:
+    // deployed empty it disables MCP, unreadable it makes the session unsayable.
+    // Either way that is the first fact about claude-code on this machine.
+    if (report.managedMcp && report.managedMcp.state !== 'exclusive') {
+        const m = report.managedMcp;
+        lines.push('');
+        lines.push(`claude-code  ${m.path}`);
+        if (m.state === 'disabled') {
+            lines.push('  managed: deployed with an empty server map — MCP is disabled by policy. No MCP', '  server loads in a claude-code session on this machine, whatever the configs below', '  declare; they are measured as files.');
+        }
+        else {
+            lines.push('  managed: this file exists and could not be read — which servers a claude-code', '  session loads cannot be said. The configs below are measured as files, and no', '  session-level claim is made for this client.');
+            if (m.error)
+                lines.push(`  ${m.error}`);
+        }
+    }
     // Configs one session loads together share a verdict object; it answers for
     // all of them at once, so it is printed under the first one and not repeated.
     const verdictPrinted = new Set();
+    const sessionPrinted = new Set();
+    let policyPrinted = false;
     for (const cfg of report.configs) {
         lines.push('');
         lines.push(`${cfg.client}  ${cfg.source}`);
+        if (cfg.managed) {
+            lines.push('  managed-mcp.json — exclusive control: a claude-code session loads only the servers', '  in this file (plus in-process servers the launching app registers, which no config', '  file describes). Other claude-code configs here are measured and do not load.');
+        }
+        if (cfg.suppressedByManagedMcp) {
+            lines.push(`  does not load: ${cfg.suppressedByManagedMcp} has exclusive control of`, '  claude-code sessions. Measured all the same — the numbers below are facts about', '  this file, not about any session.');
+        }
         const rows = cfg.servers.map((s) => ({
             name: s.name,
             tools: s.toolCount === null ? '—' : String(s.toolCount),
@@ -844,6 +969,64 @@ export function formatReport(report) {
             for (const deferralLine of deferralLines(cfg.deferral, skippedInScope))
                 lines.push(deferralLine);
         }
+        {
+            const session = report.sessions?.find((s) => ONE_SESSION_PER_CLIENT.has(cfg.client)
+                ? s.client === cfg.client
+                : s.client === cfg.client && s.sources.length === 1 && s.sources[0] === cfg.source);
+            if (session &&
+                !sessionPrinted.has(session) &&
+                (session.sources.length !== 1 || (session.deniedTokens ?? 0) > 0)) {
+                sessionPrinted.add(session);
+                const denied = (session.deniedTokens ?? 0) > 0
+                    ? ` (after ${n(session.deniedTokens)} tokens removed by deniedMcpServers)`
+                    : '';
+                const what = session.sources.length === 0
+                    ? 'no MCP servers'
+                    : `${session.sources.length} config files together`;
+                lines.push('');
+                lines.push(`  one ${cfg.client} session loads ${what}: ${n(session.totalTokens)} tokens — ` +
+                    `${pct(session.contextShare)} of a ${n(report.contextWindow)}-token context window${denied}.`);
+                lines.push('  That session figure is what --budget gates; per-file totals stay above.');
+            }
+        }
+        if (cfg.client === 'claude-code' && report.mcpPolicy && !policyPrinted) {
+            policyPrinted = true;
+            const p = report.mcpPolicy;
+            if (p.denied.length) {
+                lines.push('');
+                lines.push('  blocked by deniedMcpServers — a denied server does not load, whatever else is', "  set, so these are left out of the session claims above (never out of a file's", '  own total):');
+                for (const d of p.denied) {
+                    const tok = d.tokens != null ? ` — ${n(d.tokens)} tokens` : '';
+                    lines.push(`    ${d.server}${tok} — matched ${d.entry} (${d.source})`);
+                }
+            }
+            if (p.denyUnevaluated.length) {
+                lines.push('');
+                lines.push('  deny entries set but not evaluated here — a match would only remove more:');
+                for (const u of p.denyUnevaluated)
+                    lines.push(`    ${u.entry} (${u.source}) — ${u.reason}`);
+            }
+            if (p.allow) {
+                lines.push('');
+                lines.push(`  an MCP allowlist is set in ${p.allow.sources.join(', ')}.`);
+                if (p.allow.managedOnly) {
+                    lines.push(`    allowManagedMcpServersOnly is true in ${p.allow.managedOnly.source}, so only`, '    managed-tier entries counted below.');
+                }
+                const fails = p.allow.rows.filter((r) => r.verdict === 'fails').map((r) => r.server);
+                const unev = p.allow.rows.filter((r) => r.verdict === 'unevaluated').map((r) => r.server);
+                const hit = p.allow.rows.length - fails.length - unev.length;
+                lines.push(`    ${hit} of ${p.allow.rows.length} session server(s) match an entry read here.`);
+                if (fails.length) {
+                    lines.push(`    matched by nothing read here: ${fails.join(', ')} — reported, not removed. An`, '    entry in a tier this audit does not read (server-managed settings, an MDM', '    profile, a registry key) can only broaden an allowlist, so this is a condition', '    to check, never a subtraction.');
+                }
+                if (unev.length) {
+                    lines.push(`    not evaluated: ${unev.join(', ')} — an entry below decides them.`);
+                }
+                for (const u of p.allow.unevaluated) {
+                    lines.push(`      entry not evaluated: ${u.entry} (${u.source}) — ${u.reason}`);
+                }
+            }
+        }
         if (cfg.heaviestTools.length) {
             lines.push('');
             lines.push('  heaviest tools');
@@ -946,7 +1129,7 @@ export function formatReport(report) {
         lines.push('');
         if (!b.over) {
             const headroom = b.limit - b.worstTotal;
-            lines.push(`budget ok: ${n(b.worstTotal)} ≤ ${n(b.limit)} — ${n(headroom)} to spare`);
+            lines.push(`budget ok: ${n(b.worstTotal)} ≤ ${n(b.limit)} — ${n(headroom)} to spare (costliest session: ${b.worstSource})`);
         }
         else if (b.unestablished && b.worstTotal <= b.limit) {
             // Under the line on what was measured, but not everything was: say which

package/dist/audit/config.d.ts

@@ -67,6 +67,8 @@ export interface ConfigCandidate {
     path: string;
     /** How the file is written. Absent means JSON, with comments and trailing commas tolerated. */
     format?: 'json' | 'toml' | 'yaml';
+    /** Set on the managed MCP file, whose presence changes what a session loads. */
+    managed?: true;
 }
 /** Every place a client config is known to live, whether or not it exists. */
 export declare function configCandidates(env: {
@@ -80,6 +82,8 @@ export declare function parseConfigText(text: string, format?: ConfigCandidate['
 export interface LoadedConfig {
     client: string;
     source: string;
+    /** Carried from the candidate: this is the managed MCP file (see managedMcpPath). */
+    managed?: true;
     servers: ConfiguredServer[];
     /** Set when the file exists but could not be read/parsed. */
     error?: string;
@@ -102,6 +106,23 @@ export interface LoadedConfig {
 }
 /** Read + parse the candidates that exist. Unreadable files are reported, not thrown. */
 export declare function loadConfigs(candidates: ConfigCandidate[], cwd: string, processEnv?: Record<string, string | undefined>): LoadedConfig[];
+/**
+ * Where Claude Code looks for the managed MCP file: one fixed path per
+ * platform, in the same system directory as `managed-settings.json` — and,
+ * unlike that file, with no drop-in directory: the vendor documents a single
+ * standalone file that "cannot be delivered through server-managed settings".
+ * When it exists, a claude-code session loads only the servers it defines
+ * (plus in-process servers the launching app registers, which no config file
+ * describes). code.claude.com/docs/en/managed-mcp.md, §Exclusive control with
+ * managed-mcp.json, read **2026-09-09**.
+ */
+export declare function managedMcpPath(platform: NodeJS.Platform): string;
+/**
+ * The candidate list with the managed MCP file spliced in ahead of the
+ * claude-code user and project configs, so the file that decides what a
+ * session loads is read — and reported — before the files it can suppress.
+ */
+export declare function withManagedMcpCandidate(candidates: ConfigCandidate[], platform: NodeJS.Platform): ConfigCandidate[];
 /** One file Claude Code reads its `env` block from. */
 export interface SettingsCandidate {
     scope: ToolSearchScope;