malaria-forecast-mcp

An MCP server that gives an AI agent access to provincial malaria surveillance and short-horizon outbreak forecasting for Angola — with the guardrails that make model output safe for an agent to act on.

Built by Joaquim Timóteo. The forecasting work it wraps is described in Operational Malaria Forecasting in Angola Using Ensemble Models, Regional Clusters, and Epidemiological Memory Features (ResearchGate, Feb 2026).

---

Why MCP instead of a REST API

A REST endpoint gives a model a URL and hopes the prompt explains the rest. MCP ships the contract alongside the capability, and three consequences follow that matter for anything forecasting-shaped:

Discovery is dynamic. Tool schemas are read at connect time. Adding compare_provinces made it available to every connected client without a single prompt being rewritten.

Provenance travels with the capability. malaria://model-card is a resource the model can read before quoting a number — validation method, measured skill, known failure modes. With a REST API that context lives in a PDF somewhere, which is to say it does not reach the model at all.

Refusals are structured. Ask for a 20-week horizon and you get a typed error naming the validated range, not a plausible-looking wrong number:

{
  "error": "horizon_out_of_range",
  "detail": "horizon_weeks must be between 1 and 8; got 20. The model was validated only to 8 weeks and will not extrapolate beyond it.",
  "max_validated_horizon_weeks": 8
}

That last one is the whole argument. A forecasting model wired to an agent without guardrails will answer any question it is asked, including the ones it has no business answering.

---

What it exposes

Tools

Tool	Purpose
list_provinces	All 18 provinces with epidemiological stratum (K-means burden clustering)
get_incidence_history	Weekly incidence and the rainfall driver, filtered by date range
forecast_incidence	1–8 week forecast with empirical 80% intervals
detect_outbreak_signals	Weeks running above the same-calendar-week seasonal baseline
compare_provinces	Ranked forecast across provinces, for resource prioritisation

Resources

• malaria://model-card — architecture, validation method, measured metrics, limitations, guardrails
• malaria://provinces — province directory for grounding

Prompts

• outbreak_briefing — walks the agent through model card → history → signals → forecast, then writes a briefing that always states intervals rather than point estimates
• compare_and_prioritise — ranks provinces and requires the agent to say when two are not meaningfully separable

---

Guardrails

1. Horizons outside 1–8 weeks are refused, with the reason, rather than extrapolated.
2. Provinces with under 52 weeks of history are refused rather than forecast on a season the model has never seen.
3. Every point carries an empirical 80% interval from rolling-origin residuals — no distributional assumption.
4. Anomaly flags are seasonal. A flag means "high for this week of the year" against prior years, not "high in absolute terms" — which in a seasonal disease is the difference between a signal and a calendar.

---

Evaluation

The harness was written before the tools, and it earns its place: it caught a real defect.

python evals/backtest.py

Rolling-origin backtest, 26 origins per province per horizon — 468 scored forecasts at each horizon:

  h  origins       MAE  baseline    skill   cov80
--------------------------------------------------
  1      468    0.5677    0.8666   0.3450  79.70%
  2      468    0.5992    0.8666   0.3085  80.13%
  3      468    0.6137    0.8666   0.2919  80.77%
  4      468    0.6100    0.8666   0.2961  82.69%
  5      468    0.6051    0.8666   0.3018  82.69%
  6      468    0.6299    0.8666   0.2732  85.26%
  7      468    0.6461    0.8666   0.2544  86.11%
  8      468    0.6538    0.8666   0.2456  86.11%

skill is 1 − (model MAE / seasonal-naive MAE). The script exits non-zero if any horizon stops beating the baseline, so this is a gate rather than a report.

Two findings worth stating plainly, because they are the reason the harness exists:

Fixed ensemble weights lost to the baseline at 7–8 weeks. Local trend and climate signal decay with range while seasonal structure survives. Weights are now horizon-dependent, and skill is positive across the full range. Intuition said the ensemble was fine; the backtest said otherwise.

The intervals were miscalibrated. The textbook 0.80 quantile of absolute residuals produced 90–95% measured coverage — too wide, because residuals estimated on recent origins are systematically harder than the weeks being forecast. The quantile was calibrated down to 0.60, which measures at ~80% at short horizons and stays conservative (~86%) at long ones. Coverage is reported on every run so it cannot drift silently.

---

Data

The bundled dataset is synthetic. Provincial surveillance records are not redistributable, so the series reproduces the statistical shape of the real thing — rainy-season seasonality, burden strata, interannual variability, outbreak excursions — without exposing restricted data.

Every metric in this README describes this reimplementation on synthetic data. The published research model reports R² 0.985, MAE 6.9 per 1,000 and an 87.5% skill score on real surveillance across all 18 provinces, 2000–2024. Those are different numbers about a different artefact and the model card keeps them clearly separated.

To run against real data, implement the SurveillanceStore interface in data.py. No tool signature changes.

---

Install and run

git clone https://github.com/joaquimtimoteo/malaria-forecast-mcp
cd malaria-forecast-mcp
pip install -e .

python -m malaria_forecast_mcp        # stdio server
python scripts/smoke_check.py         # 26 end-to-end protocol checks
python evals/backtest.py              # evaluation gate
pytest tests/                         # full suite

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "malaria-forecast": {
      "command": "python",
      "args": ["-m", "malaria_forecast_mcp"],
      "env": { "PYTHONPATH": "/absolute/path/to/malaria-forecast-mcp/src" }
    }
  }
}

Then ask: "Which three provinces should we prioritise six weeks out, and how confident are you?" — the agent reads the model card, ranks provinces, checks each against seasonal baselines, and reports intervals rather than point estimates.

---

Layout

src/malaria_forecast_mcp/
    server.py        MCP tools, resources, prompts
    forecasting.py   ensemble, intervals, guardrails
    data.py          surveillance store + synthetic generator
    model_card.py    machine-readable provenance
evals/backtest.py    rolling-origin evaluation gate
scripts/smoke_check.py
tests/

Roadmap

• RAG over published epidemiological literature, so briefings cite evidence
• Real-data adapter for DHIS2 surveillance exports
• Intervention-effect handling (bed-net campaigns, IRS rounds)

Licence

MIT