Ioda Outages Mcp Server

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 <country>; 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 <source>.<method> 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 geoasn, getting the clock from the server, publication lag, native signal resolution, and which conclusions the evidence supports
• Served over MCP as the resource skill://ioda-outages-guide/SKILL.md under the template skill://{+path}; also ships in skills/ for plugin installs and the .mcpb bundle

Features

Built on @cyanheads/mcp-ts-core: stdio and Streamable HTTP transports, pluggable auth (none / jwt / oauth), swappable storage (in-memory, filesystem, Supabase, Cloudflare KV/R2/D1), structured logging with optional OpenTelemetry tracing.

IODA-specific:

• Keyless reads from a fixed HTTPS API origin; no local database or native helper.
• Historical windows use integer Unix seconds UTC: from < until <= now, at most 31 days. Alerts include transitions at both bounds (widened by extension); events and summaries include starts at until. Adjacent windows can duplicate boundary detections. Signal bounds describe aligned buckets; status echoes the requested window across components with different selection rules. IODA's API holds no outage detections before 2022-01-26 UTC and no merit-nt, bgp, or ping-slash24 observations before 2022-01-09, 2022-01-18, and 2022-02-02 (gtr has no start); an empty result for a window ending by then says so instead of suggesting another code or a wider window.
• ignoreMethods: string[] on events, alerts, and rankings excludes detections upstream before event construction and scoring: source.method, source.*, or *.method, with sources bgp, ping-slash24, merit-nt, and gtr. Case/whitespace normalize and duplicates collapse; an empty array excludes nothing. Malformed terms and *.* fail invalid_arguments; an explicit source plus its own source.* fails invalid_ignore_methods. Keep exclusions fixed across pages and ranking drill-downs; provider scores and order are preserved.
• Every related-scope outage response warns that membership coverage is unverified, even on short or empty pages. Page ioda_search_entities with the same entity type, scope, and limit, then query selected codes individually with the original window, source/exclusions, extension, and paging limit; each response supplies the concrete calls. pagination.more describes row pages, not scope completeness.
• Pagination is zero-based; follow nextPage with filters and limit unchanged. more: "possible" signals possible continuation, not a known total; restart at page 0 after changing the limit.
• Numeric inputs have no advertised maximum: a larger limit (cap 1,000), maxPoints (10,000), lookbackHours (24), or extendWindowSeconds (1,209,600) is served at the cap, and a notice names the requested value, the served value, and the route to the rest. Minimums and non-integers fail argument validation. With IODA_CLAMP_LIMITS=false, each cap is the schema maximum and a larger value fails invalid_arguments.
• Shared request pacing allows one in-flight request and at least two seconds between starts, with a 45-second invocation deadline. Avoid concurrent investigations.
• IODA describes macroscopic connectivity. Missing detections are not an all-clear; source scores are not universal severity, and observations cannot establish a shutdown cause or one office's connectivity.

Agent-friendly output:

• Provenance — endpoint links, fetch times, and the original Georgia Tech Research Corporation attribution accompany returned evidence; applied echoes effective inputs.
• Explicit uncertainty — null samples, missing fields, source coverage, and partial component failures stay distinct.
• Complete responses — content[] and structuredContent carry the same data, enrichment included, and a page is never shortened to fit a size budget. An upstream body over 4 MiB fails upstream_schema.

Getting started

Connect to the hosted instance, no install:

claude mcp add --transport http ioda-outages-mcp-server https://ioda-outages.caseyjhand.com/mcp

Or run it locally:

claude mcp add ioda-outages-mcp-server -- npx -y @cyanheads/ioda-outages-mcp-server

For other clients, add this to the MCP config file:

{  "mcpServers": {    "ioda-outages-mcp-server": {      "command": "npx",      "args": ["-y", "@cyanheads/ioda-outages-mcp-server"]    }  }}

IODA needs no API key or account, only outbound HTTPS to api.ioda.inetintel.cc.gatech.edu. For Docker or a source build, see Running the server.

Configuration

One server-specific variable, then the common framework variables:

See .env.example for the full list of framework overrides.

Running the server

Local development

Requires Bun v1.4.0 or higher (or Node.js v24+).

• Clone and install:

  sh

  git clone https://github.com/cyanheads/ioda-outages-mcp-server.gitcd ioda-outages-mcp-server && bun installcp .env.example .env   # optional: `IODA_CLAMP_LIMITS` and framework overrides

• Build and run:

  sh

  # One-time buildbun run rebuild
  # Run the built serverbun run start:stdio# orbun run start:http

• Run checks and tests:

  sh

  bun run devcheck   # Lint, format, typecheck, securitybun run test       # Vitest test suitebun run lint:mcp   # Validate MCP definitions against spec

Docker

docker run --rm -p 3010:3010 ghcr.io/cyanheads/ioda-outages-mcp-server:latest

The image defaults to HTTP transport, stateless session mode, and logs to /var/log/ioda-outages-mcp-server. To run it over stdio from an MCP client, use "command": "docker" with "args": ["run", "-i", "--rm", "-e", "MCP_TRANSPORT_TYPE=stdio", "ghcr.io/cyanheads/ioda-outages-mcp-server:latest"]. To build locally, docker build -t ioda-outages-mcp-server .; OpenTelemetry peer dependencies are installed by default — build with --build-arg OTEL_ENABLED=false to omit them.

Project structure

Development guide

See CLAUDE.md for development guidelines and architectural rules, and docs/design.md for the domain contracts. The short version:

• Handlers throw, framework catches — no try/catch in tool logic
• Use ctx.log for logging, ctx.signal for cancellation, and ctx.enrich for applied inputs and notices
• Register new tools in the createApp() arrays in src/index.ts
• Wrap external API calls: validate raw → normalize to domain type → return output schema; never fabricate missing fields, and keep both response surfaces complete

Contributing

Issues are welcome. Run checks and tests before submitting:

bun run devcheckbun run test

License

Apache-2.0; see LICENSE. IODA data retains its Georgia Tech Research Corporation copyright and remains subject to the source's terms.