Vehicle data inside your AI agent

# Vehicle data inside your AI agent

Connect CarsXE's hosted MCP server to your assistant or editor. Decode VINs and plates, retrieve vehicle records, and build workflows with named tools.

## What MCP enables

Model Context Protocol gives compatible AI agents a standard way to discover and call vehicle-data tools. Use MCP when your assistant should select tools from a schema and work with the returned records. Use [REST or SDKs](https://carsxe.com/compare) when your application should control requests directly.

The hosted vehicle-data server is separate from the documentation-search MCP at https://docs.carsxe.com/api/docs/mcp. Documentation search retrieves guidance; vehicle tools perform lookups using your CarsXE account.

## Endpoint and prerequisites

- Endpoint: https://mcp.carsxe.com/mcp
- Transport: Streamable HTTP
- API-key header: `X-API-Key`
- Requirements: a CarsXE account with access to the requested API and an MCP-compatible client.
- Node.js and npm are required only for clients using the local mcp-remote bridge. Direct HTTP clients do not need a local CarsXE server.

[Create an account](https://carsxe.com/signin) and get your key from the [developer dashboard](https://carsxe.com/dashboard/developer). Replace `YOUR_API_KEY` in the examples. Keep credentials in your client configuration; this page does not collect API keys.

## Connect with your CarsXE account

For Claude's supported remote connectors, open Settings → Connectors, add a custom connector with URL https://mcp.carsxe.com/mcp, then connect. Sign in to CarsXE and authorize access in the CarsXE window. The client receives an account-bound access token.

OAuth support depends on the client. The API-key configurations below remain available for clients that support headers. Requests use your CarsXE plan and its endpoint access. See [remote connector guidance](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp).

## Set up your client

### Claude Desktop

Configuration: `Settings → Developer → Edit Config`

Install Node.js and npm for this local bridge. Merge the entry into claude_desktop_config.json, replace the placeholder, then restart Claude Desktop. Alternatively, use the account connector described below.

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

[Official client documentation](https://support.claude.com/en/articles/10949351-getting-started-with-local-mcp-servers-on-claude-desktop)

### Cursor

Configuration: `.cursor/mcp.json or ~/.cursor/mcp.json`

Merge this entry, replace the placeholder, then enable CarsXE in the MCP settings and verify the tool list.

```json
{
  "mcpServers": {
    "carsxe": {
      "url": "https://mcp.carsxe.com/mcp",
      "headers": {
        "X-API-Key": "YOUR_API_KEY"
      }
    }
  }
}
```

[Official client documentation](https://docs.cursor.com/context/model-context-protocol)

### VS Code

Configuration: `.vscode/mcp.json`

Use the servers key in mcp.json. Replace the placeholder, run MCP: List Servers and start CarsXE. Enable the compatible agent experience in GitHub Copilot.

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

[Official client documentation](https://code.visualstudio.com/docs/agent-customization/mcp-servers)

### Windsurf

Configuration: `~/.config/devin/mcp_config.json`

For legacy Cascade only: open the Cascade Actions menu, choose Open MCP config file, merge this entry and replace the placeholder, then verify the CarsXE tool list. This is the macOS/Linux path; Windows uses %APPDATA%\devin\mcp_config.json. Devin Local uses [Devin CLI MCP configuration](https://docs.devin.ai/cli/extensibility/mcp/configuration) instead.

```json
{
  "mcpServers": {
    "carsxe": {
      "serverUrl": "https://mcp.carsxe.com/mcp",
      "headers": {
        "X-API-Key": "YOUR_API_KEY"
      }
    }
  }
}
```

[Official client documentation](https://docs.devin.ai/desktop/cascade/mcp)

### Claude CLI

Configuration: `Terminal`

Replace the placeholder before running. Start Claude Code and inspect /mcp to verify the server.

```bash
claude mcp add --transport http carsxe https://mcp.carsxe.com/mcp \
  --header "X-API-Key: YOUR_API_KEY"
claude mcp list
```

[Official client documentation](https://code.claude.com/docs/en/mcp)

### Gemini CLI

Configuration: `~/.gemini/settings.json`

Use httpUrl for Streamable HTTP. Merge the entry, replace the placeholder, restart Gemini and inspect /mcp.

```json
{
  "mcpServers": {
    "carsxe": {
      "httpUrl": "https://mcp.carsxe.com/mcp",
      "headers": {
        "X-API-Key": "YOUR_API_KEY"
      }
    }
  }
}
```

[Official client documentation](https://geminicli.com/docs/tools/mcp-server/)

### Kiro CLI

Configuration: `~/.kiro/settings/mcp.json`

Merge the entry, replace the placeholder, then start kiro-cli and inspect /mcp.

```json
{
  "mcpServers": {
    "carsxe": {
      "url": "https://mcp.carsxe.com/mcp",
      "headers": {
        "X-API-Key": "YOUR_API_KEY"
      },
      "disabled": false
    }
  }
}
```

[Official client documentation](https://kiro.dev/docs/mcp/configuration/)

### Codex CLI

Configuration: `~/.codex/config.toml`

Merge this TOML section, replace the placeholder, restart Codex and inspect /mcp.

```toml
[mcp_servers.carsxe]
url = "https://mcp.carsxe.com/mcp"
http_headers = { "X-API-Key" = "YOUR_API_KEY" }
```

[Official client documentation](https://developers.openai.com/codex/mcp)

## Documented vehicle tools

These core tools and inputs were checked against the [public hosted server implementation](https://github.com/carsxe/carsxe-mcp-server/blob/main/src/registerTools.ts) on October 6, 2026. This is a documented core list, not an exhaustive list of every hosted tool. Your connected client's tools/list response is authoritative for its current schema.

| Tool | Required inputs | Optional inputs | Returns |
| --- | --- | --- | --- |
| `get_vehicle_specs` | vin (17 characters) | None | Year, make, model and vehicle specifications |
| `decode_international_vin` | vin (17 characters) | None | International vehicle attributes |
| `decode_license_plate` | plate, state (2 characters) | country (default US) | VIN and basic vehicle information |
| `get_market_value` | vin (17 characters) | state, mileage (number), condition (excellent, clean, average or rough) | Estimated retail and trade-in values |
| `get_vehicle_history` | vin (17 characters) | format (default json) | Available title, salvage and history records |
| `get_vehicle_images` | make, model | year, trim, color, transparent, angle, photoType, size, license, format | Vehicle image URLs |
| `get_vehicle_recalls` | vin (17 characters) | None | Available recall campaigns |
| `extract_vin_from_image` | imageUrl (public image URL) | None | Recognized VIN text |
| `read_license_plate_from_image` | imageUrl (public image URL) | None | Recognized plate information |
| `get_year_make_model` | year, make, model (strings) | trim | Vehicle information by year, make and model |
| `decode_obd_code` | code | None | Diagnostic trouble-code information |
| `check_lien_and_theft` | vin (17 characters) | None | Available lien and theft records |

The hosted server uses underscore names. The older local stdio package uses different names; do not copy those names into hosted calls. Selected tools return structuredContent alongside Markdown text; clients should inspect the actual response rather than assume every result is JSON.

## Build a vehicle workflow

- Plate → VIN → specifications: call `decode_license_plate` with the plate and region, then pass the returned VIN to `get_vehicle_specs`.
- VIN → history and value: call `get_vehicle_history` and `get_market_value`; supply mileage and condition when available.
- Image → OCR → lookup: call `extract_vin_from_image` or `read_license_plate_from_image`, validate the recognized identifier, then call the corresponding lookup.

Example prompt: “Decode VIN WBAFR7C57CC811956, summarize its specifications, and estimate its market value.” Each lookup is a separate request; your assistant controls orchestration.

## Coverage and billing

MCP exposes CarsXE vehicle APIs through tools. Availability depends on the tool, region, record and your plan. Do not assume every REST endpoint is exposed by MCP, every field is returned, or every tool supports every country.

| Capability | MCP tool | REST API | SDK availability | Limitations |
| --- | --- | --- | --- | --- |
| VIN specifications | `get_vehicle_specs` | [Endpoint reference](https://docs.carsxe.com/api-reference/specifications/vehicle-specifications-vin-decoder) | Node.js: decodeVin | Returned fields vary by VIN and market. |
| International VIN | `decode_international_vin` | [Endpoint reference](https://docs.carsxe.com/api-reference/specifications/international-vin-decoder) | Check the selected language's reference | Coverage and available attributes vary by country. |
| Plate lookup | `decode_license_plate` | [Endpoint reference](https://docs.carsxe.com/api-reference/plate-decoder/license-plate-decoder-v2) | Node.js: decodePlate | Country/state support varies; this tool requires a state. |
| Market value | `get_market_value` | [Endpoint reference](https://docs.carsxe.com/api-reference/market-value/vehicle-market-value-v2) | Node.js: getMarketValue | Estimates depend on available records, mileage and condition. |
| Vehicle history | `get_vehicle_history` | [Endpoint reference](https://docs.carsxe.com/api-reference/history/vehicle-history) | Node.js: getVehicleHistory | An empty result is not proof that a vehicle has no past events. |
| Vehicle images | `get_vehicle_images` | [Endpoint reference](https://docs.carsxe.com/api-reference/images/vehicle-images) | Check the selected language's reference | Availability varies. License filters do not grant usage rights. |
| Safety recalls | `get_vehicle_recalls` | [Endpoint reference](https://docs.carsxe.com/api-reference/recalls/vehicle-recalls) | Node.js: getRecalls | Coverage and repair status depend on the source record. |
| VIN OCR | `extract_vin_from_image` | [Endpoint reference](https://docs.carsxe.com/api-reference/recognition/vin-ocr) | Check the selected language's reference | Image quality affects recognition; validate the VIN before lookup. |
| Plate OCR | `read_license_plate_from_image` | [Endpoint reference](https://docs.carsxe.com/api-reference/recognition/plate-image-recognition) | Check the selected language's reference | Recognition and plate-to-VIN lookup are separate operations. |
| Year / make / model | `get_year_make_model` | [Endpoint reference](https://docs.carsxe.com/api-reference/year-make-model/year-make-model) | Check the selected language's reference | Available trims and attributes vary by vehicle. |
| OBD codes | `decode_obd_code` | [Endpoint reference](https://docs.carsxe.com/api-reference/year-make-model/obd-codes-decoder) | Check the selected language's reference | A code description alone does not diagnose a vehicle. |
| Lien and theft | `check_lien_and_theft` | [Endpoint reference](https://docs.carsxe.com/api-reference/lien-and-theft/lien-theft-records) | Check the selected language's reference | Results reflect available records and are not a title guarantee. |

Vehicle lookups count toward your CarsXE plan's usage. Consult [current pricing](https://carsxe.com/pricing) and the relevant endpoint reference for costs and allowances. Data freshness depends on the underlying source; a live API request does not guarantee a recently updated record.

## Verify and troubleshoot

1. Confirm your client connects and lists CarsXE tools. This verifies setup before you request a vehicle lookup.
2. Check the listed input schema, then make a lookup using a vehicle you are authorized to query. A lookup consumes plan usage.
3. For authentication errors, check the API key or reconnect your account, then confirm endpoint access and available usage.
4. For connection failures, verify https://mcp.carsxe.com/mcp; bridge clients must also have Node.js/npm available.
5. For missing tools or schema errors, refresh the tool list and compare names with the connected server.
6. For empty records, check identifier accuracy and endpoint coverage. Do not substitute guessed data.

[Canonical MCP documentation](https://docs.carsxe.com/docs/integrations/mcp) · [API status](https://carsxe.com/status) · [Support](https://carsxe.com/support)