MCP Server Documentation

Full reference for the 101 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.

Quickstart — Claude Desktop

# ~/Library/Application Support/Claude/claude_desktop_config.json
{
  "mcpServers": {
    "vinassessment": {
      "command": "npx",
      "args": ["-y", "@vinassessment/mcp"],
      "env": { "VA_API_KEY": "va_live_..." }
    }
  }
}

Quickstart — raw curl

# 1. handshake
curl -X POST https://mcp.vinassessment.com/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://mcp.vinassessment.com/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://mcp.vinassessment.com/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.

# MCP Server Tool Catalog

**Status:** Specification (planned, not yet implemented)
**Plan reference:** `~/.claude/plans/goofy-rolling-hollerith.md`
**Marketing page:** `app/views/static_pages/mcp.html.haml` (`/mcp`)

The VinAssessment MCP Server exposes **94 tools**, **4 resources**, and **5 prompts** to any MCP-compatible AI assistant (Claude Desktop, Cursor, custom agents). All tools are read-only in the initial release. Every tool is tenant-scoped — see "Tenant Scoping Discipline" in the plan file for the perimeter rules enforced by `app/services/mcp/tenant_guard.rb`.

Naming convention: `verb_noun` snake_case. The `get_` prefix is avoided unless the noun would otherwise read ambiguously.

**Curation note (2026-05-19):** The catalog was reduced from 101 to 94 tools after a usefulness + partition-safety audit. Cut: `vin_auction_history` (duplicate of `auction_lookup_vin`), `auction_house_locations` (static reference data), `auction_image_match` (wrapper around `auction_lookup_vin`), `city_search` (UX autocomplete, not an insight tool), `find_similar_photos` (pure delegation wrapper), `most_searched_vins` (internal engagement metric, not dealer-relevant), `safety_features` (already returned inline by `decode_vin` + `build_data_options`). Every remaining ClickHouse query enforces partition-key predicates in WHERE — full-table scans against 127M-row tables are forbidden.

---

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

## J. Trends & Time Series (7)

| # | 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

---

## Counts

| Category | Count |
|---|---|
| A. VIN Intelligence | 7 |
| B. Vehicle Search | 10 |
| C. Dealer Inventory & Profile | 10 |
| D. Competitor Analysis | 12 |
| E. Pricing & Market | 14 |
| F. Auction Intelligence | 8 |
| G. Listing Diagnostics & Risk Signals | 4 |
| H. Window Sticker / Build | 3 |
| I. Geographic | 6 |
| J. Trends & Time Series | 7 |
| K. Image & Visual | 3 |
| L. Reports & Analytics | 10 |
| **Total tools** | **94** |
| Resources | 4 |
| Prompts | 5 |

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

Need help? Contact support or open an issue on the @vinassessment/mcp npm package.