The Roofing List: MCP server

A public, read-only MCP server for The Roofing List. AI assistants use it to find checked US roofers, siding and gutter contractors by city.

• Endpoint: https://mcp.theroofinglist.com/mcp (Streamable HTTP). No login, no API key.

• About page: https://theroofinglist.com/mcp/

Use it

Claude Code:

claude mcp add --transport http the-roofing-list https://mcp.theroofinglist.com/mcp

Claude Desktop: add this to claude_desktop_config.json. It uses mcp-remote, because the config file starts local servers only. Or add the URL as a custom connector in Settings > Connectors.

{
  "mcpServers": {
    "the-roofing-list": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.theroofinglist.com/mcp"]
    }
  }
}

Any other MCP client: connect to https://mcp.theroofinglist.com/mcp with Streamable HTTP.

Connect from any agent: .mcp.json at the root of this repo holds the server entry. Claude Code reads it when you open this repo. For any other client, copy the entry into that client's MCP config.

The data rules

• Only listed, open firms leave this server. Closed or unlisted rows are dropped, even when the data source sends them.

• No paid boost. This server has no ranking code. It keeps the order the directory sends and cuts it to limit.

• Ratings come from reviews published on The Roofing List only. No Google rating or review data: the contract has no such field, and an allowlist drops any extra field.

• A free profile never carries a website.

The rules live in src/present.ts. The tests in test/tools.test.ts prove them against a deliberately leaky stub.

Related MCP server: AgentRank MCP

How it works

• Worker name: theroofinglist-mcp

• Endpoint: POST /mcp (Streamable HTTP). No login. GET / sends a 301 to https://theroofinglist.com/mcp/.

• Stateless: createMcpHandler from agents/mcp/server builds a new McpServer for each request. No Durable Objects. Cloudflare marks McpAgent as the older path for new stateless servers.

• Protocol: the MCP SDK v2 serves the 2026-07-28 spec. It also answers 2025-era clients through its stateless fallback.

REST API

The same Worker also serves a small REST API, for RapidAPI and for people who do not use MCP. It is read-only, free and needs no key. It calls the same lookups as the MCP tools (src/lookup.ts), so both return the same records.

curl 'https://mcp.theroofinglist.com/v1/contractors?trade=roofing&city=Austin&state=TX&limit=5'
curl 'https://mcp.theroofinglist.com/v1/contractors/101'

• Errors are { "error": "..." }: 400 bad input (same messages as the tools), 404, 405 for any method but GET, 429 over the rate limit (with Retry-After: 60), 503 when the web Worker fails.

• Every response has access-control-allow-origin: *. OPTIONS answers the CORS preflight.

• Cache: public, max-age=300 on 200, 400, 404 and 405. no-store on 429 and 503, so no cache keeps a short-lived error. /openapi.json caches for 1 hour.

• openapi.json is the one source for the document. src/openapi.ts imports it. When you raise SERVER_VERSION, raise info.version too; a test checks that they match.

RapidAPI and the rate limit

All RapidAPI calls come from RapidAPI's servers. A per-IP limit would count all RapidAPI users as one caller. So:

• Set the proxy secret from the RapidAPI provider dashboard as a Worker secret: pnpm exec wrangler secret put RAPIDAPI_PROXY_SECRET. It is optional. Locally, leave it empty in .dev.vars.

• When a request carries that secret in x-rapidapi-proxy-secret, the key is rapidapi:<x-rapidapi-user>. Without the user header, the key falls back to the IP.

• A missing or wrong secret means the key is the IP. A caller cannot pick a key by sending a fake x-rapidapi-user. The compare is constant-time.

• REST and MCP keep separate budgets on the same binding: keys start with rest: or mcp:. Each gets 60 calls a minute. /openapi.json and OPTIONS do not count.

Tools

Contractor: id, name, trades, city, state, phone, profileUrl, claimed, website (claimed only), rating ({ value, count }, published reviews on our site only; absent when there are none).

See "The data rules" above for what may leave this Worker.

Run it locally

You need Node 22+ (Wrangler 4) and pnpm. You do not need a Cloudflare login.

pnpm install
pnpm dev          # MCP Worker on :8787 plus the stub web Worker
pnpm smoke        # in a second shell: official MCP client lists and calls both tools
pnpm smoke --burst  # also checks the rate limit (uses up this minute's budget)
pnpm test
pnpm typecheck

pnpm dev copies .dev.vars.example to .dev.vars the first time. Both hold a fake local token.

Against the real web app

The real data route lives in the private web app (theroofinglist-web). src/contract.ts describes it, and stub/ copies its shape with fake rows. If you have the web app, run it on port 8790 and point this Worker at it over the WEB service binding:

pnpm exec wrangler dev -c wrangler.jsonc --local --port 8792
MCP_URL=http://localhost:8792/mcp pnpm smoke

Both Workers must hold the same INTERNAL_API_TOKEN in .dev.vars.

pnpm smoke takes its ids from a search for roofers in Austin, Texas, so it runs on the stub and on real data. SMOKE_CITY and SMOKE_STATE change the search. SMOKE_CLOSED_ID names an id that must not come back: SMOKE_CLOSED_ID=103 pnpm smoke checks the stub's closed row.

Inspector: npx @modelcontextprotocol/inspector and connect to http://localhost:8787/mcp with Streamable HTTP.

How it reads data

The MCP Worker calls theroofinglist-web over a service binding (WEB). The web Worker reads through Payload, the same as the public pages. In local dev, stub/ runs under the name theroofinglist-web and serves fake rows. The stub is loose on purpose: it sends closed rows, a free website and Google fields, so the tests prove this Worker filters them.

The internal route

The private web app serves this route. src/contract.ts defines it. The path sits outside /api, so Payload's /api/[...slug] catch-all does not take it.

GET /internal/mcp/contractors?trade=<slug>&state=<USPS>&city=<city-slug>&limit=<1..25>
  200 { "contractors": Contractor[] }

GET /internal/mcp/contractors/<id>
  200 { "contractor": Contractor }
  404 { "error": "not_found" }      // also for closed or unlisted

Header on every request: x-internal-token: <INTERNAL_API_TOKEN>
  401 { "error": "unauthorized" }   // missing or wrong token

Contractor = {
  id: number,                      // Businesses.id
  name: string,
  trades: string[],                // Trades slugs, TRADE_PATHS order
  city: string,                    // city name, e.g. "Austin"
  state: string,                   // USPS code, e.g. "TX"
  phone: string | null,            // E.164
  tier: "free" | "claimed",
  website: string | null,          // as stored; the MCP Worker drops it for free
  status: "active" | "closed",
  listed: boolean,
  path: string,                    // profilePath(), e.g. "/roofers/texas/austin/lone-star-roofing"
  rating: { value: number, count: number } | null   // getRatings(): published reviews only
}

Rate limit

RATE_LIMITER is a Workers rate limiting binding: 60 requests per IP per 60 seconds, keyed on cf-connecting-ip. Over the limit, /mcp returns 429 with Retry-After: 60 and a JSON-RPC error. For RapidAPI traffic the key is the RapidAPI user; see "RapidAPI and the rate limit" above. The binding counts per Cloudflare location and is eventually consistent, so it stops abuse, not exact overuse.

Production

Live at https://mcp.theroofinglist.com/mcp (custom domain) since 4 Oct 2026. Deploy with pnpm exec wrangler deploy.

• INTERNAL_API_TOKEN is a secret on both Workers, with the same value. To rotate it, put a new value on both.

• ALLOWED_HOSTNAMES in wrangler.jsonc lists the custom domain, the workers.dev name and the local names.

• Deploy theroofinglist-web first when the contract changes. Never deploy stub/.

• Smoke test: MCP_URL=https://mcp.theroofinglist.com/mcp pnpm smoke.

• The web app serves the route at /internal/mcp/contractors/ (with a slash). A call without the slash gets a 308, which the service binding follows. One extra hop; it works.

Official MCP registry

Listed as io.github.redpath1/the-roofing-list since 5 Oct 2026. server.json in this folder is the entry. Check it:

curl -s 'https://registry.modelcontextprotocol.io/v0.1/servers?search=redpath1'

The name uses the GitHub namespace. The domain namespace (com.theroofinglist/...) needs a TXT record on the apex or a /.well-known/mcp-registry-auth file on theroofinglist.com. The Wrangler login cannot edit DNS, and the file means a web deploy, so we chose GitHub. server.json names this repository in its repository field from version 0.1.1. The registry shows that field only after 0.1.1 is published (see below). Publish it after the repository is public.

Publish a new version

The registry keeps every version for good. You cannot change or reuse a version string.

1. Install the CLI: brew install mcp-publisher (1.8.1 or later).

2. In server.json, raise version (semver, e.g. 0.1.1). Keep it the same as SERVER_VERSION in src/server.ts.

3. Check it: mcp-publisher validate server.json.

4. Log in as redpath1, who owns the namespace. Run mcp-publisher login github and enter the device code. Or reuse the gh login, without showing the token: gh auth token | xargs -I{} mcp-publisher login github --token={}.

5. Publish: mcp-publisher publish server.json.

6. Run the curl above. The new version shows "isLatest": true.

The directory page on theroofinglist.com already marks this server as in the official registry. A new version does not change that.

Public repository

https://github.com/redpath1/the-roofing-list-mcp is the published copy of the mcp/ folder in the private monorepo of The Roofing List. Develop in the monorepo. The public repo has its own short history, so do not use git subtree push: that would push the monorepo's commit history, with its author emails, to the public repo. After a change to mcp/ merges to main, copy the files instead:

git clone https://github.com/redpath1/the-roofing-list-mcp /tmp/trl-mcp
rsync -a --delete --exclude .git --exclude node_modules --exclude .wrangler --exclude .dev.vars mcp/ /tmp/trl-mcp/
cd /tmp/trl-mcp && git add -A && git commit -m "<what changed>" && git push

Commit as Keith Evans <272994924+redpath1@users.noreply.github.com>. No personal email goes into the public history.

Contributing

Issues are open. We review pull requests when there is time. We make no roadmap promises.

License

MIT. See LICENSE.