> ## Documentation Index
> Fetch the complete documentation index at: https://api-docs.hrizn.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Hrizn MCP
> Connect Cursor, Claude, and other MCP clients to live dealership data via the hosted Hrizn MCP server
The **Hrizn MCP** is a hosted [Model Context Protocol](https://modelcontextprotocol.io) server that gives AI agents **live, site-scoped dealership data** through your Public API key.
**Hrizn MCP ≠ Mintlify docs MCP.** Mintlify’s free docs MCP helps agents *read API documentation*. Hrizn MCP lets agents *call tools against this dealership’s live data* (inventory, dealer DNA, citable content).
## Endpoint
```
https://api.app.hrizn.io/v1/public/mcp
```
Transport: **Streamable HTTP** in **stateless JSON** mode. Authenticate every request with your dealership `hzk_` key.
| Header | Value |
| --------------- | ------------------------------ |
| `X-API-Key` | `hzk_…` (preferred) |
| `Authorization` | `Bearer hzk_…` (also accepted) |
| `Content-Type` | `application/json` |
## Required scopes
Create a key in Dealership Manager → **API & MCP** with the **MCP (Read)** preset for read tools, **MCP (Read + Create)** for content generation, or grant:
| Scope | Why |
| --------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `site:read` | Dealer profile, DNA, brand voices, staff, marketing, CTA links |
| `inventory:read` | Vehicle search, VIN lookup, stats, lot health |
| `content:read` | Content library and published citation URLs |
| `ideaclouds:read` | IdeaCloud topics and questions |
| `content_intelligence:read` | Content opportunity recommendations |
| `social:read` | Connected accounts, posts, and reviews |
| `content:write` | Create model landings / comparisons / sales events / IdeaCloud articles + YMMT cascade lists (**MCP (Read + Create)**) |
| `ideaclouds:write` | Create IdeaClouds, suggestions consume, selection basket, draft settings (**MCP (Read + Create)**) |
| `compliance:write` | Freeform `check_compliance` / `apply_compliance_fixes` plus article `trigger_content_compliance` (**MCP (Read + Create)**) |
For **OEM Compliance Checking** on pasted copy or Hrizn articles, grant `compliance:write` (included in **MCP (Read + Create)**). Freeform checks also require the dealership’s **Compliance Checking** plan feature (Pro+ / add-on). Lead with HIGH severity issues and `suggested_replacement`, apply selected fixes, then re-check. Automotive heuristics only — not legal advice.
For **Hrizn Market Maker** tools (local listings, days supply, competitive set, pricing, VIN appraisal helpers), also grant `market_data:read` — use the **MCP (Read + Market)** preset. Those tools require an **Unlimited** plan (or an explicit Unlimited feature override). Without Unlimited, Market Maker tools return a clear upgrade error and never call the live data provider.
Market segment tools use `vehicle_type` (`new`, `used`, or `certified`).
For **Hrizn Social Hub** post and review-reply tools, grant `social:write` and `reviews:write` — use the **MCP (Read + Social)** preset. Those tools require an **Unlimited** plan (or an explicit Unlimited feature override) when called from MCP. REST **Social Management** keys for direct Public API use are unchanged. If a network is missing or needs reconnect, tools return guidance to connect in **Dealership Manager → Social Profiles** (OAuth cannot run from MCP).
Keys are **site-scoped**. Rate limits inherit the dealership Public API limits. Market endpoints are vendor-costly — keep filters tight.
## Pagination
List tools (`find_vehicles`, `list_content`, `find_content_to_cite`, `get_content_opportunities`, `find_ideaclouds`, `list_social_posts`, `find_reviews`) return `has_more` and an opaque `next_cursor`. When `has_more` is true, call the same tool again with the same filters plus `cursor: `. Tool responses are compact JSON (not pretty-printed) to reduce token use.
## Write confirmation (dry\_run)
Mutation tools (social create/update/delete/unpublish/retry, `publish_review_reply`, content create, IdeaCloud `create_content`) require an explicit confirm gate:
1. Call with `dry_run: true` to validate and preview (no write).
2. Show the preview to the user and get approval.
3. Re-call with the same args plus `user_confirmed: true` and the returned `preview_token` to execute.
The signed token is short-lived and bound to the API key, tool, and exact payload. Changed, missing, expired, or forged tokens return an error and do not mutate.
## Wait helpers and social composites
Async generation and human media upload often need polling. Prefer the bounded wait tools over tight multi-turn loops:
* `wait_for_media_session` / `wait_for_content` / `wait_for_ideacloud` / `wait_for_content_compliance` / `wait_for_social_post` — default \~20s budget (hard max 24s). On `timed_out: true`, re-call with the same id to continue. For compliance status `not_checked`, call `trigger_content_compliance` first.
* Social posting: `prepare_social_post` (presence + optional upload session) → user uploads → `wait_for_media_session` → `finalize_social_post` with `dry_run`, then `user_confirmed` + `preview_token`.
## Discovery profiles
`tools/list` is automatically filtered to the scopes on the authenticated API key. You can further reduce tool-definition context by adding a profile to the MCP URL:
| Profile | URL suffix | Tools |
| -------- | ----------------- | -------------------------------------------------------------------------- |
| `read` | `?profile=read` | Core dealer, inventory, content, IdeaCloud, intelligence, and social reads |
| `create` | `?profile=create` | Read tools plus IdeaCloud, content, and compliance creation |
| `market` | `?profile=market` | Read tools plus Hrizn Market Maker |
| `social` | `?profile=social` | Read tools plus Social Hub posting and review replies |
| `full` | `?profile=full` | Every tool authorized by the key (default) |
A profile only narrows discovery; it never grants a missing scope. Plan-gated tools remain visible when their required scope is present so they can return upgrade guidance.
## Connect a client
Hrizn MCP speaks **remote Streamable HTTP**. Pick a client and paste the matching config — shapes differ (`url` / `httpUrl` / `serverUrl`, JSON vs Codex TOML). Dealership Manager → **API & MCP** has a logo picker for Cursor, Claude, **OpenAI Codex**, **Gemini CLI**, VS Code, Windsurf, **OpenCode**, Continue, Cline, Zed, JetBrains, and **Amazon Q / Kiro**.
### Cursor / Claude Code
`.cursor/mcp.json` (or Claude Code MCP settings):
```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
"mcpServers": {
"hrizn": {
"url": "https://api.app.hrizn.io/v1/public/mcp",
"headers": {
"X-API-Key": "${env:HRIZN_API_KEY}"
}
}
}
}
```
Set `HRIZN_API_KEY` to your `hzk_` key before launching the client.
### Claude Desktop
Settings → Developer → Edit Config (paste the key; Desktop often lacks env interpolation):
```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
"mcpServers": {
"hrizn": {
"url": "https://api.app.hrizn.io/v1/public/mcp",
"headers": {
"X-API-Key": "hzk_YOUR_KEY_HERE"
}
}
}
}
```
### OpenAI Codex (ChatGPT desktop / Codex IDE)
`~/.codex/config.toml` — Codex uses **TOML**, not JSON:
```toml theme={"theme":{"light":"github-light","dark":"github-dark"}}
[mcp_servers.hrizn]
url = "https://api.app.hrizn.io/v1/public/mcp"
[mcp_servers.hrizn.env_http_headers]
X-API-Key = "HRIZN_API_KEY"
```
Set `HRIZN_API_KEY` in the environment. Or use `http_headers` with a literal `hzk_` value for local testing.
### Gemini CLI
`~/.gemini/settings.json` — Streamable HTTP uses **`httpUrl`** (not `url`):
```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
"mcpServers": {
"hrizn": {
"httpUrl": "https://api.app.hrizn.io/v1/public/mcp",
"headers": {
"X-API-Key": "${env:HRIZN_API_KEY}"
}
}
}
}
```
### Windsurf
`~/.codeium/windsurf/mcp_config.json` — remote servers use `serverUrl`:
```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
"mcpServers": {
"hrizn": {
"serverUrl": "https://api.app.hrizn.io/v1/public/mcp",
"headers": {
"X-API-Key": "${env:HRIZN_API_KEY}"
}
}
}
}
```
### OpenCode
`opencode.json` (project) or `~/.config/opencode/opencode.json`:
```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"hrizn": {
"type": "remote",
"url": "https://api.app.hrizn.io/v1/public/mcp",
"enabled": true,
"oauth": false,
"headers": {
"X-API-Key": "{env:HRIZN_API_KEY}"
}
}
}
}
```
### VS Code / Copilot
`.vscode/mcp.json`:
```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
"servers": {
"hrizn": {
"type": "http",
"url": "https://api.app.hrizn.io/v1/public/mcp",
"headers": {
"X-API-Key": "${env:HRIZN_API_KEY}"
}
}
}
}
```
### Continue
`.continue/config.yaml` (streamable-http):
```yaml theme={"theme":{"light":"github-light","dark":"github-dark"}}
mcpServers:
- name: hrizn
type: streamable-http
url: https://api.app.hrizn.io/v1/public/mcp
requestOptions:
headers:
X-API-Key: ${{ secrets.HRIZN_API_KEY }}
```
### Cline / JetBrains AI
Same `mcpServers` + `url` + `headers` shape as Cursor (Cline: `cline_mcp_settings.json`; JetBrains: Settings → Tools → AI Assistant → MCP).
### Amazon Q / Kiro
MCP settings (`mcp.json`):
```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
"mcpServers": {
"hrizn": {
"type": "http",
"url": "https://api.app.hrizn.io/v1/public/mcp",
"headers": {
"X-API-Key": "hzk_YOUR_KEY_HERE"
}
}
}
}
```
### Zed
`settings.json` → `context_servers`:
```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
"context_servers": {
"hrizn": {
"url": "https://api.app.hrizn.io/v1/public/mcp",
"headers": {
"X-API-Key": "${env:HRIZN_API_KEY}"
}
}
}
}
```
## Tool catalog
| Tool | What it returns |
| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `get_dealer_context` | Compact site profile + dealer DNA + brand voice **metadata** + CTA links + **staff**, marketing, target geography, and categories. Check `truncated_sections` and `section_counts` when a section exceeds the response limits. |
| `find_vehicles` | Inventory search (max 50). Filters: make/model/year bands, New/Used, **age**, price/mileage, `color_family` / `exterior_color`, trim, certified, `has_description`, stock/VIN `q`, sort. Use `get_vehicle` for full `ai_description`. |
| `get_inventory_stats` | Coverage stats: totals, new/used, Hrizn AI description coverage % |
| `get_inventory_health` | Lot health: aging buckets (retail only), mix, heavy models, merchandising gaps. Never dealer cost. |
| `list_content` | Internal content catalog (generation status) |
| `get_content` | One article by id; optional truncated HTML (`include_html`) |
| `wait_for_content` | Bounded wait for article generation to reach a terminal status |
| `find_content_to_cite` | Published articles that have a public `citation_url` |
| `find_ideaclouds` | IdeaCloud topics by keyword/status |
| `get_ideacloud` | One-shot IdeaCloud status/details lookup |
| `wait_for_ideacloud` | Bounded wait for IdeaCloud research to reach a terminal status |
| `list_ideacloud_suggestions` | Create-dropdown suggestions (same suppress filters as Composer) |
| `create_ideacloud` | Keyword or suggestion → researching (consumes suggestion across app + MCP) |
| `get_ideacloud_outline` | Cluster outline for narration (labels/counts/samples — not every question) |
| `get_ideacloud_cluster` | Drill one cluster’s questions |
| `get_ideacloud_selection` | Numbered priority basket |
| `set_ideacloud_selection` | Replace ordered basket (max 15); returns full numbered basket |
| `apply_recommended_selection` | Seed basket from recommended questions |
| `update_ideacloud_settings` | Accordion draft settings (type, staff, tone, Layouts, geo) |
| `create_content` | Generate article from IdeaCloud basket + settings; then use `wait_for_content` |
| `check_compliance` | Sync OEM compliance on pasted copy — score, issues, suggested\_replacement (`compliance:write` + Compliance Checking) |
| `apply_compliance_fixes` | Apply selected issue ids / replacements; optional `recheck` (`compliance:write`) |
| `trigger_content_compliance` | Async check on existing Hrizn content (`compliance:write`) |
| `get_content_compliance` | One-shot article compliance report lookup (`content:read`) |
| `wait_for_content_compliance` | Bounded wait for an article compliance check to reach a terminal status (`content:read`) |
| `get_content_opportunities` | Content intelligence summary + top active opportunities |
| `get_content_recommendation` | One content intelligence recommendation by id |
| `get_social_presence` | Connected accounts + platform health + connect\_guidance; optional recent posts/reviews |
| `find_reviews` | Google/Facebook reviews (reviewer PII); `min_stars` / `unanswered_only` |
| `list_social_posts` | List Social Hub posts (`social:read`); item `id` is canonical for get/wait/update/delete, while `target_id` identifies one platform target |
| `get_social_post` | One Social Hub post by canonical `id` (`social:read`) |
| `wait_for_social_post` | Bounded poll until published, explicitly scheduled for a future time, or failed/error/cancelled; publish-now posts temporarily reported as scheduled remain in progress (`social:read`) |
| `wait_for_media_session` | Bounded poll of upload session until ready (**Unlimited** MCP + `social:write`) |
| `prepare_social_post` | Presence + checklist + optional upload session (**Unlimited** MCP + `social:write`) — does not create a post |
| `finalize_social_post` | Create/schedule after prepare (**Unlimited** MCP + `social:write`) — `dry_run`, then `user_confirmed` + `preview_token` |
| `update_social_post` | Update draft/scheduled post (**Unlimited** MCP + `social:write`) |
| `delete_social_post` | Delete a post (**Unlimited** MCP + `social:write`) |
| `unpublish_social_post` | Unpublish from a platform (**Unlimited** MCP + `social:write`) |
| `retry_social_post` | Retry failed publish (**Unlimited** MCP + `social:write`) |
| `get_review` | One review by id (`social:read`) |
| `generate_review_reply` | AI reply draft (**Unlimited** MCP + `reviews:write`) |
| `publish_review_reply` | Publish review reply (**Unlimited** MCP + `reviews:write`) |
| `get_vehicle` | Single vehicle by VIN including **Hrizn `ai_description`**, days on lot, certified |
| `list_vehicle_years` | Selectable years for catalog create (**content:write**) — labels only |
| `list_vehicle_makes` | Makes for a year (**content:write**) — parent-required, labels only |
| `list_vehicle_models` | Models for year+make (**content:write**) |
| `list_vehicle_trims` | Trim labels for year+make+model (**content:write**) — no MSRP/JATO |
| `list_layouts` | Web Layouts templates for modellanding/comparison/salesevent/basic/qa/expert (**content:write**) |
| `create_model_landing` | Create model landing. Ask full create-modal options first (source, trims, voice/tone, language, depth, geo, Rich Text vs Layouts). Then use `wait_for_content`. |
| `create_comparison` | Create comparison (2–5 vehicles) with the same create-modal elicitation plus featured vehicle + bias. |
| `create_sales_event` | Create sales event page. Ask Event Page modal options (category, name, dates, location, voice/depth/geo/Layouts). |
| `get_local_market_listings` | Live local segment listings + price/DOM stats (**Unlimited** + `market_data:read`) |
| `get_market_days_supply` | Live market days supply / sell-through (**Unlimited** + `market_data:read`) |
| `get_competitive_set` | Competing dealer listings for a segment (**Unlimited** + `market_data:read`) |
| `analyze_inventory_pricing` | Fleet vs local market median (**Unlimited** + `market_data:read`) |
| `appraise_vehicle` | Trade-in / YMM appraisal without inventory VIN (**Unlimited** + `market_data:read`) |
| `get_price_cut_candidates` | Aged + over-market units to reprice (**Unlimited** + `market_data:read`) |
| `get_stocking_opportunities` | Stock / acquire by local velocity (**Unlimited** + `market_data:read`) |
| `analyze_vehicle_position` | One inventory VIN vs market (no dealer cost) (**Unlimited** + `market_data:read`) |
| `get_market_price_analysis` | VIN predicted price + comps (**Unlimited** + `market_data:read`) |
| `get_vehicle_options_packages` | Factory options/packages by VIN (**Unlimited** + `market_data:read`) |
### IdeaCloud text-first curation checklist
There is no research graph canvas in MCP. Agents should:
1. Offer `list_ideacloud_suggestions` or accept a freeform keyword
2. `create_ideacloud` → `wait_for_ideacloud` until `complete`
3. `get_ideacloud_outline` — narrate clusters (do not dump every question)
4. `apply_recommended_selection` (or start empty)
5. Drill with `get_ideacloud_cluster` only as needed; mutate via `set_ideacloud_selection` (max 15) and always re-show the numbered basket
6. `update_ideacloud_settings` then `create_content`
Consumed suggestions disappear from both the in-app Create IdeaCloud dropdown and `list_ideacloud_suggestions`.
Catalog cascade tools never return JATO facts, MSRP, or provider refs. There is no bulk catalog export — always walk year → make → model → trim one level at a time.
## Example agent questions
* “Who are the sales managers at this store?”
* “Summarize this dealership’s brand voice and DNA.”
* “What used inventory is aged 60+ days?”
* “Which units are missing a Hrizn AI description?”
* “Show me the AI write-up for VIN …”
* “What IdeaClouds do we have on Camry?”
* “Top content opportunities this week?”
* “Unanswered Google reviews under 3 stars?”
* “Which published articles can I cite with a live URL?”
* “Give me a lot health snapshot — aging and merchandising gaps.”
* “Are my used RAV4s overpriced vs the local market?”
* “What’s market days supply for new Camrys near us?”
* “Which aged units should I cut price on first?”
* “Create a model landing from an in-stock Camry — ask me inventory vs catalog first.”
* “Build a catalog model landing for 2026 Honda Civic Sport after walking the YMMT lists.”
* “Compare two vehicles — for each ask inventory VIN vs year/make/model/trim.”
* “Schedule a Facebook post for Saturday at 10am local — confirm timezone from get\_dealer\_context.”
* “Attach this photo to an Instagram post — open the upload link, drop the file, then post.”
## Social Hub posting checklist (MCP)
1. `prepare_social_post` — resolve healthy platforms; set `needs_media=true` when the user will upload files (reconnect via Dealership Manager → Social Profiles if needed)
2. Draft copy (+ hashtags) and confirm schedule vs `publish_now` (IANA `scheduled_timezone` from `suggested_timezone`)
3. Media: none, durable HTTPS `media_items`, or open `upload_url` → `wait_for_media_session` until `ready`. If a pending upload link is lost, call `prepare_social_post` with the same `media_session_id` to reissue it without creating an orphan session.
4. `finalize_social_post` with `dry_run=true`, show the preview, then re-call with identical arguments plus `user_confirmed=true` and the returned `preview_token` (pass `media_session_id` when using the upload bridge)
## Security
* Treat API keys like passwords. They are shown **once** at creation.
* Prefer the **MCP (Read)** preset (least privilege). Add **MCP (Read + Market)** only for Unlimited dealers that need Hrizn Market Maker. Add **MCP (Read + Social)** only for Unlimited dealers that need Social Hub post/reply tools.
* New MCP keys need IdeaClouds, content intelligence, and social read scopes for the expanded tools; rotate older keys to pick them up.
* Revoke unused keys from Dealership Manager → **API & MCP** → API Keys.
* Hrizn MCP does not store your key; each tool call forwards it to the Public API.
* Media upload links are capability URLs (site-scoped, \~20 min TTL). Do not forward them; after status `ready` the token is invalidated.
## Troubleshooting
| Symptom | Check |
| ------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 401 on MCP | Key missing, not `hzk_…`, or wrong header |
| Tool error “Forbidden” / missing scope | Key needs MCP (Read) scopes: `site:read`, `inventory:read`, `content:read`, `ideaclouds:read`, `content_intelligence:read`, `social:read` |
| “Unlimited plan required for Hrizn Market Maker” | Site is not on Unlimited (or lacks the feature override); Market Maker tools are gated |
| “Unlimited plan required for Hrizn Social Hub” | Site is not on Unlimited (or lacks the feature override); Social Hub MCP write tools are gated |
| Connect Social Profiles message | Network missing or needs reconnect — Dealership Manager → Social Profiles |
| Media upload link lost or expired | For a pending session, re-call `prepare_social_post` with its `media_session_id` to reissue the link. Create a new session only after the old one expires. |
| Missing `market_data:read` | Use **MCP (Read + Market)** or add the scope manually |
| Missing `social:write` / `reviews:write` | Use **MCP (Read + Social)** or add the scopes manually |
| 429 | Public API rate limit — back off and retry |
| Empty `find_content_to_cite` | Articles need a public citation URL (canonical / published / posted) |
| Confusing docs vs data | Use Mintlify MCP for docs literacy; Hrizn MCP for live dealer data |
## Related
* [Authentication](/authentication) — API keys and scopes
* [Hrizn Market Maker](/api-reference/market/overview) — live local-market endpoints
* [List published content](/api-reference/content/list-published) — includes `citation_url`
* [Site](/api-reference/site/get) — dealer profile endpoints