EchelonGraph MCP server

CVE and internet-exposure data for Claude, Cursor, VS Code, Cline, and any MCP client, straight from EchelonGraph's free public feed.

It exposes EchelonGraph's CVE Pulse (NVD + MITRE-CNA pre-NVD + CISA-KEV + EPSS + GitHub GHSA, fused into one score) plus a per-CVE internet-exposure footprint: how many internet-facing services (distinct ip:port) EchelonGraph's KEV-exposure radar has on record running a version that maps to the CVE. Exposure counts are derived from Shodan data. Shodan data is owned by Shodan, which holds its copyright (© Shodan).

Its 14 tools look up one CVE (record, exploit code and fixed versions, EPSS history, vendor advisories, exposure footprint), list CISA's newest KEV additions, check whether a product or package version is affected, check an SBOM, and read a CWE and its CVEs. Every result says how it was measured (state, measured_at, method, coverage, freshness, notes), so a model cannot mistake an outage or an unassessed lookup for an all-clear.

It also serves four prompts, ready-made workflows a client can show as slash commands (triage_cve, kev_weekly_brief, am_i_affected, sbom_review; see "Prompts"), and three resources (echelongraph://methodology, echelongraph://sources and cve://{cve_id}; see "Resources").

Free and keyless: no API key, no auth, read-only. The server makes no request other than the API call a tool needs to answer.

• npm: echelongraph-mcp · Official MCP Registry: io.echelongraph/echelongraph-mcp · Docs: https://echelongraph.io/pulse/mcp
• Source: https://github.com/echelongraph/echelongraph-mcp · Changes: CHANGELOG.md · Security: SECURITY.md

Quick start

The local server runs through npx and needs Node.js 20 or later; nothing is installed globally. Add one of the blocks below to your client, restart it, then ask: "Is CVE-2023-44487 actively exploited, and how many exposed services does EchelonGraph's radar have on record for it?"

Claude Desktop

Settings → Developer → Edit Config opens claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json; Windows: %APPDATA%\Claude\claude_desktop_config.json). Add:

{
  "mcpServers": {
    "echelongraph": {
      "command": "npx",
      "args": ["-y", "echelongraph-mcp"]
    }
  }
}

Claude Code

claude mcp add --transport stdio echelongraph -- npx -y echelongraph-mcp

Add --scope user before the -- to make it available in every project, or --scope project to share it through the project's .mcp.json.

Cursor

~/.cursor/mcp.json (every project) or .cursor/mcp.json (one project):

{
  "mcpServers": {
    "echelongraph": {
      "command": "npx",
      "args": ["-y", "echelongraph-mcp"]
    }
  }
}

VS Code

.vscode/mcp.json in the workspace (VS Code's key is servers, not mcpServers):

{
  "servers": {
    "echelongraph": {
      "command": "npx",
      "args": ["-y", "echelongraph-mcp"]
    }
  }
}

or from a terminal:

code --add-mcp '{"name":"echelongraph","command":"npx","args":["-y","echelongraph-mcp"]}'

Windsurf, Cline and other clients

Clients that read an mcpServers block (Windsurf's mcp_config.json, Cline's MCP settings, and most others) take the same block as Cursor above.

Remote (no install)

The same 14 tools, four prompts and three resources are served over Streamable HTTP at:

https://mcp.echelongraph.io/mcp

Keyless, no sign-in, stateless; both protocol eras. The hosted endpoint is being rolled out: until https://mcp.echelongraph.io/health answers {"status":"ok",…}, use the npx setup above.

• claude.ai (Free, Pro, Max, Team and Enterprise plans): Customize → Connectors → + Add → Add custom connector. Name it EchelonGraph, paste the URL, choose No sign in, and add it. On Team and Enterprise an Owner adds it for the organization first, and each member then connects it. Free plans allow one custom connector.

• Claude Code:

  bash

  claude mcp add --transport http echelongraph https://mcp.echelongraph.io/mcp
  

• Cursor (mcp.json):

  json

  { "mcpServers": { "echelongraph": { "url": "https://mcp.echelongraph.io/mcp" } } }
  

• VS Code (.vscode/mcp.json):

  json

  { "servers": { "echelongraph": { "type": "http", "url": "https://mcp.echelongraph.io/mcp" } } }
  

• Windsurf (mcp_config.json):

  json

  { "mcpServers": { "echelongraph": { "serverUrl": "https://mcp.echelongraph.io/mcp" } } }
  

The hosted endpoint runs this package's code (dist/http.js, below) against the same public API, so its answers are the npm package's answers. What it sees and logs is under "Privacy", and its per-client limit under "Rate limits".

Tools

Every tool is read-only (readOnlyHint: true) and declares a title and an outputSchema. The example questions are ones a client can answer with that tool alone.

The three vendor-advisory tools relay vendor_published_at (the vendor's date), our_first_seen_at (when EchelonGraph first recorded the advisory) and withdrawn (the vendor rescinded it; the note names each one, and the search leaves them out).

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 cve_summary reads its counts

summary.critical, summary.high, summary.medium and summary.low count the active CVEs by severity band, and summary.total counts them all. summary.none counts the active CVEs with no severity band from any source: CVEs not yet scored, not CVEs rated None. The answer sends the same count again as summary.unscored.

summary.nvd_critical, summary.nvd_high, summary.nvd_medium, summary.nvd_low and summary.nvd_none count the same active CVEs a second time, by NVD's CVSS severity label (v3.x, else v4.0). Before NVD's record arrives, or where it gives none, a pre-NVD label from the CVE.org record or a GitHub advisory can stand in. They are provenance, never EchelonGraph's severity band. summary.nvd_none counts the active CVEs with no Critical, High, Medium or Low label there, and many of those carry an NVD CVSS v2 score instead, so it is neither a count of CVEs rated None nor the count of CVEs with no severity, which is summary.none.

summary.rejected counts the CVE records rejected (withdrawn) by their numbering authority. summary.total and the other counts leave them out, and they are withdrawn records, never vulnerabilities.

The tool relays the API's JSON as it was sent. When summary.none, summary.nvd_none or summary.rejected is above zero, the note says what it counts, with the number from the answer. The note says the five NVD counts add up to summary.total only when the answer's do, and says nothing about a field the answer does not carry.

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:

How cve_exposure counts

Every 12 hours, when Shodan query credits allow, the KEV-exposure radar runs one Shodan query per tracked product, reads up to 100 ip:port services per query, and keeps a service when its banner version matches a CISA-KEV or high-EPSS (>= 0.5) CVE. A service whose row has not been written or refreshed for 21 days is dropped. A count is therefore a banner-version inference over a sample: not an exploit test, and not an internet-wide census.

last_seen is when EchelonGraph last wrote or refreshed a service's row, not when the service was observed, and not when its vulnerable version was last confirmed. It is set to the time of the write when a search matches the banner, and again when a re-check finds the port still listed by Shodan InternetDB, without re-reading the banner, so a patched service can stay counted while its port stays open. Shodan's own time for the banner is not stored. So last_seen dates the write, never the sighting, and it is never measured_at (see "Structured results").

The unit is a service, not a machine. Shodan returns one banner per port and the radar keys each observation on ip:port, so a machine answering on two ports counts twice. The API's field names are kept (exposed_hosts here; distinct_hosts, ransomware_hosts and each ranked row's count in exposure_radar), but every one of them counts ip:port services.

The radar only looks for its tracked set of CVEs, so a zero means different things. The note tags each case with its exposure_state, as "(exposure_state: …)"; that tag says what the count is, and is not the result's state:

Whatever the exposure_state, the result's state is not_assessed with measured_at null: the answer does not say when any service it counts was observed (see "Structured results").

How exposure_radar counts

exposure_radar relays each radar's answer cut to the fields it can label, and its note labels every number by what it counts. A field this version does not know is left out and the note names it, whether it is a total or a field inside a ranked row; so is a known field in an unexpected shape, and a list with one malformed row is left out whole, since a partial list reads as a complete one. kev_exposure, exposed_databases and leaked_credentials also carry generated_at, when the API computed their totals, and, when the API can tell, last_run_at: when that radar last completed a check (each table below says what a completed check is for that radar).

last_run_at is a timestamp, not a count. It is recorded for the radar as a whole, not for the server instance that answered, in UTC to the second. It moves only at the end of a cycle whose reads succeeded, so a cycle that read nothing leaves it where it was. It is not the time of every record a radar's numbers count: those cover everything still on record, not only what the last check found. Nor is it generated_at, which is only when the API recomputed the totals. The API omits last_run_at when it has no completed check on record or cannot read it; the result then carries none, and the note says nothing about it. When it is there, the note gives it as, for example, "kev_exposure last completed check: 2026-09-27T03:12:44Z".

kev_exposure

Every count is over the services the KEV-exposure radar keeps: a Shodan banner whose version maps to a CISA-KEV-listed CVE (see "How cve_exposure counts").

A newest_kev row's exposure_state says whether its count is a measurement:

exposed_databases

leaked_credentials

None of them is validated. Each is a credential-shaped string in a public commit that passed EchelonGraph's filters, at most structurally checked (a checksum or format decode), and never tested against its provider, so none of these is a count of working credentials.

shadow_ai

The shadow-AI radar's answer mixes numbers that count exposed services with numbers that count every observation. So exposure_radar regroups it by what each number counts, and its note labels each one. Only shadow_ai.confirmed_exposed counts exposed services.

Neither authentication count is part of confirmed_exposed, and observed.total minus confirmed_exposed.total is not a count of secured services: it also holds observations not yet verified, whose hostname no longer resolves, or whose service no longer answers openly.

The tool relays no number it cannot label. A stats field this version does not know is left out, and the note names it; so is a count in an unexpected shape. A ranked row carries only its name and its count, and a field added to one is named too. The poller block's keys are 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.

mcp_servers.not_assessed_by_reason divides mcp_servers.not_assessed:

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:

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.

How check_affected decides

check_affected asks the matcher behind echelongraph.io/am-i-affected whether a version is affected, by one of two lookup paths:

• CPE path — product and version. product is the NVD CPE product token (openssl, nginx), which can differ from a package name. It returns the CVEs whose NVD CPE match criteria name that product with a version range that includes the version. It matches the token across vendors, so each match carries cpe_vendor and vendor_unknown: a match with vendor_unknown true is real, but its vendor is not verified to be yours.
• Registry path — ecosystem (npm, PyPI, Maven, …), package and version. Each OSV advisory record EchelonGraph holds for the package is decided against the version as affected (a match), not affected (not_affected_count) or undetermined.

Read assessed before count. assessed false means the lookup did not evaluate the component, and not_assessed_reason says why: product_not_in_cpe_corpus, package_not_cpe_nameable, candidate_load_pending (with degraded true), candidate_window_truncated, package_not_in_advisory_corpus or no_decidable_advisory. The result's state is then not_assessed, and its count of 0 never means "not affected". An advisory whose version range cannot be decided at this version is counted in undetermined_count (up to 50 listed in undetermined) and is never reported as safe. capped says the match list stopped at its cap, and candidates_capped that not every candidate CVE was loaded. A failed advisory lookup (advisory_lookup_failed) comes back as a failure. Each match keeps kev_listed, ransomware, epss_score, effective_score, effective_severity and score_assessed as the API sent them.

product, version, ecosystem and package travel in the X-EG-Product, X-EG-Version, X-EG-Ecosystem and X-EG-Package request headers, never in the URL, so request logs and trace spans that record URLs do not hold what was looked up. The endpoint reads a CPE vendor from the URL only, so this tool takes none.

Prompts

Ready-made workflows a client can show as slash commands. Each prompt names the tools to call, in order, and tells the model to read every result's state, measured_at, method, coverage and notes: not_assessed is never reported as clean, a count of 0 under assessed: false is never "not affected", and each figure cites its measured_at. A prompt makes no API request.

Resources

What a result means

Every tool answers in one of two shapes, so a model reading the result cannot mistake an outage for an all-clear:

• Success — the first text block is the API's JSON verbatim; the second is a one-line note saying the call succeeded, which base URL answered, and what it found; the third is the structured result as JSON, less what the first two already say (below). When the feed genuinely holds nothing for the query the note says so in words ("we looked and found nothing … not a lookup failure"), because a measured zero is a measurement. The exception to verbatim is exposure_radar: each radar is cut to the fields listed above, and each kev_exposure.newest_kev row gains an exposure_state. Its shadow_ai counts are regrouped as above, and its poller block carries only running and last_run_at, or is dropped when it carries no real completion time. The block's other fields describe the server instance that answered, not the radar. Its 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 30 minutes of the answer. When running is true, the note says the radar's leader last completed a cycle at that time; when it is false, the note says no cycle has completed since that time; when last_run_at is absent, the note says the radar's freshness is unknown and the block is left out. An older API answered from whichever server instance served the request, and a follower instance sent running: false with the zero time 0001-01-01T00:00:00Z; that too is unknown freshness, never presented as a stopped radar.
• Failure — an MCP error result (isError: true) whenever the lookup did not complete: the host could not be reached, it answered non-2xx, it took longer than the timeout, or it answered 2xx with a body that is not a JSON object. The text names the tool, the cause (status code or error kind), the path, and the base URL, and says it is not a finding; the second text block is the structured result as JSON, less the message's sentences (below). A failure is never rendered as a success with null fields.

Both shapes also carry a structured result, below, and repeat it in their last text block, less what an earlier block already says, so a client that passes only content to the model still sees how the answer was measured. The first text block (the API's JSON, or the failure) and the note after it are where 1.x put them.

Structured results

Since 2.0.0 every result, success or failure, carries structuredContent, and every tool declares its shape as an outputSchema in tools/list, with a title and the annotations readOnlyHint: true, destructiveHint: false, idempotentHint: true and openWorldHint: true (hints, which a client treats as untrusted).

The last text block of every result is this structured result serialized as JSON, less what an earlier text block already says verbatim, since a client may pass only content to the model. It carries the same state, measured_at, coverage and freshness (and on a failure error), key for key. It leaves out data, which is a success's first text block, and the note's sentences, which are the text block just before it (on a failure, the message) and with which notes ends: its notes holds only the sentences the envelope adds about itself, and is left out when there are none. It leaves out method too where that note quotes it verbatim, as cve_exposure's does ("Method: …"). So the text blocks together carry the whole structured result, and cannot disagree with it. Before 2.2.0 this block repeated the whole note, so every note was sent twice.

Every field comes from what the API sends; where the API does not say, the field is null and a note says so. Per tool:

• cve_summary is measured, and its measured_at is summary.last_updated, the newest modification time among the active CVE records it counts.
• search_cves is measured, with measured_at null: each record carries its own times. Its coverage repeats the list's total, total_counted, total_is_lower_bound, search_relaxed, limit and offset, and adds returned, the rows in the page. When total_counted is false the total is not a count, and the note does not call it one.
• get_cve is measured, and its measured_at is the record's updated_at, when EchelonGraph last wrote it.
• cve_exposure is not_assessed with measured_at null, every answer: the per-CVE answer carries no time at which the services it counts were observed. Its last_seen is when EchelonGraph last wrote or refreshed one of their rows, not when any of them was observed, so it is never measured_at, and a note says so. A tracked zero is not_assessed too, since a zero has no observation to date it. The count is still relayed, labelled: exposure_state is exposed, measured_zero, not_assessed or tracking_unknown, the cases of "How 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 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.
• check_affected is measured only when the answer says assessed true, and not_assessed when it says false or does not say. Its measured_at and freshness are null: a match answer carries no observation time. Its coverage gives assessed and not_assessed_reason first, then lookup (cpe or registry), match_layer, count, capped, candidates_capped, excluded_count, undetermined_count, not_affected_count and degraded.

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.

A success whose fields do not fit the tool's outputSchema (a field of a type the schema does not allow) is returned as a failure with error.kind unexpected_shape, never relayed. A field the API adds later is still relayed by every tool that relays the API's JSON as data, and exposure_radar and cve_intel, which relay a selection, leave it out and name what they leave out.

Protocol versions

The server answers both eras of the Model Context Protocol on stdio:

• 2026-07-28: a client that opens with server/discover receives a DiscoverResult listing 2026-07-28, the tools, prompts and resources capabilities and the server instructions, and then sends each request with the per-request _meta envelope.
• 2025 and earlier: a client that opens with initialize, as every 1.x SDK client does, negotiates 2025-11-25, 2025-06-18, 2025-03-26 or 2024-11-05; a version the server does not know is answered with 2025-11-25.

The first message of a connection picks its era. The DiscoverResult lists only 2026-07-28, as the SDK builds it: the 2025-era versions are reached through initialize. Both handshakes carry the package's name and version (serverInfo), and every API request carries them in its User-Agent, echelongraph-mcp/<version>.

Both handshakes also carry the server instructions: the data is public; what state, measured_at and freshness mean, and that the last text block repeats them; that exposure numbers are aggregate counts of ip:port services, not an internet-wide census; and that Shodan data is Shodan's.

Privacy: what is sent where

The npm package (stdio). The server runs on your machine and sends HTTPS requests to one host, ECHELONGRAPH_API_BASE (default https://app.echelongraph.io), one per API call a tool makes (exposure_radar makes five; every other tool makes one). No telemetry: it sends nothing else, to EchelonGraph or anyone. Every request carries the User-Agent echelongraph-mcp/<version> (+https://echelongraph.io/pulse/mcp), with the ECHELONGRAPH_MCP_UA token ahead of it when you set one, so the API's access log can count use per version. Like any HTTPS request, it also reaches the API from your network address.

Where each tool's input travels:

The API marks its answers to header-carried lookups no-store, so no shared cache keeps them, and request logs and trace spans that record URLs do not hold what was looked up there.

The hosted endpoint. A request to https://mcp.echelongraph.io/mcp reaches EchelonGraph's server first, which then calls the same API as above. Per request it logs the HTTP method and path, the status, the duration, the body size, the JSON-RPC method and (for tools/call) the tool name, the protocol version, whether an Origin header was sent, and the family of your client's User-Agent. It never logs tool arguments or a query string. When a client passes the per-client limit it logs that client's address key. It passes your client's public address to the API, in a header the API trusts only with a token it checks, so the API's rate limit counts you and not the hosted service.

EchelonGraph's privacy policy: https://echelongraph.io/privacy.

Rate limits

No API key, so the API limits each caller, one IPv4 address or one IPv6 /64 network as its platform records it. Its WAF counts all your requests together in a 60-second window and refuses one once the count passes the ceiling for its path:

Because the count is shared, heavy use of one path also uses up the lower ceilings. On top of that, 500 requests per second per caller is a burst cap on each serving instance, and check_sbom's batch route is charged per component: 1,200 components a minute per caller. Over a limit the API answers 429 with Retry-After, and the tool returns a failure (state failed, error.status 429), never empty data. The API's own documentation of these limits: https://echelongraph.io/pulse/api.

The hosted endpoint adds its own limit before the API's: 120 MCP requests a minute per client address, counted by each server instance, answered over it with HTTP 429, Retry-After and a JSON-RPC error (code -32029) that names the limit and the seconds to wait. A request body over 64 KiB is refused.

Configuration

The npm package (stdio):

The HTTP entrypoint, dist/http.js (npm run start:http), serves the same tools over Streamable HTTP on POST /mcp, with a liveness check on GET /health. It reads the three variables above and:

Develop

npm install
npm run build      # tsc → dist/
npm test           # build, then the behavioural suite over both protocol eras, against a stub API (no network needed)
npm run smoke      # spawn the server + call cve_exposure against the production API

npm run smoke calls the production API with this package's User-Agent, so its requests are counted as external MCP adoption. npm test never leaves the machine.

npm test runs the suite once over a 2026-07-28 server/discover and once over a 2025-06-18 initialize, plus the era tests. To run it against an installed package rather than dist/, set ECHELONGRAPH_MCP_BIN to that package's echelongraph-mcp bin: the tests then run the bin directly, as npx does, and read that package's own files.

Versioning

Semantic versioning: a major version changes protocol behaviour or drops a Node.js version, a minor version adds tools or fields, a patch fixes wording or behaviour without changing a tool's shape. Every release is published to npm with a provenance attestation by the public repo's release workflow, from the commit tagged v<version>. Changes per version: CHANGELOG.md.

Security

Report a vulnerability privately to support@echelongraph.io, not in a public issue. The policy, the supported versions and the scope are in SECURITY.md.

License

The code is MIT-licensed.

The CVE Pulse compilation (how EchelonGraph combines its CVE sources, and the EchelonGraph score) is © EchelonGraph, served under the CVE Pulse free-access terms; the source records it compiles stay under their publishers' terms.

Exposure counts are derived from Shodan data. Shodan data is owned by Shodan, which holds its copyright (© Shodan). EchelonGraph claims no ownership of it or copyright in it.