# vindex-mcp

MCP server for **[Vindex](https://vindexapi.dev)** — Canada-aware, pay-per-call
**vehicle intelligence** for AI agents. Decode any 17-char VIN with its original
factory-warranty terms, read merged US (NHTSA) + Canada (Transport Canada) recalls,
get LLM-clustered known-issue reports (every issue cites a verified ODI complaint number,
with a bundled reliability-aggregates block), and itemized used-car closing costs for all
of Canada + all 50 US states & DC via one unified `purchase-costs` endpoint
(`country=CA|US`). Pay **per call** with USDC on **Base** via **x402** — no signup, no
bundles, no receipts.

- **3 free tools** — no wallet, no API key.
- **4 paid tools** — flat per-call USD prices, settled in USDC on **Base Mainnet** via x402.

Try before you pay: the free `get_sample` tool returns every paid response shape for one
fixed sample vehicle (2013 Ford F-150).

---

## Quick start

### Free tier (no wallet)

```json
{
  "mcpServers": {
    "vindex": {
      "command": "npx",
      "args": ["-y", "vindex-mcp"]
    }
  }
}
```

You get `get_health`, `get_pricing`, `get_sample`.

### Paid tier (with wallet)

Add an EVM wallet private key (0x-prefixed) that holds USDC on **Base Mainnet**:

```json
{
  "mcpServers": {
    "vindex": {
      "command": "npx",
      "args": ["-y", "vindex-mcp"],
      "env": { "EVM_PRIVATE_KEY": "0x..." }
    }
  }
}
```

The paid tools (`decode_vin`, `get_recalls`, `get_known_issues`, `get_purchase_costs`)
then settle each call automatically.

### Install snippets

Claude Code:

```bash
claude mcp add vindex -- npx -y vindex-mcp
# with a wallet:
claude mcp add vindex --env EVM_PRIVATE_KEY=0x... -- npx -y vindex-mcp
```

Claude Desktop / Cursor: add the JSON block above to your MCP config
(`claude_desktop_config.json` or `.cursor/mcp.json`).

---

## Tools

### Free tools

| Tool | Description |
| --- | --- |
| `get_health` | Vindex API health + configured payment mode (live \| mock). |
| `get_pricing` | Endpoint catalog + per-call USD prices, params, networks, sources (`GET /discovery`). |
| `get_sample` | A free sample of any paid response shape (decode / recalls / known-issues / purchase-costs) for the fixed sample vehicle. `decode` includes the factory-warranty block; `known-issues` includes the bundled reliability block; `purchase-costs` returns both CA + US. |

### Paid tools

| Tool | Endpoint | Price (USD) |
| --- | --- | --- |
| `decode_vin` | `GET /v1/decode` | $0.01 — normalized VIN decode **+ original factory-warranty terms** (basic/powertrain/corrosion/roadside/EV-battery). |
| `get_recalls` | `GET /v1/recalls` | $0.01 — merged US + Canada recalls + full decoded vehicle. |
| `get_known_issues` | `GET /v1/known-issues` | $0.05 — LLM-clustered failure modes **+ bundled reliability block + full decode + complaintsAnalyzed**. |
| `get_purchase_costs` | `GET /v1/purchase-costs?country=CA\|US` | $0.02 — unified itemized closing costs for Canada (provinces/territories) or the US (states + DC). |

Prices are flat per call — **no bundles, no entitlements**. Confirm live prices any time
with `get_pricing`. Purchase-costs is ONE endpoint selected by `country=CA|US`: CA requires
`province` (optional `family_gift`, `buyer_has_plates`), US requires `state` (optional
`trade_in`, `local_rate`).

---

## How payments work (x402)

Vindex speaks the [x402](https://x402.org) `exact` scheme. The API's 402 advertises a
**Base** (USDC, EIP-3009) rail; this MCP settles on **Base**:

1. The MCP requests a paid endpoint. With no payment, the API replies **HTTP 402** with
   the accepted terms.
2. The MCP settles the call — via the standard `@x402/fetch` V2 client on a live API, or
   the mock header when the API is in `mode: mock` — and retries.
3. The API returns the data plus a `payment` block (`txHash`, `network`, `priceUsd`, `payer`).

**Compute-first, settle-after:** Vindex computes the full answer **before** charging, so
you are never billed for an error, a validation failure, or a below-threshold answer
(e.g. `get_known_issues` refuses, uncharged, below 15 complaints).

### Mock vs live

`get_health` reports `mode`. When the API is in **mock** mode the paid tools work without
a wallet (a synthetic payer is used and no chain settlement occurs) — useful for trying
the full flow for free. In **live** mode the paid tools require `EVM_PRIVATE_KEY` with
USDC on Base Mainnet; a paid call without a key returns a clear error.

---

## Environment variables

| Variable | Required | Description |
| --- | --- | --- |
| `EVM_PRIVATE_KEY` | No | 0x-prefixed wallet key with **USDC on Base Mainnet**. Required to pay a live API. Free tools work without it; against a mock API the paid tools also work without it. |
| `VINDEX_API_URL` | No | Override the API base URL (default `https://api.vindexapi.dev`). |

---

## Disclaimer

Vindex provides **informational** vehicle data aggregated from public sources (NHTSA,
Transport Canada). It is **not** professional, legal, or purchasing advice, and is
provided as-is without warranty. Recall/complaint data reflects the source databases at
fetch time. Contains information licensed under the Open Government Licence – Canada. See
<https://api.vindexapi.dev/terms.txt>.

Docs for agents: <https://api.vindexapi.dev/llms.txt> ·
full: <https://api.vindexapi.dev/llms-full.txt>

---

## License

MIT © jcislo