Quick start: API key, REST and MCP

Create an API keyCopy Anchor Link

1. Sign in to Desk and open Settings → API keys.
2. Name: quickstart. Scopes: read:pricing and mcp (add read:listings for listing search and VIN).
3. Press "Create key" and copy it immediately: the key looks like rv_live_… and is shown once.

Keep the key in an environment variable, not in code:

export IMPORTOS_API_KEY="rv_live_..."
export IMPORTOS_API="https://api.importos.app"   # locally: http://127.0.0.1:4114

$env:IMPORTOS_API_KEY = "rv_live_..."
$env:IMPORTOS_API = "https://api.importos.app"

The first request: POST /v1/landed-costCopy Anchor Link

Let us calculate a 2018 Toyota Camry (2.5 L, petrol) from Copart, Trenton (NJ) yard, a $8000 bid, delivery to Kyiv, our fee $700:

curl -s "$IMPORTOS_API/v1/landed-cost" \
  -H "Authorization: Bearer $IMPORTOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "lot_price": 8000,
    "auction": "copart",
    "vehicle": { "vin": "4T1B11HK5JU000001", "year": 2018, "fuel": "petrol", "engine_cc": 2487, "damage": "FRONT END" },
    "from": { "auction_yard": "NJ - TRENTON" },
    "to": { "country": "UA", "city": "Київ" },
    "fee_model": { "model": "fixed", "amount": 700, "currency": "USD" },
    "date": "2026-10-17"
  }'

The response contains items[] (each item has kind, amount, currency, explanation, formula, source, verified), total, total_range, warnings[], assumptions[], rulesVersion, fx[] and confidence. Remember to show warnings to users: rates with verified: false are indicative.

Look at the response headers X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset and X-Request-Id. All request fields: POST /v1/landed-cost.

If you got an error, look at the code field of the application/problem+json response: unauthorized (no or wrong key), insufficient_scope (the key lacks read:pricing), validation_error (the request body), rate_limited (wait Retry-After seconds). The code table: Authentication and limits.

Connect MCP to Claude DesktopCopy Anchor Link

1. In Claude Desktop open Settings → Developer → Edit Config. The file: %APPDATA%\Claude\claude_desktop_config.json (Windows) or ~/Library/Application Support/Claude/claude_desktop_config.json (macOS).
2. Add the server (insert your key):

{
  "mcpServers": {
    "importos": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://api.importos.app/mcp",
        "--header",
        "Authorization:${IMPORTOS_AUTH}"
      ],
      "env": { "IMPORTOS_AUTH": "Bearer rv_live_YOUR_KEY" }
    }
  }
}

The Authorization:${...} form (no space after the colon, the value in env) avoids a known Windows quoting bug with spaces in args.

3. Fully quit Claude Desktop (through the tray, not just the window) and start it again.
4. Ask: "What will a 2018 Toyota Camry 2.5 from Copart NJ cost in Ukraine, a bid of $8000?" Claude will call the calculate_landed_cost tool and return the breakdown.

The tool takes different field names than REST: lot_price_usd, destination_country, our_fee_usd, us_state. An example input:

{
  "lot_price_usd": 8000,
  "auction": "copart",
  "vehicle": {
    "year": 2018,
    "fuel": "petrol",
    "engine_cc": 2487,
    "vin": "4T1B11HK5JU000001",
    "damage": "FRONT END"
  },
  "us_state": "NJ",
  "destination_country": "UA",
  "destination_city": "Kyiv",
  "our_fee_usd": 700,
  "target_currency": "USD"
}

All tools, other clients (Cursor, Claude Code, ChatGPT) and a check with curl: MCP.