# ๐Ÿš— 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 `, 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.