# cox-automotive-mcp

First MCP server for the auto-dealership vertical. Lets Claude, Cursor, or any MCP client read dealer accounts, look up manufacturer incentives, and manage inventory listings through the Cox Automotive / Dealer Developer Portal API.

Cox Automotive is the umbrella for the auto-dealership ecosystem — Dealer.com (websites + digital marketing), vAuto (inventory + pricing), Dealertrack (DMS + financing), VinSolutions (CRM), and more. This MCP covers the publicly-documented Dealer Developer Portal API surface (Accounts, Incentives, Inventory). Other Cox brands expose additional partner-gated APIs that will be added as their surfaces become publicly documented.

## Why this exists

17,000+ US auto dealerships depend on Cox Automotive for daily operations. There's no MCP for the vertical. Existing AI tooling targets generic CRMs (HubSpot, Salesforce) that dealers don't run. This is the first.

## 12 tools

| Tool | What it does |
|---|---|
| `health_check` | Verify `COX_AUTO_API_KEY` works. |
| `list_accounts` | Paginated list of dealer accounts the API key can access. |
| `iter_accounts` | Flat list of all accounts (auto-paginates). |
| `get_account` | One dealer account by id. |
| `list_incentives` | Paginated incentives (rebates, finance offers) for an account. |
| `get_incentive` | One incentive by id within an account. |
| `search_incentives` | Filter incentives by vehicle make/model/year. |
| `list_inventory` | Paginated vehicles in a dealer's inventory. |
| `iter_inventory` | Flat list of all inventory vehicles (auto-paginates). |
| `get_vehicle` | One vehicle listing by id. |
| `create_vehicle` | Add a vehicle to inventory. |
| `update_vehicle` | Update fields on a vehicle (price, mileage, photos, status). |
| `delete_vehicle` | Remove a vehicle from inventory. |
| `search_inventory` | Filter inventory by make/model/year/price range. |

## Install

```bash
pip install cox-automotive-mcp
```

Or from source:

```bash
git clone https://github.com/sanjibani/cox-automotive-mcp
cd cox-automotive-mcp
pip install -e ".[dev]"
```

## Configure

```bash
export COX_AUTO_API_KEY=<your-dealer-developer-portal-api-key>
```

Get your API key by registering at https://developer.inv.dealer.com (My Account → Register). Cox Automotive's Mashery-backed API uses header-based API keys.

Optional overrides:
- `COX_AUTO_BASE_URL` — change the API base (sandbox, regional)
- `COX_AUTO_AUDIT_LOG` — JSONL audit log file path (defaults to stderr)

## Run

```bash
cox_automotive_mcp
```

Add to your MCP client config (Claude Desktop, Cursor, etc.):

```json
{
  "mcpServers": {
    "cox-automotive": {
      "command": "cox_automotive_mcp",
      "env": {
        "COX_AUTO_API_KEY": "your-key-here"
      }
    }
  }
}
```

## Example prompts

Once connected to your MCP client:

- "Show me every dealer account this API key has access to."
- "What Honda Civic 2024 incentives are available for dealer 1042?"
- "List all vehicles under $25,000 in dealer 1042's inventory."
- "Add this 2023 Toyota Camry I just took in: VIN 4T1B11HK5KU123456, 18,500 miles, asking $24,995, stock number P1042-12."
- "Vehicle 9001 just had new photos taken — update the photo URL to https://cdn.example.com/9001-v2.jpg."
- "Vehicle 9017 sold. Remove it from inventory."

## Architecture

Built on the `mcp-vertical-template` industry-leading patterns:

- **Shared `httpx.AsyncClient`** with connection pooling (100 max, 20 keepalive) + transport-level retries
- **Typed exception hierarchy** (`CoxAutomotiveAuthError`, `RateLimitError`, `NotFoundError`, `APIError`, `ConnectionError`) with structured fields (`http_status`, `error_code`, `request_id`, `retry_after`, `body`)
- **Application-level retry** with exponential backoff + full jitter, honoring `Retry-After`
- **Auto-paginating iterators** (`iter_accounts`, `iter_inventory`, `iter_incentives`) that walk the `page`/`pageSize` cursor without caller math
- **isError-compliance** — every MCP tool raises on failure so FastMCP sets `isError: true` on the wire (Blackwell Systems audit pattern; agents can't retry indefinitely on errors they can't see)
- **JSONL audit logging** to stderr (or `COX_AUTO_AUDIT_LOG` file) — SOC2 baseline for B2B procurement
- **Property-based tests** (Hypothesis) for JSON round-trips
- **Strict mypy** + **full ruff rule set** + **pytest** with respx HTTP mocking

## Development

```bash
git clone https://github.com/sanjibani/cox-automotive-mcp
cd cox-automotive-mcp
pip install -e ".[dev]"
pytest                    # unit + integration mocks
ruff check src tests      # lint
ruff format --check src tests  # format
mypy src                  # strict type-check
```

Test coverage is enforced at 80% via `pytest --cov`.

## Related MCPs

This is part of a portfolio of vertical MCP servers from the same author. See https://github.com/sanjibani?q=-mcp for the full list, including legal (PracticePanther), insurance (HawkSoft), dental (Open Dental), veterinary (ezyVet), home service (Jobber), church / nonprofit (Realm ACS), and the shared scaffolding template.

For custom MCP server engagements, see https://sanjibani.github.io/mcp-services/.

## License

MIT — Sanjibani Choudhury <schoudhury1991@gmail.com>