Hydrata MCP Server

hydrata-mcp-server

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. 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 is answered 405.

The server is not yet open to external accounts: there is no self-serve way to connect your own hydrata.com login to it today, and this README deliberately carries no client-side credential recipe. If you would like to use it, contact us at hydrata.com.

Tools

Version 0.2.0 exposes thirty-six tools. The table below lists the original twenty-eight and suggest_capability; tools/list returns all of them. Of the original twenty-eight, eleven that read projects, inputs and scenarios and drive a run, eight that build a model from terrain and input layers the agent has already uploaded, six that record flood observations, and three that compare a historic run with them (Compare with observations). Every tool carries MCP annotations (a title; readOnlyHint on the eleven read tools; destructiveHint only on cancel_run 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.git
cd hydrata-mcp-server
pip install -e ".[dev]"
pytest -v

Contributions welcome — see issues.

License

MIT