# WeatherXM FACT — Forecast Accuracy Tracking (MCP & Agent Guide)

> Empirical weather forecast accuracy benchmark scoring 45 NWP & AI forecast models (ECMWF IFS/AIFS, NOAA GFS/HRRR/NBM, DWD ICON, UKMO, meteoblue, meteoblue station-mLM, WeatherXM MOSAIC, etc.) against 10,000+ quality-checked WeatherXM ground stations (1.83B+ forecast evaluations across 2025).

- Interactive Dashboard: https://fact.weatherxm.com
- MCP Server Endpoint (Streamable HTTP, No Auth Required): https://fact.weatherxm.com/mcp
- MCP Discovery Manifest: https://fact.weatherxm.com/.well-known/mcp.json
- OpenAPI 3.1 Specification (REST Mirror): https://fact.weatherxm.com/openapi.json
- Methodology Documentation: https://github.com/WeatherXM/FACT/blob/main/docs/FACT_METHODOLOGY.md

---

## How Humans Can Give WeatherXM FACT to an AI Agent

### Option 1: Copy-Paste Prompt for Any AI Agent (ChatGPT, Claude, Gemini, OpenClaw, Custom Agents)
Copy and paste the following instruction directly into your AI assistant or agent system prompt:

```text
You have access to WeatherXM FACT (Forecast Accuracy Tracking), which benchmarks 45 global and regional weather forecast models against 10,000+ physical ground stations.
- If you support MCP (Model Context Protocol), connect to the unauthenticated Streamable HTTP MCP server at: https://fact.weatherxm.com/mcp
- If you can fetch URLs or call HTTP GET endpoints, use the unauthenticated JSON REST API:
  1. Global or country leaderboard: GET https://fact.weatherxm.com/api/v1/fact/leaderboard?variable=temperature&lead_day=1 (optional: &country=Switzerland)
  2. Best forecast model for coordinates: GET https://fact.weatherxm.com/api/v1/fact/best-model?lat=37.9838&lon=23.7278&variable=wind_speed&lead_day=all
  3. Ground-truth station coverage: GET https://fact.weatherxm.com/api/v1/fact/coverage?lat=37.9838&lon=23.7278&variable=temperature
  4. Head-to-head model comparison: GET https://fact.weatherxm.com/api/v1/fact/head-to-head?variable=wind_speed&models=mLM,METEOBLUE,IFS025,GFS05,ICON
Allowed variables: temperature, wind_speed, precipitation, humidity. Allowed lead_day values: all, 0, 1, 2, 3, 4, 5, 6, 7.
```

### Option 2: Connect via Native MCP (Streamable HTTP)
- **Endpoint URL:** `https://fact.weatherxm.com/mcp`
- **Authentication:** None (public read-only endpoint)
- **Claude (Web & Desktop):** Go to `Settings -> Connectors -> Add Custom Connector` and enter `https://fact.weatherxm.com/mcp`.
- **ChatGPT (Connectors / Developer Mode):** Go to `Settings -> Connectors -> Create` and enter `https://fact.weatherxm.com/mcp` (or import `https://fact.weatherxm.com/openapi.json` for Custom GPT Actions).
- **Claude Code CLI:**
  ```bash
  claude mcp add --transport http weatherxm-fact https://fact.weatherxm.com/mcp
  ```
- **Cursor / Windsurf / VS Code (`mcp.json`):**
  ```json
  {
    "mcpServers": {
      "weatherxm-fact": {
        "url": "https://fact.weatherxm.com/mcp"
      }
    }
  }
  ```

---

## Exposed MCP Tools (`https://fact.weatherxm.com/mcp`)

1. **`get_best_forecast_model`**
   - Finds which weather forecast model had the lowest verified historical error (MAE) for a `(lat, lon)` coordinate (H3 Res-7 cell, ~5.2 km²) or `station_or_report_id`, weather `variable` (`temperature`, `wind_speed`, `precipitation`, `humidity`), and `lead_day` (`all`, `0`..`7`).
2. **`check_ground_truth_coverage`**
   - Checks historical WeatherXM FACT ground-station publication coverage for any coordinate (`lat`, `lon`), plus nearest evaluated reference cell distance and interactive map citation link.
3. **`get_fact_leaderboard`**
   - Reads the global weather forecast accuracy leaderboard (MAE, RMSE, and categorical rain skill HSS, POD, FAR, CSI across lead days `0`..`7`) or country-level published H3 cell-win summaries (`country`: exact country name such as `Switzerland`, `Greece`, `Germany`, `United States`).
4. **`get_model_head_to_head`**
   - Compares up to 10 weather forecast models head-to-head across lead days `0` to `7` on global historical error curves.

---

## Example Natural-Language Prompts
- "I need to pick a weather forecast provider for wind-sensitive operations. Based on actual ground-truth verification rather than marketing claims, which models have the lowest wind speed error, and is it worth paying for a commercial station-tuned forecast over free models like GFS or ECMWF?"
- "We currently use free public models (GFS and ICON) for temperature and humidity, but errors are hurting our operations. Which commercial or AI models actually beat them in independent ground-station benchmarks?"
- "Which weather forecast provider is empirically the most accurate for precipitation and temperature across a 1-to-7 day horizon?"