# NoDTC Custom Connector for Personal Agents

This document is written for personal agents (Meta Muse, Claude, ChatGPT, Grok, Gemini) to read while connecting to NoDTC vehicle diagnostic, health scan, and visual screenshot evidence tools.

## Connection Details

- **Protocol**: Model Context Protocol (MCP) over Streamable HTTP
- **Production MCP Endpoint**: `https://nodtc.com/api/v2/connector/mcp`
- **Development MCP Endpoint**: `https://dev.nodtc.com/api/v2/connector/mcp`
- **Authentication**: Send `Authorization: Bearer <token>` on every request.
- **Credential Format**: A single Tenant API Key starting with `nodtc_live_`.
- **How to Get a Key**: If the user does not have a key, instruct them to log into [NoDTC](https://nodtc.com/app), open **Settings** &rarr; **Integrations**, and click **Generate Key** under **Tenant API Keys**.
- **Credential Storage**: Keep the user's key in Muse's Secure Credentials Store. Never print it in chat or put it in a URL.
- **Icon**: `https://nodtc.com/nodtc_app_logo_512x512.png`

## Handshake & Verification

To verify the connection, call the harmless read tool `verify_connector`. It confirms that the key is active and returns the authorized salvage yard organization (`entity_id` and `organization_name`).

## Available Actions (Read-Only)

1. **`verify_connector`**
   - **Description**: Verifies that the Tenant API Key is valid and active, and returns the authorized yard organization details.
   - **Input**: `{}` (no parameters required).

2. **`get_latest_vehicle_session`**
   - **Description**: Retrieves the most recent diagnostic scan session for a given 17-character VIN. Returns vehicle attributes (year, make, model), odometer value, health scan system summary, and public screenshot download URLs.
   - **Required Parameters**:
     - `vin`: The 17-character Vehicle Identification Number (VIN).

3. **`search_sessions`**
   - **Description**: Searches diagnostic scan sessions by filter criteria. Returns an array of matching sessions with timestamps, operator info, odometer readings, and `is_latest` flags so the agent or user can choose.
   - **Optional Parameters**:
     - `vin`: 17-character VIN to filter sessions.
     - `date`: Date of the session in `YYYY-MM-DD` format (searches the full 24-hour day).
     - `start_time`: ISO 8601 start timestamp filter.
     - `end_time`: ISO 8601 end timestamp filter.
     - `device_id`: Tablet or workstation device identifier.
     - `operator`: Email or username of the operator who started the scan.
     - `limit`: Maximum number of records to return (default: 10, max: 50).

4. **`get_session_details`**
   - **Description**: Retrieves complete diagnostic records and screenshot manifests for a specific `session_id`.
   - **Required Parameters**:
     - `session_id`: The session identifier (e.g., `sess_...`).

## Rules for Agents

- When the user asks for diagnostic results or screenshots for a VIN, call `get_latest_vehicle_session`.
- If the user asks about scans on a particular date or multiple scans exist for a vehicle, call `search_sessions` and present the session timestamps and operators to the user.
- If `odometer.value` is `null` and `odometer.status` is `"NOT_AVAILABLE"`, inform the user that the odometer was evaluated in the vehicle's health scan report but was not available on this vehicle.
- Screenshot URLs in the response are permanent public verification links (`https://nodtc.com/v/...`) featuring authentic QR codes and timestamp overlays. You can present these URLs directly to the user for download or inspection.
- Diagnostic data updates and tablet control are read-only via personal agents and are managed directly in the NoDTC web application.
