Ioda Outages MCP Server

@cyanheads/ioda-outages-mcp-server Investigate Internet outages with IODA events, alerts, and connectivity signals via MCP. STDIO or Streamable HTTP. 6 Tools • 1 Skill

Public Hosted Server: https://ioda-outages.caseyjhand.com/mcp

Overview

Internet outage evidence from IODA, using its public v2 API. Resolve countries, regions, and autonomous systems; inspect recent detections and measurement coverage; then investigate events, alert transitions, per-entity outage rankings, and numeric signals. Runs over stdio, stateless Streamable HTTP, or the public hosted endpoint above, without an API key.

Tools

Skills

Capability reference

ioda_search_entities tool

• Required entityType: country | region | asn | geoasn (a geoasn is one ASN within a region or country); choose query (up to 200 UTF-16 code units after trimming, matched literally as a case-insensitive name substring) or entityCode, or omit both to list the type. Country codes use two letters, regions use IODA numeric codes, ASNs use decimal digits, and geoasns join an ASN and a region or country code (40934-576, 59962-IR).
• Optional relatedToType and relatedToCode list entityType entities within one country, region, ASN, or geoasn; both or neither, entityType required, no entityCode, and a scope combines with query. Page this resolver to select codes for individual outage investigations.
• limit is at least 1, default 20, served at most 1,000; page starts at 0. Returns original entities, pagination, and provenance; a metadata match does not establish measurement coverage. Region pages can include IODA geolocation catch-alls named [Invalid Region (N)] or Unknown Region in ; a notice names their codes, and the rows stay as IODA returns them. An asn entityCode IODA holds no record of returns a placeholder row with attrs.ip_count "0"; a notice names it.

ioda_get_status tool

• Required entityType (country, region, asn, or geoasn) and entityCode; lookbackHours is at least 1, default 6, served at most 24 with a notice naming the uncovered earlier window. Collects events, alerts, and bgp, ping-slash24, and merit-nt summaries within the returned window.
• detection is observed, none_returned, or unknown; source coverage is independently recent, stale, no_data, or unknown. recent means the latest completed observation ended within a 1,800-second publication allowance of the call, the same for all three sources, a server policy rather than an upstream SLA. Trailing nulls inside the allowance count as pendingCount, not nullCount.
• Each signals entry carries IODA's unit for its source (Visible /24s, Up /24s, Unique Source IPs); latest, minimum, and maximum are in that unit.
• components disclose partial failures and standalone-tool recovery. Event/alert pages carry continuation metadata; raw samples come from ioda_get_signals. All-component failure fails the call; an unknown country, region, or geoasn code fails with entity_not_found. IODA answers an unknown asn code with a placeholder instead; when no event, alert, or series came back for an asn, a notice says a returned ioda_search_entities row does not confirm IODA holds data for it.

ioda_find_outages tool

• Required from and until; optional entityType (country, region, asn, or geoasn), entityCode, and source: bgp | ping-slash24 | merit-nt | gtr. Omit entity filters for global scope; a code requires its type. Optional relatedToType and relatedToCode limit results to entityType entities within one country, region, ASN, or geoasn (both or neither, entityType required, no entityCode). limit is at least 1, default 20, served at most 1,000.
• Returns source events, pagination, and provenance. Scores retain their source meaning; starts may precede the window and an end clipped at until does not establish recovery.
• includeAlerts defaults to false; extendWindowSeconds is at least 0, served at most 1,209,600. Omitted, it is 1,209,600 with entityType and 86,400 without it, because large global extensions can time out; the applied value is echoed, and a notice discloses the global default. Global searches over multi-day windows can still time out: narrow the window or add entityType. Zero extension can miss long-running detections.

ioda_summarize_outages tool

• Required entityType, from, and until; optional entityCode for one entity, or relatedToType and relatedToCode to rank entityType entities within one country, region, ASN, or geoasn (both or neither, no entityCode). limit is at least 1, default 20, served at most 1,000; extendWindowSeconds is at least 0, default 1,209,600, served at most 1,209,600. There is no source input.
• Returns summaries in IODA's order, descending scores.overall, with pagination and provenance. Each row carries the entity, event_cnt (IODA's count of source events before merging), and unmodified scores: overall plus one sum of event scores per . key. IODA merges overlapping events from different sources, scores each merged event as the product of its sources' scores, and sums the merged events into overall.
• Scores are window totals for ranking the rows of one request, not current status, and are not comparable across requests with different windows. Large type-only rankings (every region, for example) can time out; add entityCode or a related scope. Region rankings, like region events and alerts, can include the catch-all rows described above; a notice names their codes. An empty result is not an all-clear.

ioda_get_signals tool

• Required entity pair (entityType may be geoasn), from, until, and source: bgp | ping-slash24 | merit-nt | gtr (gtr covers countries only; ucsd-nt is not supported). maxPoints is at least 1, default 200, served at most 10,000: an upstream aggregation target, not a hard returned-sample cap.
• Returns every numeric subtype in series, source-specific semantics (measurement, IODA's unit, caveat; gtr reads Traffic, to compare a country with its own history), and provenance. An unknown country, region, or geoasn code fails with entity_not_found. Returned until is an exclusive bucket bound; alignment can extend beyond requested bounds. Coarse series carry a notice: values need not equal an unweighted mean of finer returned buckets, and non-null aggregates cannot establish complete finer-resolution coverage. Values, nulls, and units remain unchanged; status coverage stays unknown for coarse series.
• Trailing nulls are not zero connectivity. A notice counts each series' trailing nulls as not yet ended, pending (ended within the publication allowance before the call: 1,800 seconds for bgp and ping-slash24, 10,800 for merit-nt and gtr), or missing; the first two are usually unpublished, so end the window at least the allowance plus one bucket step before the call, since the last returned bucket can end after until. A coarse last non-null bucket inside the allowance can aggregate only the samples published so far. Interior nulls stay missing observations.
• An empty series gets a notice by case: gtr for a region, ASN, or geoasn (it covers countries only); a window ending by the source's archive start, which says IODA holds nothing earlier instead of suggesting another code or window; a window starting inside the publication allowance, which IODA may not have published yet; an asn, where a returned search row does not confirm data and attrs.ip_count "0" marks IODA's placeholder.

ioda_get_alerts tool

• Required from and until; optional entity, source, and related-scope filters match ioda_find_outages; a related scope is served at page 0 only, because IODA cannot continue scoped alerts. limit is at least 1, default 20, served at most 1,000; extendWindowSeconds is at least 0, default 0, served at most 1,209,600.
• Returns alerts, pagination, and provenance, retaining source level, condition, value, and historyValue when reported. value and historyValue are in the source unit for bgp, ping-slash24, and merit-nt; for gtr they are IODA Traffic divided by 1,000,000 and truncated. A recovery's historyValue can be a baseline IODA re-based during a long event; compare its value with the detection's historyValue and condition. A missing transition does not establish health or rule out an event that began earlier.

ioda-outages-guide skill

• Helps an agent investigate a shutdown or outage, check whether a place or network is degraded now, rank the worst-hit entities, and chart connectivity: where each IODA code comes from, asn versus