fema-nfhl-mcp-server

fema-nfhl-mcp-server

MCP server wrapping FEMA's public National Flood Hazard Layer (NFHL) ArcGIS REST service(https://hazards.fema.gov/arcgis/rest/services/public/NFHL/MapServer) — the same live datasetbehind msc.fema.gov, which the Hutton SIR agent's standing doctrine treats as non-fetchable.This server queries the NFHL directly, no API key required for the FEMA side.

Transport: Streamable HTTP (stateless)

This server runs as a small Express HTTP server exposing POST /mcp, using the MCPStreamable HTTP transport in stateless mode — every request gets its own short-livedMCP server + transport instance, connected, used, and torn down. There is no in-memory sessionstate kept between calls. This is deliberate: it makes the server safe to run on a host thatspins the process down when idle (e.g. Render's free tier) — there's nothing to lose when theprocess restarts, because nothing persists between requests anyway.

An earlier version of this server used stdio transport (local-process-only, no network).That version is kept for reference in reference/index_stdio_original.ts.txt but is not part ofthe deployable build — src/index.ts is now the HTTP entry point, and src/createServer.tsholds the actual tool registration shared by both.

GET /health is also exposed for host health checks and uptime pingers.

Why this exists (Hutton SIR context)

The SIR agent's Field Reference and Setback Routine both carry a standing rule: msc.fema.gov/portalis non-fetchable, so flood zone/BFE/panel lookups always route to a manual coordinate search. Thisserver replaces that manual step with a live tool call — the agent already desk-answers lat/long forevery site (topography section), so it can pass those same coordinates straight through.

It does not replace the "carry coordinates with the route" discipline (Quality Rule 8) — the tooloutput includes the queried coordinates in every result specifically so that discipline still holdseven when the lookup succeeds outright.

Tools

fema_flood_zone_lookup

The primary tool. Takes 1–8 labeled points (e.g. site centroid, or all four parcel corners + centroid)and returns, per point: flood zone code, SFHA flag, Base Flood Elevation + datum, FIRM panel number,effective date, and status. Flags a split-zone condition automatically if different points returndifferent zones — the exact case that matters for a site straddling a flood-zone boundary.

fema_identify_layer

Lower-level identify against any NFHL layer(s) at a point — useful for checking Letters of Map Revision(layer 1) or Letters of Map Amendment (layer 34) on a parcel, which the flood-zone tool doesn't surface.

Deploying — Render (recommended, browser-only, free)

This repo includes render.yaml, so Render can configure itself from a Blueprint — you don't haveto manually fill in build/start commands.

1. Push/upload this repo to GitHub (a browser-only, no-git-CLI way to do this is via GitHub'sweb uploader: new repo → "Add file" → "Upload files").
2. On render.com, sign up (GitHub login is easiest — no credit card requiredfor the free tier).
3. New > Blueprint, connect your GitHub account, select this repo. Render will detectrender.yaml and pre-fill everything: Node web service, free plan, npm install && npm run buildbuild command, npm start start command, /health health check path.
4. Click Apply / Deploy. Render will generate a random MCP_API_TOKEN environment variableautomatically (see render.yaml — generateValue: true). Copy that token from the service'sEnvironment tab in the Render dashboard once deployed — you'll need it in step 6.
5. Your endpoint will be https://<your-service-name>.onrender.com/mcp.
6. In claude.ai: Customize > Connectors > "+" > Add custom connector. Paste the URL from step 5.Under Advanced settings > Request headers, add:

   Authorization: Bearer <the MCP_API_TOKEN value from step 4>
   

   Click Add.

No auth needed? If you'd rather leave the endpoint fully open (it's a read-only public-datalookup, so the risk is low), delete the MCP_API_TOKEN env var in Render's dashboard after deploy —the server checks for it at request time and runs open if it's unset. See the requireAuth middlewarein src/index.ts.

Free-tier cold starts: Render's free instances spin down after 15 minutes idle and take30–60 seconds to wake on the next request. The first flood-zone lookup after a period of inactivitymay be slow or need a retry. Upgrade to Render's Starter plan (~$7/mo) to keep the service always-onif this becomes annoying.

Running locally (only if you have Node.js installed)

npm install
npm run build
PORT=3000 npm start

Then POST http://localhost:3000/mcp with a standard MCP JSON-RPC body, or point theMCP Inspector athttp://localhost:3000/mcp for a browser test UI:

npx @modelcontextprotocol/inspector

Then in the Inspector UI, choose "Streamable HTTP" transport and enter the URL above.

No environment variables are required to run it — MCP_API_TOKEN is optional (see above).

Verified so far

• Server builds clean under strict TypeScript.
• Real protocol-level test performed: started the compiled server, sent an actual HTTPinitialize request and an actual tools/list request to POST /mcp, and got back correct,well-formed MCP responses (both tools present with valid JSON Schemas, matching the descriptionsbelow) — this is a genuine test of the transport wiring, not a mock.
• GET /health confirmed working over real HTTP.
• Response parsing (extractFloodZones / extractFirmPanels, including the epoch-ms → ISO dateconversion for EFF_DATE) is exercised against a mocked response shaped exactly like the liveservice's field schema (FLD_ZONE, SFHA_TF, STATIC_BFE, V_DATUM, FIRM_PAN, EFF_DATE, etc.),confirmed against FEMA's own layer metadata for layers 28 (S_Fld_Haz_Ar) and 3 (S_FIRM_Pan).
• Error handling confirmed to degrade gracefully (clear error message, no crash) on a simulatednetwork failure.

NOT yet verified — do this before relying on it live

The build/test environment used to build this server has no network route to hazards.fema.gov,so the actual live FEMA API call has not been executed or observed. Before trusting this in areal SIR:

1. Run fema_flood_zone_lookup against a known site (e.g. a parcel you already have a confirmedFIRM panel/zone for from a past live run — Indian River County or Jefferson County both haveflood data on file) and diff the tool's output against the confirmed manual result.
2. Confirm the identify endpoint's exact response shape hasn't drifted from what's documented here —ArcGIS services occasionally change field aliasing or add/retire layers.
3. Watch for SFHA_TF values other than "T"/"F" (blank has been reported in edge cases) and confirmextractFloodZones handles that gracefully (it currently reports it as null/not-SFHA, worthdouble-checking against a real blank-value response).
4. Confirm rate-limit behavior under repeated calls (e.g. 5 points per SIR × multiple SIRs per day) —the public service doesn't publish a documented limit.
5. Confirm Render's free-tier cold start doesn't exceed claude.ai's MCP request timeout on a coldfirst call — if it does consistently, upgrade to a paid Render plan.

Known layer IDs (from FEMA's own NFHL MapServer)