Hydrata MCP Server

Official

Overview Schema Source Related Servers Discussions Admin

Attach an uploaded layer as a project input

attach_input_layer

Attaches an uploaded GeoJSON to a Hydrata project as its boundary, friction, inflow, rainfall, building, mesh_region, or culvert input layer.

Instructions

Attach a GeoJSON you uploaded to GeoNode as the project's boundary, friction, inflow, rainfall, building, mesh_region or culvert layer.

Only for a client that has a shell and an agent key. A connector agent with no shell (claude.ai) writes the layer inline with write_input_layer, or, for a file above the inline cap, gives the user the request_input_upload link instead.

The agent moves the bytes: first upload the GeoJSON yourself, with the same agent key, to GeoNode's upload endpoint at the site origin:

curl -sS -H 'Authorization: Bearer hk_...' -F "base_file=@/path/rainfall.geojson" https://<site>/api/v2/uploads/upload/

→ JSON with execution_id. Then call this tool with it. The tool polls GET /api/v2/resource-service/execution-status/<execution_id> (bounded by timeout_seconds; statuses ready → running → finished | failed), reads the new dataset's pk, and PATCHes it onto the project's DEFAULT row of that kind ('Boundary 01' … 'MeshRegion 01' — the six rows the terrain import seeds ~30 s after get_terrain reports ready; if the list is still empty the tool says so: run finalize_terrain_upload / wait for get_terrain first).

kind culvert (Hydraulic Structures; one two-point line per culvert, Inlet first, then Outlet): no culvert row is seeded by the terrain import, so a project with none answers no_default_row: write the culverts with write_input_layer, which makes the row. Hydrata converts every attached layer into the project's grid and the kind's table shape (single geometries, the_geom, the kind's own columns); attribute names are matched as they are, nothing is renamed for you (see write_input_layer). The culvert engine conveys flow through each culvert in a run (GPU lanes and localhost; the multi-core CPU lanes refuse a culvert scenario).

outcome is exactly one of: attached (row_id, gn_layer, dataset_pk and dataset_alternate — the WFS typename — of the CONVERTED layer the row now uses, source_dataset_pk — the dataset you uploaded — and every row id seen); timed_out (still importing: call again with the same arguments, except pass retry_execution_id as execution_id when the result carries one); upload_failed (the execution record, incl. its log, is returned verbatim — fix the file and upload again); no_default_row; no_dataset (finished but no resource was recorded). The PATCH is refused with a 400 if the dataset is not owned by you.

Every layer attached here is marked as written by your agent key and is UNREVIEWED until the user reviews it in their browser (the build refuses UNREVIEWED_INPUTS until then). INFLOWS: never invent an inflow location — no coordinates you made up, guessed or "placed plausibly". Import the location from the study's own files, or give the user the ui_url to draw it in the map; say in say_to_user that the inflow is unreviewed and where they check or draw it.

Refused, with no request made: kind breakline — no REST create path exists for it at HEAD (TASK-3040 AC6), so attaching one would only pretend. Also refused without a request: an execution_id that is not the UUID the upload returned. One GeoJSON per kind: all of a kind's features travel in that one file. A rainfall polygon names its gauge in its data property — create that gauge with create_time_series under the exact same name.

Input Schema

Name	Required	Description
`kind`	Yes	Which input the uploaded layer is: boundary, friction, inflow, rainfall, building, mesh_region or culvert ('structure' is a deprecated alias of building). breakline is refused (see below).
`project_id`	Yes	The project ID
`execution_id`	Yes	`execution_id` returned by your multipart POST to <origin>/api/v2/uploads/upload/
`timeout_seconds`	No	How long this call keeps polling the upload before it returns `timed_out` (default 180, ceiling 200 — claude.ai cuts a tool call at 240 s). 0 = one status read, no waiting.
`poll_interval_seconds`	No	Seconds between polls (default 5)

Output Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedv0.2.0Oct 30, 2026

changedInput schema / properties / timeout_seconds / default
```
Previous value: -240New value: +180
```

changedInput schema / properties / timeout_seconds / description

Previous value: -"How long this call keeps polling the upload before it returns `timed_out` (default 240, ceiling 280 — the prod /mcp/ proxy cuts a call at 300 s). 0 = one status read, no waiting."New value: +"How long this call keeps polling the upload before it returns `timed_out` (default 180, ceiling 200 — claude.ai cuts a tool call at 240 s). 0 = one status read, no waiting."

First observedv0.2.1Oct 29, 2026

TDQS

A4.8/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Goes far beyond the annotations: it discloses the full upload→poll→PATCH sequence, the status transitions, the 400 refusal when the dataset isn't owned by the caller, the UNREVIEWED_INPUTS build gate, refused inputs (breakline, non-UUID execution_id) with no request made, and the one-GeoJSON-per-kind constraint. The annotations (destructive false, idempotent false) are consistent with a row-PATCH that is retryable only via retry_execution_id.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the verb and the target kinds, and most paragraphs earn their place (alternatives, prerequisites, outcome codes). It is long, and one passage — the culvert engine's GPU/CPU lane behaviour — describes simulation behaviour rather than invocation of this tool, which is tangential for a 5-parameter call.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a multi-step tool with an output schema, an agent gets everything needed to call it correctly: upload endpoint with curl example, polling bounds, all outcome values, failure remediation, ownership constraint, and the review workflow afterwards. Nothing material is left implicit.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3; the description earns more by clarifying that execution_id must be the exact UUID the upload returned, documenting the outcome/timed_out retry path via retry_execution_id, and stating the kind semantics including the deprecated 'structure' alias and the breakline refusal. Timeout ceiling rationale lives in the schema, not the description, so it isn't double-counted.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource — attach an uploaded GeoJSON as one of seven enumerated project input kinds — and immediately distinguishes itself from write_input_layer and request_input_upload by client capability. An agent can pick this tool without opening a schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit when-to-use gate (client with a shell and agent key), explicit when-not (no-shell connector → write_input_layer or request_input_upload), and named prerequisites: the terrain import seeds the six default rows ~30 s after get_terrain is ready, otherwise run finalize_terrain_upload. The culvert case gets its own routing rule (write_input_layer, since no row is seeded).

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.