MCP servers

This directory holds the family of Model Context Protocol servers that the EpiHack Arizona 2026 stack uses to stream live (and, where upstream APIs are absent, mock) agency data into an LLM client like Claude Desktop or Claude Code, or into the agent pipeline under agents/.

Eleven servers ship today. Every server follows the same shape:

Index

Server Description Tools Auth posture Tests
vectorsurv-mcp/ VectorSurv national mosquito + tick surveillance API; pools, collections, agency-region intersects, vector-index math, case counts 13 Username + password → bearer (VECTORSURV_USERNAME, VECTORSURV_PASSWORD) with auto-refresh 6
knowledge-graph-mcp/ Read-only DuckDB query MCP over the EpiHack DuckLake kg (572 nodes / 791 edges / 1027 properties); regions-at-point, pathogen-by-vector, outbreak check, SELECT-only SQL escape hatch 12 None — local DuckLake catalog via env path (KG_DUCKDB_PATH); SELECT-only SQL parser blocks all writes 22
great-az-tick-check-mcp/ UA Cooperative Extension Great AZ Tick Check mail-in submission tracking + species feedback (mock backend by default) 5 Optional GATTC_API_TOKEN for a future real backend; defaults to mock-mode (no auth) 10
nws-heatrisk-mcp/ NWS public API + WPC HeatRisk gridded product; current conditions, forecast, active alerts, heat-index calculation 7 None — public API; requires a polite NWS_USER_AGENT per NOAA guidance 17
mag-hrn-mcp/ MAG Heat Relief Network cooling / hydration / respite / donation centers across Phoenix metro (May 1 – Sep 30); supply status tool is mock-only until MAG ships an occupancy feed 5 None — public ArcGIS Feature Service (MAG_HRN_FEATURE_SERVICE_URL); defaults to canned dataset of 12 Phoenix sites 35
adhs-mcp/ ADHS public surveillance summaries: heat mortality, arbovirus weekly summaries, reportable conditions (no public REST API today — canned data drawn from ADHS PDFs + ArcGIS dashboards) 6 Optional ADHS_API_TOKEN for a future real backend; mock-by-default 46
211-az-mcp/ 211 Arizona referrals + cooling-center referrals + transport dispatch with in-memory chain-of-call tracking 6 Optional AZ211_API_KEY + AZ211_BACKEND_URL for a future real backend; mock-by-default 23
whispers-mcp/ USGS WHISPers wildlife mortality events; public read-only listing tools with canned-fallback on network errors 6 None for the public listing tools (WHISPERS_BASE_URL); env-overridable + silent canned fallback 15
inaturalist-mcp/ iNaturalist citizen-science observations (AZ place_id=53); ticks, mosquitoes, fleas, rodent reservoirs 6 None — public iNaturalist API; requires INAT_USER_AGENT per iNat guidance 8
sms-entry-mcp/ SMS-only intake adapter; pure-function Twilio HMAC-SHA1 signature check, normalisation, intent parsing 6 Optional SMS_TWILIO_AUTH_TOKEN for the gateway service; SMS_MODE=mock by default 19
wearable-mcp/ HealthKit / Health Connect wearable readings (skin temp, HRV, sweat rate, heart rate); on-device-only privacy posture, mock-by-default 4 None — readings stay on-device; mock profiles (rest, heat) ship inline 23

Tool and test counts are sourced from each server’s README and its tests/ directory; bumps land in the same PR that ships the change.

How to add a new MCP server

Use vectorsurv-mcp/ as the template — it is the most complete reference in the family and follows every convention reviewers expect.

1. Scaffold

cd mcp
cp -R vectorsurv-mcp my-new-server-mcp
cd my-new-server-mcp
# rename src/vectorsurv_mcp → src/my_new_server_mcp; update pyproject.toml

Target layout:

mcp/my-new-server/
├── README.md                  # what / why / tool table / auth / env vars
├── pyproject.toml             # FastMCP + httpx + pydantic v2; uv workspace
├── src/my_new_server_mcp/
│   ├── __init__.py
│   ├── __main__.py            # `python -m my_new_server_mcp` entry
│   ├── server.py              # FastMCP() instance + @mcp.tool definitions
│   └── client.py              # httpx wrapper; env-overridable base URL
├── examples/
│   └── claude_desktop_config.json
└── tests/
    └── test_*.py              # uv run pytest

2. Conventions reviewers will check

3. Register the new server

Three places need an entry:

  1. This file — add a row to the index table above with the tool count, auth posture, and test count.
  2. schema/deep/mcp_servers.sql — add a mcp_server node plus per-tool nodes, using the next free edge-id range.
  3. plan/02-mcp-integration.md — if the new server unlocks a new agent → MCP tool route.
  4. agents/src/onehealth_agents/mcp_client.py — if any of the eight agents will call a tool on the new server, add the route + wire up the prefix.

4. Test plan in the PR

The PR description must include, at minimum:

See CONTRIBUTING.md for the full PR workflow and the privacy + data-sovereignty checklist.