vindex-mcp

MCP server for Vindex — 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)

{
  "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:

{
  "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:

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 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