Tutorial: USGS Streamflow

Environment

Data source: USGS Water Services

Overview

USGS Streamflow wraps USGS Water Services, handling authentication, pagination, and rate limits for you. This tutorial covers all 3 tools with working code examples you can copy and run.

Prerequisites

Sign up at https://context.gnist.ai/signup for a free API key (100 calls/day).
Choose your integration method: MCP protocol or REST API.

Connect via MCP

Add to your MCP client config (Claude Desktop, Cursor, etc.):

MCP Config

{
  "mcpServers": {
    "gnist-streamflow": {
      "url": "https://context.gnist.ai/mcp/streamflow/",
      "headers": {
        "Gnist-API-Key": "YOUR_API_KEY"
      }
    }
  }
}

Tools (3)

`search_stream_sites`

Search for USGS water monitoring sites. Returns active stream gauge stations with location data. Args: state_code: US state code (e.g. "CO" for Colorado, "CA" for California). Optional. limit: Maximum results (1-100, default 20).

Parameter	Type	Required	Description
`state_code`	any	optional
`limit`	integer	optional	(default: `20`)

curl -X POST "https://context.gnist.ai/mcp/streamflow/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "search_stream_sites", "arguments": {"state_code": "example"}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/streamflow/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'state_code': 'example'},
            'name': 'search_stream_sites'}},
)
print(resp.json())

`get_stream_conditions`

Get current river/stream conditions at a USGS monitoring site. Returns real-time discharge (flow rate) and gage height readings. Args: site_code: USGS site code (e.g. "09380000" for Colorado River at Lees Ferry).

Parameter	Type	Required	Description
`site_code`	string	required

curl -X POST "https://context.gnist.ai/mcp/streamflow/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "get_stream_conditions", "arguments": {"site_code": "example"}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/streamflow/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'site_code': 'example'},
            'name': 'get_stream_conditions'}},
)
print(resp.json())

`report_feedback`

Report a bug, feature request, or general feedback for this data source. Use this when something doesn't work as expected, when you'd like a new feature, or when you have suggestions for improvement. Args: feedback: Describe the issue or suggestion. feedback_type: One of 'bug', 'feature_request', or 'general'.

Parameter	Type	Required	Description
`feedback`	string	required
`feedback_type`	string	optional	(default: `general`)

curl -X POST "https://context.gnist.ai/mcp/streamflow/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "report_feedback", "arguments": {"feedback": "example"}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/streamflow/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'feedback': 'example'}, 'name': 'report_feedback'}},
)
print(resp.json())

Common Patterns

Search then retrieve
Use search_stream_sites to find items, then get_stream_conditions to get full details. This two-step pattern is common for exploring data before drilling down.

Pagination
Several tools support limit, offset, or page parameters. Start with small limits during development, then increase for production queries.

FAQ

What data does USGS Streamflow provide?

US river and stream conditions — real-time discharge, gage height from USGS gauges. It exposes 3 tools: search_stream_sites, get_stream_conditions, report_feedback.

What do I need to get started?

A Gnist API key (free tier: 100 calls/day). Sign up at https://context.gnist.ai/signup.

What format does the USGS Streamflow API return?

JSON, via either MCP protocol (JSON-RPC 2.0) or REST API.