ZonerMCP

ZonerMCP

ZonerMCP is a hardened Model Context Protocol server for Lebanon, NH zoning and GIS lookups. It exposes a Streamable HTTP MCP endpoint, queries an ArcGIS FeatureServer through an explicit layer allowlist, filters returned fields, rate-limits callers, and fails fast when required production security settings are missing.

Quick Start

Install dependencies:

npm install

Run locally without bearer auth while developing:

$env:ARCGIS_BASE_URL="https://services.arcgis.com/.../ArcGIS/rest/services/.../FeatureServer"
$env:REQUIRE_AUTH="false"
npm start

The server listens on http://localhost:5000 by default. The .env.example file documents the full environment surface, but this project does not load .env files automatically; set variables in your shell, host configuration, or Replit Secrets.

MCP Tools

• list_layers: lists the GIS layers registered for MCP access.
• describe_layer: returns allowed query modes, field profiles, and limits for one layer.
• query_features: queries an allowed layer by point, object IDs, or bounding box.
• lookup_zoning_by_address: searches the Lebanon address layer and returns zoning district matches.

HTTP Endpoints

| Endpoint | Method | Description | | --- | --- | --- | | /mcp | POST | Streamable HTTP MCP endpoint for initialize, tools/list, and tools/call. | | /mcp | GET | Server info without a session, or stream handling with a session ID. | | /mcp | DELETE | Session termination. | | /health | GET | Public health check. |

Configuration

| Variable | Default | Required | Description | | --- | --- | --- | --- | | ARCGIS_BASE_URL | none | yes | ArcGIS FeatureServer base URL. | | MCP_BEARER_TOKEN | none | when REQUIRE_AUTH=true | Bearer token accepted by /mcp. | | CORS_ALLOW_ORIGINS | none | when NODE_ENV=production | Comma-separated trusted browser origins. | | NODE_ENV | development | no | Enables production startup checks when set to production. | | PORT | 5000 | no | HTTP port. | | REQUIRE_AUTH | true | no | Set to false only for local unauthenticated development. | | ALLOW_STATELESS | true in development, false in production | no | Allows direct one-shot tools/list and tools/call requests without creating a session. | | ZONING_LAYER | 24 | no | ArcGIS layer ID for official zoning. | | ADDRESS_LAYER_NAME | LebanonNHMATMassGeoExport_Layer | no | ArcGIS layer/table name resolved from the FeatureServer catalog for address lookup. | | MAX_SESSIONS | 100 | no | Maximum concurrent MCP sessions. | | SESSION_TIMEOUT_MS | 1800000 | no | Idle session timeout. | | SESSION_REAPER_INTERVAL_MS | 300000 | no | Session cleanup interval. | | RATE_LIMIT_WINDOW_MS | 60000 | no | Rate-limit window. | | RATE_LIMIT_MAX_REQUESTS | 60 | no | Base request limit per window. | | RATE_LIMIT_AUTH_MULTIPLIER | 2 | no | Multiplier for authenticated request limits. | | CACHE_TTL_SECONDS | 300 | no | Query cache TTL. | | CACHE_MAX_ENTRIES | 500 | no | Maximum cached query results. | | MAX_FIELDS | 40 | no | Maximum explicit fields per query. |

Production Setup

Set at least:

NODE_ENV=production
ARCGIS_BASE_URL=
REQUIRE_AUTH=true
MCP_BEARER_TOKEN=
CORS_ALLOW_ORIGINS=https://trusted-client.example

Leave ALLOW_STATELESS unset in production unless a client cannot preserve MCP session IDs. If needed, set ALLOW_STATELESS=true explicitly.

Security Model

• Authentication is enabled by default.
• Production startup fails without CORS_ALLOW_ORIGINS.
• Production stateless one-shot handling is disabled unless explicitly enabled.
• Queryable layers, fields, query modes, and record caps are controlled by layer-registry.js.
• Geometry is withheld unless a layer explicitly opts in.
• Address and feature queries use bounded inputs and validation.

Development Checks

npm test
npm run audit
node --check mcp-server.js

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: melbamorph
• Source: melbamorph/zonerMCP
• License: ISC
• Homepage: https://zoner.melaniemcd.ai

Install and usage instructions live in the source repository linked above.