The Septic Guide MCP server
# The Septic Guide MCP server
Read-only [Model Context Protocol](https://modelcontextprotocol.io) server for [thesepticguide.com](https://thesepticguide.com/), a U.S. septic contractor directory built from published state license and certification records.
No API key. No writes. Every result carries a `source_url` on thesepticguide.com.
## Tools
| Tool | What it returns |
|---|---|
| `list_states` | States with a licensing page and/or company directory, with links |
| `get_state_licensing` | `state` (name or code): the agency that licenses septic work, its official lookup URL, page date, and the page's licensing Q&A |
| `search_septic_companies` | `state` plus optional `city`, `county`, `zip`, `service`, `licensed_only`, `limit`: listings with license number(s), agency verify link, phone, website, profile link |
| `get_cost_guide` | optional `topic` (e.g. `pumping`, `drain field`): short answer, cost tables, and the third-party sources the page cites. No topic = list topics |
## Data
By default the server answers from a **bundled snapshot** in `data/` (`data/snapshot.json` for the index, licensing and cost pages, plus one gzipped file per state in `data/companies/`). Every response includes `data_mode` and `data_as_of` (the snapshot date). Rebuild it with:
```bash
npm run snapshot # crawls thesepticguide.com (sitemap, state + county pages) and rewrites data/
```
Set `TSG_LIVE=1` to skip the snapshot and read thesepticguide.com live instead (6-hour in-memory cache). Live mode is also used automatically if `data/` is missing.
### Company counts
Each state page's meta description gives a headline number (e.g. Texas: "363 septic companies"). In some states the listings actually rendered on the state page plus its county pages come to fewer (Texas: 360). The server never pads results: `search_septic_companies` reports `listed_on_pages` (rendered listings it searched) and `state_page_headline_count` (the page's own number), with a `count_note` when they differ. Same-name listings with different services or license records are distinct state-list records and are kept.
## Data & limits
- Read-only. No writes, no API key, no user data collected.
- Public data from thesepticguide.com. Every result carries a `source_url` on thesepticguide.com.
- License data comes from published state agency license and certification lists, as matched by thesepticguide.com. Confirm any license with the agency `verify_url` before hiring.
- Not affiliated with any state agency.
- Snapshot data can lag the live site; check `data_as_of`.
## Use
Remote (Streamable HTTP): `https://mcp.thesepticguide.com/mcp`
Local (stdio):
```bash
git clone https://github.com/archer-clawbot/thesepticguide-mcp && cd thesepticguide-mcp && npm install && npm run build
```
```json
{ "mcpServers": { "thesepticguide": { "command": "node", "args": ["/path/to/thesepticguide-mcp/dist/stdio.js"] } } }
```
Docker: `docker build -t thesepticguide-mcp . && docker run -i --rm thesepticguide-mcp`
Develop:
```bash
npm install && npm run build
npm test # stdio smoke test with the MCP SDK client
npm test -- http # same against MCP_URL (default http://localhost:3000/mcp)
npm run start:http # http://localhost:3000/mcp
```
Deploy on Vercel: `api/mcp.ts` + `vercel.json` (rewrites `/mcp` to the function).
<!-- mcp-name: com.thesepticguide/thesepticguide -->
## License
MIT. Copyright (c) 2026 Catalyst Digital Services LLC.
TDQS
Scored across 4 tools
Each tool targets a clearly distinct resource: state index, state licensing details, company search, and cost guidance. Although licensing appears in both state licensing and company search results, the primary purposes are unambiguous.
All tool names use a consistent snake_case verb_noun pattern: list_states, get_state_licensing, search_septic_companies, get_cost_guide. The verbs accurately reflect the operations.
Four tools are well scoped for a focused septic-guide lookup server, and each covers a distinct content area. There is no unnecessary duplication or bloat.
The surface covers state discovery, licensing, company search, and cost guidance, which are the core needs of this domain. Minor gaps exist around retrieving individual company details or broader non-cost/non-licensing guide content.