# YardPermit MCP server

US backyard permits and material takeoffs inside Claude, ChatGPT, Cursor and VS Code. Ask whether a fence, deck, shed or pool needs a permit in your city, what the city charges, and how many posts or bags of concrete the job takes. The answers come from YardPermit's cited rules and formulas.

**Endpoint:** `https://mcp.yardpermit.com/mcp` (Streamable HTTP, no sign-in)

## Add it in 30 seconds

- **claude.ai:** Settings → Connectors → Add custom connector → paste the endpoint.
- **Claude Code:**
  ```bash
  claude mcp add --transport http yardpermit https://mcp.yardpermit.com/mcp
  ```
- **Cursor** (`.cursor/mcp.json`):
  ```json
  { "mcpServers": { "yardpermit": { "url": "https://mcp.yardpermit.com/mcp" } } }
  ```
- **VS Code** (`.vscode/mcp.json`):
  ```json
  { "servers": { "yardpermit": { "type": "http", "url": "https://mcp.yardpermit.com/mcp" } } }
  ```
- **ChatGPT:** turn on Developer mode (Settings → Security and login), then add a developer-mode app with the endpoint and "No authentication".

Then ask, for example:

> I'm putting up an 80 ft long, 6 ft high wood fence in Austin, Texas. Do I need a permit, and how many 80-lb bags of concrete will the posts take?

The server checks the fence against Austin's rules: no permit up to 7 ft, 6 ft along a street, and a permit for any fence in a floodplain. It quotes the city's small-project review fee in case a permit is needed, and works out 11 posts and 20 bags of concrete.

## Tools

| Tool | What it does |
|---|---|
| `check_permit` | Whether a fence, deck, shed, patio, driveway, pergola, retaining wall, pool, gazebo, garage or ADU needs a building permit under the model code (IRC 2024) or in Austin, Los Angeles, Houston, San Diego or Phoenix. Returns the city's fees and the code lines it rests on. |
| `estimate_fence_materials` | Posts, rails, post-hole size and 80-lb concrete bags for a straight fence |
| `estimate_deck_materials` | Joists, rows and lineal feet of decking, and beam length for a rectangular deck |
| `estimate_material` | Concrete bags, gravel tons, sand, topsoil or mulch for an area, or pavers with their base and bedding sand |
| `trade_wages` | BLS hourly wages of fence erectors, carpenters, cement masons and construction laborers, for the US or one state |

All five tools are read-only and say so in their annotations.

## Design

- **Rules, not guesses.** For the model code, Austin and Los Angeles, a rule engine checks the project's own measurements, and every finding names and links the code line behind it. Houston, San Diego and Phoenix answer with the city's own text. Where the code leaves a fact open, the answer says it depends and who decides. No answer is presented as a permit decision.
- **Answers a model can refine.** Each check lists the answers it used, with their ids and allowed values. A model can re-run the check with the user's real numbers, for example `{"height": 8}`.
- **No estimated prices.** Quantities come from formulas, fees from the cities' published schedules and wages from BLS. Nothing is priced without a source.
- **Small context cost.** The whole `tools/list` response for the five tools is about 5 KB, roughly 1,300 tokens.
- **Forgiving input.** It accepts city names like "Austin, TX" or "LA", plural project names, and booleans for yes/no answers. An answer it cannot use is named in the result, not silently dropped.

## How it's built

- **Stack:** TypeScript, the official MCP TypeScript SDK v2 and Cloudflare's Agents SDK (`createMcpHandler`). It runs as a stateless Streamable HTTP server on Cloudflare Workers.
- **Protection:** Workers Rate Limiting at 60 requests a minute per IP address, and Host/Origin allowlists.
- **Where the data lives:** The rule engine, formulas and data are imported at build time from the YardPermit codebase in a sibling folder. This repository holds the MCP layer, its tests and the eval. To try the server, use the public endpoint.

## Tests and checks

- **15 unit tests** (Vitest), pinned to the same figures as the site's own tests. For example, an 80 ft, 6 ft fence takes 11 posts and 20 bags of concrete.
- **MCP Inspector** (`tools/list`, `tools/call`) against the live endpoint.
- **Official MCP conformance scenarios:** `server-initialize`, `ping` and `tools-list` pass.
- **Eval:** `eval/run.mjs` sends 10 realistic questions through Claude Code with only this server connected. It checks that the model called the right tools and quoted the figures they return.
  - Results of the first run (4 Oct 2026, Claude Sonnet 5.5): **10/10 passed**, right tools 10/10.
  - Full table: [`eval/REPORT.md`](eval/REPORT.md).

## Data and sources

- **Permit rules and fees:** YardPermit's research, which cites the code section or city page behind each figure and the date it was checked. That covers IRC 2024 (ICC), Austin Development Services, the Los Angeles Municipal Code and LADBS, and the Houston, San Diego and Phoenix codes and fee schedules. This is not legal advice; the building department decides.
- **Formulas:** YardPermit's calculators, after Quikrete, the Tennessee DOT, the FHWA and the Concrete Masonry & Hardscapes Association. Each answer cites its source.
- **Wages:** U.S. Bureau of Labor Statistics, OEWS May 2025 and ECEC June 2026 (public domain).

## Need this for your API?

I build tested MCP servers like this one for other companies' APIs: up to 8 tools in 5 business days for a fixed price, with an eval report. See the **MCP Server Sprint** on [Upwork](https://www.upwork.com/freelancers/~01800cc6ed7fb14088).

## Licence

The code in this repository is MIT licensed. The data keeps the terms of its sources.