mcp-context-cost 0.18.0 → 0.20.0

package/README.md

@@ -4,9 +4,9 @@
 [![CI](https://github.com/athakur3/mcp-context-cost/actions/workflows/ci.yml/badge.svg)](https://github.com/athakur3/mcp-context-cost/actions/workflows/ci.yml)
 [![GitHub Marketplace](https://img.shields.io/badge/GitHub%20Marketplace-MCP%20context%20cost-blue?logo=github)](https://github.com/marketplace/actions/mcp-context-cost)
 
-Two entry points: `audit`, for the config you run (below), and a GitHub Action, for the
-server you publish — five lines in a workflow that fail a pull request adding more context
-cost than you meant to ship:
+Three entry points: `audit`, for the config you run (below); a GitHub Action, for the server
+you publish; and the measurement itself, as a library, for anything else. The Action is five
+lines in a workflow that fail a pull request adding more context cost than you meant to ship:
 
 ```yaml
 - uses: athakur3/mcp-context-cost@v1
@@ -24,6 +24,18 @@ gate passed or not, so a later step can comment the number on the PR or publish
 [how the gate decides](#defend-the-number-dont-just-display-it) ·
 [what the number is](docs/METHODOLOGY.md).
 
+As a library, if you want the measurement without either wrapper — the same canonical form,
+the same tokenizer, the same badge:
+
+```js
+import { measureTools, canonicalString, toBadge, METHODOLOGY_VERSION } from "mcp-context-cost";
+```
+
+It is the definition rather than the harness: measurement and canonical bytes, the color
+bands, the badge JSON, the Claude field-selection mapping, and the session-start load. It
+does not launch servers or read your config — that is what `audit` is for. The surface is
+pinned by a test, so a name is added or removed on purpose and says so in the changelog.
+
 **What do the MCP servers in your config cost you before you type anything — and what did
 that last config change add to every session you will ever run?**
 
@@ -69,16 +81,16 @@ VS Code (`.vscode/mcp.json`), Windsurf, Codex CLI (`~/.codex/config.toml`), Gemi
 Goose (`~/.config/goose/config.yaml`) — or pass `--config <path>`. Servers are measured by
 the same path as the published leaderboard (dual `tools/list` capture, `o200k_base` over
 canonical JSON), so a server in both places gets the same number. Nothing is written to your
-project, and env var **values** are never read into the output — only their names.
+project, and no **value** an entry carries — an env var, a header — is ever read into the
+output. Only their names are.
 
-A remote entry — `url`, or the client's own spelling of it — is first asked what it says to
-an unauthenticated `initialize`. An endpoint that answers is measured through the
-`mcp-remote` bridge, the path the leaderboard's remote rows already take. One that answers
-`401` or `403` is reported **auth-walled**, quoting the status and the `WWW-Authenticate`
-header it sent, with the URL: a working server this audit holds no credential for, so the
-total above it is a floor. One that answers nothing usable is **unreachable**, with the
-reason. Header values an entry carries are sent and never printed — only their names are —
-and nothing here ever opens a browser.
+A remote entry — `url`, or the client's own spelling of it — is probed before anything is
+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.
 
 Totals are reported per config file, never merged: a context window belongs to one client
 session, so summing Cursor's servers into Claude Desktop's total would describe a session
@@ -88,45 +100,21 @@ nobody runs.
 
 Not every client puts every tool definition in context on every request, so the total above
 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** — which `audit` reads rather than
-assumes. No other client's posture is readable from a file this opens, so for those the report
-gives what their vendor is on record with, or says there is nothing on record, and claims
-neither as a measurement.
-
-**Clients whose vendor is on record as deferring** — Cursor (*dynamic context discovery*),
-Codex CLI (*tool search*), and VS Code, whose record is a pair of conditions rather than a
-default. For these the report prints what the vendor states, what that record leaves open, and
-the address and date of every source behind it. It stops where Claude Code's entry stops:
-nothing here measured any of them, and no config file this reads states their posture — so the
-total is what the definitions weigh, not a bill every request is known to carry, and not a
-saving either. Cursor's record is the reason this changed: its engineering blog described the
-mechanism on 2026-01-06 while its MCP configuration page, then and now, says nothing, and a
-rule that read only that page reported an absence of a record for eight months.
-
-**Clients with no default deferral on record** — Claude Desktop, Windsurf, Gemini CLI, Zed,
-Kiro, Goose. The total is what every request carries, as in the example above. That sentence is
-an absence of a record about those clients, not a measurement of them, and the report says so
-in those words.
-
-**Claude Code defers MCP tool definitions by default** (its **tool search**): they are not
-in context at session start, and load when the model reaches for one. Three variables move
-that, and `audit` reads all three — from the shell it runs in *and* from the `env` block of
-Claude Code's own settings files (managed, `<cwd>/.claude/settings.local.json`,
-`<cwd>/.claude/settings.json`, `~/.claude/settings.json`), because a machine that switched
-deferral off in a settings file is not a machine running the default:
-
-| setting | what the audit reports |
-|---|---|
-| nothing set (the default) | every definition deferred, at any size — no threshold applies |
-| `ENABLE_TOOL_SEARCH=true` | same: every definition deferred |
-| `ENABLE_TOOL_SEARCH=false` | deferral off — every request carries the full total. In a settings `env` block that is the **string** `"false"`; the JSON boolean `false` is the last row, not this one |
-| `ENABLE_TOOL_SEARCH=auto` / `auto:N` | deferred only once definitions reach 10% / N% of the context window |
-| `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS` set to `1`, `true`, `yes` or `on` | tool search off — read first, because `ENABLE_TOOL_SEARCH` cannot override it |
-| `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS` set to `0`, `false`, `no` or `off` | it turned nothing off, so the read moves on and the rows above decide. It is a boolean flag in the client, not a marker whose presence is the signal |
-| `ANTHROPIC_BASE_URL` off `api.anthropic.com` | falls back to loading up front — consulted only while `ENABLE_TOOL_SEARCH` is unset |
-| anything else in `ENABLE_TOOL_SEARCH` | not a documented value, so nothing is claimed from it |
-| any of the three set, in a settings `env` block, to something that is not a string — a JSON boolean, a number, `null` | it is set there and what it is set to is unknown, so no posture is claimed: the report says whether these tokens are deferred cannot be said from it |
-| a server pinned `"alwaysLoad": true` in its entry | loads at session start whatever the setting says — read from the entry, named with its tokens, and left out of any threshold comparison |
+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. 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.
+
+**The model is written down once, on the methodology page**, because it gets corrected often
+and a second copy here would be a second place to correct:
+[METHODOLOGY §who pays the number](docs/METHODOLOGY.md#who-pays) carries every variable and
+what it resolves to, the four kinds of first-party record the rule admits, the questions the
+report refuses to answer rather than guess, and the address and date behind every claim. What
+follows is what that model looks like when you run it.
 
 On a machine where none of them is set, the same stack reads:
 
@@ -147,7 +135,7 @@ On a machine where none of them is set, the same stack reads:
     a tool whose _meta carries "anthropic/alwaysLoad": true, which this audit does not read from a capture
 ```
 
-**Do not take that table on trust — your own client will tell you.** Everything above is read
+**Do not take that model on trust — your own client will tell you.** All of it is read
 from Anthropic's documentation, and documentation about someone else's product is exactly the
 kind of claim this project refuses to leave unchecked elsewhere. Claude Code writes its own
 decision to a debug log, before it sends anything, so you can check your machine rather than
@@ -164,7 +152,7 @@ Three line shapes answer three different questions:
 |---|---|
 | `[ToolSearch:optimistic] mode=…, ENABLE_TOOL_SEARCH=…, result=…` | which mode it picked at startup, and the value it read. **Optimistic is its own word for a guess** — it can be revised below |
 | `Dynamic tool loading: 0/N deferred tools included` | the one that settles it: how many of the `N` deferrable tools went into the request. `0/N` is deferral actually happening |
-| `[ToolSearch:optimistic] disabled: ANTHROPIC_BASE_URL=… is not a first-party Anthropic host` | the fallback in the table above, firing, in the client's own words |
+| `[ToolSearch:optimistic] disabled: ANTHROPIC_BASE_URL=… is not a first-party Anthropic host` | the base-URL fallback, firing, in the client's own words |
 
 Read the *later* requests, not the first. A stdio server can finish connecting after the first
 request has already gone, so an early low count is a race rather than a finding.
@@ -177,8 +165,8 @@ a proportionally larger one — pass `--context` to `audit` to compare against t
 actually run.
 
 None of this is free, and it is one trivial request. These are Claude Code's own debug lines
-rather than a documented interface, so they can change; the table above is what this project
-holds to a dated re-read. No other client discovered by `audit` writes anything comparable,
+rather than a documented interface, so they can change; the methodology page is what this
+project holds to a dated re-read. No other client discovered by `audit` writes anything comparable,
 which is why no other row here is a measurement: three of them get their vendor's own record,
 dated and addressed, and the rest an absence of one.
 
@@ -189,22 +177,6 @@ tool names plus the server's `instructions` — is measured per server and publi
 leaderboard's `session start` column, and for at least one server in the published set it
 costs **more** than loading the definitions would.
 
-Three things the report will not do: it will not convert between units silently (in
-threshold mode the stack is compared as a range, because the audit counts wire bytes and the
-threshold is counted in what the client sends to the API — measured at 0.19×–1.93× across 86
-servers); it will not claim a posture the machine did not state readably, which is four
-refusals and not one — when two places set the same variable to different values, when a
-settings file exists and cannot be read, when the place that would decide sets the variable
-to something that is not a string, and when `ENABLE_TOOL_SEARCH` holds a value Claude Code
-does not document; and it will not pass an absence of a record off as a measurement, or a
-vendor's record off as one either. The first two print as unanswered questions. The third
-prints as an answer that names itself: for the six discovered clients with no default on
-record — `claude-desktop`, `windsurf`, `gemini`, `zed`, `kiro`, `goose` — the tokens are
-counted as loaded up front, and the report says so in those words, "an absence of a record
-about the client, not a measurement of it". For `cursor`, `codex` and `vscode` it prints the
-vendor's record with its dates and everything it leaves open, and claims no side.
-Full model, sources and dates: [METHODOLOGY §who pays the number](docs/METHODOLOGY.md#who-pays).
-
 **In CI**, make it a gate — the bundlesize move for agents:
 
 ```bash
@@ -212,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:
 
@@ -277,19 +256,18 @@ still match today and silence for the rest. Most installs will show a mix:
 
 ```
   server               tools  tokens   share   claude
-  github                  44  54,422   95.8%   18,406
-  memory                   9   2,378    4.2%       —
+  my-server               18   9,400   79.8%    3,120
+  my-fork                  6   2,380   20.2%       —
 ```
 
-Add `--suggest` to place each of your tools in the measured set's tool-shape distribution
-([method](docs/METHODOLOGY.md#tool-shape)) and get advice only where the data can point at
-something. Only descriptions draw advice — schemas are functional surface; descriptions are
-prose every request carries — and only descriptions at or above the 90th percentile of the
-1,430 measured tools:
+Add `--suggest` to place each of your tools in the measured set's tool-shape distribution and
+get advice only where the data can point at something. What draws a suggestion, what never
+does, and the percentile that decides are in
+[METHODOLOGY §tool shape](docs/METHODOLOGY.md#tool-shape):
 
 ```
   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.
@@ -305,8 +283,8 @@ are not:
 
 ```
   changed — published versions of your servers that have moved since
-  (index 2026-09-04, 2 published captures; matched by canonical hash, never by name):
-    notes (published as obsidian) — you have the capture published 2026-08-19 at 1,132 tokens;
+  (index 2026-09-05, 99 published captures; matched by canonical hash, never by name):
+    notes (published as my-server) — you have the capture published 2026-08-19 at 1,132 tokens;
       the current one is 2,062 (+930, 2026-08-26)
     updating all 1 would add 930 tokens to every request in this client.
 ```
@@ -349,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
@@ -378,9 +356,10 @@ the method is [Claude divergence](docs/METHODOLOGY.md#claude-divergence).
 
 ## Why trust the number?
 
-Every published number is backed by a `measurement.json` containing the raw `tools/list`
-capture, the SHA-256 of its canonical bytes, the pinned tokenizer (`o200k_base`), and the
-exact launch command. Disputes reduce to a byte-level diff:
+Every published number is backed by a `measurement.json`. What it holds, and the five lines
+that re-derive the number from it, are in
+[METHODOLOGY §reproduce it](docs/METHODOLOGY.md#reproduce-it). Disputes reduce to a byte-level
+diff, and the CLI does that for you:
 
 ```bash
 npx -y mcp-context-cost verify results/github/measurement.json
@@ -417,8 +396,8 @@ 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 |
-| `upstream/` | `badge.sh` + composite-action patch + bash tests — the self-serve badge recipe, carried here |
+| `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 |
 | `docs/` | methodology, dashboard, and a generated page per measured server |
@@ -434,14 +413,12 @@ That prints the number and writes nothing. Published records
 (`results/<name>/measurement.json`, `badges/<name>.json`, the `history.csv`
 row) come from CI: a developer machine is a different architecture under
 different load, and a measurement taken there describes it rather than the
-server. `local-mcp`'s failing record was made on an arm64 laptop, and its
-stderr named an architecture the record itself did not — which is why every
-measurement now records `isolation.arch`. The entry turned out to be
-unavailable on both architectures, and a record that says where it was made
-is what lets that be told from a broken server. To get your server into the
-leaderboard, add an entry to `servers.yaml` and open a pull request; the check
-on that PR measures the entry read-only, and the rotation publishes it after
-merge.
+server. Which machine a number applies to, and the failed record that made it
+a rule, are in
+[METHODOLOGY §which machine a number applies to](docs/METHODOLOGY.md#which-machine-a-number-applies-to).
+To get your server into the leaderboard, add an entry to `servers.yaml` and
+open a pull request; the check on that PR measures the entry read-only, and the
+rotation publishes it after merge.
 
 For a badge on your own README, run the published CLI in your server's own CI
 (the [gate](#defend-the-number-dont-just-display-it) below writes
@@ -457,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:
@@ -469,7 +446,7 @@ cp results/my-server/measurement.json .context-cost/baseline.json
 
 # on every pull request
 npx -y mcp-context-cost measure --name my-server --command "node dist/index.js" \
-  --baseline .context-cost/baseline.json --max-increase 500
+  --baseline .context-cost/baseline.json --max-increase 100
 ```
 
 ```
@@ -483,50 +460,18 @@ INCREASE FAIL: +121 tokens, over the 100 allowed — this change adds that to ev
 
 Both sides are single measurements carrying per-tool counts, so an established
 change is attributed exactly: which tools arrived, which grew, and by how much.
-And `--max-increase` fails on more than the number — a server that stops
-starting on the branch makes the total go *down*, and reporting that as an
-improvement is the one mistake a gate like this must not make, so a change that
-could not be established fails too.
+And `--max-increase` fails on more than the number here too: a change that could
+not be established fails the gate, for the reason the `audit` gate gives above.
 
-As a GitHub Action, that whole workflow is five lines
-([full example](examples/server-author-ci.yml)):
-
-```yaml
-- uses: athakur3/mcp-context-cost@v1
-  with:
-    name: my-server
-    command: node dist/index.js
-    baseline: .context-cost/baseline.json
-    max-increase: 500
-```
-
-It exposes `tokens`, `tools`, `status`, `measurement` and `badge` as outputs —
-available whether the gate passed or not — so a later step can comment the
-number on the pull request or publish the badge.
+As a GitHub Action that whole workflow is the five lines at the top of this page
+([full example](examples/server-author-ci.yml)) — the same inputs, and the same
+outputs written whether the gate passed or not, for a later step to comment on
+the pull request or publish as a badge.
 
 Point the link at the measurement behind the number — for servers in this sweep that is
 `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 ~220-line raw-wire
-implementation (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
@@ -536,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
@@ -25,23 +26,23 @@ export interface AuditServerResult {
     toolCount: number | null;
     /** Share of this config's measured total, 0–1. */
     share: number | null;
-    command?: string;
-    url?: string;
+    command?: string | undefined;
+    url?: string | undefined;
     /** Names only — a server's env values never enter a report. */
     envVarNames: string[];
     /** Names only, and only for a remote entry that carries any — values never enter a report. */
-    headerNames?: string[];
+    headerNames?: string[] | undefined;
     /** Claude Code's `alwaysLoad: true`, read from the entry: loads at session start whatever the setting. */
-    alwaysLoad?: true;
-    canonicalSha256?: string | null;
+    alwaysLoad?: true | undefined;
+    canonicalSha256?: string | null | undefined;
     /**
      * Anthropic-request cost from the published Claude divergence run, only when
      * its captured hash matches this install (`--claude`). `null` means the
      * install doesn't match what was published — silence, not a stale guess.
      * `undefined` means `--claude` wasn't requested at all.
      */
-    claudeTokens?: number | null;
-    notes?: string;
+    claudeTokens?: number | null | undefined;
+    notes?: string | undefined;
 }
 export interface HeaviestTool {
     server: string;
@@ -96,9 +97,18 @@ export interface AuditConfigResult {
     heaviestTools: HeaviestTool[];
     trimAdvice: TrimAdvice | null;
     /** Present only when `--suggest` ran with a usable baseline. */
-    suggestions?: ConfigSuggestions;
+    suggestions?: ConfigSuggestions | undefined;
     /** Present only when `--changed` ran with a usable capture index. */
-    captureVerdicts?: ServerCaptureVerdict[];
+    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';
@@ -171,30 +181,73 @@ export interface AuditReport {
          * against the whole stack and the verdict fails rather than passing on a
          * total that understates by an unknown amount.
          */
-        unestablished?: string[];
+        unestablished?: string[] | undefined;
         /** Present only when over budget: the arithmetic of getting back under it. */
-        fit?: BudgetFit;
+        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;
         measuredAt: string;
-    };
+    } | undefined;
     /** Which published tool-shape baseline `--suggest` read its percentiles from. */
     toolShape?: {
         generatedAt: string;
         toolCount: number;
         serverCount: number;
-    };
+    } | undefined;
     /** Which published capture index `--changed` joined against. */
     captureIndex?: {
         generatedAt: string;
         captureCount: number;
-    };
+    } | undefined;
     /** Present only when a baseline report was supplied (`--baseline`). */
-    diff?: AuditDiff;
+    diff?: AuditDiff | undefined;
     /** Present only when `--max-increase` was supplied alongside a baseline. */
-    increaseGate?: IncreaseGate;
+    increaseGate?: IncreaseGate | undefined;
     problems: string[];
 }
 /** Cache key for measurement reuse: the exact argv two configs would spawn. */
@@ -218,38 +271,36 @@ export declare function collapsedKeys(configs: LoadedConfig[]): Set<string>;
  * launching a single server.
  */
 export declare function buildReport(configs: LoadedConfig[], measured: Map<string, Measurement>, opts?: {
-    contextWindow?: number;
-    budget?: number;
-    generatedAt?: string;
+    contextWindow?: number | undefined;
+    budget?: number | undefined;
+    generatedAt?: string | undefined;
     /** Published `tools-delta/v1` run to join against (`--claude`); omit to skip the join. */
-    divergence?: DivergenceRun | null;
+    divergence?: DivergenceRun | null | undefined;
     /** Published `tool-shape/v1` baseline (`--suggest`); omit to skip suggestions. */
-    toolShape?: ToolShapeBaseline | null;
+    toolShape?: ToolShapeBaseline | null | undefined;
     /** Published `capture-index/v1` (`--changed`); omit to skip the version join. */
-    captureIndex?: CaptureIndex | null;
+    captureIndex?: CaptureIndex | null | undefined;
     /**
      * The audited machine's SHELL tool-search variables. Passed in rather than
      * read here so this stays pure and a report is reproducible from its
      * inputs; `runAudit` supplies the real environment. Omitted means the shell
      * set nothing.
      */
-    env?: ToolSearchEnv;
+    env?: ToolSearchEnv | undefined;
     /**
      * The other place those variables come from: Claude Code's own settings
      * files, highest precedence first, as `loadSettingsSources` read them.
      * `runAudit` supplies these. Omitted means they were not read here — which
      * the report says, rather than reporting a default it did not establish.
      */
-    settings?: ToolSearchSource[];
+    settings?: ToolSearchSource[] | undefined;
     /**
      * What each remote endpoint said to an unauthenticated `initialize`, keyed
      * by `serverKey`. `runAudit` supplies it from `probeRemotes`; omitted, a
      * remote entry is reported as not probed rather than as anything else.
      */
-    remotes?: Map<string, RemoteProbe>;
+    remotes?: Map<string, RemoteProbe> | undefined;
 }): AuditReport;
 /** Human output. JSON output is the report object itself. */
 export declare function formatReport(report: AuditReport): string;
-/** Top-level tool list across every config — used by nothing yet, handy for --json consumers. */
-export declare function allHeaviestTools(report: AuditReport, limit?: number): HeaviestTool[];
 export type { ToolMeasurement };