Repository avatar
Developer Tools
v0.1.0
active

hydronode

tech.hydronode/hydronode

Ask about your IoT sensors, devices, anomalies and automations, switch outputs and log values.

Documentation

HydroNode

hydronode-mcp

Hosted Model Context Protocol (MCP) server for HydroNode IoT sensors, time series and controls.

CI MIT license Go 1.24+ MCP Streamable HTTP

Ask Claude, ChatGPT, Cursor, VS Code or Codex about your HydroNode sensors in plain language, and let them switch outputs, send commands, tick off messages or draft automations with the rights you grant.

Connect in 30 seconds

Hosted endpoint: https://hydronode.tech/mcp

ClientSetup
CursorAdd to Cursor or add {"mcpServers":{"hydronode":{"url":"https://hydronode.tech/mcp"}}} to .cursor/mcp.json
VS CodeInstall in VS Code or add {"servers":{"hydronode":{"type":"http","url":"https://hydronode.tech/mcp"}}} to .vscode/mcp.json
Claude.ai / Claude DesktopSettings → Connectors → Add custom connector → https://hydronode.tech/mcp
Claude Codeclaude mcp add --transport http hydronode https://hydronode.tech/mcp
ChatGPTSettings → Connectors → Add MCP connector → https://hydronode.tech/mcp
CodexAdd [mcp_servers.hydronode] with url = "https://hydronode.tech/mcp" to ~/.codex/config.toml
Claude plugin (connector + skills)claude plugin marketplace add TexhFexLabs/hydronode-skills, then claude plugin install hydronode@hydronode
Clients without remote MCPrun the bridge npx -y mcp-remote https://hydronode.tech/mcp as a local stdio server (needs Node.js)

On first use your browser opens HydroNode's OAuth 2.1 consent page so you can choose which projects the assistant may see and whether it gets read-only access (hydronode:read) or edit access (hydronode:write, hydronode:automations). Manage or revoke connected apps anytime under https://hydronode.tech/account/security#connected-apps.

Architecture

Claude / ChatGPT ──HTTPS──► <host>/mcp ──Traefik──► hnmcp (this repo: stateless, no DB, no secrets)
                                                      │ Agent API with the user's own token
                                                      ▼
                                                   hnbackend (http://hnbackend:8080, internal only)
  • Hosted only. Remote MCP over Streamable HTTP at https://<host>/mcp, stateless, JSON answers. No local mode.
  • OAuth 2.1 only. Clients discover the HydroNode authorization server via RFC 9728 metadata, register themselves (DCR or Client ID Metadata Document) and the user picks scopes and projects on HydroNode's consent page.
  • Condensed answers. History comes as ≤ 48 buckets with min/avg/max, lists as ≤ 20 items. Never raw dumps.
  • Isolated. hnmcp has no database access and no server secrets. It forwards the caller's agent token (hoa_…) to the backend's Agent API over the internal network. Agent tokens work nowhere else: Traefik blocks them on every public route except /mcp, and the backend only accepts them without proxy headers.

Contracts: hydronode-backend/docs/api/OAUTH.md, hydronode-backend/docs/api/AGENT_API.md.

Tools (19)

ToolKindWhat it does
overviewreadProjects, device counts by status, open anomalies, unread messages, what needs attention
findreadSensors, data points, stations, projects by name, id or DevEUI
get_sensorreadOne sensor with status, battery, signal, firmware and every data point
summarize_historyreadMin/max with time, average, trend, gaps, ≤ 48 buckets
find_periodsreadWhen a value was below/above a threshold
comparereadUp to 4 data points, or one point against an earlier span (shift)
list_anomalies / get_anomalyreadDetected anomalies and their explanation
list_messagesreadInbox
device_healthreadOnly devices with problems
consolereadLatest device requests with rejection reasons
public_stationsreadPublic stations by name or location
list_automationsreadAutomations, one with recent runs
set_valuewriteSwitch or set a writable data point (destructive hint)
send_commandwriteQueue a typed device command (destructive hint)
log_valuewriteRecord a manual measurement
mark_messageswriteRead, unread, archive, restore, read all
toggle_automationwriteAutomation on/off
create_automationautomationsDry run by default; no webhooks ever

Write tools are always listed. Without the scope they answer with a clear text and a link to Connected apps, and the HTTP answer is 403 with WWW-Authenticate: Bearer error="insufficient_scope", scope="…" so clients that support step-up reopen the consent (switch HNMCP_STEPUP_HTTP).

Prompts: daily_report, why_offline, do_i_need_to_water, compare_weeks.

Endpoints

Path
POST /mcpMCP (Streamable HTTP, stateless). Needs Authorization: Bearer hoa_…
GET /.well-known/oauth-protected-resource/mcpRFC 9728 metadata
GET /q/health/live, /q/health/readyhealth (ready also checks the backend)

Configuration

EnvDefault
HNMCP_LISTEN:8080listen address
HNMCP_BACKEND_URLrequiredinternal backend, e.g. http://hnbackend:8080
HNMCP_PUBLIC_URLrequiredpublic origin, e.g. https://hydronode.tech (resource = +/mcp)
HNMCP_AUTH_SERVERHNMCP_PUBLIC_URLOAuth issuer
HNMCP_ALLOWED_ORIGINShttps://claude.ai,https://claude.com,https://chatgpt.combrowser origins allowed on /mcp (requests without Origin always pass)
HNMCP_RATE_PER_MIN120requests per token per minute (the backend has its own limits)
HNMCP_STEPUP_HTTPtrueanswer missing scopes with HTTP 403 step-up
HNMCP_LOG_LEVELINFO

Security

  • Accepts only hoa_ agent tokens; PATs, refresh tokens and JWTs are refused without a backend call.
  • Token check via GET /api/agent/v1/me, cached 30 s by SHA-256 hash (rejected tokens 10 s, one lookup for concurrent requests); revocation applies within 30 s here and immediately in the backend.
  • Only Agent API paths can be called, ids are validated, redirects are never followed.
  • Origin allowlist, 64 KiB body limit, 20 s per request, per-token rate limit, at most 300 rejected tokens per minute and address (above that only already verified tokens pass).
  • Logs carry tool name, status, duration and a 12-character token hash. Never tokens, arguments or answers.
  • distroless nonroot image, read-only filesystem, no capabilities.

Develop

go test -race ./...
go run honnef.co/go/tools/cmd/staticcheck@v0.8.2 ./...
go run golang.org/x/vuln/cmd/govulncheck@v1.9.0 ./...

# against a local backend (mvn quarkus:dev on :8080, OAuth + Agent API on in %dev)
HNMCP_LISTEN=:8091 HNMCP_BACKEND_URL=http://localhost:8080 \
HNMCP_PUBLIC_URL=http://localhost:8091 HNMCP_AUTH_SERVER=http://localhost:8080 \
HNMCP_ALLOWED_ORIGINS=http://localhost:6274 go run ./cmd/hnmcp
npx @modelcontextprotocol/inspector   # connect to http://localhost:8091/mcp

Release

BranchWorkflowImage
any, PRci.ymlnone (vet, gofmt, staticcheck, race tests, govulncheck)
intint.ymlghcr.io/texhfexlabs/hydronode-mcp:int, :int-<sha> (amd64)
main (push or manual, only from main)release.yml:latest, :0.1.<run>, amd64+arm64, cosign keyless; prod timer hnmcp-autodeploy swaps it

Listed in the MCP Registry as tech.hydronode/hydronode (server.json, docs/REGISTRY.md). Claude Connectors Directory texts: docs/CLAUDE_DIRECTORY.md.

License

MIT, see LICENSE.

No installation packages available.

Remote