Core Concepts

3.1 Resources and tools

The specification models the dealership as two kinds of capability, mapped onto MCP:

• Resources are things an agent can read — a vehicle in inventory, a lead, a repair order. Resources are addressable, typed, and stable.
• Tools are things an agent can do — create a lead, request a trade valuation, book a service appointment. Tools have typed inputs, typed outputs, and an explicit error contract.

A read MUST NOT have side effects. Any state change MUST be expressed as a tool call.

3.2 Tenancy and dealership scoping

Every resource exists within a dealership (the tenant). A conformant server MUST scope all reads and tools to an explicit dealership context — never return or mutate data across dealerships in a single call. The dealership is identified by a stable dealership_id.

How the context is supplied is implementation-defined (a parameter on the call or a value bound to the access token), but it MUST be explicit and MUST be enforced server-side. A token scoped to one dealership MUST NOT be able to read or act on another. Multi-rooftop groups are modeled as multiple dealerships, not as a blended tenant.

3.3 Identifiers

Every resource MUST carry a stable id that is unique within its namespace for that dealership. Where an industry identifier exists (for example a vin for a vehicle), it MUST be exposed as a named field in addition to id — never as the primary id itself, which is server-scoped.

3.4 Pagination

List operations MUST be cursor-based. A list response includes the page of items and an opaque next_cursor that is absent when the list is exhausted. Servers MUST treat cursors as opaque and MUST NOT require clients to construct them.

{
  "items": [ /* ... */ ],
  "next_cursor": "eyJvIjoyNX0"
}

3.5 Errors

Tools and resources MUST return structured, machine-readable errors with a stable code, a human-readable message, and an optional details object. Codes are namespaced and stable so agents can branch on them.

{
  "error": {
    "code": "deals.trade_value_unavailable",
    "message": "No trade valuation is available for this VIN in this market.",
    "details": { "vin": "1HGCM82633A004352" }
  }
}

Servers SHOULD distinguish retryable from terminal errors and SHOULD NOT leak provider internals or PII in error messages.

3.6 Eventing

For Level 3, a server exposes subscriptions so agents can react to change — a new lead, a status change on a repair order — rather than polling. Events reference the resource by id and carry a change type (created, updated, deleted). Delivery is at-least-once; consumers MUST be idempotent on the resource id and event identifier.

3.7 Time, money, and units

• Timestamps MUST be RFC 3339 / ISO 8601 with an explicit offset.
• Monetary amounts MUST be expressed as a minor-unit integer plus an ISO 4217 currency — never a float.
• Measures (mileage, etc.) MUST carry an explicit unit field.