MCP Server Documentation
Full reference for the 94 tools exposed by the VinAssessment MCP Server. Every tool's name, what it does, the data tables it queries, and what it returns. Quickstart guides for Claude Desktop, Cursor, and raw JSON-RPC.
Endpoint
https://vinassessment.com/mcp/v1
Authentication
OAuth 2.1 (PKCE S256, dynamic client registration) or the header
Authorization: Bearer va_live_…
Format
JSON-RPC 2.0 over HTTP+SSE
On this page
Quickstart — Claude Desktop
The server is a remote SSE endpoint — no local package to install. Add it directly to your config:
# ~/Library/Application Support/Claude/claude_desktop_config.json
{
"mcpServers": {
"vinassessment": {
"url": "https://vinassessment.com/mcp/v1/sse",
"headers": { "Authorization": "Bearer va_live_..." }
}
}
}
Quickstart — Cursor
Open Cursor Settings → MCP Servers → New Server and configure a remote (URL) server — no command/package required:
| Name | vinassessment |
| Type | sse (url) |
| URL | https://vinassessment.com/mcp/v1/sse |
| Header | Authorization: Bearer va_live_... |
Quickstart — raw curl
# 1. handshake
curl -X POST https://vinassessment.com/mcp/v1/messages \
-H "Authorization: Bearer va_live_..." \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"curl","version":"1.0"}}}'
# 2. list tools
curl -X POST https://vinassessment.com/mcp/v1/messages \
-H "Authorization: Bearer va_live_..." \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'
# 3. call a tool
curl -X POST https://vinassessment.com/mcp/v1/messages \
-H "Authorization: Bearer va_live_..." \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"lookup_vin","arguments":{"vin":"5XYP3DHC2NG267350"}}}'
Tool catalog (full)
Every tool is read-only, tenant-scoped to your licensed perimeter, and rate-limited per your tier. See the /mcp marketing page for the 12-domain summary; the full reference is below.
- A. VIN Intelligence & Decoding (7)
- B. Vehicle Search & Discovery (10)
- C. Dealer Inventory & Profile (10)
- D. Competitor Analysis (12)
- E. Pricing & Market Analysis (14)
- F. Auction Intelligence (8)
- G. Listing Diagnostics & Risk Signals (4)
- H. Window Sticker & Build Data (3)
- I. Geographic & Regional (6)
- J. Trends & Time Series (7)
- K. Image & Visual (3)
- L. Reports & Aggregated Analytics (10)
- MCP Resources (4)
- MCP Prompts (5)
A. VIN Intelligence & Decoding (7)
| # | Tool | What it does |
|---|---|---|
| 1 | lookup_ |
Full 360° report on a VIN: decode + active listings + price band + rank + title + auctions count, scoped to the caller's licensed perimeter |
| 2 | decode_ |
Lightweight decode: make/model/trim/engine/drivetrain/safety from VIN |
| 3 | decode_ |
Bulk decode for up to 50 VINs in a single call |
| 4 | vin_ |
Full listing history for a VIN — active and delisted, with prices and DOM |
| 5 | vin_ |
Time-series of listing prices per VIN (powers chart timelines) |
| 6 | vin_ |
Distinct US states the VIN has been listed in (replacement for title status — title data not accessible) |
| 7 | vin_ |
Distinct dealers that have ever listed this VIN with first/last seen dates and price range (replacement for ownership summary) |
B. Vehicle Search & Discovery (10)
| # | Tool | What it does |
|---|---|---|
| 9 | search_ |
Search active listings by make/model/year/trim/price/mileage/zip+radius/body/fuel; sort by distance, price, or DOM |
| 10 | search_ |
Free-text search ("white pickup under $35k near Dallas") with LLM-assisted query parsing |
| 11 | find_ |
Vehicles similar by ML feature vectors or visually-matching photos |
| 12 | find_ |
Image-similarity lookup via perceptual hash (dhash / Hamming distance) |
| 13 | detect_ |
Same VIN listed across multiple platforms — merged into a single canonical record |
| 14 | search_ |
Listings added within the last N hours in a region |
| 15 | search_ |
Listings whose price dropped within a period |
| 16 | search_ |
Stale inventory: anything sitting more than N days |
| 17 | search_ |
CPO-only filter using new_ + CPO markers |
| 18 | search_ |
Vehicles that match a dealer's trade-in profile (model/year/mileage band) |
C. Dealer Inventory & Profile (10)
| # | Tool | What it does |
|---|---|---|
| 19 | my_ |
Caller's own inventory at a glance: total units, mix by make/model, avg price, avg DOM, oldest listing |
| 20 | my_ |
Full paginated list of caller's listings (custom_vehicles take priority over scraped) |
| 21 | dealer_ |
Inventory for any dealer in the caller's authorized list, by dealer_ or dealer_ |
| 22 | dealer_ |
Dealer name, address, phone, website, hours, photos, review rating |
| 23 | dealer_ |
Paginated Google reviews for a dealer |
| 24 | dealer_ |
Find dealers by name, ZIP+radius, or specialty make |
| 25 | dealer_ |
DOM distribution (0–30 / 31–60 / 60–90 / 90+ days) |
| 26 | dealer_ |
How a dealer's prices compare to market median (% above/below) |
| 27 | dealer_ |
Top makes by volume, with share of total stock |
| 28 | dealer_ |
When the dealer was last scraped, how many vehicles were added/removed |
D. Competitor Analysis (12)
| # | Tool | What it does |
|---|---|---|
| 29 | find_ |
Comparable competitor vehicles for a VIN (same prefix8, price ≥ $2000) within a radius, via CompetitorResolver |
| 30 | competitor_ |
Fast count of active competitors in a radius |
| 31 | competitor_ |
Caller's rank by price among competitors ("#12 of 47, below median") |
| 32 | competitor_ |
Buckets (low / Q1 / median / Q3 / high) with histogram data |
| 33 | competitor_ |
Full competitor table with dealer, price, mileage, DOM, distance |
| 34 | competitor_ |
Competitors who changed price in a period (drops and raises) |
| 35 | competitor_ |
Net-new competitor listings in the last 24h / 7d |
| 36 | competitor_ |
Listings that disappeared (proxy for sold) |
| 37 | dealer_ |
Head-to-head summary: my dealer vs a named competitor across model, price, DOM |
| 38 | find_ |
Competitors priced significantly below market median (risk or opportunity) |
| 39 | find_ |
Mirror of #38 — competitors priced above |
| 40 | competitor_ |
Which trims competitors stock — gap analysis vs caller's lot |
E. Pricing & Market Analysis (14)
| # | Tool | What it does |
|---|---|---|
| 41 | price_ |
Low / median / high for (year, make, model, trim) within a radius |
| 42 | price_ |
Same band, but aggregated per ZIP |
| 43 | price_ |
Band that accounts for mileage bucket |
| 44 | suggest_ |
Recommended price for a VIN — three scenarios: aggressive / market / premium |
| 45 | trade_ |
Fair / Good / Excellent trade-in estimate (60 / 70 / 80% of median) |
| 46 | price_ |
Weekly avg/min/max price time-series |
| 47 | price_ |
Monthly aggregation with year-over-year change |
| 48 | mileage_ |
Scatter data for odometer ↔ price charts |
| 49 | dom_ |
Days-on-market distribution by model or region |
| 50 | avg_ |
Median and mean DOM per make/model |
| 51 | price_ |
How a model compares to its segment average (mid-size sedan, full-size SUV) |
| 52 | regional_ |
Same model across multiple regions side-by-side |
| 53 | platform_ |
Autotrader vs Cars.com vs Facebook vs CarGurus for the same vehicle |
| 54 | calculate_ |
Pure financial calculator — monthly payment, total interest, schedule |
F. Auction Intelligence (8)
| # | Tool | What it does |
|---|---|---|
| 54 | auction_ |
Every auction lot for a given VIN — IAAI/Copart hammer price, damage class, photos, sale date |
| 55 | auction_ |
Search auction lots by year/make/model/state/damage/auction house |
| 56 | auction_ |
Hammer-price low/median/high for (year, make, model, primary damage) |
| 57 | auction_ |
Average repair cost for a damage class |
| 58 | auction_ |
Most recent N sold lots for a model |
| 59 | auction_ |
No-sale lots and no-sale rate |
| 60 | damage_ |
How much a primary damage class drops the price vs. clean |
| 61 | wholesale_ |
Auction hammer vs retail listing for the same vehicle |
G. Listing Diagnostics & Risk Signals (4)
| # | Tool | What it does |
|---|---|---|
| 62 | listing_ |
When the listing was last refreshed, days since last price change, staleness flag |
| 63 | vin_ |
How many distinct platforms and dealers have listed this VIN over time |
| 64 | spec_ |
VIN decode vs listing-claimed make/model/year disagreement (potential fraud / data error) |
| 65 | listing_ |
Photo count + description length + filled-fields ratio → quality grade A/B/C |
H. Window Sticker & Build Data (3)
| # | Tool | What it does |
|---|---|---|
| 66 | fetch_ |
Returns Monroney sticker URL/PDF, generates if missing |
| 67 | window_ |
Structured fields: MSRP, options, packages, factory options |
| 68 | build_ |
Factory options for a VIN (HUD, leather, packages) — includes safety features |
I. Geographic & Regional (6)
| # | Tool | What it does |
|---|---|---|
| 69 | zip_ |
All ZIP codes within N miles |
| 70 | zip_ |
ZIP → city / state / lat / lon |
| 71 | state_ |
Listings per state with top makes |
| 72 | city_ |
Dealer count and active vehicle count by city |
| 73 | map_ |
Hierarchical state → city → dealer → vehicle aggregation by zoom level |
| 74 | find_ |
Every dealer within a radius (for outreach) |
J. Trends & Time Series (7)
| # | Tool | What it does |
|---|---|---|
| 75 | market_ |
Active-listing count for a model — weekly/monthly |
| 76 | market_ |
Disappearance velocity (proxy sold-rate) |
| 77 | dealer_ |
How a competitor's stock changed over time |
| 78 | price_ |
Standard deviation of prices over a period |
| 79 | seasonal_ |
Seasonal rhythms (convertibles in spring, 4WD in winter) |
| 80 | new_ |
New vs used listing share by region |
| 81 | listing_ |
Average days from list → delist |
K. Image & Visual (3)
| # | Tool | What it does |
|---|---|---|
| 82 | vehicle_ |
All image URLs for a VIN or listing |
| 83 | best_ |
Cover / main image |
| 84 | photo_ |
Photo count plus a low-quality flag (<5 photos) |
L. Reports & Aggregated Analytics (10)
| # | Tool | What it does |
|---|---|---|
| 85 | vehicle_ |
One-call markdown report for a VIN: decode, history, prices, auctions, title, sticker |
| 86 | dealer_ |
Full dealer report: profile + inventory + pricing position + competitor benchmark + reviews |
| 87 | market_ |
Report by (year, make, model): supply, price band, top dealers, regional split, trends |
| 88 | regional_ |
Report by region/state: top makes, average price, DOM, hot models |
| 89 | price_ |
Top-N listings with price change (drops and raises) over a period |
| 90 | inventory_ |
Caller's listings >60/90 days with new-price suggestions |
| 91 | gap_ |
Trims that competitors stock but caller does not |
| 92 | opportunity_ |
Auction VINs with profitable retail flip spread |
| 93 | dealer_ |
Caller vs a specific competitor — head-to-head across 10 metrics |
| 94 | export_ |
Markdown/CSV snapshot of any of the above (delivered as mcp://reports/<id> resource) |
MCP Resources (4)
Read-only documents the AI can pull into context:
mcp://docs/tool-catalog— this catalog as markdownmcp://docs/data-sources— domain and table dictionarymcp://docs/dealer/{business_— caller's dealer profileid} mcp://docs/glossary— DOM, MSRP, hammer-price, prefix8, etc.
MCP Prompts (5)
Pre-built one-click templates:
daily_— "What's new with competitors in the last 24 hours?"competitor_ brief weekly_— Weekly trends across the caller's regionmarket_ pulse vin_— Full 360° report for a VINdeep_ dive pricing_— Caller's inventory with red-flagged pricesreview auction_— Auction lots with retail-vs-wholesale spreadopportunities
Error codes
| Code | Meaning | Action |
|---|---|---|
| 401 | Invalid or revoked API key | Reissue a key in your dashboard |
| 429 | Rate limit exceeded for your tier | Wait for Retry-After seconds and retry |
| tenant_violation | ZIP/dealer/state outside licensed perimeter or tier insufficient | Use a covered ZIP or upgrade tier |
Ready to connect?
MCP is its own subscription. You don't need a dealer plan or the REST API to use it.









