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.

Get MCP Access What is the MCP Server?

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)

# Tool What it does
1 lookup_vin Full 360° report on a VIN: decode + active listings + price band + rank + title + auctions count, scoped to the caller's licensed perimeter
2 decode_vin Lightweight decode: make/model/trim/engine/drivetrain/safety from VIN
3 decode_vin_batch Bulk decode for up to 50 VINs in a single call
4 vin_history_listings Full listing history for a VIN — active and delisted, with prices and DOM
5 vin_price_history Time-series of listing prices per VIN (powers chart timelines)
6 vin_listing_count_by_state Distinct US states the VIN has been listed in (replacement for title status — title data not accessible)
7 vin_dealer_history 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_inventory Search active listings by make/model/year/trim/price/mileage/zip+radius/body/fuel; sort by distance, price, or DOM
10 search_inventory_by_text Free-text search ("white pickup under $35k near Dallas") with LLM-assisted query parsing
11 find_similar_vehicles Vehicles similar by ML feature vectors or visually-matching photos
12 find_visually_similar_listings Image-similarity lookup via perceptual hash (dhash / Hamming distance)
13 detect_duplicate_listings Same VIN listed across multiple platforms — merged into a single canonical record
14 search_new_arrivals Listings added within the last N hours in a region
15 search_price_drops Listings whose price dropped within a period
16 search_long_dom_listings Stale inventory: anything sitting more than N days
17 search_certified_preowned CPO-only filter using new_vehicle=0 + CPO markers
18 search_trade_in_candidates Vehicles that match a dealer's trade-in profile (model/year/mileage band)

C. Dealer Inventory & Profile (10)

# Tool What it does
19 my_inventory_overview Caller's own inventory at a glance: total units, mix by make/model, avg price, avg DOM, oldest listing
20 my_inventory_list Full paginated list of caller's listings (custom_vehicles take priority over scraped)
21 dealer_inventory Inventory for any dealer in the caller's authorized list, by dealer_name or dealer_identity_id
22 dealer_profile Dealer name, address, phone, website, hours, photos, review rating
23 dealer_reviews Paginated Google reviews for a dealer
24 dealer_search Find dealers by name, ZIP+radius, or specialty make
25 dealer_inventory_age_buckets DOM distribution (0–30 / 31–60 / 60–90 / 90+ days)
26 dealer_pricing_position How a dealer's prices compare to market median (% above/below)
27 dealer_make_mix Top makes by volume, with share of total stock
28 dealer_scraping_freshness When the dealer was last scraped, how many vehicles were added/removed

D. Competitor Analysis (12)

# Tool What it does
29 find_competitors Comparable competitor vehicles for a VIN (same prefix8, price ≥ $2000) within a radius, via CompetitorResolver
30 competitor_count Fast count of active competitors in a radius
31 competitor_rank Caller's rank by price among competitors ("#12 of 47, below median")
32 competitor_price_distribution Buckets (low / Q1 / median / Q3 / high) with histogram data
33 competitor_listings_table Full competitor table with dealer, price, mileage, DOM, distance
34 competitor_price_change_alerts Competitors who changed price in a period (drops and raises)
35 competitor_new_listings Net-new competitor listings in the last 24h / 7d
36 competitor_sold_listings Listings that disappeared (proxy for sold)
37 dealer_vs_competitor_summary Head-to-head summary: my dealer vs a named competitor across model, price, DOM
38 find_underpriced_competitors Competitors priced significantly below market median (risk or opportunity)
39 find_overpriced_competitors Mirror of #38 — competitors priced above
40 competitor_trims_breakdown Which trims competitors stock — gap analysis vs caller's lot

E. Pricing & Market Analysis (14)

# Tool What it does
41 price_band Low / median / high for (year, make, model, trim) within a radius
42 price_band_by_zip Same band, but aggregated per ZIP
43 price_band_with_mileage Band that accounts for mileage bucket
44 suggest_price Recommended price for a VIN — three scenarios: aggressive / market / premium
45 trade_in_value Fair / Good / Excellent trade-in estimate (60 / 70 / 80% of median)
46 price_trend_weekly Weekly avg/min/max price time-series
47 price_trend_monthly Monthly aggregation with year-over-year change
48 mileage_price_correlation Scatter data for odometer ↔ price charts
49 dom_distribution Days-on-market distribution by model or region
50 avg_dom_by_make Median and mean DOM per make/model
51 price_vs_segment How a model compares to its segment average (mid-size sedan, full-size SUV)
52 regional_price_comparison Same model across multiple regions side-by-side
53 platform_price_comparison Autotrader vs Cars.com vs Facebook vs CarGurus for the same vehicle
54 calculate_loan_payment Pure financial calculator — monthly payment, total interest, schedule

F. Auction Intelligence (8)

# Tool What it does
54 auction_lookup_vin Every auction lot for a given VIN — IAAI/Copart hammer price, damage class, photos, sale date
55 auction_search Search auction lots by year/make/model/state/damage/auction house
56 auction_price_band Hammer-price low/median/high for (year, make, model, primary damage)
57 auction_repair_cost_estimate Average repair cost for a damage class
58 auction_recent_sales Most recent N sold lots for a model
59 auction_unsold_lots No-sale lots and no-sale rate
60 damage_impact_on_value How much a primary damage class drops the price vs. clean
61 wholesale_to_retail_spread Auction hammer vs retail listing for the same vehicle

G. Listing Diagnostics & Risk Signals (4)

# Tool What it does
62 listing_freshness_score When the listing was last refreshed, days since last price change, staleness flag
63 vin_market_footprint How many distinct platforms and dealers have listed this VIN over time
64 spec_mismatch_check VIN decode vs listing-claimed make/model/year disagreement (potential fraud / data error)
65 listing_completeness_score Photo count + description length + filled-fields ratio → quality grade A/B/C

H. Window Sticker & Build Data (3)

# Tool What it does
66 fetch_window_sticker Returns Monroney sticker URL/PDF, generates if missing
67 window_sticker_summary Structured fields: MSRP, options, packages, factory options
68 build_data_options Factory options for a VIN (HUD, leather, packages) — includes safety features

I. Geographic & Regional (6)

# Tool What it does
69 zip_neighbors All ZIP codes within N miles
70 zip_to_geo ZIP → city / state / lat / lon
71 state_inventory_summary Listings per state with top makes
72 city_dealer_density Dealer count and active vehicle count by city
73 map_aggregation Hierarchical state → city → dealer → vehicle aggregation by zoom level
74 find_dealers_in_radius Every dealer within a radius (for outreach)
# Tool What it does
75 market_supply_trend Active-listing count for a model — weekly/monthly
76 market_demand_signal Disappearance velocity (proxy sold-rate)
77 dealer_inventory_growth How a competitor's stock changed over time
78 price_volatility_index Standard deviation of prices over a period
79 seasonal_patterns Seasonal rhythms (convertibles in spring, 4WD in winter)
80 new_vs_used_share New vs used listing share by region
81 listing_velocity Average days from list → delist

K. Image & Visual (3)

# Tool What it does
82 vehicle_images All image URLs for a VIN or listing
83 best_listing_photo Cover / main image
84 photo_count_quality_check Photo count plus a low-quality flag (<5 photos)

L. Reports & Aggregated Analytics (10)

# Tool What it does
85 vehicle_full_report One-call markdown report for a VIN: decode, history, prices, auctions, title, sticker
86 dealer_full_report Full dealer report: profile + inventory + pricing position + competitor benchmark + reviews
87 market_report_by_model Report by (year, make, model): supply, price band, top dealers, regional split, trends
88 regional_market_report Report by region/state: top makes, average price, DOM, hot models
89 price_change_report Top-N listings with price change (drops and raises) over a period
90 inventory_aging_report Caller's listings >60/90 days with new-price suggestions
91 gap_analysis_report Trims that competitors stock but caller does not
92 opportunity_report Auction VINs with profitable retail flip spread
93 dealer_competitive_report Caller vs a specific competitor — head-to-head across 10 metrics
94 export_report 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 markdown
  • mcp://docs/data-sources — domain and table dictionary
  • mcp://docs/dealer/{business_id} — caller's dealer profile
  • mcp://docs/glossary — DOM, MSRP, hammer-price, prefix8, etc.

MCP Prompts (5)

Pre-built one-click templates:

  • daily_competitor_brief — "What's new with competitors in the last 24 hours?"
  • weekly_market_pulse — Weekly trends across the caller's region
  • vin_deep_dive — Full 360° report for a VIN
  • pricing_review — Caller's inventory with red-flagged prices
  • auction_opportunities — Auction lots with retail-vs-wholesale spread

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.