# MCP

Endpoint: `https://data-services.autouncle.com/mcp`. Full guides per client: https://data-services.autouncle.com/docs/mcp

## Transport

- Streamable HTTP. Each JSON-RPC message is a `POST` with `Content-Type: application/json` and `Accept: application/json, text/event-stream`. Responses are JSON.
- Stateless: no `Mcp-Session-Id`. `tools/call` works without `initialize`. `initialize` returns protocol version `2025-06-18`, server name `autouncle_data`.
- Tools: `valuate_car`, `normalize_vehicle`, `decode_vin`, `decode_hsn_tsn`, `lookup_plate`, `search_vehicles`, `get_valuation`, `get_account`. Prompt: `value_a_car`. Details: [tools.md](tools.md).

## Authentication

- **API key:** `Authorization: Bearer au_test_...` (or `au_live_...`). Any bearer token starting with `au_` is treated as an API key. Test keys give free simulated results.
- **OAuth:** discovered from the `401` response (`WWW-Authenticate: Bearer resource_metadata="https://data-services.autouncle.com/.well-known/oauth-protected-resource/mcp"`). Resource: `https://data-services.autouncle.com/mcp`. Authorization code with S256 PKCE; dynamic client registration supported; no client ID metadata document. The user picks one organization at consent. **OAuth valuations are always live.**
- Scopes: `valuations:write` (valuate_car), `valuations:read` (get_valuation), `catalogue:read` (search_vehicles), `account:read` (get_account), `vehicles:read` (normalize_vehicle, decode_vin, decode_hsn_tsn, lookup_plate). Membership and scopes are re-checked on every call.

## Minimal client configuration

```json
{
  "mcpServers": {
    "autouncle-data": {
      "type": "http",
      "url": "https://data-services.autouncle.com/mcp",
      "headers": { "Authorization": "Bearer ${AUTOUNCLE_API_KEY}" }
    }
  }
}
```

Key names and interpolation syntax differ per client (`${VAR}` in Claude Code, `${env:VAR}` in Cursor and Windsurf, `inputs` in VS Code, `bearer_token_env_var` in Codex). Follow https://data-services.autouncle.com/docs/mcp for the exact format. ChatGPT supports OAuth only.

## Using the tools well

1. Call `get_account` first. Note `key.mode`, scopes and `credits_remaining`.
2. If the identity is ambiguous, use `search_vehicles` (`search` → `generations` with `year` → `drivetrains`) and send IDs in `vehicle.catalogue`.
3. Call `valuate_car` with the REST body as arguments plus a new `idempotency_key`.
4. In live mode, confirm with the user before each valuation or batch.
5. Report price, currency, price basis, 80% interval, grade, warnings, hints and notes; show `attribution_text`.

## Results and errors

- Results come as `structuredContent` and as JSON text in `content`, with the same fields as REST.
- `refused` and `failed` valuations return `isError: true` with the valuation envelope and `error`. Request problems (scope, country, limits) return `isError: true` with a Problem.
- No response headers over MCP: read `retry_after` from the body for `rate_limited`, `concurrency_limited` and `engine_busy`, then retry with the same `idempotency_key` and arguments.
- Authentication failures are HTTP `401` with a JSON-RPC error whose `data` is a Problem.
- Drivetrain filters (`fuel`, `transmission`, `power_hp`) and item lookup by ID exist only over REST; over MCP, list drivetrains and filter them yourself.