1. API Docs

    MCP Integration

    CarJam exposes a Model Context Protocol (MCP) server so AI agents can retrieve vehicle data using the same API products you already have access to. All requests are billed against your Developer API key.

    Endpoint

    <site>/mcp/

    The MCP server speaks JSON-RPC 2.0 over HTTP POST. There is no SSE stream — a GET on the endpoint returns 405 Method Not Allowed.

    Authentication

    Pass your Developer API key in the API-KEY HTTP header on every request. The key is used for rate limiting and billing, identical to the classic REST API.

    The endpoint does not support OAuth, so a client has to be able to send a static header, either natively or through a bridge. Both cases are covered below.

    Configuration: clients that send headers natively

    Cursor, Claude Code, Windsurf and similar clients take the URL and the header directly.

    {
    "mcpServers": {
        "carjam": {
            "url": "https://www.carjam.co.nz/mcp/",
            "headers": {
                "API-KEY": "<Developer API Key>"
            }
        }
    }
}

    Claude Code can be configured from the command line instead:

    claude mcp add --transport http carjam https://www.carjam.co.nz/mcp/ -H "API-KEY: <Developer API Key>"

    Other MCP clients may use their own configuration format, but the endpoint URL and API-KEY header are the only required values.

    Configuration: Claude Desktop

    Claude Desktop's custom connectors expect OAuth and cannot send a static header, so the url form above does not work there. Run the endpoint through mcp-remote instead — a small stdio bridge that adds the header for you. It needs Node.js 18 or newer, so check node -v first.

    1. Open the configuration file. In Claude Desktop, go to Settings > Developer > Edit Config. That opens ~/Library/Application Support/Claude/claude_desktop_config.json on macOS, or %APPDATA%\Claude\claude_desktop_config.json on Windows.

    2. Add the carjam entry, replacing YOUR-KEY-HERE with your Developer API key. If the file already has an mcpServers block, add the entry inside it rather than replacing the file.

    {
    "mcpServers": {
        "carjam": {
            "command": "npx",
            "args": [
                "-y", "mcp-remote",
                "https://www.carjam.co.nz/mcp/",
                "--transport", "http-only",
                "--header", "API-KEY:${CARJAM_API_KEY}"
            ],
            "env": { "CARJAM_API_KEY": "YOUR-KEY-HERE" }
        }
    }
}

    3. Restart Claude Desktop completely — Cmd+Q on macOS, or exit from the system tray on Windows. Closing the window is not enough; the configuration is only read at launch.

    4. Check the connection. Open a new chat and click the tools icon in the message box. carjam should be listed with one tool, CarJam_vehicle_search. Claude asks for your permission the first time it calls the tool.

    Leave ${CARJAM_API_KEY} literal in args and put the key in env: mcp-remote substitutes it at startup, which keeps the key out of process listings and out of its own logs. --transport http-only is required, or mcp-remote spends its first attempt probing for an SSE stream this endpoint does not offer.

    Troubleshooting Claude Desktop

    • The server does not appear. Check the JSON is valid — a trailing comma breaks the whole file silently — then quit and relaunch.
    • Windows, "server disconnected" straight away. Claude Desktop cannot always launch npx directly. Change "command" to "cmd" and start args with "/c", "npx", "-y", "mcp-remote", ....
    • Logs. ~/Library/Logs/Claude/mcp-server-carjam.log on macOS, %APPDATA%\Claude\logs\ on Windows.
    • It keeps asking you to sign in. Delete ~/.mcp-auth and restart. mcp-remote caches authorisation state there and it can go stale.
    • Errors from CarJam. "Invalid API key" means the key is wrong or disabled; "No development connection application" means the account is not an approved developer account; "Cap has been reached for the month" means the spend cap needs raising.

    The key sits in a plain-text file on the machine running Claude Desktop, so issue one key per person rather than sharing one. If your developer account has an IP allowlist, it has to include every machine running the bridge.

    Tools

    The server currently exposes one tool: CarJam_vehicle_search. It accepts a plate or VIN and a set of flags that map directly to the Vehicle queries API product. Charges for each call match the equivalent REST call.

    Parameters

    • plate — Plate number or VIN. Required.
    • basic — Comprehensive vehicle details: make, model, year, body, engine, fuel, seating, registration, WOF/COF, odometer history, licensing, weight, inspections, status flags. Default: true.
    • owner — Add current ownership details (registration number, party type, addresses, trading name, odometer at transfer).
    • owners — Add complete ownership history.
    • rucs — Add RUC licence history (types, dates, weights, hubodometer).
    • ppsr — Add PPSR money owing and security interest search. May take several seconds. Do not retry within 5 minutes for the same plate.
    • ppsrh — Complementary to ppsr. Also searches past plates for money owing. Additional charges apply.
    • valuation — Add market valuation, dealer prices, variants and pricing based on current and estimated odometer.
    • fws — Add fire/water/structural damage write-off warnings.
    • warnings — Add compulsory recalls, write-off and other warnings.
    • cache — Lookup in CarJam cache before going to NZTA. Accepts 0 (no cache), 1 (default 10-year cache), or a strtotime() expression such as -1 month. Not applicable to personalised plates. Cached responses are charged at a minimal rate.

    Agents should pass translate=1 implicitly through the tool to receive human-readable strings instead of raw NZTA codes; the server handles this automatically.

    Response

    The tool returns the same JSON payload as <site>/a/car for the given flag combination. See Vehicle queries for the field reference.

    Example

    With the server configured, an agent can resolve natural-language questions directly:

    Get me the VIN for plate ABC123.

    The agent calls CarJam_vehicle_search with { "plate": "ABC123" } and returns the VIN plus basic vehicle details from the response.

    What's the WOF status and are there any money owed?

    The agent calls the tool with { "plate": "ABC123", "ppsr": true } and reports the latest WOF inspection result, expiry date and PPSR money owing status in one turn.

    Terms

    Use of the MCP server is subject to the API Terms and Conditions. All requests are billed against your Developer API key at the same rates as the equivalent REST calls.

    — 👩‍💻 API