This page lists every tool the Hydrata MCP server offers, the access level each one needs, and the refusals an agent can meet and what to do about them. The server currently has 42 tools.
Every tool returns its result as JSON. Inputs go in as inline GeoJSON, or through a link where you drop a big file in your browser. No tool accepts raw file bytes. Tools that change something hand back a link to the map (see Working with an agent).
In the Level column, each level includes the ones before it: Read < Draft < Launch. Writes means the tool changes something; "reads only" means it never does.
Projects, scenarios and runs
| Tool |
What it does |
Level |
Writes |
list_projects |
List the ANUGA projects you can see, a page at a time |
Read |
Reads only |
get_project |
Get one project: name, projection, visibility, your role, its base map and a link to it. Also your levels datum, and a warning if it differs from the terrain's |
Read |
Reads only |
get_scenario |
Get one scenario's state: status from its latest run, inputs, mesh estimate and price; warns about time series nothing uses |
Read |
Reads only |
get_run_status |
Status of a run: status, phase and percent complete, with a say_to_user line the agent relays. Pass wait_seconds (up to 180) and the call waits inside, returning early when the status, phase or progress moves |
Read |
Reads only |
get_run |
Full run record: timing, compute, mesh and result log, and the state of the full time series (SWW) download |
Read |
Reads only |
get_flow_hydrograph |
Flow (Q) across a drawn line from the run's playback store: signed peak and time, volume, the sign convention and a by-difference mass balance. It is not a gauge reading |
Read |
Reads only |
list_runs |
List the runs across a project, optionally filtered by status |
Read |
Reads only |
create_project |
Create a project with a name and projection. It starts unpublished |
Draft |
Writes |
create_scenario |
Create a draft scenario and report its mesh-triangle estimate. Does not build or run. Accepts sources, the documents it is based on |
Draft |
Writes |
update_scenario |
Change a scenario's name, size (resolution, duration) or the inputs attached to it. Does not build or run |
Draft |
Writes |
clone_scenario |
Copy a scenario as a variant. The copy uses the same input rows as the original until you give it its own (write_input_layer with a target, then overrides). Does not build or run |
Draft |
Writes |
build_scenario |
Build a scenario's mesh and package, showing the estimate first. Needs confirm=true above 100,000 triangles |
Launch |
Writes |
start_simulation |
Start a run for a built scenario. Spends compute. It has no compute_backend option: Hydrata chooses the compute |
Launch |
Writes |
retry_run |
Rebuild the scenario of a run that ended in error, as a new run. The failed run keeps its error |
Launch |
Writes |
cancel_run |
Cancel a run that is built, queued or computing |
Launch |
Writes |
| Tool |
What it does |
Level |
Writes |
list_terrain_sources |
List the terrain Hydrata can fetch for a site (for example GA 5 m and Copernicus) |
Read |
Reads only |
create_terrain_from_source |
Have Hydrata fetch terrain from one of its own sources and wait for the import. Use this before any other terrain route. Needs levels_datum, the datum of your levels, which the agent asks you for |
Launch |
Writes |
presign_terrain_upload |
Step 1 of importing your own terrain GeoTIFF: return an upload address. Only for a client that can send files; if no source covers the site, upload your DEM in the map |
Draft |
Writes |
finalize_terrain_upload |
Step 2: register the uploaded terrain and start the import. Takes vertical_datum_declared (the datum of the uploaded terrain itself) and levels_datum (the datum of your levels). Creates the project's default input layers |
Launch |
Writes |
get_terrain |
Wait for a terrain import to finish. Reports the declared, recorded and inferred datum, your levels datum (with a warning if it differs from the terrain's) and the true minimum and maximum |
Read |
Reads only |
sample_terrain |
Read the ground level at up to 500 points (longitude, latitude), so a culvert, inflow or boundary can be placed on the ground. A point outside the terrain or on no-data has no level |
Read |
Reads only |
terrain_profile |
Read the ground along a line, one sample every step_m metres, with the lowest sample (the channel invert candidate). The same values as the Profile panel |
Read |
Reads only |
list_inputs |
List a project's input layers by kind, and whether each has features |
Read |
Reads only |
describe_input_kinds |
Describe the format of each input layer kind, generated from Hydrata's own models |
Read |
Reads only |
read_input_layer |
Read the features of a project input layer, so the agent adds to what you drew |
Read |
Reads only |
write_input_layer |
Write a boundary, friction, inflow, rainfall, building, mesh-region or culvert layer from inline GeoJSON. The agent states authored_method and, when it cites a document, sources |
Draft |
Writes |
request_input_upload |
Get the link where you drop a big input file (over about 150 KB) in your browser. Nothing is created until you drop it |
Read |
Reads only |
attach_input_layer |
Attach an already uploaded GeoJSON as an input layer. Breakline layers are refused |
Draft |
Writes |
list_time_series |
List a project's time series (rain gauges, hydrographs, tides), without their rows |
Read |
Reads only |
create_time_series |
Create a time series from rows of time and value, for an inflow, rainfall or stage. Accepts sources |
Draft |
Writes |
update_time_series |
Correct the rows or details of a time series. Accepts sources |
Draft |
Writes |
delete_time_series |
Delete a time series. One a feature still uses is refused, and the refusal names the layer and feature |
Draft |
Writes |
Flood observations
| Tool |
What it does |
Level |
Writes |
create_observation_layer |
Create a flood observation layer in a project |
Draft |
Writes |
list_observations |
List a project's observation layers, or one layer's observations |
Read |
Reads only |
add_observations |
Add observations (flood mark, timed level, gauge record, dry point) to a layer |
Draft |
Writes |
update_observation |
Change fields of one observation |
Draft |
Writes |
delete_observation |
Delete one observation and its photos. This cannot be undone |
Draft |
Writes |
add_observation_photo_link |
Attach a photo to an observation as a link, never as a file |
Draft |
Writes |
get_observation_comparison |
Compare a run with the project's observations: how well it matches |
Read |
Reads only |
set_observation_exclusion |
Leave an observation out of one run's comparison, or put it back |
Draft |
Writes |
set_comparison_tolerance |
Save the project's default tolerance for comparing runs with observations |
Draft |
Writes |
Feedback
| Tool |
What it does |
Level |
Writes |
suggest_capability |
Tell the Hydrata team about something you asked for that no tool can do. The agent uses it only after checking the other tools. At most 20 a day per person |
Read |
Writes a suggestion only |
Refusals and what to do
When Hydrata refuses a request, the agent receives a code. Most are written to be passed on to you.
| Code |
Meaning |
What to do |
AGENT_KEY_INVALID |
The key is revoked or not recognised |
Make a new key, or connect again |
AGENT_KEYS_UNAVAILABLE |
Agent keys do not work on this Hydrata site |
Use hydrata.com |
AGENT_LEVEL_INSUFFICIENT |
The key's level is below what the action needs |
Make a key or connection at a higher level |
AGENT_KEY_SCOPE |
The action is one agents may never take |
Do it yourself in the browser |
AGENT_CANNOT_REVIEW_INPUTS |
An agent tried to review inputs |
Review them yourself in the Review panel |
AGENT_PAUSED |
Hydrata has paused agent launches or writes |
Wait; the agent should tell you and stop. See activity and controls |
UNREVIEWED_INPUTS |
Build, Run or Retry is refused until a person reviews the agent's inputs |
Review the inputs in the browser, then ask the agent to continue |
RUN_INVALIDATED |
An agent-written input changed after the scenario was built, so the build is not what was reviewed; or the scenario's settings (resolution, duration) changed after it was built |
Build the scenario again, then run |
CONSENT_REQUIRED |
The run costs more than the key may spend without asking, or Hydrata cannot price it in advance |
Open the consent link. See run consent |
CONSENT_STALE |
The scenario was rebuilt, or the price or compute changed, since the consent link was made |
Ask the agent to start the run again, and consent again |
UNITS_MISMATCH |
A time series has the wrong units for its type |
Use mm/hr for rainfall, m3/s for inflow and m for stage |
TRAILING_VALUE_HELD |
A hydrograph or hyetograph ends on a value other than 0 |
End it with a 0 row, or confirm the hold is intended |
MESH_TOO_LARGE |
The mesh is above the server's ceiling |
Use a coarser resolution or a smaller boundary |
BOUNDARY_NO_EXTERNAL |
No boundary edge is marked External |
Mark the outer edges External in the map |
MESH_REGION_UNITS_UNMARKED |
Mesh-region resolutions are not marked as lengths in metres |
Ask the Hydrata team to convert them, through support |
| HTTP 429 |
Too many requests in a short time |
Nothing; the agent should wait and try again |
For developers
- Endpoint:
https://hydrata.com/mcp/
- Transport: StreamableHTTP
- Server version: 0.2.0
- Source: github.com/Hydrata/hydrata-mcp-server
- Registry: registry.modelcontextprotocol.io, published as
com.hydrata/hydrata-mcp-server
- Credentials: a tool call needs an agent key (sent as
Authorization: Bearer hk_…) or a one-click connection. A username and password is refused. Listing the tools needs no credential.