Hrizn MCP

The Hrizn MCP is a hosted Model Context Protocol 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: <next_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:

Call with dry_run: true to validate and preview (no write).
Show the preview to the user and get approval.
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. 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):

{
  "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):

{
  "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:

[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):

{
  "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:

{
  "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:

{
  "$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:

{
  "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):

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):

{
  "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:

{
  "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:

Offer list_ideacloud_suggestions or accept a freeform keyword
create_ideacloud → wait_for_ideacloud until complete
get_ideacloud_outline — narrate clusters (do not dump every question)
apply_recommended_selection (or start empty)
Drill with get_ideacloud_cluster only as needed; mutate via set_ideacloud_selection (max 15) and always re-show the numbered basket
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.”

prepare_social_post — resolve healthy platforms; set needs_media=true when the user will upload files (reconnect via Dealership Manager → Social Profiles if needed)
Draft copy (+ hashtags) and confirm schedule vs publish_now (IANA scheduled_timezone from suggested_timezone)
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.
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

Authentication — API keys and scopes
Hrizn Market Maker — live local-market endpoints
List published content — includes citation_url
Site — dealer profile endpoints

Getting Started

Concepts

Guides

Scopes

Endpoint

Required scopes

Write confirmation (dry_run)

Discovery profiles

Connect a client

Cursor / Claude Code

Claude Desktop

OpenAI Codex (ChatGPT desktop / Codex IDE)

Gemini CLI

Windsurf

OpenCode

VS Code / Copilot

Continue

Cline / JetBrains AI

Amazon Q / Kiro

Zed

Tool catalog

IdeaCloud text-first curation checklist

Example agent questions

Security

Troubleshooting

​Endpoint

​Required scopes

​Pagination

​Write confirmation (dry_run)

​Wait helpers and social composites

​Discovery profiles

​Connect a client

​Cursor / Claude Code

​Claude Desktop

​OpenAI Codex (ChatGPT desktop / Codex IDE)

​Gemini CLI

​Windsurf

​OpenCode

​VS Code / Copilot

​Continue

​Cline / JetBrains AI

​Amazon Q / Kiro

​Zed

​Tool catalog

​IdeaCloud text-first curation checklist

​Example agent questions

​Social Hub posting checklist (MCP)

​Security

​Troubleshooting

​Related

Endpoint

Required scopes

Pagination

Write confirmation (dry_run)

Wait helpers and social composites

Discovery profiles

Connect a client

Cursor / Claude Code

Claude Desktop

OpenAI Codex (ChatGPT desktop / Codex IDE)

Gemini CLI

Windsurf

OpenCode

VS Code / Copilot

Continue

Cline / JetBrains AI

Amazon Q / Kiro

Zed

Tool catalog

IdeaCloud text-first curation checklist

Example agent questions

Social Hub posting checklist (MCP)

Security

Troubleshooting

Related