# 🚗 CarsXE MCP Server

A modular, extensible Model Context Protocol (MCP) server for querying and analyzing vehicle data from [CarsXE](https://carsxe.com), with beautiful, chat-friendly Markdown output for LLMs and chatbots.

### Products

- [Vehicle History](https://carsxe.com/vehicle-history)
- [Vehicle Plate Decoder](https://carsxe.com/vehicle-plate-decoder)
- [Vehicle Specifications](https://carsxe.com/vehicle-specifications)
- [International VIN Decoder](https://carsxe.com/international-vin-decoder)
- [Vehicle Images](https://carsxe.com/vehicle-images)
- [Vehicle Recalls](https://carsxe.com/vehicle-recalls)
- [Vehicle Market Value](https://carsxe.com/vehicle-market-value)

---

## ℹ️ What is CarsXE MCP Server?

The CarsXE MCP server is a **Node.js/TypeScript** application that exposes a suite of tools for querying comprehensive vehicle data from [CarsXE](https://carsxe.com). It is designed for seamless integration with LLMs (like Anthropic Claude, OpenAI GPT, etc.), chatbots, and developer tools, providing:

- 🧩 **Clean, modular code** for each CarsXE endpoint
- 📝 **Consistent, Markdown-rich output** for chat/LLM environments
- 🛡️ **Robust error handling** and user-friendly messages
- 🔌 **Easy extensibility** for new endpoints and features

---

## 💡 Why Use CarsXE with MCP?

Connecting CarsXE to your AI editor or chat client via MCP gives you a supercharged vehicle data experience — directly inside the tools you already use:

| Benefit                           | Description                                                                                 |
| --------------------------------- | ------------------------------------------------------------------------------------------- |
| **Ask in plain English**          | No need to know API endpoints or parameters — just describe what you want                   |
| **Context-aware answers**         | The AI combines live vehicle data with your question for tailored, actionable responses     |
| **No tab switching**              | Get VIN [specs](https://carsxe.com/vehicle-specifications), [history](https://carsxe.com/vehicle-history), [recalls](https://carsxe.com/vehicle-recalls), and [values](https://carsxe.com/vehicle-market-value) without leaving your editor or chat             |
| **Chain requests effortlessly**   | Decode a plate → get full specs → check recalls → get market value, all in one conversation |
| **Always live data**              | Every query hits the CarsXE API in real time — no stale cache or outdated results           |
| **Works in your favorite editor** | Claude Desktop, Cursor, VS Code, Windsurf, and any MCP-compatible client                    |

---

## ✨ Features

- 🤖 Uses Anthropic Claude to generate comprehensive, professional answers based on the API data and user query
- 🚙 Query [vehicle specs](https://carsxe.com/vehicle-specifications), [history](https://carsxe.com/vehicle-history), [images](https://carsxe.com/vehicle-images), [recalls](https://carsxe.com/vehicle-recalls), [market value](https://carsxe.com/vehicle-market-value), and more
- 🏷️ Decode [license plates](https://carsxe.com/vehicle-plate-decoder) and [international VINs](https://carsxe.com/international-vin-decoder) (including OCR from images)
- 🛠️ Decode OBD (On-Board Diagnostics) codes
- 🎨 All endpoints return elegant, grouped, emoji-rich Markdown
- 🧩 ChatGPT / MCP Apps hosts can render vehicle, market-value, and recall cards via dedicated render tools
- 🧑‍💻 Modular code: types, API logic, and formatters are separated for maintainability
- 🧪 Simple to run, test, and extend

---

## ⚙️ Prerequisites

**CarsXE API key** ([get one here](https://api.carsxe.com/dashboard/developer))

---

## 🖥️ Installation by Editor

All editors use the same remote MCP endpoint. Replace `YOUR_API_KEY` with your actual CarsXE API key in every config below.

---

### Cursor Marketplace / Grok Bot

After listing, install **CarsXE** from the [Cursor Marketplace](https://cursor.com/marketplace) (Grok Bot uses the same catalog). Then open **Plugins → Configure** and set `CARSXE_API_KEY` from the [CarsXE developer dashboard](https://api.carsxe.com/dashboard/developer). Do not commit or paste a real key into the repo.

The Cursor deeplink below remains available as a fallback.

---

### Claude Desktop

#### 1️⃣ Download and Install Claude Desktop

- Go to the official [Claude Desktop download page](https://claude.ai/download)
- Download the installer for your operating system (macOS, Windows, or Linux)
- Install Claude Desktop by following the on-screen instructions

#### 2️⃣ Configure Claude Desktop to Use the CarsXE MCP Server

**a. Open Claude Desktop Settings**

- Launch the Claude Desktop app
- Click on **Claude** in the menu bar
- Select **Settings**
- In the Settings window, go to the **Developer** tab (you may need to scroll or expand advanced options)
- Click **Edit Config** (or **Open Config File**)

**b. Edit the Configuration File**

- This will open the `claude_desktop_config.json` file in your default text editor.
- Locate the `"mcpServers"` section. If it does not exist, add it as shown below.
- Add or update the following entry for CarsXE:

  ```json
  "mcpServers": {
    "carsxe": {
      "command": "npx",
      "args": [
        "mcp-remote@latest",
        "https://mcp.carsxe.com/mcp",
        "--header",
        "X-API-Key: YOUR_API_KEY"
      ]
    }
  },
  ```

- Replace `YOUR_API_KEY` with your actual CarsXE API Key
- **Tip:** You can add multiple MCP servers under `"mcpServers"` if you use more than one.
- **Save** the configuration file and close your editor.

**c. Restart Claude Desktop**

- Close and reopen the Claude Desktop app to apply the new configuration.

  > It may take a short delay for the changes to take effect.

#### 3️⃣ Verify the CarsXE MCP Server is Available

- After restarting, open Claude Desktop.
- Go to the tools or plugins section (usually in the search bar or under a tools menu).
- You should see **CarsXE** listed as an available MCP server/tool.
- Try running a CarsXE tool (e.g., get_vehicle_specs) to verify everything is working.
  > This will only work if your API key is associated with an active subscription.

---

### Cursor

Fallback if the marketplace listing is not available yet:

[Install CarsXE MCP for Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=CarsXE&config=eyJuYW1lIjoiQ2Fyc1hFIiwidXJsIjoiaHR0cHM6Ly9tY3AuY2Fyc3hlLmNvbS9tY3AiLCJoZWFkZXJzIjp7IlgtQVBJLUtleSI6IllPVVJfQVBJX0tFWSJ9fQ==)

The install dialog will open pre-filled with:

| Field      | Value                      |
| ---------- | -------------------------- |
| **Name**   | CarsXE                     |
| **Type**   | streamableHttp             |
| **URL**    | https://mcp.carsxe.com/mcp |
| **Header** | `X-API-Key: YOUR_API_KEY`  |

Replace `YOUR_API_KEY` with your actual [CarsXE API key](https://api.carsxe.com/dashboard/developer), then click **Install**.

---

### Visual Studio Code (GitHub Copilot)

[Install CarsXE MCP for VS Code](vscode:mcp/install?%7B%22name%22%3A%22CarsXE%22%2C%22url%22%3A%22https%3A%2F%2Fmcp.carsxe.com%2Fmcp%22%2C%22headers%22%3A%7B%22X-API-Key%22%3A%22YOUR_API_KEY%22%7D%7D)

After clicking install, you'll need to add your API key manually:

1. Open **Command Palette** (`Ctrl+Shift+P` / `Cmd+Shift+P`)
2. Run **MCP: List Servers**
3. Find **CarsXE** in the list and click on it
4. Click **Show Configuration**
5. Replace `YOUR_API_KEY` with your actual [CarsXE API key](https://api.carsxe.com/dashboard/developer):

```json
   "CarsXE": {
     "type": "http",
     "url": "https://mcp.carsxe.com/mcp",
     "headers": {
       "X-API-Key": "YOUR_ACTUAL_KEY_HERE"
     }
   }
```

6. Save the file — VS Code will connect automatically.

> **Note:** Make sure you have the **GitHub Copilot** extension installed and agent mode enabled (`chat.agent.enabled` in VS Code settings).

---

### Windsurf

#### 1️⃣ Open MCP Configuration

- Go to **Windsurf Settings** → **MCP** (or press `Ctrl+,` and search for MCP)
- Click **"Edit Config"** to open `~/.codeium/windsurf/mcp_config.json`

#### 2️⃣ Add the CarsXE Server

```json
{
  "mcpServers": {
    "carsxe": {
      "command": "npx",
      "args": [
        "mcp-remote@latest",
        "https://mcp.carsxe.com/mcp",
        "--header",
        "X-API-Key: YOUR_API_KEY"
      ]
    }
  }
}
```

#### 3️⃣ Restart Windsurf

Reload the window or restart Windsurf. Open the Cascade chat panel — CarsXE tools will appear automatically.

---

### Other Editors (Manual / Generic)

For any other MCP-compatible client, register a remote MCP server using:

- **Endpoint:** `https://mcp.carsxe.com/mcp`
- **Transport:** HTTP (Streamable HTTP)
- **Auth header:** `X-API-Key: YOUR_API_KEY`

Consult your editor's MCP documentation for the exact configuration format.

---

## 🖼️ ChatGPT / MCP Apps UI (data → render)

Hosts that implement [MCP Apps](https://modelcontextprotocol.io/extensions/apps/overview) (including [ChatGPT](https://developers.openai.com/apps-sdk/mcp-apps-in-chatgpt)) can show inline vehicle cards. CarsXE keeps **fetch tools as data tools** and mounts UI only from dedicated **render tools**, so ChatGPT does not remount an iframe on every lookup.

Recommended call flow:

1. Call a data tool (`get_vehicle_specs`, `get_market_value`, or `get_vehicle_recalls`). It returns Markdown plus `structuredContent` — no `_meta.ui.resourceUri`.
2. The model may refine that structured result.
3. Call the matching render tool (`render_vehicle_card`, `render_market_value`, or `render_recalls`) with those fields.
4. The host loads the `ui://carsxe/…` HTML resource (`text/html;profile=mcp-app`) and renders the card once.

Cards use published tokens from [`@carsxe/design-system`](https://ui.carsxe.com/docs/theming) (`--primary` `#065774`, `--background` `#F9F9F9`, `--card` `#FFFFFF`, rounded-2xl chrome) and the official `Logo` assets `https://ui.carsxe.com/logo-light.png` / `logo-dark.png`.

Auth is unchanged: MCP still requires an API key or OAuth. x402 remains REST-only.

**Preview the cards locally** (no API key, mock data):

```bash
npm run preview:ui
```

Then open `previews/vehicle-card.html`, `previews/market-value.html`, and `previews/recalls.html` in a browser.

---

## 🛠️ Available Tools & Example Prompts

Below is a list of all available CarsXE tools, their parameters, and example prompts. These prompts work in any MCP-connected client.

### 1. `get_vehicle_specs` 🚙

- **Description:** Get comprehensive vehicle specifications by VIN ([Vehicle Specifications](https://carsxe.com/vehicle-specifications))
- **Parameters:**
  - `vin` (string, required): 17-character Vehicle Identification Number
- **Example Prompts:**

  > What are the full specs for VIN `WBAFR7C57CC811956`?

  > Is this a V6 or V8? VIN: `WBAFR7C57CC811956`

  > What trim level is `WBAFR7C57CC811956`?

- **Output:** Markdown-formatted vehicle specs (year, make, model, engine, dimensions, colors, equipment, etc.)

---

### 2. `decode_license_plate` 🏷️

- **Description:** Decode a vehicle's license plate to get VIN and basic info ([Vehicle Plate Decoder](https://carsxe.com/vehicle-plate-decoder))
- **Parameters:**
  - `plate` (string, required): License plate number
  - `state` (string, optional): State abbreviation (e.g., CA)
  - `country` (string, required, default: US): Country code
- **Example Prompts:**

  > What car has license plate `7XER187` in California?

  > Decode plate `7XER187` state `CA`

  > Look up the plate `ABC1234` in Texas

- **Output:** Markdown summary of decoded vehicle info (VIN, make, model, year, etc.)

---

### 3. `decode_international_vin` 🌍

- **Description:** Decode an international VIN for detailed info ([International VIN Decoder](https://carsxe.com/international-vin-decoder))
- **Parameters:**
  - `vin` (string, required): 17-character VIN
- **Example Prompts:**

  > Decode this European VIN: `WF0MXXGBWM8R43240`

  > What car is `WAUZZZ8K9AA123456`? It's a German VIN.

- **Output:** Markdown with international vehicle details (manufacturer, specs, emissions, etc.)

---

### 4. `get_market_value` 💰

- **Description:** Get estimated market value for a vehicle by VIN ([Vehicle Market Value](https://carsxe.com/vehicle-market-value))
- **Parameters:**
  - `vin` (string, required): 17-character VIN
  - `state` (string, optional): US state abbreviation
  - `mileage` (number, optional): Current mileage of the vehicle to adjust the market value
  - `condition` (string, optional): Overall condition of the vehicle — `excellent`, `clean`, `average`, or `rough`
- **Example Prompts:**

  > How much is `WBAFR7C57CC811956` worth?

  > I'm thinking of buying VIN `WBAFR7C57CC811956` — what's a fair price?

  > What's the trade-in value for `WBAFR7C57CC811956` in Florida with 45,000 miles in clean condition?

- **Output:** Markdown with market value breakdown (retail, trade-in, MSRP, etc.)

---

### 5. `get_vehicle_history` 🕓

- **Description:** Get a comprehensive vehicle history report by VIN ([Vehicle History](https://carsxe.com/vehicle-history))
- **Parameters:**
  - `vin` (string, required): 17-character VIN
  - `format` (string, optional): Response format (json or xml)
- **Example Prompts:**

  > Has `WBAFR7C57CC811956` ever been in an accident?

  > Show me the full history for VIN `WBAFR7C57CC811956`

  > How many owners has `WBAFR7C57CC811956` had?

- **Output:** Markdown with history records (junk/salvage, insurance, brands, titles, odometer, etc.)

---

### 6. `get_vehicle_images` 🖼️

- **Description:** Get vehicle images by make, model, and filters ([Vehicle Images](https://carsxe.com/vehicle-images))
- **Parameters:**
  - `make` (string, required)
  - `model` (string, required)
  - `year`, `trim`, `color`, `transparent`, `angle`, `photoType`, `size`, `license`, `format` (all optional)
- **Example Prompts:**

  > Show me photos of a blue 2018 Toyota Tacoma

  > Get images of a red 2022 Ford Mustang GT

  > What does a white 2020 Tesla Model 3 look like?

- **Output:** Markdown with up to 5 images (links, thumbnails, details)

---

### 7. `get_vehicle_recalls` 🚨

- **Description:** Get vehicle recall information by VIN ([Vehicle Recalls](https://carsxe.com/vehicle-recalls))
- **Parameters:**
  - `vin` (string, required): 17-character VIN
- **Example Prompts:**

  > Does `1C4JJXR64PW696340` have any open recalls?

  > I just bought VIN `1C4JJXR64PW696340` — should I be worried about recalls?

  > Check for safety recalls on `WBAFR7C57CC811956`

- **Output:** Markdown with recall details (date, description, risk, remedy, status, etc.)

---

### 8. `read_license_plate_from_image` 🏷️

- **Description:** Recognize and extract license plate(s) from a vehicle image URL ([Vehicle Plate Decoder](https://carsxe.com/vehicle-plate-decoder))
- **Parameters:**
  - `imageUrl` (string, required): Direct URL to an image of a vehicle's license plate
- **Example Prompts:**

  > What's the plate number in this image? `https://imagedelivery.net/moyiiSImjJPI_EZVxNMBBw/f49aed53-d736-4370-f3f4-97418841c800/public`

  > Read the license plate from this photo: `[image URL]`

- **Output:** Markdown with detected plates, confidence scores, bounding boxes, vehicle type, etc.

---

### 9. `extract_vin_from_image` 🔍

- **Description:** Extract the VIN from a vehicle image using OCR
- **Parameters:**
  - `imageUrl` (string, required): Direct URL to an image of a vehicle's VIN
- **Example Prompts:**

  > Extract the VIN from this image: `https://user-images.githubusercontent.com/5663423/30922082-64edb4fa-a3a8-11e7-873e-3fbcdce8ea3a.png`

  > What's the VIN in this photo? `https://res.cloudinary.com/carsxe/image/upload/q_auto/f_auto/v1713204144/base/images/vin-ocr/vin.jpg`

- **Output:** Markdown with detected VIN, confidence, bounding box, and candidates

---

### 10. `get_year_make_model` 📅

- **Description:** Get comprehensive vehicle info by year, make, model, and optional trim ([Vehicle Specifications](https://carsxe.com/vehicle-specifications))
- **Parameters:**
  - `year` (string, required)
  - `make` (string, required)
  - `model` (string, required)
  - `trim` (string, optional)
- **Example Prompts:**

  > What are the specs for a 2020 Toyota Camry?

  > Tell me about the 2019 Honda Civic Sport trim

  > What colors were available on the 2021 Ford F-150?

- **Output:** Markdown with vehicle details, colors, features, options, and packages

---

### 11. `decode_obd_code` 🛠️

- **Description:** Decode an OBD code and get diagnosis information
- **Parameters:**
  - `code` (string, required): OBD code (e.g., P0115)
- **Example Prompts:**

  > My check engine light is on with code `P0115` — what does it mean?

  > Decode OBD code `P0300`

  > I have a `C1234` code on my dashboard — is it serious?

- **Output:** Markdown with code, diagnosis, and date

---

### 12. `check_lien_and_theft` 🔒

- **Description:** Get lien and theft information for a vehicle by VIN
- **Parameters:**
  - `vin` (string, required): 17-character Vehicle Identification Number
- **Example Prompts:**

  > Is there a lien on `WBAFR7C57CC811956`?

  > I'm buying a used car with VIN `WBAFR7C57CC811956` — check if it's stolen

  > Verify the title is clean for `WBAFR7C57CC811956`

- **Output:** Markdown with lien holder information, theft records, recovery dates, and status

---

### 13. `get_recalls_by_ymm` 🚨

- **Description:** Get safety recall information by year, make, and model (no VIN required) ([Vehicle Recalls](https://carsxe.com/vehicle-recalls))
- **Parameters:**
  - `year` (string, required): 4-digit model year
  - `make` (string, required)
  - `model` (string, required)
- **Example Prompts:**

  > Are there any recalls on a 2026 Toyota Corolla?

  > Check safety recalls for a 2019 Honda Civic

  > What recalls affect 2020 Ford F-150s?

- **Output:** Markdown with NHTSA campaign numbers, components, risk, and remedies

---

### 14. `submit_recalls_batch` 📦

- **Description:** Submit an async bulk recall check for up to 10,000 VINs ([Vehicle Recalls](https://carsxe.com/vehicle-recalls))
- **Parameters:**
  - `vins` (string[] or comma-separated string, optional)
  - `csv` (string, optional): inline CSV of VINs
  - `csvUrl` (string, optional): HTTPS URL to a CSV of VINs
  - `webhookUrl` (string, optional): HTTPS webhook when the batch finishes
- **Example Prompts:**

  > Submit a recalls batch for VINs `1HGBH41JXMN109186`, `5YJSA1E26HF000001`, and `1C4JJXR64PW696340`

  > Start a bulk recall check from this CSV URL: `https://example.com/vins.csv`

- **Output:** Markdown with `batchId` and status. Poll `get_recalls_batch_status` next.

---

### 15. `get_recalls_batch_status` 📦

- **Description:** Check the status of a previously submitted recalls batch ([Vehicle Recalls](https://carsxe.com/vehicle-recalls))
- **Parameters:**
  - `batchId` (string, required)
- **Example Prompts:**

  > What's the status of recalls batch `brb_mnablbn7_wvbaqv`?

- **Output:** Markdown with status, processed VIN counts, and hit rate

---

### 16. `get_recalls_batch_results` 📦

- **Description:** Fetch completed bulk recall results as JSON (after status is `completed` or `partial`) ([Vehicle Recalls](https://carsxe.com/vehicle-recalls))
- **Parameters:**
  - `batchId` (string, required)
- **Example Prompts:**

  > Get the recall results for batch `brb_mnablbn7_wvbaqv`

- **Output:** Markdown summary per VIN (truncated for large batches)

---

### 17. `download_recalls_batch` 📦

- **Description:** Download completed bulk recall results as CSV ([Vehicle Recalls](https://carsxe.com/vehicle-recalls))
- **Parameters:**
  - `batchId` (string, required)
- **Example Prompts:**

  > Download the CSV for recalls batch `brb_mnablbn7_wvbaqv`

- **Output:** Markdown preview of the CSV

---

### 18. `get_ymm_options` 📋

- **Description:** List cascading year, make, model, trim, or variant options for dropdowns ([Vehicle Specifications](https://carsxe.com/vehicle-specifications))
- **Parameters:**
  - `dimension` (string, optional): `years` | `makes` | `models` | `trims` | `variants`
  - `year`, `make`, `model`, `trim` (all optional filters)
- **Example Prompts:**

  > What years does CarsXE have vehicle data for?

  > List Toyota models

  > What Tacoma variants were available in 2026?

- **Output:** Markdown list of the inferred or requested dimension

---

### 19. `get_ownership_by_vin` 👤

- **Description:** Enterprise — look up registered owner(s) for a VIN
- **Parameters:**
  - `vin` (string, required): 17-character VIN
  - `include` (string, optional): `demographics,emails,phones,vehicle_history`
- **Example Prompts:**

  > Who is the registered owner of VIN `1FT8X3BT0BEA61538`?

- **Output:** Markdown with owners, contact info, demographics, and vehicle history. Billed per owner record.

---

### 20. `get_ownership_by_person` 👤

- **Description:** Enterprise — look up a person by name, street address, and ZIP
- **Parameters:**
  - `firstName`, `lastName`, `address`, `zip` (required)
  - `include` (string, optional)
- **Example Prompts:**

  > Look up John Sample at 123 Example St, ZIP 90210

- **Output:** Markdown with matched people, contact info, and linked vehicles

---

### 21. `get_ownership_by_address` 👤

- **Description:** Enterprise — look up residents at a street address + ZIP
- **Parameters:**
  - `address`, `zip` (required)
  - `include`, `variant` (optional; prefer `include`)
- **Example Prompts:**

  > Who lives at 123 Example St in ZIP 90210?

- **Output:** Markdown with residents and linked vehicles

---

### 22. `get_ownership_by_zip` 👤

- **Description:** Enterprise — search people in a 5-digit ZIP with optional filters
- **Parameters:**
  - `zip` (string, required)
  - `gender`, `minAge`, `maxAge`, `income`, `page`, `limit`, `include`, `variant` (optional)
- **Example Prompts:**

  > Find people in ZIP 90210 aged 45+ 

  > Search ZIP 49646 for women with income code F

- **Output:** Markdown page of matching records. Billed per record returned (default limit 15, max 100).

---

### 23. `render_vehicle_card` 🖼️

- **Description:** Render a visual VIN identity + key-specs card. Always call `get_vehicle_specs` first and pass its `structuredContent`. ([Vehicle Specifications](https://carsxe.com/vehicle-specifications))
- **Parameters:** `vin` (required) plus optional year, make, model, trim, style, engine, transmission, drivetrain, fuel, MPG, seating, MSRP, built-in country
- **Example Prompts:**

  > Get specs for VIN `WBAFR7C57CC811956`, then show the vehicle card.

- **Output:** MCP Apps / ChatGPT iframe card. Text fallback summarizes the vehicle.

---

### 24. `render_market_value` 🖼️

- **Description:** Render retail and trade-in value bands. Always call `get_market_value` first and pass its `structuredContent`. ([Vehicle Market Value](https://carsxe.com/vehicle-market-value))
- **Example Prompts:**

  > What's VIN `WBAFR7C57CC811956` worth in California? Then show the market value card.

- **Output:** MCP Apps / ChatGPT iframe card. Text fallback summarizes the valuation.

---

### 25. `render_recalls` 🖼️

- **Description:** Render an open-recalls list. Always call `get_vehicle_recalls` first and pass its `structuredContent`. ([Vehicle Recalls](https://carsxe.com/vehicle-recalls))
- **Example Prompts:**

  > Check recalls for VIN `1C4JJXR64PW696340` and show the recalls card.

- **Output:** MCP Apps / ChatGPT iframe card. Text fallback reports recall count.

---

## 🔗 Chaining Tools — Power User Examples

The real power of CarsXE MCP comes from chaining tools in a single conversation:

**Scenario 1 — Pre-purchase due diligence:**

1. > Decode plate `7XER187` in California
2. > Now get its full history
3. > Does it have any open recalls?
4. > What's it worth if I buy it today?

**Scenario 2 — Spotted a car on the street:**

1. > Read the plate from this image: `[photo URL]`
2. > Look up that plate in Texas
3. > Show me photos of that car model

**Scenario 3 — Mechanic / service shop:**

1. > Decode this VIN from the dashboard photo: `[image URL]`
2. > Get its full specs
3. > My customer says the check engine code is P0300 — what does that mean for this vehicle?

**Scenario 4 — Fleet recall scan without VINs:**

1. > List Toyota models for 2020
2. > Check recalls for a 2020 Toyota Camry
3. > Submit a recalls batch for these inventory VINs: `[list]`
4. > Check the batch status, then show results

---

## 🔐 OAuth 2.1 (Claude.ai custom connector)

The hosted server at `https://mcp.carsxe.com/mcp` supports two authentication methods:

1. **API key** (unchanged) — `X-API-Key` header, `Authorization: Bearer <api-key>`, or `?key=` query parameter. Used by Claude Desktop / `mcp-remote` and local clients.
2. **OAuth 2.1** — used by hosted MCP clients such as the Claude.ai custom connector. Clicking **Connect** in Claude.ai runs a standard Authorization Code + PKCE flow: dynamic client registration (RFC 7591), browser sign-in on the CarsXE consent page, then token exchange. Access tokens (`mcp_at_*`, 1 h) map to the user's CarsXE API key; refresh tokens (`mcp_rt_*`, 90 d) are rotated on every refresh.

Requests with no credentials get `401` with a `WWW-Authenticate` challenge, which is what prompts Claude.ai to start the flow.

### Environment variables

| Variable | Default | Purpose |
| --- | --- | --- |
| `OAUTH_ISSUER` | `https://mcp.carsxe.com` | Issuer / endpoint base in the discovery metadata |
| `OAUTH_WEB_BASE` | `https://api.carsxe.com` | CarsXE web app hosting the OAuth logic |
| `MCP_OAUTH_INTERNAL_SECRET` | _(unset)_ | Set in the host environment, never commit. When unset, OAuth bearer tokens are rejected but API-key auth keeps working. |

> The Cloudflare Workers deployment (`src/index.ts`) does not serve the OAuth surface — only the GCP Cloud Run deployment (`src/index.gcp.ts`) behind `mcp.carsxe.com` does.