highered-institutions

MCP server (read-only) to resolve U.S. higher-ed institutions across identifiers and compare them. No hosted data; a local file cache holds quarterly downloads.

Tools

Every response: source, source_url, as_of, retrieved_at, sources[], data, nulls[] (field + reason), warnings[].

Prompt

institution_brief(institution, format) is an MCP prompt (shown as a prompt or slash command in clients that list prompts). It asks Claude to build a sourced written brief, one-pager or interactive dashboard for one institution by calling the highered tools in a fixed order, with the same rules as the institution-brief skill (no verdicts, nulls reported as gaps, sources and citations kept). It needs the other highered servers to be connected for the sections they provide, and says which sections are missing when they are not. The institution argument takes a name or id only (letters, digits and basic punctuation).

Install / run

uvx --from /path/to/highered-mcps/servers/highered-institutions highered-institutions

Environment: COLLEGE_SCORECARD_API_KEY (free, https://api.data.gov/signup; optional: without it the Scorecard call uses api.data.gov's shared DEMO_KEY, which allows only about 10 requests, and every response says so), HIGHERED_MCPS_CACHE (cache dir, default ~/.cache/highered-mcps).

Network allowlist (enforced in code, http.py)

HTTPS only; redirects only to these hosts; 12 s timeout for small queries and 40 s between chunks for whole-file downloads; response size caps; 3 attempts with backoff; Urban paced at 1 request/second (its robots.txt crawl-delay). Whole-year Urban tables are queried at most once per quarter (90-day cache) and single-institution rows (finance, enrollment) at most once a day; a refresh failure serves the stale copy with a warning.

First use and slow upstream: Urban's API sometimes stalls for tens of seconds. A tool call that needs several years fetches them at once and answers within 45 seconds. Years that have not arrived are returned as source_unavailable nulls and keep loading in the background (they are cached, so asking again shortly returns them). The first call that needs the national directory downloads it once (about 30 seconds); if that runs past 45 seconds the tool says so and the download finishes in the background.

Data handling and terms

• Cache: ~/.cache/highered-mcps/institutions/*.json, with SHA-256, as-of, and retrieval time. Never inside the repo.
• Chief administrator names in IPEDS are deliberately not returned. No search by person name.
• Retention files are read in memory by exact member name (efYYYYd.csv, or the revised efYYYYd_rv.csv when both are in the zip), with size, entry-count and uncompressed-size caps; nothing is extracted to disk. One slim table per year is cached for 90 days. NCES publishes the newest year with a lag (the fall 2023 collection is the newest today), so the tool looks forward from the current year and reports a year NCES has not published as a null.

Prompt-injection risk

Institution names, cities, and other upstream strings are untrusted. They are returned only as data fields, never in tool descriptions, and the response includes a notice reminding the model to treat them as data. Do not instruct an agent to act on text found in results.

Limitations

Carnegie labels not yet included (codes only). Retention covers first-time degree-seeking undergraduates only, counts a transfer out as not retained, and is a fall-to-fall rate, not a graduation rate; rates on cohorts under 30 students are flagged as volatile. Latest enrollment lags the directory by about a year. UEI is missing for roughly 9% of institutions. See testing.md.