# Introduction

> MarketCheck MCP Server gives AI applications and LLMs direct access to automotive market data through the Model Context Protocol, enabling natural-language vehicle search, price prediction, and market analytics across US, Canada, and UK markets.

The MarketCheck MCP Server connects AI applications to the full MarketCheck automotive data platform through the [Model Context Protocol (MCP)](https://modelcontextprotocol.io). Instead of writing API calls by hand, your AI assistant can search inventory, predict prices, decode VINs, and analyze market trends using natural language.

MCP is an open standard that lets AI models call external tools in a structured, type-safe way. The MarketCheck MCP Server wraps the MarketCheck REST API into a set of tools that any MCP-compatible client can use — including Claude Desktop, Cursor, Windsurf, and custom AI applications.



## Architecture

![MCP Server Architecture](/img/mcp-server/architecture.svg)The server acts as a bridge — translating MCP tool calls into MarketCheck API requests and returning structured results back to the AI client.



## Two Ways to Access

You can connect to the **hosted server** or **run it locally**:

| Option        | URL / Command | What You Need |
|---------------|---------------|---------------|
| **Hosted** (recommended) | `https://api.marketcheck.com/mcp?api_key=YOUR_API_KEY` | API key only |
| **Local** | `python server.py` | Python 3.12+, cloned repo, API key |


Get your API key from the [MarketCheck Developer Portal](https://developers.marketcheck.com/).



## Tools

The server exposes nine tools organized by market and function. Each tool maps to one or more MarketCheck API endpoints and is designed for AI consumption — with automatic type coercion, token-optimized responses, and structured parameter validation.



### US & Canada

| Tool           | Purpose        | Key Capability |
|----------------|----------------|----------------|
| [`search_active_cars`](/docs/get-started/api/mcp/tools/search-active-cars) | Search live inventory | 80+ filters, faceted search, dealer/private/auction |
| [`search_past_90_days`](/docs/get-started/api/mcp/tools/search-past-90-days) | Search expired/sold listings | Historical pricing, market trends, sold analysis |
| [`predict_price_with_comparables`](/docs/get-started/api/mcp/tools/predict-price) | ML-based price prediction | Predicted value + comparable active listings |
| [`decode_vin_neovin`](/docs/get-started/api/mcp/tools/decode-vin) | Decode VIN to full specs | Trim, engine, MSRP, options, features |
| [`get_car_history`](/docs/get-started/api/mcp/tools/car-history) | Listing history by VIN | Price changes, dealer history, days on market |
| [`get_sold_summary`](/docs/get-started/api/mcp/tools/sold-summary) | Sold vehicle analytics | 5 years of data, ranking, grouping, advanced filters <badge type="warning">

Experimental

</badge>

 <badge type="info">

Enterprise

</badge> |




### United Kingdom

| Tool           | Purpose        | Key Capability |
|----------------|----------------|----------------|
| [`search_uk_active_cars`](/docs/get-started/api/mcp/tools/uk-tools) | Search live UK inventory | VRM lookup, ULEZ compliance, insurance groups |
| [`search_uk_recent_cars`](/docs/get-started/api/mcp/tools/uk-tools) | Search expired/sold UK listings | UK-specific historical data and lease/finance filters |




### Utility

| Tool    | Purpose |
|---------|---------|
| `get_server_info` | Returns server capabilities, tool list, resource URIs, and usage guidance |




## Pricing

All standard MCP tools are included in your MarketCheck API subscription at no extra cost. Every tool call consumes API credits the same way a direct REST API request would — there is no additional MCP surcharge.

| Tool    | Pricing |
|---------|---------|
| `search_active_cars` | Included with API subscription |
| `search_past_90_days` | Included with API subscription |
| `predict_price_with_comparables` | Included with API subscription |
| `decode_vin_neovin` | Included with API subscription |
| `get_car_history` | Included with API subscription |
| `search_uk_active_cars` | Included with API subscription |
| `search_uk_recent_cars` | Included with API subscription |
| `get_server_info` | Free |
| `get_sold_summary` | Variable per-query pricing (see [Sold Summary → Pricing](/docs/get-started/api/mcp/tools/sold-summary#pricing)) |


> **NOTE**: 
> The `get_sold_summary` tool is the only exception — it runs against a large-scale analytical data warehouse and is billed separately based on query complexity. See the [Sold Summary documentation](/docs/get-started/api/mcp/tools/sold-summary#pricing) for details.



## Market Coverage

| Region           | Active Inventory | Historical Data  | Price Prediction |
|------------------|------------------|------------------|------------------|
| United States | Yes | Yes (90 days + 5-year sold summary) | Yes |
| Canada | Yes | Yes (90 days) | — |
| United Kingdom | Yes | Yes (90 days) | — |




## MCP Resources

In addition to tools, the server exposes MCP resources that provide metadata and discovery information to clients:

| Resource URI | Description  |
|--------------|--------------|
| `car://search/active` | Active search schemas, parameter definitions, and examples |
| `car://search/facets` | Available filter facets and their valid values |
| `recent://search/info` | Historical search capabilities and constraints |
| `price://predict/info` | Price prediction documentation and parameters |
| `history://car/info` | Listing history information and usage |
| `vin://decode/info` | VIN decoder capabilities and response format |
| `sold-summary://info` | Sold vehicle analysis features and ranking options |




## Transport Modes

The server supports two transport protocols depending on your deployment:

- **STDIO** — Default mode for desktop MCP clients like Claude Desktop and Cursor. The client spawns the server as a subprocess and communicates through standard input/output.
- **StreamableHTTP** — HTTP-based transport for web applications and remote deployments. The server runs as a persistent HTTP service.



## Key Design Decisions

Several design choices make the server well-suited for AI consumption:

- **Token optimization** — Large response objects (dealer details, build specs, full photo arrays) are stripped by default to reduce token usage. Enable them explicitly when needed.
- **Type coercion** — LLMs sometimes send numbers as strings. The server automatically handles this, accepting `"5"` where an integer is expected.
- **Facets-first workflow** — The server encourages discovering exact filter values before searching, preventing empty results from mismatched values.



## See Also

- [Getting Started](/docs/get-started/api/mcp/getting-started) — Install and configure the server
- [Workflows & Use Cases](/docs/get-started/api/mcp/workflows) — Common patterns and recipes