Gauge

Gauge — connector documentation

• MCP endpoint: https://gauge.connectorbay.com/mcp
• REST API: POST https://gauge.connectorbay.com/v1/tools/{tool_name}, described by the OpenAPI 3.1 spec at https://gauge.connectorbay.com/openapi.json
• Transport: Streamable HTTP, stateless, MCP specification 2025-06-18 or later
• Authentication: none required. An optional Authorization: Bearer <key> raises rate limits.
• Health: https://gauge.connectorbay.com/health · Tool schemas: https://gauge.connectorbay.com/tools.json
• Publisher: Unify Dynamics LLC · connectorbay.com/gauge · agent@connectorbay.com

What Gauge is for

"What's the river flow like right now", "is this creek running high for this time of year", "find a stream gauge near me" — answered from the same live network of sensors the U.S. Geological Survey has run on American rivers, streams and lakes for over a century, without opening USGS's own web dashboard.

What it does

The latest reading from one monitoring site — streamflow in cubic feet per second, gage height in feet, and whatever else that station happens to measure (water temperature, dissolved oxygen, pH, turbidity), each with its own timestamp (current_conditions); the same for several sites in one call, since USGS's API accepts a comma-separated site list natively (multi_site_snapshot); finding monitoring stations by state or county FIPS code and site type — stream, lake, spring, well (find_sites); the same within an approximate radius of a coordinate (sites_near); a window of recent daily-mean values for a chosen parameter, going back up to a year (historical_daily_values); how today's flow compares to that calendar day's historical 10th/25th/50th/75th/90th percentiles from USGS's full period of record — "is this river running high for late September" (flow_stats_context); a station's metadata — name, coordinates, drainage area, altitude, county/state (site_info); a plain-language glossary of the numeric parameter codes USGS uses (parameter_glossary); and unit conversion between cfs/cms (flow) and ft/m (height), since USGS always reports in U.S. customary units (unit_convert).

What it is not

Gauge is not a flood-warning system. It reads the same public sensor network NOAA/NWS uses, but it does not compute flood stages, does not issue warnings, and a quiet reading here is not proof a river is safe — sensors go offline, readings can lag by minutes to hours, and "gage height" is measured from a local, arbitrary datum that is not comparable across sites without knowing that site's specific flood-stage thresholds. For an official flood warning or forecast, check NOAA/NWS at water.noaa.gov. This connector's siblings — hazard (earthquakes, tsunami, cyclones, volcanoes) and skyward (weather) — cover other hazard feeds; none of the three is a substitute for local emergency guidance.

One more honest note: as of when this connector was built, USGS's statistics service (flow_stats_context) reliably returns the 10th/25th/50th/75th percentiles but its 90th-percentile column comes back empty for every site checked — a live quirk of that upstream service, not a bug here. The tool says so plainly rather than inventing a number.

Tools

Current conditions

current_conditions — The latest reading from one USGS monitoring site for every parameter it currently reports — typically streamflow (cfs) and gage height (ft), sometimes also water temperature, dissolved oxygen, pH and more — each with its own observation timestamp. Use for "what's the current flow on the Potomac", "how high is the river at site 01646500 right now". Args: site_id.

multi_site_snapshot — Current streamflow, gage height and water temperature for several USGS sites at once, in a single upstream call (USGS's API accepts a comma-separated site list natively). Use for "compare flow at these three gauges", "check all my usual river sites". Args: site_ids.

Site search

find_sites — Find USGS monitoring sites by state or county. Give a site's number to current_conditions or site_info. Use for "find stream gauges in Colorado", "what USGS sites are in Fairfax County, VA". Args: state, county, site_type, max_results.

sites_near — USGS monitoring sites within an approximate radius of a coordinate, nearest first. The search box is computed from simple planar math (not exact geodesics), which is fine at this scale but means the 'radius' is approximate, especially at high latitudes. Use for "any stream gauges near me", "USGS sites near 38.9, -77.1". Args: latitude, longitude, radius_miles, site_type, max_results.

History & context

historical_daily_values — Recent daily-mean values for one USGS site and parameter (default: streamflow) — one value per calendar day going back up to a year, from USGS's daily-values service. Use for "show the last 30 days of flow on the Potomac", "daily gage height for the past two weeks". Args: site_id, days, parameter_cd.

flow_stats_context — How today's reading at a site compares to that calendar day's historical percentiles (10th, 25th, 50th/median, 75th, 90th) computed by USGS from its full period of record — "is this river running high or low for late September". Not every site/parameter combination has published statistics; this tool says so plainly rather than guessing. Use for "is the Potomac running high for this time of year". Args: site_id, parameter_cd.

Reference

site_info — A USGS monitoring station's metadata: name, coordinates, altitude, drainage area, county/state, site type and time zone. No current readings — use current_conditions for those. Use for "what river is site 01646500 on", "how big is the watershed above this gauge". Args: site_id.

parameter_glossary — Glossary of USGS parameter codes — what each five/six-digit code measures and in what unit (00060 streamflow, 00065 gage height, 00010 water temperature, and others actually seen on tested sites). Use for "what does parameter code 00065 mean", "what units is streamflow in". Args: code.

unit_convert — Convert between flow units (cfs/cms/gpm) or length units (ft/m, mi/km) — useful because USGS always reports in US customary units (cfs, ft). Use for "convert 500 cfs to cubic meters per second", "how many feet is 2 meters of gage height". Args: value, from_unit, to_unit.

Conventions

• Read-only. Every tool reads public data or computes; nothing is written anywhere and nothing about the user is stored.
• Result envelope. ok: true with data, or ok: false with a structured error (bad_input, not_found, upstream_error). degraded lists optional sources that were unreachable.
• Rate limits. Free tier 60 tool calls/minute and 300/day per user (keyed on the user identifier supplied by the host agent, else client IP); Pro keys raise this. Over-limit calls return HTTP 429 with Retry-After. initialize and tools/list are never counted.

Support

agent@connectorbay.com · connectorbay.com/gauge/support

Gauge — Privacy Policy

Effective 24 September 2026. Unify Dynamics LLC ("we", "us"), Menlo Park, California.

What Gauge is. Gauge is a connector (an MCP server and REST API) that AI assistants and personal agents call on your behalf to read U.S. Geological Survey river, stream and lake gauge data: current conditions, site search, historical daily values, statistical context, station metadata, a parameter glossary and unit conversion. You interact with your assistant; the assistant sends us only the arguments needed for that one lookup.

What we receive. The arguments of each tool call — a USGS site number, a state or county code, a latitude/longitude and radius, a parameter code, or a value to convert — the technical headers needed to serve the request (an IP address or a client identifier supplied by the assistant, and a Pro API key if you have one), and standard server logs.

What we send onward. Each request is forwarded, as needed, to USGS Water Services (waterservices.usgs.gov) — a public, keyless, no-account U.S. federal API — carrying only the site number, geographic filter or parameter code needed to answer it. No other third party is involved. We do not send USGS your identity, your conversation, or anything about you beyond what a location-based public-data lookup requires.

What we do not receive or store. We do not receive your conversation with the assistant or your name, and we do not build a profile from your queries: each request is answered independently and nothing carries over between requests. Live and historical readings are cached briefly (a few minutes to a few hours depending on how fast the underlying data changes) purely to reduce repeat calls to USGS; this cache holds public gauge data, never anything about you. Rate-limit counters (a client identifier and timestamps) are held in memory for at most 24 hours. Hosting-provider access logs, which contain IP addresses and request paths but not request bodies, are retained for up to 30 days for security and abuse prevention.

Sub-processors. USGS Water Services (U.S. Geological Survey, public domain data, no account or key required). Hosting: Vercel (United States regions).

Legal bases and your rights. Our processing is necessary to provide the service you request through your assistant. Because we store no personal data beyond short-lived logs, requests to access, correct or delete personal data are usually satisfied automatically; you can still contact agent@connectorbay.com and we will respond within 30 days. We do not sell or share personal information and do not use your data to train models.

Children. Gauge is a general-audience service operated by the adult using the assistant.

Changes. We will post changes here with a new effective date.

Gauge — Terms of Service

Effective 24 September 2026. These terms govern use of the Gauge connector ("the Service") operated by Unify Dynamics LLC ("we", "us").

1. The Service. Gauge returns river, stream and lake gauge data — current streamflow and gage height, site search, recent daily history, statistical percentile context, station metadata, a parameter glossary and unit conversion — read live from USGS Water Services, a public U.S. federal API. It is accessed through an AI assistant or directly over MCP or HTTP.
2. Not a flood-warning system, and not official. Gauge is an independent informational tool, not affiliated with or endorsed by the U.S. Geological Survey, NOAA, or the National Weather Service. It does not issue flood warnings or forecasts, and nothing in the Service should be relied on for a decision where the safety of a person or property depends on getting it right. For official flood warnings, watches and forecasts, use NOAA/NWS (water.noaa.gov) and local emergency-management guidance.
3. Data currency and gaps. Streamflow and gage-height readings are provisional and subject to revision by USGS; individual sensors can go offline, lag, or report erroneous values without notice. "Gage height" is referenced to a local, site-specific datum and is not comparable across sites without independently knowing that site's flood-stage thresholds. Absence of an alarming reading here is not proof of safety.
4. Acceptable use. Automated use within the published rate limits is welcome.
5. Availability. The Service is provided "as is" without warranty. We may change, limit or discontinue it at any time, including if USGS changes or discontinues the underlying data service.
6. Data. Our Privacy Policy describes what we process. In short: your query's arguments are forwarded to USGS Water Services as needed to answer it, and nothing about you is stored.
7. Pro keys. Optional Pro API keys are issued at our discretion, are personal to the holder and may be revoked for abuse.
8. Liability. To the fullest extent permitted by law, Unify Dynamics LLC is not liable for any loss, including any loss arising from flooding or other water-related hazards, arising from use of or reliance on the Service. Our total liability is limited to US $100.
9. Governing law. California law; venue in San Mateo County, California.
10. Contact. Unify Dynamics LLC · agent@connectorbay.com · https://connectorbay.com/gauge

Gauge support

Email agent@connectorbay.com. We answer within two business days.

• MCP endpoint: https://gauge.connectorbay.com/mcp
• REST API: https://gauge.connectorbay.com/openapi.json
• Live status: https://gauge.connectorbay.com/health

When you report a problem, include the question you asked your agent, roughly when, and which agent you used (for example Claude, ChatGPT or Gemini). Never send us passwords, account numbers or ID numbers. Gauge never asks for them.