⚡ VoltSentry

US Power Grid Stress Intelligence — MCP Tool

🚀 View Live Status | 🔌 MCP Integration | 📖 API Reference

VoltSentry is a production-grade Model Context Protocol (MCP) server providing real-time situational awareness of the US electrical infrastructure. By correlating live data from the EIA and NOAA, it calculates grid stress using NERC-calibrated reliability thresholds.

Builder: DeeThunder (Isaac-Great Atanda) Category: Real World Data & Utilities

---

🏗️ Architecture

┌─────────────────────────────────────────────────────────┐
│  Layer 4 — MCP Server (server.ts)                       │
│  Express + MCP SDK. Clustering, compression, security.  │
│  Endpoints: / • /health • /api/stress/:region • /mcp    │
├─────────────────────────────────────────────────────────┤
│  Layer 3 — Cache (cache.ts)                             │
│  Redis (production) + in-memory fallback (local dev).   │
│  30-minute TTL. Request deduplication.                  │
├─────────────────────────────────────────────────────────┤
│  Layer 2 — Stress Scorer (scorer.ts)                    │
│  5-signal NERC-calibrated algorithm → 0–100 score.      │
│  Produces verdict + actionable insight + NERC context.  │
├─────────────────────────────────────────────────────────┤
│  Layer 1 — Data Fetcher (fetcher.ts)                    │
│  EIA + NOAA + EIA Nuclear in parallel via Promise.all.  │
│  10s timeout per call. Graceful fallbacks.              │
└─────────────────────────────────────────────────────────┘

Data Sources (all free)

Source	What	Update Frequency
EIA API	Demand, forecast, net generation per region	Hourly
NOAA Weather API	Temperature per region (no key needed)	Hourly
EIA Nuclear Outages	MW of nuclear capacity offline	Daily

---

🔌 How to Connect (MCP)

VoltSentry is fully compatible with the Model Context Protocol (MCP). You can easily give your AI agents (like Claude Desktop or custom agents) real-time access to US Power Grid data.

MCP Endpoint: https://voltsentry-384876274118.europe-west1.run.app/mcp

When connected, your agent will have access to the analyze_grid_stress tool, allowing it to seamlessly answer questions about the power grid and assess regional energy crises autonomously.

---

🌐 How to Use (REST API)

VoltSentry also exposes a standard REST API so you can build dashboards, mobile applications, or automation scripts without needing to run any infrastructure yourself. All data points are updated in real-time.

Base URL: https://voltsentry-384876274118.europe-west1.run.app

# Example: Check the stress level of the Texas grid (ERCOT)
curl https://voltsentry-384876274118.europe-west1.run.app/api/stress/ERCO

---

📖 API Reference

GET / — Health Check

Returns basic server status.

GET /health — Detailed Health

Returns real-time metrics, cache stats, and secret configuration status.

GET /api/regions — Region Listing

Returns all supported grid regions with names, cities, and endpoints.

GET /api/stress/:region — Single Region Analysis

Returns full Grid Stress Report for one region.

Example: GET /api/stress/ERCO

{
  "region": "ERCO",
  "timestamp": "2026-03-13T17:32:31.227Z",
  "stressScore": 48,
  "stressLabel": "ELEVATED",
  "demandMW": 49643,
  "forecastMW": 46079,
  "generationHeadroomPercent": -4.1,
  "temperatureF": 67,
  "nuclearOffline": 13215.974,
  "historicalDeviationPercent": 10.55,
  "verdict": "ERCO grid is ELEVATED but manageable...",
  "actionableInsight": "No immediate action needed...",
  "scoringBreakdown": {
    "demand_vs_forecast": 10,
    "generation_headroom": 25,
    "temperature_extreme": 0,
    "nuclear_offline": 10,
    "historical_deviation": 3
  },
  "nercContext": "Grid is approaching NERC planning margins..."
}

GET /api/stress — All Regions (sorted by stress)

POST /mcp — MCP Endpoint (CTX Protocol)

JSON-RPC 2.0 endpoint for MCP clients. AI agents call analyze_grid_stress with { region: "ERCO" }.

---

Supported Regions

Code	Region	Major Cities
ERCO	Texas (ERCOT)	Dallas, Houston, Austin
CISO	California (CAISO)	Los Angeles, San Francisco
PJM	Mid-Atlantic	Philadelphia, Washington DC
MISO	Midwest	Chicago, Detroit, Minneapolis
ISNE	New England (ISO-NE)	Boston, Providence
NYIS	New York (NYISO)	New York City
SWPP	Southwest Power Pool	Oklahoma City, Kansas City
PACW	Pacific Northwest	Seattle, Portland
SOCO	Southeast (Southern Co)	Atlanta, Birmingham
TVA	Tennessee Valley	Knoxville, Nashville