Hydrata - ANUGA Flood Simulation

hydrata-mcp-server

[License: MIT]

MCP server for Hydrata Cloud — build ANUGA flood models from terrain and input layers, run simulations, track progress, and retrieve results through the Model Context Protocol.

Connect and authenticate

Endpoint: https://hydrata.com/mcp/ — Transport: Streamable HTTP.

Every tool call needs the caller's own hydrata.com credential: an agent key (Authorization: Bearer hk_…), a named, revocable grant at one of three levels (read < draft < launch) that the account owner creates — and can revoke, one at a time or all at once — on the site's Agent keys page (/agents/). The server holds no identity and no key store of its own: it checks only the shape of the credential (an hk_ prefix, or with the connect flow configured a JWT-shaped token) and forwards the one accepted Authorization header unchanged to the Hydrata REST API, where Django verifies it on every tool call (for a connect-flow token: signature, issuer, audience, expiry and the live grant; for an agent key: the stored hash and the live grant) — so results are scoped by the real user's project permissions and the key's level, and the audit trail names them. Every JSON-RPC request — initialize, tools/list and ping as well as tools/call — that does not carry exactly one accepted credential (an agent key, or with the one-click connect flow configured its access token) is answered with 401, a JSON-RPC error -32001 and WWW-Authenticate: Bearer realm="hydrata.com" (plus resource_metadata="…" when the connect flow is configured) before it reaches the MCP SDK: no Authorization header, HTTP Basic, or any other Bearer token such as a GeoNode OAuth token. Agent keys and connect-flow tokens both map to an agent grant, so both are subject to the grant's level, the account's pause switch, the spend limit and the agent activity log. The 401 on the first request is what tells an OAuth-aware client such as claude.ai that the server needs sign-in (TASK-3987), so the tool catalog is not served to a request without a credential of an accepted shape; for initialize, tools/list and ping that credential is checked for shape only, not verified. The one exception (TASK-4177): MCP catalog crawlers whose User-Agent matches an allowlist (HYDRATA_MCP_DISCOVERY_USER_AGENTS, default mcptry.com indexer,SmitheryBot) may run initialize, ping and tools/list with no Authorization header, so catalogs can show the tools; tools/call always needs a credential, and real clients never match, so they still get the 401 and the sign-in default. Each claim about this server's security behaviour is cited to code or a test in docs/security-model.md; to report a vulnerability see SECURITY.md. A body that is not JSON-RPC is left to the SDK's own error, and a GET on the endpoint is answered 405. A static MCP Server Card (SEP-2127), built from server.json, is served without credentials at GET https://hydrata.com/mcp/server-card. The catalog icon, a 512×512 PNG of the Hydrata mark, is served the same way at GET https://hydrata.com/mcp/icon.png and listed in server.json and serverInfo.icons.

Anyone with a hydrata.com account can connect. There are two ways in, and both give the assistant a named, revocable permission at one access level (Read, Draft or Launch):

• One-click connect (OAuth) — for claude.ai, ChatGPT and any MCP client that can add a connector by URL. Add https://hydrata.com/mcp/ as a custom connector, sign in with your Hydrata account, name the connection and choose its level. The assistant never sees your password.

• Agent key — for Claude Code, scripts and any client that can send an HTTP header. Create a key on the Agent keys page (https://hydrata.com/agents/) and send it as Authorization: Bearer hk_…. In Claude Code:

  bash

  claude mcp add --transport http hydrata https://hydrata.com/mcp/ --header "Authorization: Bearer hk_YOUR_KEY"

  Do not add --scope project: that writes the key into the project's shared .mcp.json.

Keys and connections are listed, and revoked, on the same Agent keys page. A run that costs money waits for your consent in the browser unless the key's monthly spend limit covers it. Full guide: Connect an AI assistant in the Hydrata MCP docs.

Tools

Version 0.2.2 exposes forty-two tools, all listed below; nineteen of them only read. Every tool carries MCP annotations: a title and explicit boolean readOnlyHint, destructiveHint, idempotentHint and openWorldHint (openWorldHint is false on every tool: they reach only your Hydrata account). destructiveHint is true only on cancel_run, delete_time_series and delete_observation.

The hand-back: the engineer signs off in the map

Every tool that changes something (create_project, finalize_terrain_upload, get_terrain, create_time_series, attach_input_layer, create_scenario, build_scenario, start_simulation, cancel_run, retry_run, the five flood observation writes, and the three comparison tools) also returns:

• ui_url — https://<site>/catalogue/#/map/<base_map>?panel=…&layer=…&scenario=…&run=…, which opens the project map on the thing that changed (the Inputs panel framing the attached layer, the Hydrology panel, the scenario, the run);
• summary — numbers the engineer can check (feature count and bbox, elevation range, row count and time span, triangle estimate and price);
• say_to_user — the sentence the agent should relay.

The server's instructions tell the agent to hand the link to the user after each layer lands and to wait for the user before start_simulation. Refusals the user can fix in the map (no boundary, no External boundary edge) carry the link too. Every request the server forwards carries X-Hydrata-Client: mcp/<version> and X-Hydrata-Session: <uuid> — informational only (client-asserted), never used for authorship.

No tool accepts file contents inline. The agent moves the bytes itself — the terrain GeoTIFF to the presigned URL, a GeoJSON layer to the REST API upload endpoint — and hands the server the resulting key or upload id.

No read tool relays a presigned S3 URL. A run's result links are 6-hour capabilities carrying a temporary AWS credential, and the server forwards the caller's own credential rather than holding one, so a tool that echoed such a link would widen what an agent transcript is worth beyond what the caller asked for. Every read tool (and start_simulation) elides them, recursively, by key name (s3_*_url) and by value shape (any string carrying X-Amz-Signature / X-Amz-Security-Token, redacted in place so the rest of a log line survives); results stay viewable through the gn_layer_* WMS entries. presign_terrain_upload is the sole exception: its upload_url is the URL the caller explicitly asked for.

Typical workflow

Run a scenario that already exists:

list_projects → get_scenario → start_simulation → poll get_run_status → get_run

Import a model and run it:

create_project → presign_terrain_upload → PUT the GeoTIFF → finalize_terrain_upload → get_terrain→ create_time_series / attach_input_layer → create_scenario → build_scenario→ start_simulation → poll get_run_status → get_run

What is Hydrata?

Hydrata is a geospatial hydraulic modeling platform. It runs ANUGA flood simulations in the cloud — upload terrain data, configure scenarios, run simulations on managed compute (Celery, EC2, or AWS Batch), and visualise results on interactive maps.

ANUGA is an open-source hydrodynamic model developed by Geoscience Australia and the Australian National University. It solves the shallow water wave equations using finite volumes on an unstructured triangular mesh.

Development

git clone https://github.com/Hydrata/hydrata-mcp-server.gitcd hydrata-mcp-serverpip install -e ".[dev]"pytest -v

Contributions welcome — see issues.

License

MIT