Skip to main content
Glama
hydronode-mcp

hydronode-mcp

by TexhFexLabs

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

Client

Setup

Cursor

Add to Cursor or add {"mcpServers":{"hydronode":{"url":"https://hydronode.tech/mcp"}}} to .cursor/mcp.json

VS Code

Install in VS Code or add {"servers":{"hydronode":{"type":"http","url":"https://hydronode.tech/mcp"}}} to .vscode/mcp.json

Claude.ai / Claude Desktop

Settings → Connectors → Add custom connector → https://hydronode.tech/mcp

Claude Code

claude mcp add --transport http hydronode https://hydronode.tech/mcp

ChatGPT

Settings → Connectors → Add MCP connector → https://hydronode.tech/mcp

Codex

Add [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 MCP

run 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.

Related MCP server: AetherEdge

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)

Tool

Kind

What it does

overview

read

Projects, device counts by status, open anomalies, unread messages, what needs attention

find

read

Sensors, data points, stations, projects by name, id or DevEUI

get_sensor

read

One sensor with status, battery, signal, firmware and every data point

summarize_history

read

Min/max with time, average, trend, gaps, ≤ 48 buckets

find_periods

read

When a value was below/above a threshold

compare

read

Up to 4 data points, or one point against an earlier span (shift)

list_anomalies / get_anomaly

read

Detected anomalies and their explanation

list_messages

read

Inbox

device_health

read

Only devices with problems

console

read

Latest device requests with rejection reasons

public_stations

read

Public stations by name or location

list_automations

read

Automations, one with recent runs

set_value

write

Switch or set a writable data point (destructive hint)

send_command

write

Queue a typed device command (destructive hint)

log_value

write

Record a manual measurement

mark_messages

write

Read, unread, archive, restore, read all

toggle_automation

write

Automation on/off

create_automation

automations

Dry 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 /mcp

MCP (Streamable HTTP, stateless). Needs Authorization: Bearer hoa_…

GET /.well-known/oauth-protected-resource/mcp

RFC 9728 metadata

GET /q/health/live, /q/health/ready

health (ready also checks the backend)

Configuration

Env

Default

HNMCP_LISTEN

:8080

listen address

HNMCP_BACKEND_URL

required

internal backend, e.g. http://hnbackend:8080

HNMCP_PUBLIC_URL

required

public origin, e.g. https://hydronode.tech (resource = +/mcp)

HNMCP_AUTH_SERVER

HNMCP_PUBLIC_URL

OAuth issuer

HNMCP_ALLOWED_ORIGINS

https://claude.ai,https://claude.com,https://chatgpt.com

browser origins allowed on /mcp (requests without Origin always pass)

HNMCP_RATE_PER_MIN

120

requests per token per minute (the backend has its own limits)

HNMCP_STEPUP_HTTP

true

answer missing scopes with HTTP 403 step-up

HNMCP_LOG_LEVEL

INFO

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

Branch

Workflow

Image

any, PR

ci.yml

none (vet, gofmt, staticcheck, race tests, govulncheck)

int

int.yml

ghcr.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.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Connects AI assistants to physical devices via MCP, enabling LLMs to reason about sensor data, perform cross-device correlation, and interpret anomalies.
      4
      Apache 2.0
    • A
      license
      B
      quality
      C
      maintenance
      Exposes a deterministic IoT edge runtime — Modbus/CAN/J1939 acquisition, local rules, alarms, and history — to AI assistants as typed, governed MCP tools. Reads are safe by default; device control stays deny-by-default, explicitly confirmed, and audited.
      23
      3
      Apache 2.0
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI assistants to query and, when scoped writes are enabled, manage cloud estate data—inventory, costs, recommendations, schedules, governance, and deployments—across AWS, Azure, and GCP through a hosted remote MCP endpoint.
      Apache 2.0
    • A
      license
      Not graded
      quality
      A
      maintenance
      Enables AI clients such as Claude, Cursor, VS Code, and Windsurf to list and manage workspaces, projects, tasks, AI agents, and automations through a hosted OAuth-secured endpoint or a local stdio package. Also generates MCP tools from any OpenAPI spec.
      2,530 npm
      MIT