Skip to main content
Glama
Underground Utility Permit Review MCP Server

Underground Utility Permit Review MCP Server

by erincheong

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.json

  • Windows %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

search_permits

Which cases match this filter?

get_permit

What's the full review for this one case?

find_utility_conflicts

Across everything, what's dangerous to dig near?

portfolio_summary

How are we doing overall, and where is risk concentrated?

recommend_verification

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.

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+ft

That 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 (2026-07-28)

server/discover → tools/call with _meta on every request

Legacy (2025-11-25, 2025-06-18)

initialize → notifications/initialized → tools/call

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.js

Covers 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 tools
find_utility_conflictsFind hazardous unverified crossingsA
Read-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 reviewA
Read-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 riskA
Read-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 planA
Read-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 casesA
Read-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

    A4.4/5.0

    Scored across 5 tools

    Disambiguation5/5

    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).

    Naming Consistency4/5

    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.

    Tool Count5/5

    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.

    Completeness5/5

    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

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables 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.
      -
    • A
      license
      A
      quality
      C
      maintenance
      Provides Claude Code read-only access to PostgreSQL for relational queries, schema inspection, EXPLAIN plans, pgvector similarity searches, and Apache AGE graph traversals.
      6
      Apache 2.0
    • F
      license
      A
      quality
      B
      maintenance
      Enables 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.
      7
      1
      -
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables 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.
      1
      MIT