CREHQ MCP Server

A Model Context Protocol server that turns CREHQ's live location-intelligence REST API into native tools for Claude and other AI agents. Ask an agent "where should Chipotle open next?", "which hotel chain is this venue affiliated with?", "who has ever occupied this address?", or "what are Aspen Dental's credit signals?" — and it can actually answer, backed by CREHQ's canonical, multi-source government-verified database of franchise & multi-unit brands, individual storefronts, FDD financials, credit signals, and site-level tenancy history.

This is a thin wrapper over CREHQ's existing production API (https://crehq.com/wp-json/crehq/v1). It does not store data or modify anything server-side — it authenticates with your API key and forwards calls.

---

What it exposes (33 tools)

Upgrade / paywall routing

• crehq_request_upgrade — use when a sandbox user asks for premium data such as credit signals, FDD/Item 19, site-selection criteria, real-estate requirements, contacts, source provenance, change history, bulk downloads, whitespace, co-tenancy, or site timeline. With a free sandbox key, this records upgrade intent in CREHQ and returns the user a clear upgrade path instead of saying the data does not exist.
• crehq_intelligence_preview — for Pro self-serve keys, spends the one monthly controlled intelligence preview credit and returns a bounded evidence frame without exposing raw premium tables or redistribution rights.

Entity affiliation

• crehq_resolve_entity_affiliation — resolve a venue URL, name, or address to an evidence-backed affiliation status, canonical brand, operator, and parent company across hotels, restaurants, retail, healthcare, banks, auto dealers, EV charging, and other location categories. Valid outcomes include branded, independent, not a commercial venue, and unresolved. A paid-access response preserves its exact checkout URL and CREHQ intent id. Checkout emails a new Pro key that must be installed before retrying; the current credential is not upgraded in place.

Companies / brands

• crehq_companies_list — list brands, filter by category & expansion status
• crehq_companies_search — resolve a brand name → CREHQ company id (start here)
• crehq_company_get — canonical brand profile, verified unit count, ownership
• crehq_company_credit_signals — credit profile, sponsor/issuer context, ratings, capital structure
• crehq_company_franchise — FDD fees, royalties, investment, Item 19 figures
• crehq_company_real_estate — site-selection criteria & target geographies
• crehq_company_contacts — real-estate / development decision-maker contacts

Locations

• crehq_locations_list — store records by brand / state / category
• crehq_location_get — one location with full attributes & verification trace
• crehq_locations_search — fuzzy multi-field location search
• crehq_locations_nearby — radius search around a lat/lng (trade-area mapping)
• crehq_locations_bulk — bulk pull by id list, brand list, or GeoJSON polygon
• crehq_locations_events — cross-brand open/close/relocate lifecycle stream
• crehq_location_history — full event log for one physical store

History & flagship differentiators

• crehq_company_changes — date-bounded change feed for one brand
• crehq_company_occupancy — point-in-time roster (footprint on a past date)
• crehq_site_timeline — every brand that ever occupied an address, over time

Premium intelligence (Intel & Enterprise tiers)

• crehq_whitespace — markets where competitors are present but the brand isn't
• crehq_co_tenancy — which brands cluster near this brand's stores
• crehq_location_site_profile — CREHQ Modeled Site Profile for one location
• crehq_company_site_pattern — empirical brand site pattern from observed footprint/context
• crehq_recent_location_context — recent observed/opening rows with traffic, demographics, and coverage flags

Modeled Site Profile outputs must be described as CREHQ-modeled from observed location/context data, not as company-stated site requirements unless the response includes explicit stated-requirement provenance.

The Modeled Site Profile REST routes are staged pending explicit production approval. Until those routes are published, these three tools may return a 404 even though the MCP catalog advertises them for local testing.

Datasets

• crehq_datasets_list / crehq_dataset_get / crehq_dataset_download / crehq_dataset_categories
• crehq_purchased_datasets_list — list dataset snapshots purchased by the connected key owner, including snapshot date and hosted MCP access status.
• crehq_purchased_dataset_locations — query rows from a buyer-owned point-in-time dataset snapshot during the hosted access window.

Trends

• crehq_trends_company — outlet/fee/financial time series for a brand
• crehq_trends_geographic — metro/state concentration & velocity

---

Getting an API key

1. Free sandbox (1,000 calls/mo, 2 req/s, no credit card): https://crehq.com/developers/sandbox/ — enter your email, complete the browser verification challenge, and a key is emailed to you. The key is delivered by email only and looks like crehq_live_xxxxxxxx…. Sandbox keys can run bounded location lookups (crehq_locations_list by brand, and crehq_locations_nearby by radius) and call the entity-affiliation resolver once per month. If the user asks for premium intelligence, call crehq_request_upgrade; it records the requested topic for CREHQ follow-up and tells the user what to upgrade.
2. Pro MCP — $99/mo, self-serve Stripe checkout. Includes bounded D1 location queries, selected D2 provenance fields, 25,000 core calls/month, up to 250 affiliation resolver calls/month, and one controlled intelligence preview per month. Start at https://crehq.com/developers/sandbox/#pro-checkout.
3. Datasets / Intelligence / Enterprise — buy licensed point-in-time dataset snapshots when you need the file; use enterprise licensing for premium intelligence, refresh plans, API/feed delivery, redistribution, embedded rights, and SLAs. See https://crehq.com/pricing/.

---

Fastest way to try CREHQ in an agent

1. Get a sandbox key at https://crehq.com/developers/sandbox/.
2. For hosted/remote MCP clients, add https://mcp.crehq.com/mcp and authorize with that key.
3. For local stdio clients, install with npx -y crehq-mcp-server and set CREHQ_API_KEY.
4. Ask: Use CREHQ to identify the brand, operator, and parent affiliation of the venue at https://www.earleycrescent.org/.

Self-serve keys expose the affiliation resolver, bounded location lookups, upgrade routing, purchased-dataset access, and the controlled intelligence preview. The backend still enforces the key's actual Free, Pro, and purchased dataset entitlements, returning a structured upgrade or purchase response when needed. Intel and Enterprise keys expose broader API tools according to the key's CREHQ tier.

---

Install & build

Requires Node.js ≥ 18.

Install the published stdio server with npx:

CREHQ_API_KEY=crehq_live_xxxxx npx crehq-mcp-server

Or build from source:

git clone <this-repo> crehq-mcp-server
cd crehq-mcp-server
npm install
npm run build          # compiles TypeScript → dist/
cp .env.example .env    # then edit .env and set CREHQ_API_KEY

Verify your key against the live API before wiring up a client:

export CREHQ_API_KEY=crehq_live_xxxxx
./test.sh               # exercises 6 read endpoints with curl

Run the server standalone (it speaks MCP over stdio, so it will wait for a client on stdin — Ctrl-C to exit):

CREHQ_API_KEY=crehq_live_xxxxx node dist/index.js

---

Connect to Claude Desktop

Add this to your claude_desktop_config.json:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "crehq": {
      "command": "npx",
      "args": ["-y", "crehq-mcp-server"],
      "env": {
        "CREHQ_API_KEY": "crehq_live_your_key_here"
      }
    }
  }
}

Restart Claude Desktop. The CREHQ tools appear under the tools (🔌) menu.

Other MCP clients

Any stdio-capable MCP client (Claude Code, Cursor, Cline, Continue, the mcp CLI, custom @modelcontextprotocol/sdk clients, etc.) connects the same way — run node dist/index.js as the server command with CREHQ_API_KEY in the environment.

Claude Code:

claude mcp add crehq --env CREHQ_API_KEY=crehq_live_xxxxx -- npx crehq-mcp-server

Hosted remote connector

The hosted Cloudflare Worker version is kept in remote/. It provides the same CREHQ connector as a remote MCP server at https://mcp.crehq.com/mcp, with OAuth/key exchange and scope gating for premium tools. Its own deploy notes are in remote/DEPLOY.md and connector-submission copy is in remote/CONNECTOR-SUBMISSION.md.

The MCP Registry metadata lives in server.json, with registry ownership declared by mcpName in package.json.

Maintainer workflow

GitHub Actions owns the repeatable release path:

• CI builds and tests the stdio package and the hosted Worker on every push.
• Deploy Remote MCP deploys remote/ changes to Cloudflare Workers and then verifies https://mcp.crehq.com/health.
• Publish npm publishes the stdio package from a vX.Y.Z tag or manual workflow dispatch. It skips safely when that package version already exists.

Required repository secrets are already named:

• NPM_TOKEN
• CLOUDFLARE_API_TOKEN
• CLOUDFLARE_ACCOUNT_ID

---

Configuration

Env var	Required	Default	Purpose
CREHQ_API_KEY	yes	—	Your crehq_live_… key
CREHQ_API_BASE	no	https://crehq.com/wp-json/crehq/v1	Override API base (staging/proxy)
CREHQ_TIMEOUT_MS	no	30000	Per-request timeout in ms
CREHQ_API_SURFACE	no	auto	Auto-detect sandbox vs full key; can be selfserve or full for debugging

---

Error handling

Tools never crash the agent's turn — failures come back as a readable message with a fix-it hint:

• No key set → instructs you to set CREHQ_API_KEY and links the sandbox.
• 401 / 403 → "invalid or revoked key / endpoint not in your tier" + upgrade link. For credit signals, FDD, site-selection criteria, contacts, provenance, change history, bulk data, whitespace, co-tenancy, or site timeline, call crehq_request_upgrade.
• 404 → "check the id/slug; resolve it with a search tool first."
• 429 → respects Retry-After; reminds you of the free-tier 2 req/s limit.
• 5xx / timeout / network → transient-error guidance to retry with backoff.

Pagination, cache, and stream cursors (X-WP-Total, X-CREHQ-Next-Since, X-CREHQ-Cache, rate-limit headers) are surfaced in a response metadata footer on each result so the agent can paginate and poll correctly.

---

Note on testing

The build, typecheck, MCP protocol handshake, tool catalog, argument validation, and the full HTTP request/response/error pipeline are verified end-to-end against the live production API (a real request returns a real 403 Invalid or revoked API key with the correct hint). Fetching real data rows requires a valid key — the sandbox key is delivered by email, so set CREHQ_API_KEY and run ./test.sh to confirm live data responses.

---

License

MIT. CREHQ data is licensed separately per your API tier/contract.