echelongraph-mcp 2.2.0 → 2.3.1

package/README.md

@@ -18,14 +18,34 @@ API call a tool needs to answer.
 | Tool | What it does |
 |---|---|
 | `cve_summary` | Counts of active CVEs by severity, and when the feed was last updated. |
-| `search_cves` | Search/filter CVEs (severity, min CVSS, text, sort) with EchelonGraph scores. |
-| `get_cve` | Full record for one CVE: CVSS v3 and (when scored) v4, the EchelonGraph score and its confidence, EPSS, CISA-KEV status and known ransomware use, the GitHub GHSA id, references, and its published, modified and `updated_at` times. |
+| `search_cves` | Search/filter CVEs (severity, min CVSS, text, sort) with EchelonGraph scores and `score_assessed`; the note names each row not yet scored. |
+| `get_cve` | Full record for one CVE: CVSS v3 and (when scored) v4, the EchelonGraph score and its confidence, whether EchelonGraph has scored it (`score_assessed`), EPSS, CISA-KEV status and known ransomware use, the GitHub GHSA id, references, and its published, modified and `updated_at` times. |
 | `cve_exposure` | Internet-exposure footprint for a CVE: exposed service count (distinct ip:port, the `exposed_hosts` field) + country/product breakdown, from the KEV-exposure radar. |
-| `exposure_radar` | Aggregate totals across the exposure radars: services running CISA-KEV CVEs; unauthenticated data stores and observability UIs, found through Shodan (LeakIX when Shodan query credits run low) and then confirmed by EchelonGraph's own identified check, which is not a pure read (on Redis it names its client; on ClickHouse its query lands in the server's query log); leaked credentials; shadow AI. Every number is labelled by what it counts, and a field the tool cannot label is left out and named. |
+| `exposure_radar` | Aggregate totals across the exposure radars: services running CISA-KEV CVEs; unauthenticated data stores and observability UIs, found through Shodan (LeakIX when Shodan query credits run low) and then confirmed by EchelonGraph's own identified check, which is not a pure read (on Redis it names its client; on ClickHouse its query lands in the server's query log); leaked credentials; shadow AI; and MCP servers found in EchelonGraph's own Certificate Transparency feed, by RFC 9728 verdict, protocol era and transport. Every number is labelled by what it counts, and a field the tool cannot label is left out and named. |
 
 Every figure is as fresh as the schedule that refreshes it. The CVE feed is polled from its
 sources on a schedule; each radar refreshes on its own.
 
+### How `get_cve` and `search_cves` read the EchelonGraph score
+
+`echelongraph_score` (0 to 10), its band `echelongraph_severity` and the risk priority
+`echelongraph_risk` (0 to 100) are EchelonGraph's score only when the record's
+`score_assessed` is `true`. A CVE EchelonGraph has not scored carries `score_assessed: false`,
+and it is **not yet scored**, not scored 0. The API leaves those three fields out on it, or (an
+API before that change) sends `0`, `NONE` and `0` as placeholders, which are not a rating and do
+not mean the CVE is harmless. Its `score_confidence` is `NONE`, and `score_unassessed_reason`
+says why: no source has yet published severity data EchelonGraph can score, or the record was
+rejected (withdrawn) by its numbering authority, and a rejected record is never scored.
+
+Both tools relay the API's JSON as it was sent, and the note says what the score is, for
+`get_cve` per CVE and for `search_cves` per row, naming each CVE it is about:
+
+| API answer | What the note says |
+|---|---|
+| `score_assessed: true` | Nothing more: the score is a score. |
+| `score_assessed: false` | **NOT YET SCORED**, tagged "(score_assessed: false)": report the CVE as not yet scored, never as a zero or low score. Each of `echelongraph_score`, `echelongraph_severity` and `echelongraph_risk` it carries is named as a placeholder. A rejected record is **NOT SCORED** instead. |
+| no `score_assessed` field | The answer does not say whether the CVE was scored (an API older than the field), and a zero `echelongraph_score` in it is not a rating. |
+
 ### How `cve_exposure` counts
 
 Every 12 hours, when Shodan query credits allow, the KEV-exposure radar runs one Shodan query
@@ -164,6 +184,74 @@ its name and its count, and a field added to one is named too. The `poller` bloc
 checked the same way: a key this version does not know is left out and named, while the
 instance fields it knows are left out as described below.
 
+#### `mcp_servers`
+
+The AI-exposure radar's MCP-server verdicts, from `GET /api/v1/public/ai-exposure/stats?service=mcp`.
+Every hostname was named like an MCP server in EchelonGraph's own Certificate Transparency
+feed, matched by hostname pattern; no Shodan data is used. Each is checked by EchelonGraph's
+identified MCP probe: a `server/discover` request, and `initialize` only if that is refused. It
+never sends `tools/call`. The answer is counts and timestamps only, with no hostname, version or
+server name, and the tool repeats no string it carries but its timestamps. Each hostname is
+counted once, by its latest verdict on record, and EchelonGraph's own control servers are left
+out. The unit is a hostname, not an ip:port service.
+
+| Field | What it counts |
+|---|---|
+| `mcp_servers.total` | Hostnames the radar has checked for an MCP server, each once, by its latest verdict on record. Not every one is an MCP server: see `mcp_servers.not_assessed_by_reason`. It is `mcp_servers.protected` + `mcp_servers.pending_readjudication` + `mcp_servers.not_assessed`. |
+| `mcp_servers.protected` | Hostnames whose `/mcp` endpoint asked for credentials (a 401 or 403) and whose OAuth protected-resource metadata validated under RFC 9728: a 200 JSON document whose resource is identical to the server's identifier and that names at least one authorization server. |
+| `mcp_servers.prm_via.header`, `mcp_servers.prm_via.wellknown_path`, `mcp_servers.prm_via.wellknown_root` | The protected ones, by where that document was found: the same-origin URL the credential challenge named; `/.well-known/oauth-protected-resource` followed by the endpoint's path; or `/.well-known/oauth-protected-resource` itself. They add up to `mcp_servers.protected`. |
+| `mcp_servers.pending_readjudication` | Verdicts decided by a rule EchelonGraph has since replaced and not yet re-checked under the current rules. They are in neither `mcp_servers.protected` nor `mcp_servers.not_assessed`. |
+| `mcp_servers.not_assessed` | The rest, whose protection the radar could not assess. Not assessed does not mean unprotected. `mcp_servers.not_assessed_by_reason` puts each of them in exactly one bucket (below). |
+| `mcp_servers.own_controls_excluded` | EchelonGraph's own control servers, left out of every other `mcp_servers` number. |
+| `mcp_servers.window.from`, `mcp_servers.window.to` | Timestamps, not counts: when the oldest and the newest of the verdicts counted were last checked. The counts are each hostname's latest verdict, not one sweep at one time. With no verdict counted there is no window. |
+| `mcp_servers.last_run_at` | A timestamp, not a count: when the AI-exposure radar, which checks other AI services as well as MCP servers, last completed a check (a cycle whose reads succeeded and whose scan opt-out register answered). It is not the time of every verdict counted. |
+| `mcp_servers.enabled` | Whether the API reports the radar running: true when a check completed within 45 minutes of its answer. |
+| `mcp_servers.counted_at` | A timestamp, not a count: when the API read these counts. |
+
+`mcp_servers.not_assessed_by_reason` divides `mcp_servers.not_assessed`:
+
+| Bucket | What it holds |
+|---|---|
+| `mcp_servers.not_assessed_by_reason.identified_no_challenge` | Servers that identified themselves as MCP servers (a DiscoverResult, an InitializeResult, or the endpoint event of the deprecated HTTP+SSE transport) and did not ask for credentials at the handshake. That is normal in MCP: authorization is optional in the spec, and a server can enforce it at `tools/call` instead, which EchelonGraph never sends. So this bucket is not a finding of exposure. |
+| `mcp_servers.not_assessed_by_reason.resource_mismatch` | An endpoint that asked for credentials, whose metadata document's resource is absent or not identical to the server's identifier. |
+| `mcp_servers.not_assessed_by_reason.cross_origin_pointer` | An endpoint that asked for credentials, whose challenge named a metadata URL on another origin, which EchelonGraph records and does not request. |
+| `mcp_servers.not_assessed_by_reason.bare_challenge_no_prm` | An endpoint that asked for credentials, whose challenge named no metadata URL, and neither well-known URI answered 2xx. |
+| `mcp_servers.not_assessed_by_reason.pointer_unreachable` | An endpoint that asked for credentials, whose same-origin metadata URL did not answer 2xx in full. |
+| `mcp_servers.not_assessed_by_reason.pointer_invalid` | An endpoint that asked for credentials, whose challenge's metadata pointer is not a URL EchelonGraph will request. |
+| `mcp_servers.not_assessed_by_reason.no_authorization_servers` | An endpoint that asked for credentials, whose metadata document names no authorization server. |
+| `mcp_servers.not_assessed_by_reason.wellknown_unreachable` | An endpoint that asked for credentials, where a well-known metadata request got no complete HTTP answer. |
+| `mcp_servers.not_assessed_by_reason.metadata_invalid` | An endpoint that asked for credentials, whose metadata answer is not a 200 with a JSON object within the size cap. |
+| `mcp_servers.not_assessed_by_reason.challenge_unadjudicated` | An endpoint that asked for credentials before EchelonGraph read RFC 9728 metadata, not re-checked since. |
+| `mcp_servers.not_assessed_by_reason.no_http_answer` | Hostnames that gave no HTTP answer: DNS, TCP or TLS failed, or the request timed out. Not a count of MCP servers. |
+| `mcp_servers.not_assessed_by_reason.not_identified_as_mcp` | Hostnames that answered HTTP with nothing that identified an MCP server: a login or error page, a body that is not JSON-RPC, a 4xx or 5xx. Not a count of MCP servers. |
+
+The eight credential-challenge buckets hold endpoints that asked for credentials: only their
+metadata did not validate, so none of them is shown to lack protection.
+
+`mcp_servers.era` and `mcp_servers.transport` each divide every counted hostname, so each adds
+up to `mcp_servers.total`:
+
+| Bucket | What it holds |
+|---|---|
+| `mcp_servers.era.legacy` | An initialize-era server: an InitializeResult, or the endpoint event of the deprecated HTTP+SSE transport. |
+| `mcp_servers.era.dual` | A server that answered `server/discover` and itself named an initialize-era version too. A lower bound: a server built on the reference SDK names only modern versions there, and is counted modern. |
+| `mcp_servers.era.modern` | A server that answered `server/discover` and named no initialize-era version. Not proven modern-only: EchelonGraph does not send it `initialize` to tell. |
+| `mcp_servers.era.unknown` | Nothing identified an era; every credential challenge is here. |
+| `mcp_servers.era.not_measured` | A verdict recorded before EchelonGraph's probe began recording the era, not re-checked since. |
+| `mcp_servers.transport.streamable_http` | Identified by a POST to `/mcp`. |
+| `mcp_servers.transport.legacy_sse` | Identified by the endpoint event of `GET /sse`, the deprecated HTTP+SSE transport. |
+| `mcp_servers.transport.unknown` | Nothing identified a transport. |
+| `mcp_servers.transport.not_measured` | Recorded before the era probe, not re-checked since. |
+
+The tool refuses the answer, as a failure of that radar and never as zeros, when it does not say
+`service` `mcp` (an API older than `?service=mcp` ignores the parameter and answers its counts
+over every AI service it checks), when `mcp_servers.total`, `mcp_servers.protected`,
+`mcp_servers.pending_readjudication` or `mcp_servers.not_assessed` is missing or not a whole
+number, or when they contradict each other. A partition whose buckets are not exactly those
+above, each a whole number adding up to the count it divides, is left out whole and named. A
+field this version does not know is left out, and named only when its name is shaped like a
+field name.
+
 ## What a result means
 
 Every tool answers in one of two shapes, so a model reading the result cannot mistake an
@@ -255,9 +343,11 @@ a note says so. Per tool:
   `cve_exposure` counts", and `coverage.in_scope` is the API's `tracked`. It becomes `measured`
   only when the API serves a time at which the counted services were observed.
 - `exposure_radar` is `not_assessed` with `measured_at` `null`: every radar answered, but no
-  stats answer says when the services or records it counts were observed, so no count is
-  presented as a dated measurement. Its numbers keep the labels above. `freshness` holds each
-  radar's `last_run_at` where the API serves one, and for `shadow_ai` also `running`.
+  answer gives one time at which what it counts was observed, so no count is presented as a
+  dated measurement. `mcp_servers` dates its verdicts only by a window, `mcp_servers.window.from`
+  to `mcp_servers.window.to`, over checks made at different times, which is not one observation
+  time. Its numbers keep the labels above. `freshness` holds each radar's `last_run_at` where the
+  API serves one, for `shadow_ai` also `running`, and for `mcp_servers` also `enabled`.
 
 The CVE feed tools' `freshness` is `null`: the feed's answers carry no time at which its
 pollers last completed a poll for the feed as a whole.

package/dist/index.js

@@ -12,9 +12,9 @@
 //     the call succeeded, where, and what it found — in words, including when it found
 //     nothing ("we looked and found nothing" is a measurement). One exception: exposure_radar
 //     relays each radar's answer cut to the fields it can label by what they count, and names
-//     what it left out (readKEVExposure, readExposedDatabases, readLeakedCredentials and
-//     readShadowAI; #2307, #2313). content[2] is the envelope below, as JSON, less what
-//     content[0] and the note already say.
+//     what it left out (readKEVExposure, readExposedDatabases, readLeakedCredentials,
+//     readShadowAI and readMCPServers; #2307, #2313, #2315). content[2] is the envelope below,
+//     as JSON, less what content[0] and the note already say.
 //   - failure (isError: true): the lookup did not complete — unreachable host, non-2xx,
 //     timeout, or a 2xx whose body is not a JSON object — named by tool, cause and base URL,
 //     in content[0]; content[1] is the envelope below, as JSON, less the message's sentences.
@@ -199,6 +199,8 @@ function describeFailure(f) {
             return `EchelonGraph answered HTTP ${f.status} ${where} but the body was not JSON (${f.detail}).`;
         case "not_object":
             return `EchelonGraph answered HTTP ${f.status} ${where} but the body was not a JSON object (${f.detail}).`;
+        case "unexpected_shape":
+            return `EchelonGraph answered HTTP ${f.status} ${where}, but ${f.detail}.`;
     }
 }
 // What a model must not conclude from a failure.
@@ -330,6 +332,60 @@ const realInstant = (s) => s !== undefined && Date.parse(s) > 0;
 // Stats, in memory), and is relayed in data but not presented as the feed's freshness.
 const CVE_FEED_METHOD = "EchelonGraph's CVE Pulse feed: CVE records compiled from NVD, MITRE-CNA pre-NVD records, CISA-KEV, EPSS and GitHub GHSA, each polled from its source on a schedule.";
 const NO_FEED_FRESHNESS = "freshness is null: the CVE feed's answer carries no time at which its pollers last completed a poll for the feed as a whole.";
+function scoreStateOf(rec) {
+    const v = boolAt(rec, "score_assessed");
+    return v === true ? "assessed" : v === false ? "not_assessed" : "unstated";
+}
+const scoreRejected = (rec) => strAt(rec, "score_unassessed_reason") === "rejected";
+// The fields that hold a placeholder, not a score, on a CVE that is not scored.
+const PLACEHOLDER_FIELDS = ["echelongraph_score", "echelongraph_severity", "echelongraph_risk"];
+// No sentence below writes a digit: a note that says "0" beside "score" is the defect itself.
+const UNSTATED_SCORE = "echelongraph_score is EchelonGraph's score only when score_assessed is true, so a zero echelongraph_score there is not a rating: it can be the placeholder a CVE not yet scored carries.";
+// get_cve's sentences about the one CVE's score, each starting with a space; none when the
+// answer says the CVE is scored.
+function cveScoreNote(cve, rec) {
+    const state = scoreStateOf(rec);
+    if (state === "assessed")
+        return "";
+    if (state === "unstated") {
+        return ` The answer does not say whether EchelonGraph has scored ${cve}: it carries no score_assessed (an API older than that field sends none). ${UNSTATED_SCORE}`;
+    }
+    const rejected = scoreRejected(rec);
+    const reportAs = rejected ? "not scored" : "not yet scored";
+    const head = rejected
+        ? ` (score_assessed: false) NOT SCORED: the record of ${cve} was rejected (withdrawn) by its numbering authority (score_unassessed_reason rejected), and EchelonGraph does not score a withdrawn record, so the record holds no EchelonGraph score for it.`
+        : ` (score_assessed: false) NOT YET SCORED: EchelonGraph has not yet scored ${cve}, so the record holds no EchelonGraph score for it, and the absence of one does not mean ${cve} is harmless.`;
+    const why = strAt(rec, "score_unassessed_reason") === "no_signal" ? " score_unassessed_reason is no_signal: no source has yet published severity data EchelonGraph can score." : "";
+    const carried = PLACEHOLDER_FIELDS.filter((k) => field(rec, k) !== undefined && field(rec, k) !== null);
+    const placeholders = carried.length
+        ? ` ${listed(carried)} ${carried.length === 1 ? "is a placeholder" : "are placeholders"}, not a score: report ${cve} as ${reportAs}, and do not repeat ${carried.length === 1 ? "that value" : "those values"} as its score.`
+        : ` Report ${cve} as ${reportAs}, not as a zero or low score.`;
+    return `${head}${why}${placeholders}`;
+}
+// search_cves' sentences about its rows' scores, naming each row a sentence is about, each
+// starting with a space; none when every row says it is scored.
+function rowsScoreNote(d) {
+    const rows = field(d, "cves");
+    if (!Array.isArray(rows) || rows.length === 0)
+        return "";
+    const n = rows.length;
+    const ids = (pred) => rows.flatMap((r, i) => (pred(r) ? [strAt(r, "cve_id") ?? `cves[${i}]`] : []));
+    const notYet = ids((r) => scoreStateOf(r) === "not_assessed" && !scoreRejected(r));
+    const rejected = ids((r) => scoreStateOf(r) === "not_assessed" && scoreRejected(r));
+    const unstated = ids((r) => scoreStateOf(r) === "unstated");
+    const of = (k) => (k < n ? `${k} of the ${n} CVEs in this page` : n === 1 ? "the 1 CVE in this page" : `all ${n} CVEs in this page`);
+    const out = [];
+    if (notYet.length) {
+        out.push(`(score_assessed: false) NOT YET SCORED: ${of(notYet.length)} ${be(notYet.length)} not yet scored by EchelonGraph: ${listed(notYet)}. For each, echelongraph_score, echelongraph_severity and echelongraph_risk, where its row carries them, are placeholders, not a score, and the absence of a score does not mean the CVE is harmless: report each as not yet scored, not as a zero or low score.`);
+    }
+    if (rejected.length) {
+        out.push(`(score_assessed: false) NOT SCORED: ${of(rejected.length)} ${rejected.length === 1 ? "has a record" : "have records"} rejected (withdrawn) by the numbering authority (score_unassessed_reason rejected), which EchelonGraph does not score: ${listed(rejected)}. For each, echelongraph_score, echelongraph_severity and echelongraph_risk, where its row carries them, are placeholders, not a score: report each as not scored.`);
+    }
+    if (unstated.length) {
+        out.push(`The answer does not say whether EchelonGraph has scored ${of(unstated.length)}: ${listed(unstated)} (no score_assessed in ${unstated.length === 1 ? "its row" : "their rows"}; an API older than that field sends none). ${UNSTATED_SCORE}`);
+    }
+    return out.map((s) => ` ${s}`).join("");
+}
 async function cveSummary() {
     const tool = "cve_summary";
     try {
@@ -409,21 +465,24 @@ async function searchCVEs(a) {
         const relaxedNote = relaxed === true
             ? " The API relaxed the search phrase to all of its words (search_relaxed is true), so these rows are a superset of the rows that match the phrase itself."
             : "";
+        // Then what each row's score is (#2535): empty when every row says it is scored, or there
+        // are no rows.
+        const tail = `${relaxedNote}${rowsScoreNote(r.data)}`;
         // A total the API did not count is not a count: the page's own rows are all that is known.
         if (counted === false) {
             const empty = shown === 0 && (offset ?? 0) === 0;
             return succeeded(r.data, empty
-                ? `${head} The query returned 0 CVEs — a measured empty result: EchelonGraph was queried successfully and nothing matched these filters (we looked and found nothing). This is not a lookup failure.${relaxedNote}`
-                : `${head} The API did not count the matches (total_counted is false), so its total is not a count${shown === undefined ? "" : `; ${shown} returned in this page`}.${relaxedNote}`, env);
+                ? `${head} The query returned 0 CVEs — a measured empty result: EchelonGraph was queried successfully and nothing matched these filters (we looked and found nothing). This is not a lookup failure.${tail}`
+                : `${head} The API did not count the matches (total_counted is false), so its total is not a count${shown === undefined ? "" : `; ${shown} returned in this page`}.${tail}`, env);
         }
         const total = numAt(r.data, "total") ?? shown;
         if (total === undefined)
-            return succeeded(r.data, `${head}${relaxedNote}`, env);
+            return succeeded(r.data, `${head}${tail}`, env);
         if (total === 0 && floor !== true) {
-            return succeeded(r.data, `${head} The query matched 0 CVEs — a measured empty result: EchelonGraph was queried successfully and nothing matched these filters (we looked and found nothing). This is not a lookup failure.${relaxedNote}`, env);
+            return succeeded(r.data, `${head} The query matched 0 CVEs — a measured empty result: EchelonGraph was queried successfully and nothing matched these filters (we looked and found nothing). This is not a lookup failure.${tail}`, env);
         }
         const matched = floor === true ? `at least ${total} CVEs (total_is_lower_bound is true: the count stopped at that floor)` : `${total} CVEs`;
-        return succeeded(r.data, `${head} The query matched ${matched}${shown === undefined ? "" : `; ${shown} returned in this page`}.${relaxedNote}`, env);
+        return succeeded(r.data, `${head} The query matched ${matched}${shown === undefined ? "" : `; ${shown} returned in this page`}.${tail}`, env);
     }
     catch (e) {
         return crashed(tool, e);
@@ -439,7 +498,8 @@ async function getCVE(cve_id) {
         if (!r.ok)
             return failed(tool, r);
         const written = strAt(r.data, "updated_at");
-        return succeeded(r.data, `${okHead(tool, r.status)} Returned the record for ${strAt(r.data, "cve_id") ?? id}.`, {
+        const cve = strAt(r.data, "cve_id") ?? id;
+        return succeeded(r.data, `${okHead(tool, r.status)} Returned the record for ${cve}.${cveScoreNote(cve, r.data)}`, {
             state: "measured",
             measured_at: instantOrNull(written),
             method: CVE_FEED_METHOD,
@@ -624,13 +684,16 @@ async function cveExposure(cve_id) {
 }
 // Every quadrant that finds its services through Shodan, attributed. The exposed-database
 // radar searches Shodan dorks and falls back to LeakIX when the Shodan query budget is low
-// (core-backend/internal/exposeddb/poller.go).
-const RADAR_SOURCES = "KEV-exposure, exposed-database and shadow-AI discovery use Shodan data (shadow AI also uses Certificate Transparency logs; exposed databases fall back to LeakIX when Shodan query credits run low).";
+// (core-backend/internal/exposeddb/poller.go). MCP-server discovery is named too, as the one
+// that uses none (#2315; see the block comment above readMCPServers), so the attribution is
+// never read as covering it.
+const RADAR_SOURCES = "KEV-exposure, exposed-database and shadow-AI discovery use Shodan data (shadow AI also uses Certificate Transparency logs; exposed databases fall back to LeakIX when Shodan query credits run low). MCP-server discovery uses no Shodan data: its hostnames come from EchelonGraph's own Certificate Transparency feed, matched by hostname pattern.";
 const RADARS = [
     ["kev_exposure", "/api/v1/public/kev-exposure/stats"],
     ["exposed_databases", "/api/v1/public/exposed-databases/stats"],
     ["leaked_credentials", "/api/v1/public/leaked-credentials/stats"],
     ["shadow_ai", "/api/v1/public/shadow-ai-radar/stats"],
+    ["mcp_servers", "/api/v1/public/ai-exposure/stats?service=mcp"],
 ];
 // The shadow-AI stats answer, regrouped by what each number counts (#2307).
 //
@@ -1195,33 +1258,265 @@ function readShadowAI(sa) {
         sentences.push(`Latest shadow-AI observation on record: ${lastObservation}.`);
     return { data, sentences };
 }
-const EXPOSURE_RADAR_DESCRIPTION = `Aggregate totals from EchelonGraph's internet-exposure radars, each refreshed on its own schedule: internet-facing services running actively-exploited (CISA-KEV) CVEs, plus the ransomware-linked subset, derived from Shodan data; unauthenticated data stores and observability UIs, found through Shodan (LeakIX when Shodan query credits run low) and then confirmed by EchelonGraph's own identified check (not a pure read: on Redis it names its client, and on ClickHouse its query is recorded in the server's query log); leaked credentials sampled from public GitHub push events; and shadow AI services found through Certificate Transparency logs and Shodan and then checked by EchelonGraph's identified probes. Every number in the result is labelled here and in the result's note by what it counts; a field this version cannot label is left out and named in the note. ` +
+// ── mcp_servers: GET /api/v1/public/ai-exposure/stats?service=mcp (#2315) ──
+//
+// core-backend/internal/aiexposure (handler.go MCPPublicCounts, store.go): the AI-exposure
+// radar's MCP rows, one per hostname, each counted once by its latest verdict on record, with
+// EchelonGraph's own control servers left out and counted in own_controls_excluded. Counts,
+// timestamps and one constant (service "mcp"); no hostname, version or server name.
+//   total                   protected + pending_readjudication + not_assessed
+//   protected               the /mcp endpoint answered 401/403 and its RFC 9728 protected-resource
+//                           metadata validated (prm.go); prm_via divides exactly these rows by
+//                           where that document was found
+//   pending_readjudication  a verdict of a rule since replaced, not yet re-checked (store.go
+//                           readjudicationPredicate); in neither of the other two
+//   not_assessed            the rest; not_assessed_by_reason divides exactly these rows, first
+//                           match wins: the eight prm.go reason codes (a challenge whose metadata
+//                           did not validate), identified_no_challenge, challenge_unadjudicated
+//                           (a challenge recorded before #2312), no_http_answer, not_identified_as_mcp
+//   era, transport          divide every counted row; a row written before #2314 recorded an era
+//                           is not_measured (era.go says what each value rests on)
+//   window                  from/to: the oldest and newest last-check time over the counted rows
+//   enabled, last_run_at    exactly as the unparameterised answer computes them: the AI-exposure
+//                           radar's fleet-wide liveness and last completed check, over every AI
+//                           service it checks, not MCP servers alone. enabled is true when a check
+//                           completed within liveWindow (45 minutes) of the answer.
+//   counted_at              when the API read the counts
+//
+// Discovery uses no Shodan data, so this reader carries no Shodan attribution. poller.go
+// discover enqueues only hostnames that store.go CandidateHosts matches by pattern (catalog.go
+// HostPatternIndex) in ct_domains and shadow_ct_observations, and that query drops every domain
+// holding a ':'; a Shodan row's domain is its ip:port (shadowctlog poller.go shodanDomain), so
+// none reaches the queue.
+//
+// identified_no_challenge is where #2307's mistake would be made again: a server that
+// identified itself as an MCP server and asked for no credentials at the handshake. MCP
+// authorization is optional (MCP 2026-07-28, Authorization › Protocol Requirements), a server
+// can enforce it at tools/call, and the probe never sends tools/call (mcp.go), so nothing here
+// says whether such a server gives anything away. Every text says what the bucket is, and never
+// calls it open, exposed or unauthenticated.
+//
+// What is refused, and what is left out. An API older than ?service=mcp ignores the parameter
+// and answers its counts over EVERY AI service, `protected` among them (aiexposure PublicCounts);
+// relayed as MCP-server counts, that is #2307 again. And the API refuses to serve counts that
+// contradict its method (a 500, never a 200 that breaks a sum), so a 200 that breaks one is not
+// an answer of that contract. So the radar is refused, as a per-radar failure (mcpRefusal),
+// when the answer does not say service "mcp", when a headline count is missing or not a whole
+// number, or when total is not the sum of the other three. Below the headline, the file's rule
+// for a known field in an unexpected shape holds: a partition is relayed only with exactly its
+// buckets, each a whole number, adding up to the count it divides, or it is left out whole and
+// named, since a partition missing a bucket, or carrying one this version cannot label, is an
+// undercount that reads as complete. A field this version does not know is left out, and named
+// only when its name is shaped like a field name: the answer is counts only, a key could itself
+// be a hostname, and the tool repeats no string the answer carries but its timestamps.
+const MCP_HEADLINE = ["total", "protected", "pending_readjudication", "not_assessed"];
+const MCP_CHALLENGE_REASONS = [
+    "resource_mismatch",
+    "cross_origin_pointer",
+    "bare_challenge_no_prm",
+    "pointer_unreachable",
+    "pointer_invalid",
+    "no_authorization_servers",
+    "wellknown_unreachable",
+    "metadata_invalid",
+];
+const MCP_PARTITIONS = {
+    not_assessed_by_reason: {
+        of: "not_assessed",
+        buckets: ["identified_no_challenge", ...MCP_CHALLENGE_REASONS, "challenge_unadjudicated", "no_http_answer", "not_identified_as_mcp"],
+    },
+    prm_via: { of: "protected", buckets: ["header", "wellknown_path", "wellknown_root"] },
+    era: { of: "total", buckets: ["legacy", "dual", "modern", "unknown", "not_measured"] },
+    transport: { of: "total", buckets: ["streamable_http", "legacy_sse", "unknown", "not_measured"] },
+};
+const MCP_PARTITION_NAMES = Object.keys(MCP_PARTITIONS);
+const MCP_INSTANTS = ["last_run_at", "counted_at"];
+const MCP_KNOWN = new Set(["service", ...MCP_HEADLINE, ...MCP_PARTITION_NAMES, "own_controls_excluded", "window", "enabled", ...MCP_INSTANTS]);
+// What each challenge reason code says (prm.go prmReasonCodes), for the note.
+const MCP_CHALLENGE_MEANS = {
+    resource_mismatch: "the document's resource is absent or not identical to the server's identifier",
+    cross_origin_pointer: "the challenge pointed to metadata on another origin, which EchelonGraph does not request",
+    bare_challenge_no_prm: "no metadata URL was named and neither well-known URI answered 2xx",
+    pointer_unreachable: "the same-origin metadata URL did not answer 2xx in full",
+    pointer_invalid: "the metadata pointer is not a URL EchelonGraph will request",
+    no_authorization_servers: "the document names no authorization server",
+    wellknown_unreachable: "a well-known metadata request got no complete HTTP answer",
+    metadata_invalid: "the answer is not a 200 JSON object within the size cap",
+};
+// A count as the MCP answer states one: a whole number, zero or more.
+const isWhole = (v) => typeof v === "number" && Number.isSafeInteger(v) && v >= 0;
+// The shape of a field name. An unknown key of this shape is named when left out; any other is
+// counted, not repeated, since it could be a hostname.
+const FIELD_NAME = /^[a-z][a-z0-9_]{0,63}$/;
+// core-backend aiexposure handler.go liveWindow: how recently a check must have completed for
+// the API to answer enabled true. A liveness window, not a re-probe interval.
+// MCP_CHALLENGE_REASONS as the tool description names them, spelled out as ONE constant string: the
+// description is published, and the site's tool-claims check (marketing-site lib/mcpToolClaims.test.ts)
+// reads every description statically, folding only references to constant strings, so a .map() here
+// made the whole description unreadable to it. tools.test.mjs pins this to MCP_CHALLENGE_REASONS.
+const MCP_CHALLENGE_REASON_FIELDS = "mcp_servers.not_assessed_by_reason.resource_mismatch, mcp_servers.not_assessed_by_reason.cross_origin_pointer, mcp_servers.not_assessed_by_reason.bare_challenge_no_prm, mcp_servers.not_assessed_by_reason.pointer_unreachable, mcp_servers.not_assessed_by_reason.pointer_invalid, mcp_servers.not_assessed_by_reason.no_authorization_servers, mcp_servers.not_assessed_by_reason.wellknown_unreachable and mcp_servers.not_assessed_by_reason.metadata_invalid";
+const MCP_ENABLED_WITHIN = "45 minutes";
+// Why an ?service=mcp answer is not relayed at all, or undefined when it can be read. The
+// sentence quotes no value the answer carries.
+function mcpRefusal(body) {
+    if (!isPlainObject(body))
+        return "the answer is not a JSON object carrying the MCP-server counts";
+    if (body.service === undefined) {
+        return "the answer carries no service field, so it is not the MCP-server counts: an API older than service=mcp ignores that parameter and answers the AI-exposure radar's counts over every AI service it checks, which this tool does not relay as MCP-server counts";
+    }
+    if (body.service !== "mcp")
+        return "the answer names a service other than mcp, so it is not the MCP-server counts";
+    const bad = MCP_HEADLINE.filter((k) => !isWhole(body[k]));
+    if (bad.length)
+        return `its ${listed(bad)} ${be(bad.length)} missing or not a whole number of zero or more, so its counts are not relayed`;
+    const [total, protectedN, pending, notAssessed] = MCP_HEADLINE.map((k) => body[k]);
+    if (total !== protectedN + pending + notAssessed) {
+        return "its counts contradict each other (total is not protected + pending_readjudication + not_assessed, an answer the API's own integrity check does not serve), so they are not relayed";
+    }
+    return undefined;
+}
+function readMCPServers(src) {
+    const data = {};
+    const unusable = [];
+    const unsummed = [];
+    for (const k of MCP_HEADLINE)
+        data[k] = src[k];
+    for (const k of MCP_PARTITION_NAMES) {
+        const { of, buckets } = MCP_PARTITIONS[k];
+        const v = src[k];
+        const exact = isPlainObject(v) && Object.keys(v).length === buckets.length && buckets.every((b) => Object.prototype.hasOwnProperty.call(v, b) && isWhole(v[b]));
+        if (!exact) {
+            unusable.push(k);
+            continue;
+        }
+        if (buckets.reduce((sum, b) => sum + v[b], 0) !== src[of]) {
+            unsummed.push(k);
+            continue;
+        }
+        data[k] = Object.fromEntries(buckets.map((b) => [b, v[b]]));
+    }
+    if (isWhole(src.own_controls_excluded))
+        data.own_controls_excluded = src.own_controls_excluded;
+    else
+        unusable.push("own_controls_excluded");
+    // window: from and to, both real instants, from not after to. With no row counted the API has
+    // no window to give (null, or from and to null), and none is relayed.
+    const w = src.window;
+    const from = strAt(w, "from");
+    const to = strAt(w, "to");
+    const noWindow = w === null || w === undefined || (isPlainObject(w) && w.from === null && w.to === null && Object.keys(w).length === 2);
+    if (isPlainObject(w) && Object.keys(w).length === 2 && realInstant(from) && realInstant(to) && Date.parse(from) <= Date.parse(to))
+        data.window = { from, to };
+    else if (!(noWindow && src.total === 0))
+        unusable.push("window");
+    if (typeof src.enabled === "boolean")
+        data.enabled = src.enabled;
+    else
+        unusable.push("enabled");
+    // A timestamp that is not a real instant is not relayed as one (readRadar's rule).
+    for (const k of MCP_INSTANTS) {
+        const s = strAt(src, k);
+        if (realInstant(s))
+            data[k] = s;
+        else if (src[k] !== undefined && src[k] !== null && typeof src[k] !== "string")
+            unusable.push(k);
+    }
+    const extra = Object.keys(src).filter((k) => !MCP_KNOWN.has(k));
+    const named = extra.filter((k) => FIELD_NAME.test(k));
+    const unnamed = extra.length - named.length;
+    const sentences = [];
+    const n = (k) => data[k];
+    const b = (p, bucket) => `mcp_servers.${p}.${bucket} (${data[p][bucket]})`;
+    sentences.push(`MCP servers: mcp_servers.total (${n("total")}) counts hostnames the AI-exposure radar has checked for an MCP server, each once, by its latest verdict on record; each was named like an MCP server in EchelonGraph's own Certificate Transparency feed, and not every one is an MCP server.`);
+    if (n("total") === 0)
+        sentences.push("mcp_servers.total is 0: the radar holds no verdict on record for a hostname named like an MCP server.");
+    sentences.push(`mcp_servers.protected (${n("protected")}) counts hostnames whose /mcp endpoint asked for credentials (a 401 or 403) and whose OAuth protected-resource metadata validated under RFC 9728: a 200 JSON document whose resource is identical to the server's identifier and that names at least one authorization server.`);
+    if (data.prm_via) {
+        sentences.push(`mcp_servers.prm_via divides them by where that document was found: ${b("prm_via", "header")}, the same-origin URL the challenge named; ${b("prm_via", "wellknown_path")}, /.well-known/oauth-protected-resource followed by the endpoint's path; and ${b("prm_via", "wellknown_root")}, that URI at the root.`);
+    }
+    sentences.push(`mcp_servers.pending_readjudication (${n("pending_readjudication")}) counts verdicts decided by a rule EchelonGraph has since replaced and not yet re-checked under the current rules; they are in neither mcp_servers.protected nor mcp_servers.not_assessed.`, `mcp_servers.not_assessed (${n("not_assessed")}) counts the rest, whose protection the radar could not assess; not assessed does not mean unprotected${data.not_assessed_by_reason ? ", and mcp_servers.not_assessed_by_reason puts each in exactly one bucket" : ""}.`);
+    if (data.not_assessed_by_reason) {
+        sentences.push(`${b("not_assessed_by_reason", "identified_no_challenge")} counts servers that identified themselves as MCP servers (a DiscoverResult, an InitializeResult, or the endpoint event of the deprecated HTTP+SSE transport) and did not ask for credentials at the handshake.`, "That is normal in MCP: authorization is optional in the spec, and a server can enforce it at tools/call instead, which EchelonGraph never sends, so this bucket is not a finding of exposure.", `Endpoints that asked for credentials (a 401 or 403) but whose RFC 9728 metadata did not validate are counted by why: ${MCP_CHALLENGE_REASONS.map((r, i) => `${i === MCP_CHALLENGE_REASONS.length - 1 ? "and " : ""}${b("not_assessed_by_reason", r)}, ${MCP_CHALLENGE_MEANS[r]}`).join("; ")}.`, "Each of those endpoints asked for credentials, so none of them is shown to lack protection: only its metadata did not validate.", `${b("not_assessed_by_reason", "challenge_unadjudicated")} counts endpoints that asked for credentials before EchelonGraph read RFC 9728 metadata, not re-checked since.`, `${b("not_assessed_by_reason", "no_http_answer")} counts hostnames that gave no HTTP answer (DNS, TCP or TLS failed, or the request timed out), and ${b("not_assessed_by_reason", "not_identified_as_mcp")} hostnames that answered HTTP with nothing that identified an MCP server (a login or error page, a body that is not JSON-RPC, a 4xx or 5xx): neither is a count of MCP servers.`);
+    }
+    if (data.era) {
+        sentences.push(`mcp_servers.era divides every counted hostname by the protocol era its answer identified: ${b("era", "legacy")}, an initialize-era server (an InitializeResult, or the legacy SSE endpoint event); ${b("era", "dual")}, answered server/discover and named an initialize-era version too, a lower bound, since a server built on the reference SDK names only modern versions there and is counted modern; ${b("era", "modern")}, answered server/discover and named no initialize-era version, not proven modern-only, since EchelonGraph does not send initialize to tell; ${b("era", "unknown")}, nothing identified an era, every credential challenge included; and ${b("era", "not_measured")}, a verdict recorded before EchelonGraph's probe began recording the era and not re-checked since.`);
+    }
+    if (data.transport) {
+        sentences.push(`mcp_servers.transport divides them by the transport that identified the server: ${b("transport", "streamable_http")}, a POST to /mcp; ${b("transport", "legacy_sse")}, the endpoint event of GET /sse (the deprecated HTTP+SSE transport); ${b("transport", "unknown")}, nothing identified one; and ${b("transport", "not_measured")}, recorded before the era probe and not re-checked since.`);
+    }
+    if (data.own_controls_excluded !== undefined) {
+        sentences.push(`mcp_servers.own_controls_excluded (${n("own_controls_excluded")}) counts EchelonGraph's own control servers, which are left out of every other mcp_servers number.`);
+    }
+    if (data.window) {
+        sentences.push(`mcp_servers.window says when the verdicts counted were last checked: the oldest at ${from} (mcp_servers.window.from) and the newest at ${to} (mcp_servers.window.to), so the counts are each hostname's latest verdict, not one sweep at one time.`);
+    }
+    const at = data.last_run_at;
+    if (typeof at === "string") {
+        sentences.push(`mcp_servers last completed check: ${at} (mcp_servers.last_run_at, a timestamp, not a count).`, "mcp_servers.last_run_at is when the AI-exposure radar, which checks other AI services as well as MCP servers, last finished a cycle whose reads succeeded and whose scan opt-out register answered.", "mcp_servers.last_run_at is not the time of every verdict the mcp_servers numbers count (mcp_servers.window says when those were checked); nor is it mcp_servers.counted_at, when the API read those numbers.");
+    }
+    if (data.enabled === true) {
+        sentences.push(`mcp_servers.enabled is true: the API reports the AI-exposure radar running, a check having completed within ${MCP_ENABLED_WITHIN} of its answer.`);
+    }
+    else if (data.enabled === false) {
+        sentences.push(`mcp_servers.enabled is false: the API does not report the AI-exposure radar running (no check completed within ${MCP_ENABLED_WITHIN} of its answer), so these numbers may be stale.`);
+    }
+    if (typeof data.counted_at === "string") {
+        sentences.push(`mcp_servers.counted_at (${data.counted_at}) is when the API read these counts: a timestamp, not a count, and not when any verdict was checked.`);
+    }
+    sentences.push(...leftOut("mcp_servers", named, unusable));
+    if (unsummed.length)
+        sentences.push(`Left out of mcp_servers because their buckets do not add up to the count they divide: ${unsummed.join(", ")}.`);
+    if (unnamed) {
+        sentences.push(`Also left out of mcp_servers: ${unnamed} field${unnamed === 1 ? "" : "s"} whose name is not shaped like a field name, not repeated here, since a name could itself identify a server.`);
+    }
+    return { data, sentences };
+}
+const EXPOSURE_RADAR_DESCRIPTION = `Aggregate totals from EchelonGraph's internet-exposure radars, each refreshed on its own schedule: internet-facing services running actively-exploited (CISA-KEV) CVEs, plus the ransomware-linked subset, derived from Shodan data; unauthenticated data stores and observability UIs, found through Shodan (LeakIX when Shodan query credits run low) and then confirmed by EchelonGraph's own identified check (not a pure read: on Redis it names its client, and on ClickHouse its query is recorded in the server's query log); leaked credentials sampled from public GitHub push events; and shadow AI services found through Certificate Transparency logs and Shodan and then checked by EchelonGraph's identified probes. It also gives MCP-server counts: hostnames named like an MCP server in EchelonGraph's own Certificate Transparency feed (no Shodan data), each counted once by its latest verdict from EchelonGraph's identified MCP probe, which never sends tools/call. Every number in the result is labelled here and in the result's note by what it counts; a field this version cannot label is left out and named in the note. ` +
     `kev_exposure: kev_exposure.distinct_hosts counts distinct ip:port services, not machines (a machine answering on two ports counts twice), with at least one CISA-KEV-listed CVE on record, and kev_exposure.ransomware_hosts those with a ransomware-linked one; kev_exposure.kev_cves_exposed and kev_exposure.ransomware_cves count distinct CVEs with at least one such service; kev_exposure.correlations counts service×CVE pairs, not services, so a service with three KEV CVEs counts three times. kev_exposure.top_products, kev_exposure.top_countries and kev_exposure.top_cves rank up to 12 products, 10 countries and 12 CVEs by those services; kev_exposure.top_cves[].cvss_v3_score and kev_exposure.top_cves[].epss_score are the highest CVSS v3 base score and EPSS probability recorded on that CVE's observations. kev_exposure.trend counts service×CVE pairs still on record by the week in which each was first recorded, over 12 weeks, so earlier weeks read low. kev_exposure.newest_kev lists the 15 CVEs that EchelonGraph's CVE records most recently mark as CISA-KEV-listed, each with an exposure_state: exposed, where kev_exposure.newest_kev[].exposed_hosts counts distinct ip:port services on record with it; or not_assessed, where the API's answer holds no measurement for that CVE (its 0 is not one) and no count is relayed, and cve_exposure says per CVE whether the radar tracks it. kev_exposure.newest_kev[].cvss_v3_score and kev_exposure.newest_kev[].epss_score are the CVE record's CVSS v3 base score and EPSS probability. ` +
     `exposed_databases: exposed_databases.distinct_hosts counts distinct ip:port services the check confirmed answering without authentication, and exposed_databases.engines the distinct engine types among them; exposed_databases.top_engines and exposed_databases.top_countries rank up to 15 engines and 10 countries by those services. exposed_databases.pii_likely and exposed_databases.pci_likely count services whose schema names (never record values) pass a high-confidence, precision-first gate for personal or payment-card data, so a service outside them is not shown to hold no such data. ` +
     `leaked_credentials: leaked_credentials.total counts (repository, secret) pairs, not distinct secrets, so one secret in three repositories counts three times; leaked_credentials.distinct_secrets counts each secret once and leaked_credentials.distinct_repos counts repositories; leaked_credentials.top_providers and leaked_credentials.top_types rank up to 15 providers and secret types by those pairs. None is validated: each is a credential-shaped string that passed EchelonGraph's filters, at most structurally checked and never tested against its provider. Each of those three radars also carries generated_at, when the API computed its totals, and, when the API can tell, last_run_at. kev_exposure.last_run_at, exposed_databases.last_run_at and leaked_credentials.last_run_at are timestamps, not counts: each is when that radar last completed a check, a cycle whose reads succeeded, among them a Shodan search (for exposed_databases, or its LeakIX fallback) that answered at least one query, or for leaked_credentials a read of the public GitHub event stream. A cycle that read nothing does not move it, and it is not the time of every record a radar's numbers count, which cover everything still on record, not only what the last check found. A radar whose answer carries no last_run_at has none in the result, and the note says nothing about it. ` +
-    `shadow_ai: the result is regrouped by what each number counts. shadow_ai.confirmed_exposed counts services EchelonGraph's probes found answering without an authentication gate (liveness active, or rechecking during a re-check): confirmed_exposed.total is the sum of confirmed_exposed.by_category, and confirmed_exposed.last_24h counts those first recorded in the last 24 h. Of the shadow_ai numbers, only confirmed_exposed counts exposed services. shadow_ai.observed counts every Certificate Transparency or Shodan observation on record, whatever its verification state: its numbers are observed, not exposed. They are observed.total; observed.by_category (the same observations by category); observed.last_24h (those first recorded in the last 24 h); observed.trend_30d (observations per UTC day over the last 30 days); and observed.top_products, observed.top_countries and observed.top_issuers (up to ten products, countries and issuers ranked by observations, where an issuer is the certificate's CA for a Certificate Transparency observation and the hosting operator Shodan reports for a Shodan one). shadow_ai.authentication counts observations by probe outcome: authentication.observed where a probe observed an authentication gate (a 401/403, a login page or an auth marker), and authentication.not_determined where the service answered but no probe could tell. Neither authentication count is part of confirmed_exposed, and observed.total minus confirmed_exposed.total is not a count of secured services. The shadow-AI poller block carries only running and last_run_at: last_run_at is when the radar's leader last completed a Certificate Transparency (crt.sh) cycle, and its running is true only when that was within ${SHADOW_AI_SILENT_AFTER} of the answer. ${SHODAN_OWNERSHIP}`;
+    `shadow_ai: the result is regrouped by what each number counts. shadow_ai.confirmed_exposed counts services EchelonGraph's probes found answering without an authentication gate (liveness active, or rechecking during a re-check): confirmed_exposed.total is the sum of confirmed_exposed.by_category, and confirmed_exposed.last_24h counts those first recorded in the last 24 h. Of the shadow_ai numbers, only confirmed_exposed counts exposed services. shadow_ai.observed counts every Certificate Transparency or Shodan observation on record, whatever its verification state: its numbers are observed, not exposed. They are observed.total; observed.by_category (the same observations by category); observed.last_24h (those first recorded in the last 24 h); observed.trend_30d (observations per UTC day over the last 30 days); and observed.top_products, observed.top_countries and observed.top_issuers (up to ten products, countries and issuers ranked by observations, where an issuer is the certificate's CA for a Certificate Transparency observation and the hosting operator Shodan reports for a Shodan one). shadow_ai.authentication counts observations by probe outcome: authentication.observed where a probe observed an authentication gate (a 401/403, a login page or an auth marker), and authentication.not_determined where the service answered but no probe could tell. Neither authentication count is part of confirmed_exposed, and observed.total minus confirmed_exposed.total is not a count of secured services. The shadow-AI poller block carries only running and last_run_at: last_run_at is when the radar's leader last completed a Certificate Transparency (crt.sh) cycle, and its running is true only when that was within ${SHADOW_AI_SILENT_AFTER} of the answer. ` +
+    `mcp_servers: counts and timestamps only, no hostname. mcp_servers.total counts hostnames the AI-exposure radar has checked for an MCP server, each once by its latest verdict on record, and not every one is an MCP server; EchelonGraph's own control servers are left out, and mcp_servers.own_controls_excluded counts them. mcp_servers.total is mcp_servers.protected plus mcp_servers.pending_readjudication plus mcp_servers.not_assessed. mcp_servers.protected counts hostnames whose /mcp endpoint asked for credentials and whose OAuth protected-resource metadata validated under RFC 9728; mcp_servers.prm_via divides them by where that document was found: mcp_servers.prm_via.header, mcp_servers.prm_via.wellknown_path and mcp_servers.prm_via.wellknown_root. mcp_servers.pending_readjudication counts verdicts of a rule since replaced, not yet re-checked. mcp_servers.not_assessed counts the rest, whose protection the radar could not assess (not assessed does not mean unprotected), and mcp_servers.not_assessed_by_reason puts each in one bucket. mcp_servers.not_assessed_by_reason.identified_no_challenge holds servers that identified themselves as MCP servers and did not ask for credentials at the handshake. That is normal in MCP: authorization is optional in the spec, and a server can enforce it at tools/call instead, which EchelonGraph never sends, so this bucket is not a finding of exposure. ${MCP_CHALLENGE_REASON_FIELDS} hold endpoints that asked for credentials but whose RFC 9728 metadata did not validate, by why, so none of them is shown to lack protection; mcp_servers.not_assessed_by_reason.challenge_unadjudicated holds endpoints that asked for credentials before that check existed, not yet re-checked. mcp_servers.not_assessed_by_reason.no_http_answer holds hostnames that gave no HTTP answer, and mcp_servers.not_assessed_by_reason.not_identified_as_mcp hostnames whose HTTP answer identified no MCP server. mcp_servers.era divides every counted hostname by protocol era: mcp_servers.era.legacy; mcp_servers.era.dual, a lower bound; mcp_servers.era.modern, not proven modern-only; mcp_servers.era.unknown; and mcp_servers.era.not_measured, recorded before the era probe and not re-checked since. mcp_servers.transport divides them by transport: mcp_servers.transport.streamable_http, mcp_servers.transport.legacy_sse, mcp_servers.transport.unknown and mcp_servers.transport.not_measured. mcp_servers.window.from and mcp_servers.window.to are when the oldest and the newest of the verdicts counted were last checked. mcp_servers.last_run_at is a timestamp, not a count: when the AI-exposure radar, which checks other AI services too, last completed a check; mcp_servers.enabled is whether one completed within ${MCP_ENABLED_WITHIN} of the answer, and mcp_servers.counted_at is when the API read the counts. A partition whose buckets do not add up to the count it divides is left out and named; an answer that does not say it is the MCP-server counts, or whose mcp_servers.total, mcp_servers.protected, mcp_servers.pending_readjudication and mcp_servers.not_assessed are missing or contradict each other, is a failure. ${SHODAN_OWNERSHIP}`;
 // exposure_radar's envelope. Every radar answered, but no stats answer says when the services
 // or records it counts were observed: each count covers everything that radar still holds on
 // record, and the answer carries only generated_at (when the API computed the totals) and
 // last_run_at (the radar's last completed check), neither of which is that time (#2335). So
 // the result is not_assessed with measured_at null, and says why; its numbers keep their labels,
 // and freshness carries each radar's last_run_at where the API serves one.
-const RADAR_METHOD = "Aggregate counts over what each radar holds on record: kev_exposure, Shodan banners whose version maps to a CISA-KEV-listed CVE; exposed_databases, services found through Shodan (LeakIX when Shodan query credits run low) and confirmed by EchelonGraph's own identified check; leaked_credentials, credential-shaped strings in public GitHub push events; shadow_ai, services found through Certificate Transparency logs and Shodan and checked by EchelonGraph's identified probes.";
+//
+// mcp_servers (#2315) does not change that, by the envelope's own rule (the `state` block above
+// the State type): an exposure count is measured only with measured_at, "when the underlying
+// observation was made, as the API states it", and otherwise it is not_assessed and relayed as
+// what the source holds on record. The MCP answer states no such time. Its counts are each
+// hostname's LATEST verdict, and window.from and window.to are the oldest and newest last-check
+// times over the counted rows, a span of checks made at different times, not one observation.
+// Taking window.to as measured_at would date every count by its newest verdict, the reading
+// #2335 and #2439 refuse for last_run_at and last_seen; window.from would date each one by its
+// oldest. And the envelope is one for five radars, four of which carry no time of observation at
+// all, so a measured state would date their numbers too (#2313 done-means 5). So the state stays
+// not_assessed with measured_at null, the window is relayed in data and labelled by the note,
+// and the envelope's own note names it.
+const RADAR_METHOD = "Aggregate counts over what each radar holds on record: kev_exposure, Shodan banners whose version maps to a CISA-KEV-listed CVE; exposed_databases, services found through Shodan (LeakIX when Shodan query credits run low) and confirmed by EchelonGraph's own identified check; leaked_credentials, credential-shaped strings in public GitHub push events; shadow_ai, services found through Certificate Transparency logs and Shodan and checked by EchelonGraph's identified probes; mcp_servers, the latest verdict on record per hostname named like an MCP server in EchelonGraph's own Certificate Transparency feed, from EchelonGraph's identified MCP probe (server/discover, and initialize only if that is refused; never tools/call), where protected means the endpoint's RFC 9728 protected-resource metadata validated.";
 const RADAR_NAMES = RADARS.map(([name]) => name);
-const RADAR_STATE_NOTE = "state is not_assessed: every radar answered, but no stats answer says when the services or records it counts were observed, so no count here is presented as a dated measurement and measured_at is null. Each count is what that radar holds on record, and the note labels each one by what it counts.";
-const RADAR_FRESHNESS_NOTE = "freshness gives each radar's last completed check where the API serves one (freshness.kev_exposure.last_run_at, freshness.exposed_databases.last_run_at, freshness.leaked_credentials.last_run_at, and freshness.shadow_ai.last_run_at with freshness.shadow_ai.running), and null where it does not.";
+const RADAR_STATE_NOTE = "state is not_assessed: every radar answered, but none gives one time at which what it counts was observed: kev_exposure, exposed_databases, leaked_credentials and shadow_ai give none, and mcp_servers dates its verdicts at most by a window (mcp_servers.window), from the oldest check among them to the newest, so no count here is presented as a dated measurement and measured_at is null. Each count is what that radar holds on record, and the note labels each one by what it counts.";
+const RADAR_FRESHNESS_NOTE = "freshness gives each radar's last completed check where the API serves one (freshness.kev_exposure.last_run_at, freshness.exposed_databases.last_run_at, freshness.leaked_credentials.last_run_at, freshness.shadow_ai.last_run_at with freshness.shadow_ai.running, and freshness.mcp_servers.last_run_at with freshness.mcp_servers.enabled), and null where it does not.";
 async function exposureRadar() {
     const tool = "exposure_radar";
     try {
         const results = await Promise.all(RADARS.map(([, path]) => api(path)));
         const data = {};
         const failures = [];
-        RADARS.forEach(([name], i) => {
+        RADARS.forEach(([name, path], i) => {
             const r = results[i];
-            if (r.ok)
+            if (!r.ok)
+                return void failures.push([name, r]);
+            // mcp_servers is read only when the answer is the MCP-server counts at all (mcpRefusal): an
+            // answer that is not is a failure of that radar, named like any other, never zeros.
+            const refused = name === "mcp_servers" ? mcpRefusal(r.data) : undefined;
+            if (refused === undefined)
                 data[name] = r.data;
             else
-                failures.push([name, r]);
+                failures.push([name, { ok: false, kind: "unexpected_shape", path, status: r.status, detail: refused }]);
         });
         if (failures.length) {
             // All or nothing: a radar picture with one quadrant missing reads as the whole one,
@@ -1241,6 +1536,7 @@ async function exposureRadar() {
             exposed_databases: readExposedDatabases(data.exposed_databases),
             leaked_credentials: readLeakedCredentials(data.leaked_credentials),
             shadow_ai: readShadowAI(data.shadow_ai),
+            mcp_servers: readMCPServers(data.mcp_servers),
         };
         const relayed = {};
         const said = [];
@@ -1251,6 +1547,7 @@ async function exposureRadar() {
         // Only what the readers relayed: a last_run_at that is not a real instant never got there.
         const stamp = (radar, ...keys) => instantOrNull(strAt(relayed[radar], ...keys));
         const running = boolAt(relayed.shadow_ai, "poller", "running");
+        const enabled = boolAt(relayed.mcp_servers, "enabled");
         return succeeded(relayed, `${okHead(tool)} All ${RADARS.length} radars answered: ${RADARS.map(([name]) => name).join(", ")}. Every number relayed is labelled below by what it counts, and a field this version cannot label is left out and named. ${said.join(" ")} ${RADAR_SOURCES} ${SHODAN_OWNERSHIP} Each radar refreshes on its own schedule.`, {
             state: "not_assessed",
             measured_at: null,
@@ -1261,6 +1558,7 @@ async function exposureRadar() {
                 exposed_databases: { last_run_at: stamp("exposed_databases", "last_run_at") },
                 leaked_credentials: { last_run_at: stamp("leaked_credentials", "last_run_at") },
                 shadow_ai: { last_run_at: stamp("shadow_ai", "poller", "last_run_at"), running: running ?? null },
+                mcp_servers: { last_run_at: stamp("mcp_servers", "last_run_at"), enabled: enabled ?? null },
             },
             notes: [RADAR_STATE_NOTE, RADAR_FRESHNESS_NOTE],
         });
@@ -1327,9 +1625,13 @@ const CVERecord = z.looseObject({
     cvss_v3_score: opt(z.number()),
     cvss_v4_score: opt(z.number()),
     cvss_v4_severity: opt(z.string()),
-    echelongraph_score: opt(z.number()),
-    echelongraph_severity: opt(z.string()),
+    // #2535: the score is a score only beside score_assessed true (see cveScoreNote).
+    echelongraph_score: opt(z.number()).describe("EchelonGraph's 0-10 score for the CVE: a score only when score_assessed is true. With score_assessed false it is a placeholder, not a rating."),
+    echelongraph_severity: opt(z.string()).describe("The severity band of echelongraph_score: a rating only when score_assessed is true. With score_assessed false it is a placeholder (NONE)."),
+    echelongraph_risk: opt(z.number()).describe("EchelonGraph's 0-100 risk priority, fused from the score, exploitation and automatability: a rating only when score_assessed is true. With score_assessed false it is a placeholder."),
     score_confidence: opt(z.string()),
+    score_assessed: opt(z.boolean()).describe("Whether EchelonGraph has scored the CVE. true: echelongraph_score, echelongraph_severity and echelongraph_risk are its score. false: the CVE is NOT YET SCORED, not scored 0, and any of those three it carries is a placeholder, not a rating; the API may leave them out. Absent (an API older than the field): the answer does not say whether the CVE was scored."),
+    score_unassessed_reason: opt(z.string()).describe("Why score_assessed is false: no_signal, no source has yet published severity data EchelonGraph can score; or rejected, the record was withdrawn by its numbering authority and is never scored. Absent when the CVE is scored."),
     epss_score: opt(z.number()),
     epss_percentile: opt(z.number()),
     kev_listed: opt(z.boolean()),
@@ -1445,12 +1747,25 @@ const ShadowAIData = z.strictObject({
     poller: z.strictObject({ running: z.boolean(), last_run_at: Instant }).optional(),
 });
 const LastRun = z.strictObject({ last_run_at: Instant.nullable() });
+// mcp_servers as readMCPServers relays it, from the same constants (#2315): the headline counts
+// always (an answer without them is refused), and each partition with exactly its buckets or not
+// at all.
+const Whole = z.number().int().min(0);
+const MCPServersData = z.strictObject({
+    ...Object.fromEntries(MCP_HEADLINE.map((k) => [k, Whole])),
+    ...Object.fromEntries(MCP_PARTITION_NAMES.map((k) => [k, z.strictObject(Object.fromEntries(MCP_PARTITIONS[k].buckets.map((b) => [b, Whole]))).optional()])),
+    own_controls_excluded: Whole.optional(),
+    window: z.strictObject({ from: Instant, to: Instant }).optional(),
+    enabled: z.boolean().optional(),
+    ...Object.fromEntries(MCP_INSTANTS.map((k) => [k, Instant.optional()])),
+});
 const EXPOSURE_RADAR_OUTPUT = envelopeSchema({
     data: z.strictObject({
         kev_exposure: zRadar(KEV_SPEC, { newest_kev: z.array(NewestKEVRow) }),
         exposed_databases: zRadar(EXPOSED_DB_SPEC),
         leaked_credentials: zRadar(LEAKED_CREDS_SPEC),
         shadow_ai: ShadowAIData,
+        mcp_servers: MCPServersData,
     }),
     coverage: z.strictObject({
         radars: z.array(z.string()).describe("The radars this tool reads."),
@@ -1462,12 +1777,13 @@ const EXPOSURE_RADAR_OUTPUT = envelopeSchema({
         exposed_databases: LastRun,
         leaked_credentials: LastRun,
         shadow_ai: z.strictObject({ last_run_at: Instant.nullable(), running: z.boolean().nullable() }),
+        mcp_servers: z.strictObject({ last_run_at: Instant.nullable(), enabled: z.boolean().nullable() }),
     }),
     error: ErrorSchema.extend({
         radars: z
             .array(z.strictObject({
             radar: z.string(),
-            kind: z.enum(["network", "timeout", "http", "not_json", "not_object"]),
+            kind: z.enum(["network", "timeout", "http", "not_json", "not_object", "unexpected_shape"]),
             path: z.string(),
             status: z.number().int().nullable(),
             message: z.string(),
@@ -1494,12 +1810,17 @@ const INSTRUCTIONS = [
     "That is not the time of every record the radar's numbers count, which cover everything still on record, and it is null when the API does not say.",
     "Every figure is as fresh as the schedule that refreshes it.",
     "Exposure numbers are aggregate: counts of distinct ip:port services on EchelonGraph's record (a machine answering on two ports counts twice), not machines, and not an internet-wide census.",
+    "exposure_radar's mcp_servers counts hostnames instead, each by its latest verdict on record.",
     `${SHODAN_ATTRIBUTION} ${SHODAN_OWNERSHIP}`,
+    "exposure_radar's mcp_servers counts use no Shodan data: their hostnames come from EchelonGraph's own Certificate Transparency feed.",
 ].join(" ");
 const ANNOTATIONS = { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true };
 const CVE_ID_ARG = z.string().describe("a CVE ID, e.g. CVE-2023-44487");
 // What each description says about its structured result, naming only fields its schema holds.
 const FEED_ENVELOPE = "Its structured result carries state (measured), measured_at, method, coverage, freshness (null: the feed serves no poll-completion time) and notes, with data equal to the API's JSON; the result's last text block repeats it without data (the first text block) and without the note's sentences (the text block before it), with which notes ends.";
+// #2535: what search_cves and get_cve say about score_assessed, one constant string, since the
+// site's tool-claims check (marketing-site lib/mcpToolClaims.test.ts) folds only constant strings.
+const SCORE_ASSESSED_DESCRIPTION = "echelongraph_score, echelongraph_severity and echelongraph_risk are EchelonGraph's score only when score_assessed is true. With score_assessed false the CVE is NOT YET SCORED, not scored 0: any of those three it carries (0, NONE, 0) is a placeholder, not a rating, and does not mean the CVE is harmless; the API may leave them out instead, score_confidence is NONE, and score_unassessed_reason says why (a rejected record, withdrawn by its numbering authority, is never scored, and the note says NOT SCORED). The note labels each such CVE NOT YET SCORED: report it that way, never as a score of 0. An answer with no score_assessed (an API older than that field) does not say whether the CVE was scored, the note says so, and a 0 there is not a rating either.";
 // One server, built per connection by serveStdio for whichever era the client opens with.
 // tools/list answers in registration order, which is the order below.
 function createServer() {
@@ -1512,7 +1833,7 @@ function createServer() {
     }, async () => checked("cve_summary", CVE_SUMMARY_OUTPUT, await cveSummary()));
     server.registerTool("search_cves", {
         title: "Search CVEs",
-        description: `Search/list CVEs from EchelonGraph's CVE feed (NVD + MITRE-CNA pre-NVD + CISA-KEV + EPSS + GitHub GHSA, each polled on a schedule). Filter by severity, minimum CVSS, free text, and sort. Returns cves, each with cve_id, severity, cvss_v3_score, echelongraph_score, epss_score and kev_listed where the record has them, and the list's total, total_counted (false: the matches were not counted, so total is not a count), total_is_lower_bound (true: at least total), search_relaxed (true: a phrase was relaxed to all of its words), limit and offset. ${FEED_ENVELOPE} coverage repeats total, total_counted, total_is_lower_bound, search_relaxed, limit and offset, and gives returned, the rows in this page.`,
+        description: `Search/list CVEs from EchelonGraph's CVE feed (NVD + MITRE-CNA pre-NVD + CISA-KEV + EPSS + GitHub GHSA, each polled on a schedule). Filter by severity, minimum CVSS, free text, and sort. Returns cves, each with cve_id, severity, cvss_v3_score, echelongraph_score and score_assessed (whether EchelonGraph has scored it), epss_score and kev_listed where the record has them, and the list's total, total_counted (false: the matches were not counted, so total is not a count), total_is_lower_bound (true: at least total), search_relaxed (true: a phrase was relaxed to all of its words), limit and offset. ${SCORE_ASSESSED_DESCRIPTION} ${FEED_ENVELOPE} coverage repeats total, total_counted, total_is_lower_bound, search_relaxed, limit and offset, and gives returned, the rows in this page.`,
         inputSchema: z.object({
             search: z.string().optional().describe("free-text search (product, vendor, or keyword, e.g. 'tomcat')"),
             severity: z.enum(["CRITICAL", "HIGH", "MEDIUM", "LOW"]).optional().describe("filter to one severity"),
@@ -1525,7 +1846,7 @@ function createServer() {
     }, async (a) => checked("search_cves", SEARCH_CVES_OUTPUT, await searchCVEs(a)));
     server.registerTool("get_cve", {
         title: "CVE detail",
-        description: `Full record for one CVE: description, severity, cvss_v3_score, cvss_v4_score and cvss_v4_severity (when the record has a CVSS v4 score), echelongraph_score and echelongraph_severity with score_confidence (EchelonGraph's multi-source score), epss_score and epss_percentile, CISA-KEV status (kev_listed, kev_added_date, and kev_ransomware for known ransomware-campaign use), ghsa_id (GitHub GHSA), references, published, modified and updated_at; each field only where the record has it. Pass a CVE ID like CVE-2023-44487. ${FEED_ENVELOPE}`,
+        description: `Full record for one CVE: description, severity, cvss_v3_score, cvss_v4_score and cvss_v4_severity (when the record has a CVSS v4 score), echelongraph_score and echelongraph_severity with score_confidence (EchelonGraph's multi-source score) and score_assessed (whether EchelonGraph has scored it), epss_score and epss_percentile, CISA-KEV status (kev_listed, kev_added_date, and kev_ransomware for known ransomware-campaign use), ghsa_id (GitHub GHSA), references, published, modified and updated_at; each field only where the record has it. Pass a CVE ID like CVE-2023-44487. ${SCORE_ASSESSED_DESCRIPTION} ${FEED_ENVELOPE}`,
         inputSchema: z.object({ cve_id: CVE_ID_ARG }),
         outputSchema: GET_CVE_OUTPUT,
         annotations: ANNOTATIONS,
@@ -1539,7 +1860,7 @@ function createServer() {
     }, async ({ cve_id }) => checked("cve_exposure", CVE_EXPOSURE_OUTPUT, await cveExposure(cve_id)));
     server.registerTool("exposure_radar", {
         title: "Exposure radar totals",
-        description: `${EXPOSURE_RADAR_DESCRIPTION} Its structured result's state is not_assessed with measured_at null: every radar answered, but no stats answer says when the services or records it counts were observed, so no count is presented as a dated measurement; each count is still relayed, labelled, as what that radar holds on record. freshness gives each radar's last_run_at (and shadow_ai's running) where the API serves one; coverage names the radars that answered; data is the relayed result above. The result's last text block repeats the structured result without data (the first text block) and without the note's sentences (the text block before it), with which notes ends.`,
+        description: `${EXPOSURE_RADAR_DESCRIPTION} Its structured result's state is not_assessed with measured_at null: every radar answered, but none gives one time at which what it counts was observed (mcp_servers dates its verdicts at most by a window, mcp_servers.window), so no count is presented as a dated measurement; each count is still relayed, labelled, as what that radar holds on record. freshness gives each radar's last_run_at (and running for shadow_ai, enabled for mcp_servers) where the API serves one; coverage names the radars that answered; data is the relayed result above. The result's last text block repeats the structured result without data (the first text block) and without the note's sentences (the text block before it), with which notes ends.`,
         outputSchema: EXPOSURE_RADAR_OUTPUT,
         annotations: ANNOTATIONS,
     }, async () => checked("exposure_radar", EXPOSURE_RADAR_OUTPUT, await exposureRadar()));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "echelongraph-mcp",
-  "version": "2.2.0",
+  "version": "2.3.1",
   "mcpName": "io.echelongraph/echelongraph-mcp",
   "description": "EchelonGraph CVE and internet-exposure data as an MCP server: CVEs with EchelonGraph multi-source scores, CISA-KEV and EPSS, plus a per-CVE internet-exposure footprint derived from Shodan data. Shodan data is owned by Shodan, which holds its copyright (© Shodan). Free and keyless, for Claude, Cursor and any MCP client.",
   "type": "module",

package/server.json

@@ -8,12 +8,12 @@
     "url": "https://github.com/echelongraph/echelongraph-mcp",
     "source": "github"
   },
-  "version": "2.2.0",
+  "version": "2.3.1",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "echelongraph-mcp",
-      "version": "2.2.0",
+      "version": "2.3.1",
       "transport": {
         "type": "stdio"
       },