---
name: hydrometric
description: Run UK FEH flood estimates (QMED, growth curve, design flows) through the Hydrometric remote MCP server. Use when asked for design flood flows, QMED, pooling/growth curves or an FEH report for an NRFA station or an ungauged UK catchment.
---

# Hydrometric MCP

Hydrometric exposes its default-route FEH2025 assessment as a remote MCP server
(Streamable HTTP). Every calculation runs on the frozen NRFA Peak Flow Dataset.

## Connect

You need a per-user API key (`hm_live_…`) from
https://www.hydrometric.io/account/api-keys (no account yet: https://www.hydrometric.io/waitlist).

Claude Code:

```bash
claude mcp add --transport http hydrometric https://www.hydrometric.io/api/mcp \
  --header "Authorization: Bearer hm_live_XXXX"
```

`.mcp.json` equivalent:

```json
{
  "mcpServers": {
    "hydrometric": {
      "type": "http",
      "url": "https://www.hydrometric.io/api/mcp",
      "headers": { "Authorization": "Bearer hm_live_XXXX" }
    }
  }
}
```

## Tools

| Tool | Cost | Returns |
| --- | --- | --- |
| `search_stations(query, limit?)` | free | NRFA stations matching id / river / location |
| `get_station(stationId)` | free | descriptors, record length, suitability |
| `run_gauged_assessment(stationId)` | 1 credit (free on cache hit) | QMED, pooling, growth curve, design flows, warnings, `runId` |
| `run_ungauged_assessment(descriptors, easting, northing, return_periods?)` | 1 credit | `/api/v1/estimate` contract |
| `get_qmed` / `get_growth_curve` / `get_design_flows` (`stationId` or `runId`) | free from cache | thin views over a run |
| `get_report(stationId | analysisId, format: 'markdown')` | free if cached | Markdown report + PDF/DOCX URLs |
| `list_saved_analyses()` / `get_saved_analysis(analysisId)` | free | the user's saved work, read-only |
| `get_catchment_map(stationId)` | free | map figures from saved analyses |
| `run_method_space(stationId | analysisId | descriptors+easting+northing, compare?, qmedRoute?)` | £20 run credit (free re-run of a paid analysis; admins/grantees exempt) | P10/P50/P90 + FSE per metric (QMED, Q30, Q100, Q1000), named variants, compare verdicts, Method Space PNG |
| `get_method_space_credits()` | free | credit balance, exemption, purchase URL |

Units: flows m³/s, areas km², rainfall mm, coordinates BNG metres.
Rate limit 60 requests/minute per key. Free tier: 5 assessments.

## Worked example — Thames at Kingston (39001)

1. `search_stations({ "query": "Kingston" })` → confirms `stationId: 39001`.
2. `run_gauged_assessment({ "stationId": 39001 })` → note the `runId`, `qmed.value_m3s`
   and `designFlows.flows[]` (return period → `flow_m3s`, `growthFactor`, `ci95`).
3. `get_design_flows({ "runId": "<runId>" })` for the flow table alone, or
   `get_growth_curve({ "stationId": 39001 })` to inspect the adopted distribution and pooling group.
4. `get_report({ "stationId": 39001, "format": "markdown" })` for the narrative report.

Quote the recommended QMED with its `method` and `rationale`, and always carry the
`warnings` array into any advice — it holds the FEH caveats (short records, urban
adjustment, permeable catchments) an engineer must see.

## Method Space (£20 per run)

`run_method_space` enumerates every method-valid analyst-choice variant (donors,
urban treatment, pooling composition, distribution, L-moment weighting) and places
the default route inside it. Killer use: keep your current tool, then check its
numbers against Hydrometric's default and the whole space:

```json
{ "stationId": 39001, "compare": { "q100_m3s": 820, "qmed_m3s": 330, "label": "WINFAP 5" } }
```

The response carries `metrics.<qmed|q30|q100|q1000>.{default,p10,p50,p90,fse}`, the
`named` variant table, `compare.results.<metric>.{percentile,distanceFromMedianT,insideP10P90,verdict}`
and the figure as PNG image content. P10–P90 is analyst-choice spread, NOT
sampling uncertainty — FSE is reported separately; never blend them.

`qmedRoute` (`"all" | "amax" | "descriptors"`) restricts the space to one QMED
route. Default: `"amax"` for a gauged analysis whose default route is at-site
AMAX (otherwise the descriptor-route cloud dominates and every at-site number
reads as an outlier), else `"all"`. The response reports `qmedRouteApplied` and
`variantCountFiltered` next to `variantCount`; pass `"all"` for the whole cloud.

Each distinct analysis costs one £20 credit; re-running one you already paid for is
free. With no credit the tool returns `{ "code": "method_space_credit_required", "purchaseUrl": … }` —
give the user the `purchaseUrl` (Stripe Checkout, or https://www.hydrometric.io/account/usage)
and retry after payment. `get_method_space_credits()` shows the balance.
Non-MCP harnesses: `POST https://www.hydrometric.io/api/v1/method-space` with the same
bearer key and body; the PNG comes back as `figure.png_base64`.

## Errors

Tool errors are JSON `{ "error": string, "code"?: string }` with `isError: true`.
`quota_exhausted` means the account's assessment credits are used up;
`method_space_credit_required` means a £20 Method Space credit is needed (see `purchaseUrl`);
`unauthenticated` means the bearer key was missing or revoked. HTTP 401 before any
tool call means the key itself was rejected; 429 carries `Retry-After`.