Documentation

Hospital temperature-risk reports

This tool was Groundswell's submission to the FortyGuard Hackathon 2026. It estimates how recent and forecast temperatures may increase deaths among people living near a selected hospital. This page explains the calculation, its sources, and where it should not be used.

Connect an agent

Groundswell exposes the hospital temperature-risk workflow through one protected Streamable HTTP MCP server. A connected agent can find a hospital, request a report, and retrieve the finished analysis. It cannot browse every saved report.

Quick install

Get a connection code from Groundswell. Treat it like a password and enter it only on the Groundswell authorization page.
Add the endpoint below as a Streamable HTTP MCP server named Groundswell.
When the browser opens the page titled "Connect to Groundswell," enter the connection code, review the access request, and select Authorize.
Enable Groundswell in a new conversation. Verify it with a hospital search before requesting a report.

MCP server URL

https://mcp-production-d65f.up.railway.app/mcp

Transport: Streamable HTTP
Authorization: Browser OAuth with S256 PKCE
Tools: 3 fixed tools

Client setup

ChatGPT

Open Settings, then Security and login. Turn on Developer mode.
Open ChatGPT Plugins, select the plus button, and create a connection named Groundswell with the MCP server URL.
Complete Groundswell's browser authorization and review the three tools.
Start a new conversation and enable Groundswell from the tools menu.

Developer mode depends on account and workspace policy. OpenAI documents the current flow in its ChatGPT connection guide.

Claude

On an individual plan, open Customize, then Connectors, and select Add custom connector. On Team or Enterprise, an owner adds a Custom Web connector in Organization settings.
Name it Groundswell and add the MCP server URL.
Complete Groundswell's browser authorization.
In a conversation, open Connectors and enable Groundswell.

See Anthropic's remote MCP connector guide for plan and workspace controls.

Other MCP clients

Use a client that supports remote Streamable HTTP servers, OAuth protected-resource discovery, dynamic public-client registration, and authorization code flow with S256 PKCE. Enter only the endpoint in the client. Do not add a client secret, connection code, access token, query parameter, or custom authorization header.

For protocol debugging, inspect the endpoint and list its tools with npx @modelcontextprotocol/inspector@latest. The browser authorization step still requires a valid Groundswell connection code.

Report workflow

Search first and confirm the hospital and inputs with the user. Then call start_analysis once. Keep the returned UUID and poll only after the server's requested delay.

Call search_hospitals. Present close matches and keep the chosen hospitalId.
Confirm the report title and catchment radius, then call start_analysis. Keep its analysisId and pollAfterMs.
After that delay, call get_analysis. Repeat while status is queued or running. Stop on succeeded or failed.

Tool reference

`search_hospitals`

Read-only

Searches the supported CMS hospital catalogue by name, city, or two-letter US state code.

query: , required string, 2 to 100 characters.
limit: , optional integer from 1 to 25, default 10.

Returns matching hospital IDs, names, types, emergency-service status, coordinates, city, state, timezone, active model confidence tier, and source receipts. Low-confidence matches are flagged in the text response.

`start_analysis`

Creates or reuses a report

Starts a persistent 14-day mortality outlook using the prior 21 days of temperature. Equivalent active or completed work is reused when possible.

title: , required string, 1 to 120 characters.
hospitalId: , required ID returned by search_hospitals.
radiusKm: , required number from 0.25 to 2.8 kilometres.

Returns analysisId, status, creation time, and pollAfterMs. It does not wait for the report.

`get_analysis`

Read-only · requires a report UUID

Reads one known analysis. Pass the required UUID in analysisId.

Returns queued or running progress, a terminal failure, or the complete report. A successful report includes temperature periods, map cells, mortality estimates, confidence and warning fields, and source provenance.

Authentication and access

The connection code approves an MCP client. It is not a FortyGuard or Open-Meteo API key and does not expose Groundswell's database credentials. After approval, the client receives a short-lived token that works only at this MCP endpoint. The MCP server uses a separate private token when it calls the analysis service.

The client discovers the authorization endpoints and registers without a client secret.
The browser asks for the Groundswell connection code. The app has no user account or login session.
A one-use authorization code expires after five minutes. S256 PKCE binds it to the client that started the connection.
The access token lasts one hour and is bound to the exact MCP endpoint and mcp scope. The client sends it only in the Authorization header.
There is no public report-list tool. A client can read a report only when it knows that report's unguessable UUID.

Verify a connection

Ask the client: "Search Groundswell for Massachusetts General Hospital." Confirm that it calls search_hospitals and returns a hospital ID. Stop there unless you intend to create a report.

Debug a connection

No tools appear: Confirm the URL ends in /mcp, the transport is Streamable HTTP, and Groundswell is enabled in the current conversation. Reconnect after changing the server configuration.
403 or "connection code is incorrect": The authorization page did not accept the code. Confirm the current code with Groundswell and restart the connection. Each new client authorization requires it.
401 or a repeated authorization prompt: The client has no valid access token. Remove or disconnect Groundswell, add it again, and complete browser authorization.
429 or analysis_limit_reached: Analysis capacity has been reached. Wait for the HTTP Retry-After value or retryAfterSeconds, then retry once.
Queued or running: This is normal progress, not a failure. Keep the same UUID and wait for pollAfterMs before calling get_analysis again.
Structured tool error: Read error.code, error.message, and error.retryable. Retry only when retryable is true, and preserve the original analysis UUID.

Methodology

A report estimates temperature-attributable all-cause mortality during the next 14 days for residents inside the selected radius. It is a population estimate, not a count of hospital patients or deaths at the facility.

Temperature inputs

Open-Meteo supplies hourly temperature at the hospital for the previous 21 days and the next 14 days. Groundswell converts these hourly values into daily means. The recent values are archived weather-model estimates, not weather-station readings.

FortyGuard supplies a 100 m map of mean, minimum, and maximum temperature for the previous 21 days. Groundswell uses the difference between each grid cell and the hospital grid cell to localize the Open-Meteo series. This approach carries the recent spatial pattern into the forecast. It does not create an independent weather forecast for each grid cell.

Residents in the catchment

The selected radius defines a circular catchment around the hospital. The app assigns WorldPop's 2026 population pixels to the exact FortyGuard grid polygons, then checks that population is neither lost nor assigned twice. Every temperature and mortality total is weighted by this estimated resident population. The result describes people who live nearby, not the hospital's service population.

How temperature affects mortality

Groundswell fitted state mortality models with CDC death records and ERA5-Land temperature data from 2014 through 2019. Each model estimates how mortality changes as daily mean temperature moves away from the temperature associated with the lowest mortality.

Temperature can affect mortality on the day of exposure or during the following 21 days. The model accounts for this delay. Each date in the 14-day forecast combines the recent and forecast temperatures that can affect mortality on that date. The report does not include effects expected after the forecast ends.

A 2019 state mortality rate supplies the expected daily deaths for the catchment. Groundswell applies the modeled temperature effect in each populated grid cell, then sums the cells and days. A positive estimate means more deaths than at the lowest-risk temperature. A negative estimate means fewer. These are modeled estimates, not counts of identifiable deaths.

The Time chart expresses each daily total per 100,000 catchment residents. The Temperature chart separates that total into heat and cold contributions according to whether each lagged exposure is above or below the model's minimum-mortality temperature. When heat and cold effects interact, the calculation divides the shared effect equally so the two contributions add exactly to the daily total.

Risk concentration divides the range of cell-level 14-day mortality rates into five equal-width bands, then sums the resident population in the cells within each band. The bands describe relative variation inside this catchment. They are not clinical thresholds and should not be compared as fixed categories between reports.

Age and cause estimates

The five age and seven cause rows use the same localized temperature series and their own age- and cause-specific models. Cause estimates use the whole catchment population. WorldPop does not supply local age structure for this report, so age rows apply each group's share of the 2019 state population to the catchment. "Who is most affected" ranks rows by temperature-attributable deaths per 100,000 people during the 14-day outlook. The percentage change compares each row with its own baseline mortality at its own minimum-mortality temperature, so it is not used to compare burden between rows. Intervals shown for some rows reflect ranges created by suppressed source death counts. The all-age headline is calculated separately and is not the sum of these rows.

Confidence and state support

High: The release checks found no material anomaly in the observed hot-tail curve structure. This does not mean the model has been externally validated.
Medium: The observed hot-tail curve has a limited structural concern. Reports retain the estimate and show a medium-confidence notice.
Low: Reports retain the estimate and show a low-confidence notice in the request form and report. Low-confidence age or cause rows also retain their rating.

This tier rates observed hot-tail shape. It does not include uncertainty in the minimum-mortality temperature, effect significance, external validation, or the certainty of a row's rank.

Reports cover the 48 contiguous states and District of Columbia when a state has a rated all-age model. Alaska, Hawaii, and US territories are outside the current hospital and model coverage. Groundswell checks availability when each report starts because model coverage can change between releases.

Limits

The Open-Meteo forecast can be wrong, and the app does not publish a forecast uncertainty interval.
Downscaling carries one recent FortyGuard spatial pattern across all 35 daily temperatures. Local conditions may change during the forecast.
WorldPop is a modeled population estimate, and the R2025A release is an alpha product. It does not measure who is present on a given day.
Mortality models and baseline rates are state-level. Applying them to a small area assumes the catchment resembles the state in ways the report cannot observe.
If a localized temperature is outside the model's supported range, the report flags the affected population share and names affected age or cause rows.
The report does not estimate emergency visits, admissions, patient demand, staffing need, or outcomes for an individual. Do not use it as a clinical tool or as the sole basis for emergency decisions.

Data sources

Every report carries the exact source versions, validity dates, retrieval times, and available checksums used for that result. These are the primary sources and the reason each is in the product.

US national temperature mortality estimate: Chu, Dubrow, and Chen analyzed NCHS death records for every county in the contiguous United States from 2000 through 2020. They estimated an annual average of 45,992 deaths attributable to low temperatures and 3,414 attributable to high temperatures. The combined estimate of 49,406 deaths per year provides context on the landing page. It is not an input to hospital reports.
FortyGuard Temperature API: The heatmap-tcm-100m result supplies mean, minimum, and maximum temperature in degrees Celsius for 100 m GeoJSON cells over the prior 21 complete days. The FortyGuard Hackathon 2026 focuses on FortyGuard's hyperlocal temperature data. The fine grid captures local differences that a single weather point cannot. The report records a one-way source receipt and requested dates. See the FortyGuard API limits.
Open-Meteo Forecast API: The forecast-api source supplies hourly 2 m air temperature in degrees Celsius at the hospital point for 21 complete recent days and 14 forecast days. One API and one local timezone keep the historical and forecast series aligned. Recent values requested with past_days are archived model values, not station observations. Open-Meteo publishes details of its archived forecasts and licence.
WorldPop Global2 population counts: The report uses the 2026 United States constrained population-count surface, release R2025A v1, at 3 arc-second resolution. Units are estimated people per pixel. Its resolution is close to the FortyGuard grid and lets the app weight temperature and mortality by where residents are estimated to live. The release is an alpha product. Read the release statement for construction and limitations.
Baselines: Groundswell uses pre-pandemic mortality data and a 2019 baseline. All-age and cause models use 2014 through 2019. Age models use 2015 through 2019. The public source inputs are:
CMS Hospital General Information: Provider Data Catalog identifier xubh-q36u supplies Medicare-registered hospital identity, address, facility type, and emergency-service status. It is chosen as the authoritative national facility catalogue. Each report retains the catalogue vintage used.
US Census Geocoder: The Census batch geocoder supplies hospital latitude and longitude from the CMS address. It provides one nationwide locator with a named benchmark vintage. The catalogue excludes unmatched addresses and tied results rather than guessing a coordinate.

Contact Groundswell

Groundswell Earth, Inc. builds and operates this project. Questions about the application, data, privacy, or terms may be sent to hello@groundswell.earth. Learn more at groundswell.earth.