@modelcontextprotocol/inspector 2.13.0 → 2.15.0

package/clients/web/dist/fonts/Fredoka-OFL.txt

@@ -0,0 +1,93 @@
+Copyright 2016 The Fredoka Project Authors (https://github.com/hafontia/Fredoka-One)
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+http://scripts.sil.org/OFL
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded, 
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

package/clients/web/dist/fonts/RobotoMono-OFL.txt

@@ -0,0 +1,93 @@
+Copyright 2015 The Roboto Mono Project Authors (https://github.com/googlefonts/robotomono)
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+https://openfontlicense.org
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded, 
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

package/clients/web/dist/index.html

@@ -4,12 +4,9 @@
     <meta charset="UTF-8" />
     <link rel="icon" type="image/svg+xml" href="/assets/MCP-CWGQJYyH.svg" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <link rel="preconnect" href="https://fonts.googleapis.com" />
-    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
-    <link href="https://fonts.googleapis.com/css2?family=Fredoka:wght@300..700&family=Roboto+Mono:ital,wght@0,100..700;1,100..700&display=swap" rel="stylesheet" />
     <title>MCP Inspector</title>
-    <script type="module" crossorigin src="/assets/index-BqEbhCDX.js"></script>
-    <link rel="stylesheet" crossorigin href="/assets/index-dqp8Sd8W.css">
+    <script type="module" crossorigin src="/assets/index-BZ94R6fh.js"></script>
+    <link rel="stylesheet" crossorigin href="/assets/index-tBehH5iF.css">
   </head>
   <body>
     <div id="root"></div>

package/clients/web/static/sandbox_proxy.html

@@ -33,7 +33,31 @@
          src/utils/sandbox-csp.ts). The proxy assigns that pre-wrapped document
          to `srcdoc` verbatim — it never parses or injects into the untrusted
          bytes — so the CSP `<meta>` is guaranteed to be the first `<head>`
-         child of the inner document. -->
+         child of the inner document.
+
+         Self-navigation: a sandboxed frame may always navigate ITSELF —
+         `allow-top-navigation` governs other frames, not its own — and the
+         sandbox flags follow it, so a page the app navigates to is still
+         opaque ("null") and still `inner.contentWindow`. Nothing in the app's
+         own CSP can stop that (CSP has no shipped navigation directive), so
+         two controls here do instead:
+           1. A `frame-src` / `child-src` policy on THIS document, installed
+              per render before the inner frame is loaded (see
+              `installFramePolicy`). A parent's `frame-src` governs every
+              navigation of its child frame, including one the child starts,
+              so the inner frame can load only the srcdoc (not a fetch, so not
+              subject to it), the dedicated app origin, or the app's approved
+              `frameDomains`. It is a <meta> rather than a header because the
+              sources are only known once the resource-ready message arrives.
+           2. Navigation detection (see `closeNavigatedFrame` and its
+              callers): a navigation 1. refuses raises a policy violation on
+              this document, and on the srcdoc path the frame leaving its
+              document anyway (a navigation 1. allowed, such as to a declared
+              frame domain) is reported by the host wrapper's departure
+              script, and also shows as a second `load`. Any of them closes
+              the relay, removes the frame and tells the host. This half is
+              defense in depth, not the boundary: a navigated page's scripts
+              can run before either signal arrives. -->
     <title>MCP-UI Proxy</title>
     <style>
       html,
@@ -76,6 +100,38 @@
         return allowList.join("; ");
       }
 
+      // The approved `frameDomains` from the resource-ready message's `csp`
+      // (the host has already filtered them; see approveCspSources in
+      // src/utils/sandbox-csp.ts). Re-screened here because they become CSP
+      // source expressions on THIS document: anything carrying whitespace, a
+      // directive or list separator, or a quote (a keyword such as 'self',
+      // which would name this proxy's own origin) is dropped.
+      function approvedFrameSources(csp) {
+        const list = csp && Array.isArray(csp.frameDomains) ? csp.frameDomains : [];
+        return list.filter(
+          (s) => typeof s === "string" && s !== "" && !/[\s;,'"]/.test(s),
+        );
+      }
+
+      // Restrict what the inner frame may be navigated to, by installing a
+      // `frame-src` / `child-src` policy on this document (see the head
+      // comment for why a parent's policy is the control that works). Must run
+      // BEFORE the inner frame starts its navigation. Policies only ever
+      // intersect, so a second call can narrow but never widen what an
+      // earlier one allowed — a re-render in the same proxy document fails
+      // closed. `child-src` is set alongside so the restriction holds even in
+      // a browser that falls back to it for frames; the srcdoc document
+      // inherits this policy too, which is harmless because its own policy
+      // already limits frames to the same `frameDomains` and workers to
+      // 'none'.
+      function installFramePolicy(sources) {
+        const list = sources.length > 0 ? sources.join(" ") : "'none'";
+        const meta = document.createElement("meta");
+        meta.httpEquiv = "Content-Security-Policy";
+        meta.content = `frame-src ${list}; child-src ${list}`;
+        document.head.appendChild(meta);
+      }
+
       // The exact embedder origins this proxy accepts, injected by the sandbox
       // controller when it serves this page (see `embedderOriginsLiteral` in
       // server/sandbox-controller.ts). It is the same list the served
@@ -166,6 +222,95 @@
       // based on the permissions requested by the app
       document.body.appendChild(inner);
 
+      // Set once the inner frame is seen leaving the document the host loaded.
+      // From then on the relay is closed in both directions and every message
+      // is dropped: whatever the frame holds is no longer the app, even though
+      // it still satisfies `event.source === inner.contentWindow` and still
+      // serialises its origin as "null".
+      let navigatedAway = false;
+
+      // Fail closed on a frame that tried to leave its document: stop
+      // relaying, remove the frame (which destroys whatever document it
+      // holds), and tell the host through the app's own logging channel,
+      // which it already surfaces. Idempotent, because one attempt can be
+      // seen twice (a blocked navigation is both a policy violation and, in
+      // Chromium, a second `load` onto an error page).
+      function closeNavigatedFrame(what) {
+        if (navigatedAway) return;
+        navigatedAway = true;
+        inner.remove();
+        console.error(
+          `[Sandbox] the app ${what}; the frame was removed and the relay closed.`,
+        );
+        window.parent.postMessage(
+          {
+            jsonrpc: "2.0",
+            method: "notifications/message",
+            params: {
+              level: "error",
+              logger: "mcp-inspector-sandbox",
+              data: `The MCP App ${what}. The Inspector removed the frame and stopped relaying messages; reload the app to try again.`,
+            },
+          },
+          EXPECTED_HOST_ORIGIN,
+        );
+      }
+
+      // A navigation the frame policy (installFramePolicy) refuses is
+      // reported HERE, on the policy's own document. Engines differ in what
+      // follows: Chromium commits an error page (a second `load`), while
+      // Firefox leaves the original document in place and fires nothing
+      // further. The violation is the one signal both give, so it is what
+      // makes the attempt visible to the host everywhere. The app's own
+      // nested-frame violations are reported to the app's document, not
+      // this one, so they do not reach this listener.
+      document.addEventListener("securitypolicyviolation", (e) => {
+        if (
+          e.effectiveDirective === "frame-src" ||
+          e.effectiveDirective === "child-src"
+        ) {
+          closeNavigatedFrame(
+            "tried to navigate its frame to an origin it did not declare",
+          );
+        }
+      });
+
+      // Watch a srcdoc load for the frame navigating itself elsewhere. The
+      // srcdoc document fires at most one `load`, so any later one is a
+      // different document — another page (one the frame policy allowed,
+      // such as a declared frame domain), a blocked navigation's error page,
+      // or a reload. All of them close the frame. A navigation started while
+      // the srcdoc is still loading aborts it before its `load`, so the next
+      // document's `load` is the FIRST one; that case is caught by the
+      // departure message instead (see DEPARTURE_MESSAGE_KEY).
+      //
+      // The frame is detached while it is configured and re-attached after
+      // the listener is on, so the only `load` it can fire first is the
+      // srcdoc's: inserting a frame that already carries `srcdoc` skips the
+      // initial about:blank `load` that a bare frame would fire, which is what
+      // makes "the second load" unambiguous across engines.
+      function loadSrcdocWatchingForNavigation(html) {
+        inner.remove();
+        inner.srcdoc = html;
+        let loads = 0;
+        inner.addEventListener("load", function onLoad() {
+          loads += 1;
+          if (loads === 1) return;
+          inner.removeEventListener("load", onLoad);
+          closeNavigatedFrame(
+            "navigated its frame away from the document the host loaded",
+          );
+        });
+        document.body.appendChild(inner);
+      }
+
+      // The host wrapper (wrapSandboxedHtml in src/utils/sandbox-csp.ts)
+      // runs a script ahead of the app's code that posts
+      // `{ mcpInspectorSandbox: "departing" }` when the srcdoc document starts
+      // to leave (`beforeunload` / `pagehide`), whether or not it ever
+      // finished loading. It is consumed here and never relayed.
+      const DEPARTURE_MESSAGE_KEY = "mcpInspectorSandbox";
+
       const RESOURCE_READY_NOTIFICATION =
         "ui/notifications/sandbox-resource-ready";
       const PROXY_READY_NOTIFICATION = "ui/notifications/sandbox-proxy-ready";
@@ -190,6 +335,9 @@
       // never parses or injects into the untrusted bytes.
 
       window.addEventListener("message", async (event) => {
+        // Closed for good once the frame navigated away (see
+        // loadSrcdocWatchingForNavigation): nothing is relayed either way.
+        if (navigatedAway) return;
         if (event.source === window.parent) {
           // Validate that messages from parent come from the expected host origin.
           // This prevents malicious pages from sending messages to this sandbox.
@@ -204,7 +352,7 @@
           }
 
           if (event.data && event.data.method === RESOURCE_READY_NOTIFICATION) {
-            const { html, sandbox, permissions, src } = event.data.params;
+            const { html, sandbox, permissions, src, csp } = event.data.params;
             // The host asked for the dedicated-origin path: it published the
             // wrapped document to its own app-origin listener and is handing
             // us the URL. Only an absolute http(s) URL is honored — anything
@@ -299,6 +447,10 @@
               // an app silently rendering the wrong bytes.
               inner.removeAttribute("srcdoc");
               innerOrigin = srcUrl.origin;
+              // The frame may hold only the app-origin document. That
+              // document's own nested frames are governed by its own header
+              // (it is not srcdoc, so it does not inherit this policy).
+              installFramePolicy([srcUrl.origin]);
               inner.src = srcUrl.href;
             } else if (typeof html === "string") {
               // The host has already wrapped the app's HTML in a fixed shell
@@ -323,16 +475,25 @@
                 .filter((t) => t && t.toLowerCase() !== "allow-same-origin");
               inner.setAttribute("sandbox", fallbackTokens.join(" "));
               innerOrigin = "null";
-              inner.srcdoc = html;
+              // The srcdoc load itself is not a fetch, so `frame-src` does not
+              // apply to it; what it does stop is the frame being navigated to
+              // anything but the app's approved `frameDomains` afterwards.
+              installFramePolicy(approvedFrameSources(csp));
+              loadSrcdocWatchingForNavigation(html);
             }
           } else {
             if (inner && inner.contentWindow) {
               // Target the inner frame's real origin on the dedicated-origin
               // path, so a frame that navigated itself elsewhere stops
               // receiving host messages. The opaque default has no targetable
-              // origin ("null" is not a valid targetOrigin), so it keeps "*" —
-              // safe there because the frame is `srcdoc` and cannot navigate
-              // to another origin's document without allow-top-navigation.
+              // origin ("null" is not a valid targetOrigin), so it has to use
+              // "*" — which on its own would deliver to WHATEVER document the
+              // frame holds: a sandboxed frame can navigate itself to another
+              // origin without allow-top-navigation, and the new page keeps the
+              // opaque origin and the same contentWindow. What keeps "*" from
+              // reaching such a page is the frame policy (installFramePolicy),
+              // which blocks the navigation, and the navigation watch, which
+              // closes this relay if the frame leaves its document anyway.
               inner.contentWindow.postMessage(
                 event.data,
                 innerOrigin === "null" ? "*" : innerOrigin,
@@ -354,6 +515,16 @@
             );
             return;
           }
+          if (event.data && event.data[DEPARTURE_MESSAGE_KEY] === "departing") {
+            // Only the opaque srcdoc path watches for departure: a
+            // dedicated-origin app is targeted by its real origin instead.
+            if (innerOrigin === "null") {
+              closeNavigatedFrame(
+                "navigated its frame away from the document the host loaded",
+              );
+            }
+            return;
+          }
           // Relay messages from inner frame to parent window.
           // Use specific origin instead of "*" to prevent message interception.
           window.parent.postMessage(event.data, EXPECTED_HOST_ORIGIN);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@modelcontextprotocol/inspector",
-  "version": "2.13.0",
+  "version": "2.15.0",
   "description": "The Model Context Protocol Inspector",
   "keywords": [
     "MCP",
@@ -111,6 +111,7 @@
     "smoke:web:browser": "node scripts/install-smoke-browser.mjs && node scripts/smoke-web-browser.mjs",
     "smoke:web:app": "node scripts/install-smoke-browser.mjs && node scripts/smoke-web-app.mjs",
     "smoke:web:elicit": "node scripts/install-smoke-browser.mjs && node scripts/smoke-web-elicitation.mjs",
+    "smoke:web:sandbox": "node scripts/install-smoke-browser.mjs && node scripts/smoke-web-sandbox-navigation.mjs",
     "smoke:web:tabs": "node scripts/install-smoke-browser.mjs chromium && node scripts/smoke-web-tabs.mjs chromium",
     "smoke:web:engine": "node scripts/run-engine-smokes.mjs",
     "smoke:web:chromium": "node scripts/run-engine-smokes.mjs chromium",
@@ -148,7 +149,7 @@
     "zod": "^4.4.3"
   },
   "engines": {
-    "node": ">=22.19.0"
+    "node": "^22.23.4 || ^24.22.1 || >=26.12.1"
   },
   "allowScripts": {
     "fsevents": false
@@ -158,7 +159,7 @@
     "@modelcontextprotocol/server-legacy": "2.4.0",
     "@types/node": "^24.12.4",
     "@types/proper-lockfile": "^4.1.4",
-    "@vitest/coverage-v8": "4.1.11",
+    "@vitest/coverage-v8": "4.1.12",
     "eslint": "^10.8.0",
     "eslint-plugin-react-hooks": "^7.1.1",
     "express": "^5.2.1",
@@ -167,6 +168,9 @@
     "semver": "^7.8.5",
     "typescript": "~5.9.3",
     "typescript-eslint": "^8.65.0",
-    "vitest": "4.1.11"
+    "vitest": "4.1.12"
+  },
+  "overrides": {
+    "minimatch": "^11.0.4"
   }
 }

package/skills/mcpdo/SKILL.md

@@ -79,7 +79,10 @@ more).
 - Connections persist across separate `mcpdo` invocations and **self-heal**: a
   dropped transport (expired session, exited stdio child) transparently
   re-dials on next use with stored credentials. Don't monitor or reconnect
-  manually; only an `auth_required` error needs action (re-run `connect`).
+  manually; only an exit-`3` auth error needs action (re-run `connect`):
+  `auth_required`, `oauth_error` (the authorization server refused — its
+  `oauthError` / `oauthErrorDescription` say why), or `oauth_timeout` (the
+  sign-in was not completed in time).
   `mcpdo disconnect` ends one connection; `mcpdo daemon stop` resets
   everything.
 - The `[legacy]` / `[modern]` era tag on `connections/list` is the negotiated
@@ -97,7 +100,10 @@ more).
   stdio server) or to more than one URL is rejected with guidance. EMA IdP
   login records lead with their bare issuer URL and carry a trailing
   `enterprise IdP login` marker, and clear by that bare issuer URL
-  (`mcpdo auth/clear https://idp.example.com`). Run `connect` as its **own
+  (`mcpdo auth/clear https://idp.example.com`). To diagnose a 401/403 —
+  wrong audience, missing scope, expired token — run `mcpdo auth/show <url or
+  name>`: it prints the stored access token's decoded claims (unverified) and
+  expiry relative to now, never the token itself. Run `connect` as its **own
   command** — never chained with `&&`, `;`, or a follow-on
   `tools/list`/`connections/show`. A connect that needs sign-in exits 0 while
   the connection is still unusable, so a chained command runs against a
@@ -163,3 +169,58 @@ more).
 - Parked calls expire after 10 minutes; one parked call per connection. Pass
   `--elicit off` on `connect` to have well-behaved servers fall back to their
   own defaults instead of asking.
+
+## Load runs (`tools/call --load`)
+
+- The summary's `latencyMs` and `okThroughput` cover **successful** calls
+  only; failures are timed in `errorLatencyMs`, and `isError` results' text
+  is tallied in `toolErrorMessages` (thrown ones in `errorMessages`). Judge a
+  run on these, not on `throughput`, which counts failures too.
+- With `--load-rate`, compare `achievedRate` to `rate` and read
+  `droppedSlots`: slots nobody was free to take are dropped, so a server too
+  slow for the target can still report healthy latency. A shortfall under 90%
+  also prints a warning on stderr.
+- `--load-scenario <file>` (no tool name) loads a weighted mix of
+  `tools/call` / `resources/read` / `prompts/get` steps; the top-level counts
+  are totals and `steps[]` breaks them down per step — find the slow or
+  failing step there.
+- Identical calls flatter a caching server. Vary them with placeholders in
+  argument values (`id:=user-{{seq}}`, `{{uuid}}`, `{{rand:1-50}}`,
+  `{{worker}}`) or `--load-args-file rows.ndjson` (one argument object per
+  line, cycled; `--load-args-random` to shuffle).
+- To find a server's knee, step the load: `--load-steps 10,25,50` or
+  `--load-ramp 10:100:60` (concurrency; `--load-step-by rate` for rate), each
+  stage `--load-step-duration` seconds. Read `stages[]` top to bottom for
+  where `latencyMs.p99` or `errorRate` jumps. `--load-stop-on-breach` with a
+  `--load-max-*` threshold stops at the first breaching stage.
+- Latency has `p50`/`p90`/`p95`/`p99`/`p999`. Gate a run with
+  `--load-max-p50`/`-p95`/`-p99`, `--load-max-error-rate` or
+  `--load-min-throughput` (ok calls/s); a breach exits `10` after the summary.
+  To gate on "no worse than last time", save a `--format json` summary and
+  pass `--load-baseline prev.json --load-max-regression 10%` on the same run
+  shape (`load_regression` on a regression, `load_baseline_mismatch` when the
+  runs differ in tool, concurrency, bounds, rate or stages).
+- `--load-interval <sec>` adds an `intervals[]` time series (spot a GC pause
+  or a slow leak the totals hide); `--load-warmup <sec>` leaves a warm-up out
+  of the statistics (reported under `warmup`). Progress lines on stderr appear
+  only with `--format text`.
+- If the generator rather than the server is the bottleneck (throughput stops
+  rising while the server is idle), mcpdo cannot help: use the one-shot CLI's
+  `mcp-inspector --cli <url> … --load --load-workers 4`, which spreads the
+  run over processes and merges one summary.
+- To measure notification fan-out, `--load-subscribe <uri>
+  --load-subscribers 50` subscribes 50 sessions; a tool name makes each
+  successful call a trigger (latency from its start), and no tool listens for
+  `--load-duration` to the server's own updates. Read `fanout.missed` and
+  `fanout.deliveryMs`.
+- To load session setup and teardown too (servers behind gateways see many
+  short sessions), add `--load-churn` (HTTP/SSE only): each worker connects,
+  makes `--load-churn-calls` calls (default `1`), disconnects, repeats.
+  Connect cost is in `churn.connectMs`, not in `latencyMs`.
+- `--load-rate` is closed-loop: busy workers drop slots, which hides
+  queueing. Add `--load-open-loop` to keep every slot and time calls from
+  their scheduled start (`openLoop: true` in the summary).
+- `stoppedEarly` (`reason` + `detail`) means the run ended before its bounds:
+  `consecutive_errors` (the server stopped answering), `connection_lost`,
+  `threshold_breached` (a stepped run's `--load-stop-on-breach`), or
+  `interrupted`. The counts cover only what completed.