@deltahydro/mcp

Connect Delta Hydro Studio to Claude, and run real hydrology and hydraulic design work from a conversation.

Ask for a culvert to be sized and Claude will delineate the catchment, pull the real flow path and slope off an elevation profile, compute time of concentration, look up the design rainfall, work out the peak flow, and run the HDS-5 culvert check — saving each step as a Studio record and handing you a link to open it.

The calculations run on Delta Hydro's servers using the same engines the app uses. Claude drives them; you review the results in Studio, where the charts, tables and Word/Excel exports live.

Preview. Access is currently limited to Delta Hydro administrators while the surface is being validated.

What you get

25 tools — watershed delineation, watercourse profile, time of concentration, design rainfall, ARF, design storm, Rational, TR-55, flood frequency analysis, hydrograph generation, PMP, culvert design, channel analysis, channel lining, GVF profiles, weir analysis, detention basin routing, stream gauge search, USGS flood estimates, plus lookups over your own saved calculations and reference library.

Skill cards as MCP resources — the engineering guidance for each method, so Claude applies the right one with the right inputs. Start with dhs://skills/index.

Design procedures as MCP prompts — end-to-end workflows such as peak-flow-from-scratch, size-a-culvert and flood-design-estimation, which tell Claude the correct order of operations and, importantly, which decisions to put back to you rather than make on its own.

Setup

Helping someone set this up as an AI assistant? Ask which client they use first — the steps differ. Never ask them to paste their API key into a chat; it only ever belongs in a config file. And when editing an existing config, merge into mcpServers rather than replacing it.

Requires Node.js 18+ (node --version), since the bridge runs via npx.

1. Get an API key

In Studio: Settings → API Keys → New Key. Give it both the read and write scopes (without write, Claude can look things up but cannot run or save a calculation). The key is shown once — copy it.

2a. Claude Desktop

Edit claude_desktop_config.json:

| OS | Path | | -- | ---- | | macOS | ~/Library/Application Support/Claude/claude_desktop_config.json | | Windows | %APPDATA%\Claude\claude_desktop_config.json | | Linux | ~/.config/Claude/claude_desktop_config.json |

If the file does not exist, create it with exactly this:

{
  "mcpServers": {
    "delta-hydro": {
      "command": "npx",
      "args": ["-y", "@deltahydro/mcp"],
      "env": { "DELTA_HYDRO_API_KEY": "dh_your_key_here" }
    }
  }
}

If it already exists, add delta-hydro inside the existing mcpServers object — do not replace the file. Overwriting it silently disconnects every other MCP server the user had, and they usually do not notice until something else breaks:

{
  "mcpServers": {
    "filesystem": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/me"] },
    "delta-hydro": {
      "command": "npx",
      "args": ["-y", "@deltahydro/mcp"],
      "env": { "DELTA_HYDRO_API_KEY": "dh_your_key_here" }
    }
  }
}

On Windows, some Claude Desktop builds cannot launch npx directly. If the server fails to start, route it through the shell — "command": "cmd" and "args": ["/c", "npx", "-y", "@deltahydro/mcp"], keeping env unchanged.

Then quit and reopen Claude Desktop (on macOS ⌘Q — closing the window is not enough). delta-hydro should appear in the tools menu.

2b. Claude Code — no bridge needed

Claude Code speaks HTTP directly, so skip this package entirely:

claude mcp add --transport http delta-hydro \
  https://studio.deltahydro.tech/api/mcp \
  --header "Authorization: Bearer dh_your_key_here"

2c. Cursor / VS Code — no bridge needed either

Add to ~/.cursor/mcp.json (or a project .cursor/mcp.json), merging as above:

{
  "mcpServers": {
    "delta-hydro": {
      "url": "https://studio.deltahydro.tech/api/mcp",
      "headers": { "Authorization": "Bearer dh_your_key_here" }
    }
  }
}

Verify it works

DELTA_HYDRO_API_KEY=dh_... npx -y @deltahydro/mcp --check

Connects, lists the tools, prints a summary and exits. This is the first thing to run when something looks wrong.

Credits

Tool calls are billed to your Studio account at the same per-tool rate as the in-app AI agent — most tools cost 1 credit, a few cost 2, and lookups (geocoding, searching your saved work, reading documentation) are free.

You are not billed for model usage: you are bringing your own Claude subscription, so you pay only for the engineering.

Options

| Variable | Required | Default | |---|---|---| | DELTA_HYDRO_API_KEY | yes | — | | DELTA_HYDRO_URL | no | https://studio.deltahydro.tech |

| Flag | Does | |---|---| | --check | Connect, list tools, print a summary, exit | | --version | Print the bridge version | | --help | Usage and a config example |

Troubleshooting

"DELTA_HYDRO_API_KEY is not set" — the env block is missing from your client config, or the client did not pass it through. Restart the client after editing the config.

The server does not appear at all in Claude Desktop — almost always invalid JSON in claude_desktop_config.json; the app fails silently on a parse error. Validate the file. Also check node --version reports 18 or newer.

Other MCP servers stopped working — the config was overwritten instead of merged. Restore the other mcpServers entries.

401 Unauthorized — the key is wrong, revoked, or expired. Check Settings → API Keys in Studio; mint a new one if in doubt.

403 "available to administrators only" — expected during the preview. The MCP surface is admin-gated while it is being validated.

429 — more than 60 tool calls in a minute from one key. Wait a minute.

Tools are missing — a key with only the read scope hides every tool that saves a record. Create a key with write as well.

A tool call times out — watershed delineation and watercourse profiles call external elevation services and can take well over a minute. The server keeps working to completion even if the client stops waiting, so check Studio before retrying — the record may already be there.

A note on responsibility

Claude can drive these tools, but it cannot take professional responsibility for the result. Every record it creates is tagged in Studio with where it came from, and appears in the calculation audit trail. Review the inputs and the outputs before any of it reaches a drawing, a report or a signature.

© Delta Hydro Engineers (Pty) Ltd