Underground Utility Permit Review MCP Server
This server provides read-only access to an excavation permit review system, enabling intelligent triage, risk analysis, and field verification planning across a portfolio of permits without direct action.
Search permits: Find pending excavation permits by street, city, applicant, project type, verdict, risk level, flagged status, or specific utility types.
Get permit details: Retrieve a complete review for a single permit, including every nearby utility line with owner, distance, ASCE 38-02 data quality grade, provenance, crossing risk, overall verdict, and lines requiring verification.
Find utility conflicts: Scan the entire portfolio to identify hazardous individual utility lines (e.g., close to excavation, poorly evidenced, or with conflicting data sources), ranked by consequence-weighted risk, with filters for distance, data quality, utility type, city, or source disagreements.
Portfolio summary: Generate aggregate statistics such as verdict distribution, risk concentration by city or project type, corroboration rates, and total unverified exposure.
Recommend field verification: Produce a prioritized potholing plan (list of lines to physically verify) for a single permit or the whole portfolio, optimized for limited field budgets.
Deep linking: All results include links to a human-facing dashboard for visual inspection of permits and utility lines.
Data provenance: Every utility line includes ASCE 38-02 quality grade and source information, enabling transparent risk assessment.
Key constraints: read-only (no approval or dispatch); no authentication (runs as local user via stdio); distances are precomputed scalar values, not live GIS geometry.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Underground Utility Permit Review MCP Server Which pending permits have unverified gas lines within 5 feet?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Underground Utility Permit Review — MCP Server
An MCP server that gives Claude direct, read-only access to a portfolio of pending excavation permit reviews and the underground utility lines near each one.
The permit review dashboard answers these questions for a human looking at a screen. This answers them for an agent — same data, same scoring rules, no interface.
Zero dependencies. node server.js is the entire install.
Why build this
A dashboard assumes a person sits down and browses. That works until the question is "across every permit I have open, what's about to hurt someone?" — at which point browsing twenty-four cases is the wrong shape of work.
The interesting shift is that the tools aren't a mirror of the database. There is no
"conflicts" table; find_utility_conflicts exists because triage across a portfolio is a real
question a reviewer asks and a screen answers badly. Designing the tool boundaries around
questions rather than tables is most of the product work here.
Related MCP server: postgres-mcp-lab
What Claude can do with it
You: Which pending permits have unverified gas lines within 5 feet of the dig?
Claude: [find_utility_conflicts · utility_types=["Gas line"] · max_distance_ft=5]
Two, and both are high risk:
Firestone Blvd. & Studebaker Rd. — 2 in gas main, 2.4 ft from the excavation,
Level D. That's a county record with no independent verification, so the
position is approximate and the line is well inside strike range.
Artesia Blvd. & Carpintero Ave. — 2 in gas line at 4 ft, Level C. The county
record and the independent detection disagree on diameter, so neither can be
relied on until someone confirms it.
I'd pothole both before either permit is signed.Other things it handles well:
"Summarise my permit portfolio risk by city."
"I have one crew for one day. What should they pothole?"
"Walk me through PRM-1001 and tell me what's unresolved."
"How much of the county record have we actually corroborated?"
Install
Requires Node 18+. Nothing to npm install.
1. Point Claude Desktop at it. Edit the config file:
macOS
~/Library/Application Support/Claude/claude_desktop_config.jsonWindows
%APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"utility-permits": {
"command": "node",
"args": ["/absolute/path/to/utility-mcp-server/server.js"]
}
}
}The path must be absolute — Claude Desktop doesn't run from your project directory.
2. Restart Claude Desktop. Fully quit it; closing the window isn't enough.
3. Confirm. The tools appear in the tool menu. Ask "what permit tools do you have?"
The tools
Tool | The question it answers |
| Which cases match this filter? |
| What's the full review for this one case? |
| Across everything, what's dangerous to dig near? |
| How are we doing overall, and where is risk concentrated? |
| Given a limited field budget, what do we pothole first? |
Every tool is annotated readOnlyHint: true. Nothing here can approve a permit or dispatch
a crew. That's a deliberate boundary, not an unfinished feature: an agent that can sign off
on an excavation without a human in the loop is a liability, and the fastest way to lose a
utility customer's trust is to build one.
Results link back into the dashboard
Every result carries a deep link to the human UI — down to the specific utility line that triggered it:
https://erincheong.github.io/permit-review-dashboard/#permit=PRM-1001&line=4&set=PRM-2008,PRM-1001&label=Gas+lines+within+5+ftThat opens the permit with the offending line already expanded and highlighted, and Back returns to the permits from the query rather than the full portfolio.
The agent is a second door onto the same data, not a replacement for it. It's good at "across everything, what's dangerous." It's bad at "let me see the county record with my own eyes." So it hands off to the thing that's good at that, and remembers where you came from.
Hash routing rather than query strings, so the links also work against a copy opened straight
off the filesystem. Point them elsewhere with UTILITY_DASHBOARD_URL.
Provenance travels with every result
Every utility line comes back carrying its ASCE 38-02 quality grade, what that grade means in
plain language, and where the record came from. The server's instructions tell the model to
keep them attached:
A Level D record is not a known position — it is a decades-old drawing whose source disclaims any guarantee of accuracy, and treating it as fact is how people get hurt.
This matters more for an agent than for a dashboard. A human looking at a red badge infers uncertainty. A model summarising into prose will flatten "county record, unverified, position approximate" into "there's a gas line at 4 feet" unless the data fights back.
One scoring module, two surfaces
src/scoring.js holds the risk rules, and the dashboard uses the same ones. If they diverged,
a reviewer and an agent could look at the same permit and disagree about whether it's safe to
approve — which is worse than either being wrong alone. The test suite asserts the server's
numbers for the shared corridors match what the dashboard displays.
Protocol notes
This is a dual-era server, written directly against the spec rather than an SDK.
MCP changed its negotiation model in revision 2026-07-28: instead of an initialize
handshake establishing a session, every request carries its own protocol version in _meta
and the server accepts or rejects each one independently. Older clients still open with
initialize. This server speaks both:
Client | Flow |
Modern ( |
|
Legacy ( |
|
An unsupported version gets UnsupportedProtocolVersionError (-32022) listing what the
server does support, so the client can retry instead of guessing.
Transport rule worth knowing: stdio MCP is newline-delimited JSON, and the server must
write nothing to stdout that isn't a valid MCP message. A stray console.log corrupts the
stream and the server appears to hang — it's the single most common way these break. All
logging here goes to stderr, and there's a test asserting stdout stayed clean.
Writing the protocol by hand instead of importing the SDK was a deliberate choice: it's about 250 lines, and it means there's nothing in this repo I can't explain.
Tests
122 checks, run against a real spawned server process speaking actual JSON-RPC over stdio — nothing stubbed.
npm test # or: node tests/verify_server.jsCovers both handshakes, version rejection, every tool's behaviour and schema conformance, error handling for unknown tools and bad arguments, malformed-JSON resilience, the rule that notifications are never answered, stdout hygiene, determinism across processes, and cross-artifact agreement with the dashboard.
The schema validator is hand-written (~30 lines) so the test suite has no dependencies either.
Data
The first six permit cases are real corridors from the LA County Substructure Grid Map (County of Los Angeles Open Data), carried over verbatim from the dashboard. The other eighteen are synthetic, generated from a fixed seed so the portfolio is big enough for search and filtering to mean something.
Every case carries a dataSource field saying which it is. An agent answering questions about
this data should never have to guess whether a record is real — and neither should anyone
watching a demo.
Per the county's own disclaimer, it makes no warranty as to the accuracy, timeliness, or completeness of the data, and recommends utility research be conducted under the supervision of a licensed civil engineer. That disclaimer is why county-only records are graded Level D by default.
Known limitations
No spatial geometry. Distances are precomputed scalars, not a real GIS layer. A production version sits on PostGIS and takes a bore path, not a permit ID.
Read-only by design, so there's no write path to argue about yet. When there is, it should require explicit human confirmation rather than a tool annotation.
No auth. stdio means it runs as the local user with their file permissions. A hosted version needs real per-customer access control, since permit and utility data is commercially sensitive and sometimes security-sensitive.
Consequence weights are asserted, not derived. Gas at 10× and fiber at 1× is a judgment. In a real deployment those come from the customer's own liability exposure and would differ between a gas utility and a fiber contractor.
Available Tools
5 toolsfind_utility_conflictsFind hazardous unverified crossingsARead-onlyIdempotent
Scan the whole permit portfolio for individual utility lines that are dangerous to dig near: close to the excavation, poorly evidenced, or where the county record and the independent detection disagree. This is the cross-portfolio triage question — 'what is about to hurt someone' — rather than a per-permit lookup. Results are ranked by consequence-weighted risk.
Inputs: city, limit, max_quality, utility_types, +2 more. Returns: criteria, conflicts, matchCount, totalConsequenceExposure
get_permitGet full permit reviewARead-onlyIdempotent
Retrieve the complete review for one permit case: every utility line near the excavation, its owner, distance, ASCE 38-02 data quality grade, provenance, and crossing risk, plus the overall verdict and which lines need field verification before sign-off.
Inputs: permit_id (required). Returns: lines, permit, verificationRequired
portfolio_summarySummarise portfolio riskARead-onlyIdempotent
Roll up the whole permit portfolio: how many cases sit at each verdict, where the risk is concentrated by city and project type, overall record corroboration, and how much unverified consequence exposure is outstanding. Use this for 'how are we doing' questions rather than per-permit ones.
Inputs: group_by. Returns: totals, breakdown, byVerdict, totalPermits
recommend_verificationRecommend field verification planARead-onlyIdempotent
Produce a prioritised potholing plan: which specific lines should be physically exposed before excavation, in what order, and why. Ranks by consequence-weighted risk so a limited field budget is spent where a strike would cost the most. Call with a permit_id for one case, or with no arguments for a portfolio-wide plan.
Inputs: max_items, permit_id. Returns: scope, planItems, candidateCount, exposureAddressed, +1 more
search_permitsSearch permit casesARead-onlyIdempotent
Search and filter pending excavation permit cases. Use this to find permits by street, city, applicant, project type, permit verdict, or risk level. Returns a summary of each match, not the full utility line detail — call get_permit for that.
Inputs: city, limit, query, verdict, +4 more. Returns: permits, matchCount, totalPermits, filtersApplied
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 5 tools
Each tool addresses a distinct question: per-permit search and retrieval, cross-portfolio risk triage, portfolio-wide summary, and prioritized verification planning. Even search_permits and find_utility_conflicts are clearly separated by intent (query-based vs risk-based scanning).
Four of five tools use a clear verb_noun pattern (search_permits, get_permit, find_utility_conflicts, recommend_verification), but portfolio_summary breaks the pattern by using a noun_noun structure instead of something like summarize_portfolio. This is a minor deviation.
Five tools is ideal for this domain. Each tool has a unique role and the count is not excessive or sparse; the server is well-scoped to the permit review workflow.
The tool surface covers the full read/analysis lifecycle: search (search_permits), detail (get_permit), cross-cutting risk (find_utility_conflicts), roll-up (portfolio_summary), and actionable recommendation (recommend_verification). There are no obvious dead ends or missing operations for the stated purpose.
Related MCP Connectors
Read-only Google Ads, GA4 and Search Console data for Claude, with no Google Cloud setup.
Query your org's data in natural language — read-only MCP access to SQL, NoSQL, files & warehouses.
Read-only access to Cogram projects, meetings, email, RFIs and drawings for architects and engineers
Query 40 databases from Claude, ChatGPT, or Cursor — on any device. Read-only, encrypted, audited.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceEnables read-only, natural-language querying of a MySQL permit database, allowing users to ask plain-English questions and receive SQL-backed explanations via Claude Code CLI.-
- AlicenseAqualityCmaintenanceProvides Claude Code read-only access to PostgreSQL for relational queries, schema inspection, EXPLAIN plans, pgvector similarity searches, and Apache AGE graph traversals.6Apache 2.0
- FlicenseAqualityBmaintenanceEnables construction permitting teams to analyze portfolios of active permits by ranking risk, detecting day-over-day changes, identifying systemic bottlenecks, and generating daily executive action plans. Also supports single-permit readiness audits, missing-document reports, blocker explanations, resubmission checklists, and semantic search over municipal requirements.71-
- AlicenseNot gradedqualityCmaintenanceEnables read-only access to geotechnical investigation project databases and official standard data interface files from AI workflows, supporting project summaries, borehole lists, arbitrary table queries, and interface file generation, parsing and validation. It also recognizes Excel result tables such as exploration point schedules and dynamic penetration test statistics, converting them into normalized records.1MIT