vectorsurv-mcp¶
Source
Server lives at mcp/vectorsurv-mcp/.
The content below is included verbatim from its README.md.
title: VectorSurv MCP server¶
vectorsurv-mcp — Model Context Protocol server for VectorSurv¶
A Model Context Protocol server that exposes the VectorSurv vector-borne disease surveillance API as a set of tools an LLM (Claude Desktop, Claude Code, Claude API agents, or any other MCP client) can call.
Built for the EpiHack Arizona 2026 Wildlife & Vector-Borne Diseases focus group.
Spec-aligned (v1.0.44). All paths, query parameters, and authentication flow are verified against the OpenAPI spec at https://api.vectorsurv.org/openapi. A snapshot lives in
openapi/; diff it against future fetches to detect drift.
What it does¶
| MCP tool | Backed by |
|---|---|
vectorsurv_version |
GET /version |
vectorsurv_list_agencies |
GET /v1/agency |
vectorsurv_agency_region_intersect |
GET /v1/agency-region-intersect |
vectorsurv_list_regions |
GET /v1/region |
vectorsurv_list_test_targets |
GET /v1/test/target |
vectorsurv_list_sites |
GET /v1/site |
vectorsurv_get_collections |
GET /v1/arthropod/collection (or /v1/tick/collection) |
vectorsurv_get_pools |
GET /v1/arthropod/pool (with type=mosquito|tick|nontick) |
vectorsurv_pools_are_positive |
GET /v1/arthropod/pool/are-positive |
vectorsurv_get_case_counts |
GET /v1/case-count |
vectorsurv_calculate_abundance |
client-side: Σ num_count / Σ trap_nights |
vectorsurv_calculate_infection_rate |
client-side MIR or bc-MLE |
vectorsurv_calculate_vector_index |
client-side: abundance × IR |
Plus two MCP resources: vectorsurv://disease-acronyms and
vectorsurv://query-syntax (a Mongoose-style cheat-sheet).
Why this matters for EpiHack¶
VectorSurv is the leading platform for mosquito and tick surveillance in the U.S. (Maricopa County Vector Control reports to it; California, Texas, and many other state and local programs use it as their backbone). Exposing it as an MCP server lets an LLM:
- Answer ad-hoc surveillance questions in conversational form ("What was the WNV vector index in agency 7 during biweek 18 of 2025?").
- Find Arizona agencies in one call (
agency_region_intersect), filter to their pools and collections, and compute the same metrics that VectorSurv Gateway shows in its UI. - Feed real surveillance data into the DuckLake knowledge graph without writing R or Python glue.
Authentication¶
VectorSurv uses HTTP Bearer (JWT). The server obtains a token from
POST /login with a JSON body and refreshes it before the one-hour
expiry. Credentials come from environment:
```bash export VECTORSURV_USERNAME=your_gateway_username export VECTORSURV_PASSWORD=your_gateway_password
Optional: point at sandbox or dev¶
export VECTORSURV_BASE_URL=https://api.vectorsurv.org
Other endpoints documented in the spec:¶
https://sandbox.api.vectorsurv.org/¶
https://dev.api.vectorsurv.org/¶
```
A .env.example template is included; copy to .env and source it.
Query syntax notes¶
The API uses Mongoose-style operators in the query string. The client handles this transparently; if you're inspecting requests:
GET /v1/arthropod/pool
?type=mosquito
&query[collection_date][$gte]=2024-05-01
&query[collection_date][$lte]=2024-09-30
&query[agency]=55
&populate[0]=test
&populate[1]=species
&page=1
&pageSize=1000
Don't pass flat start_date=... or agency_ids=... — the API doesn't
read them.
Install & run¶
As a Claude Desktop MCP server¶
- Install
uvif you don't have it. - Drop the snippet in
examples/claude_desktop_config.jsoninto your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.jsonon macOS,%APPDATA%\Claude\claude_desktop_config.jsonon Windows). - Replace the path with the absolute path to this directory.
- Fill in
VECTORSURV_USERNAMEandVECTORSURV_PASSWORD. - Restart Claude Desktop.
As a Claude.ai custom connector (remote MCP, hosted on this VM)¶
Claude.ai (web + desktop) can talk to this server directly as a custom
connector once it's reachable over the public internet via HTTPS. The
EpiHack VM (epihack-test.cis240692.projects.jetstream-cloud.org) hosts the
reporting app behind nginx; the steps below put the MCP endpoint behind the
same hostname at /mcp/vectorsurv.
TLS is not provisioned yet. As of writing the VM's nginx serves plain
http://on port 80 only (no certbot cert). Provision HTTPS first —sudo certbot --nginx -d epihack-test.cis240692.projects.jetstream-cloud.org— or front the endpoint with a tunnel (below). Without it, Claude.ai will refuse the connector.One namespace, many servers. The VM runs several MCP servers, so each one gets its own sub-path under
/mcp/(/mcp/vectorsurv,/mcp/nws, …) on its own local port. The trick is to give each server its full public path asFASTMCP_STREAMABLE_HTTP_PATHso nginx can proxy the path straight through without rewriting.HTTPS is required. Claude.ai will not connect to a plain
http://URL. The VM must terminate TLS (the existing nginx + certbot, or a tunnel — both shown below).
1 — Run the server in HTTP transport, bound to localhost. Set its public sub-path and a dedicated port:
```bash cd /home/exouser/epihack-2026/mcp/vectorsurv-mcp uv sync MCP_TRANSPORT=streamable-http \ FASTMCP_HOST=127.0.0.1 FASTMCP_PORT=8010 \ FASTMCP_STREAMABLE_HTTP_PATH=/mcp/vectorsurv \ VECTORSURV_USERNAME=your_gateway_username \ VECTORSURV_PASSWORD=your_gateway_password \ uv run vectorsurv-mcp
→ MCP endpoint now live at http://127.0.0.1:8010/mcp/vectorsurv¶
```
To keep it running across logouts, drop it in a systemd unit (e.g.
/etc/systemd/system/vectorsurv-mcp.service) with the env vars in
Environment= lines, then systemctl enable --now vectorsurv-mcp.
2 — Expose it over HTTPS. The VM runs nginx (see
ansible/roles/nginx) in front of the
reporting app; once TLS is provisioned (see the note above), it terminates
HTTPS for this endpoint too. Add one location per MCP server, each
proxying its sub-path to that server's local port. Because the server owns
the full /mcp/vectorsurv path, nginx passes the URI through unchanged (no
trailing-slash rewriting). Streamable HTTP keeps a long-lived response open,
so disable buffering and raise the read timeout:
```nginx
inside the existing server { … } block for the FQDN¶
location /mcp/vectorsurv { proxy_pass http://127.0.0.1:8010; proxy_http_version 1.1; proxy_set_header Host $host; proxy_set_header X-Forwarded-Proto $scheme; proxy_set_header Connection ""; proxy_buffering off; # flush the stream immediately proxy_read_timeout 3600s; # keep the SSE channel open chunked_transfer_encoding on; }
add a sibling block per server, e.g.:¶
location /mcp/nws¶
```
sudo nginx -t && sudo systemctl reload nginx. The public connector URL is:
https://epihack-test.cis240692.projects.jetstream-cloud.org/mcp/vectorsurv
The live nginx config is ansible-generated (
onehealth.conf.j2says do not edit by hand) — a redeploy overwrites manual edits. To make the route permanent, add an entry to themcp_http_serverslist inansible/group_vars/all.yml; thenginxrole renders onelocationper entry on the nextansible-playbookrun:
yaml mcp_http_servers: - { name: vectorsurv, path: /mcp/vectorsurv, port: 8010 } # - { name: nws, path: /mcp/nws, port: 8011 }
No nginx access? A quick alternative is a tunnel that brings its own TLS:
```bash cloudflared tunnel --url http://127.0.0.1:8010 # prints an https://… URL; append /mcp/vectorsurv
or: ngrok http 8010 # then use https://.ngrok.app/mcp/vectorsurv¶
```
3 — Add it in Claude.ai. Settings → Connectors → Add custom
connector. Give it a name (e.g. VectorSurv (EpiHack AZ)) and paste the
HTTPS /mcp/vectorsurv URL from step 2. Save, then enable the connector from the
tools/attachments menu in a conversation. The vectorsurv_* tools and the
vectorsurv://… resources become available to Claude.
Security — read before exposing. This server holds your VectorSurv Gateway credentials and the
/mcp/vectorsurvendpoint above is unauthenticated: anyone who learns the URL can query VectorSurv through your login. For a short-lived hackathon demo that's usually acceptable; for anything longer, restrict access (IP allow-list / VPN), put an auth layer in front (Claude.ai custom connectors support OAuth 2.0), or tear the tunnel down when you're done. Never commit real credentials — keep them in thesystemdunit or a sourced.envonly.
Standalone¶
bash
cd mcp/vectorsurv-mcp
uv sync
uv run vectorsurv-mcp # stdio (default)
MCP_TRANSPORT=streamable-http uv run vectorsurv-mcp # HTTP
Tests¶
bash
cd mcp/vectorsurv-mcp
uv run pytest
Unit tests exercise the abundance / MIR / bc-MLE / vector-index math against synthetic data; they don't require live credentials.
Endpoint overrides¶
Every path is overridable via env, so the deployed server can be
corrected without a code change if VectorSurv's spec drifts:
VECTORSURV_PATH_LOGIN, _VERSION, _AGENCIES, _AGENCY_REGION,
_SITES, _REGIONS, _REGION_TYPES, _ARTHRO_COLLECTION,
_TICK_COLLECTION, _POOLS, _TICK_POOLS, _POOL_ARE_POSITIVE,
_ABUNDANCE_FLAT, _CASE_COUNT, _TEST_TARGET, _TEST_METHOD,
_TICK_CALC_ABUND.
Calculations¶
- Abundance —
Σ num_count / Σ trap_nightsper interval. - MIR (Minimum Infection Rate) —
scale × positives / mosquitoes_tested. - bc-MLE — Hepworth bias-corrected MLE assuming roughly equal
pool sizes. For heterogeneous pool sizes, prefer the
pooltestrR package orPooledInfRate. VectorSurv also has a server-side tick abundance calculation atPOST /v1/tick/calculation/abundance(async job, poll for results) which the client can drive if you need their authoritative numbers. - Vector Index —
abundance × infection_rate / scale, per the Maricopa County and VectorSurv definition.
License¶
MIT, alongside the rest of epihack-2026.