# Carregados API and MCP

Carregados exposes public REST resources, a scoped authenticated API, a hosted stateless MCP server, OpenAPI 3.1, and machine-readable discovery.

## Start here

- MCP endpoint: `https://carregados.com.br/mcp`
- MCP discovery: [/.well-known/mcp.json](https://carregados.com.br/.well-known/mcp.json)
- Authentication: [/auth.md](https://carregados.com.br/auth.md)
- OAuth discovery: [/.well-known/oauth-authorization-server](https://carregados.com.br/.well-known/oauth-authorization-server)
- Protected resource: [/.well-known/oauth-protected-resource](https://carregados.com.br/.well-known/oauth-protected-resource)
- OpenAPI: [/openapi.json](https://carregados.com.br/openapi.json)
- Agent guide: [/docs/agents.md](https://carregados.com.br/docs/agents.md)
- Markdown routes: [/routes.md](https://carregados.com.br/routes.md)

## Hosted MCP server

The single remote endpoint uses stateless Streamable HTTP. It implements MCP `2026-07-28`, including per-request envelopes, `Mcp-Method` and `Mcp-Name` routing headers, deterministic tool ordering, and cache hints. Stateless 2025 Streamable HTTP requests remain supported during migration; there is no SSE-only or stdio endpoint.

Public-only client configuration:

```json
{
  "mcpServers": {
    "carregados": {
      "url": "https://carregados.com.br/mcp"
    }
  }
}
```

For account tools, use OAuth Authorization Code with S256 PKCE through the MCP protected-resource metadata at https://carregados.com.br/.well-known/oauth-protected-resource/mcp. If the client cannot use OAuth, place a manually provisioned `Authorization: Bearer cg_...` token in secure HTTP-header configuration. Do not put credentials directly in a shared config file.

## Public API

No authentication is required:

- `GET /api/public/stations?state=parana%20(pr)&city=curitiba`
- `GET /api/public/stations/:stationId`
- `GET /api/public/stations/map?latitude=-25.43&longitude=-49.27&radiusKm=25&minPowerKw=50&connectorIds=20&verified=true`
- `GET /api/public/places?q=Curitiba`
- `GET /api/public/vehicles?q=Dolphin`
- `GET /api/public/vehicles/:vehicleId?subtypeId=:subtypeId`
- `GET /api/public/cars?maker=byd&state=parana%20(pr)`
- `GET /api/public/cars/:carId`
- `GET /api/public/market-data`
- `POST /api/v1/routes/plan` (authentication optional)

Public station search/detail/map, place-search, and favorite-station responses omit exact coordinates; caller-provided coordinates are used only for search and `distanceKm`. Route-planning responses may include route geometry, and authenticated owned-location responses retain their coordinates. The station-map endpoint supports status, 24/7, minimum/maximum power, maximum price, review count, network, connector, amenity, POI, verification, and photo filters. Public car responses omit seller contact data, owner ids, drafts, and removed listings.

Example:

```bash
curl --fail-with-body \
  --header 'Accept: application/json' \
  'https://carregados.com.br/api/public/stations?state=parana%20(pr)&city=curitiba'
```

## Authenticated API

```http
Authorization: Bearer cg_...
```

Supported scopes: `cars:read`, `cars:write`, `locations:read`, `locations:write`, `routes:plan`, `garage:read`, `garage:write`, `favorites:read`, `favorites:write`, `trips:read`, `trips:write`, `checkins:read`, `checkins:write`, `notifications:read`, `notifications:write`, `destaques:write`, `checkout:create`.

Endpoints:

- `GET /api/v1/me`
- `GET|POST /api/v1/cars`
- `GET|PATCH|DELETE /api/v1/cars/:carId`
- `POST /api/v1/routes/plan`
- `GET|POST /api/v1/locations`
- `GET|PATCH /api/v1/locations/:locationId`
- `GET|POST /api/v1/garage`
- `GET|PATCH|DELETE /api/v1/garage/:vehicleId`
- `GET /api/v1/favorites`
- `PUT|DELETE /api/v1/favorites/:stationId`
- `GET|POST /api/v1/trips`
- `GET|PATCH|DELETE /api/v1/trips/:tripId`
- `GET /api/v1/check-ins`
- `POST /api/v1/stations/:stationId/check-ins`
- `DELETE /api/v1/check-ins/:checkInId`
- `GET|PATCH /api/v1/notifications`
- `GET|PATCH /api/v1/notification-preferences`
- `POST /api/v1/locations/:locationId/destaque/checkout`

Example token check:

```bash
curl --fail-with-body \
  --header 'Authorization: Bearer cg_...' \
  --header 'Accept: application/json' \
  'https://carregados.com.br/api/v1/me'
```

Authenticated mutations enforce ownership and scopes, rate limit by token/user, accept request correlation through `X-Request-Id`, and write audit events. Create operations accept an `Idempotency-Key` for safe retries, while mutable detail resources expose `ETag` and accept `If-Match` to reject stale writes. API authentication failures return a standards-based `WWW-Authenticate` challenge with protected-resource discovery. See [auth.md](https://carregados.com.br/auth.md) for OAuth, agent registration, manual provisioning, and revocation.

## Markdown representations

- `GET /routes.md`
- `GET /estacoes.md` and `GET /estacoes/:stationId.md`
- `GET /carros.md` and `GET /carros/:carId.md`
- `GET /dados-sobre-o-mercado-eletrico.md`
- `GET /planejador.md`

Selected HTML routes also support `Accept: text/markdown`.

## MCP tool reference

### `search_public_stations`

Search public charging-station data by state, city, or caller-provided origin without exposing station coordinates.

- Auth: No authentication required.
- Mutates data: no.
- Requires confirmation: no.
- Costed/abuse-controlled: no.

Required inputs:
- None.

Optional inputs:
- `state` (string, optional): Brazilian state value used by Carregados, for example "parana (pr)".
- `city` (string, optional): City value used by Carregados, for example "curitiba".
- `latitude` (number, optional): Caller-provided origin latitude used only to calculate distanceKm.
- `longitude` (number, optional): Caller-provided origin longitude used only to calculate distanceKm.
- `limit` (integer, optional): Page size from 1 to 25.
- `page` (integer, optional): 1-based page number.

Output:
- Query context, station summaries, public trip-planning links, and distanceKm only when caller origin is supplied.

Example:

```json
{
  "state": "parana (pr)",
  "city": "curitiba",
  "limit": 10
}
```

Notes:
- Does not return station latitude, longitude, entrance coordinates, or encoded map coordinates.
- Use caller-provided latitude/longitude only for distance calculations.

### `get_public_station`

Get public details for one charging station without exposing station coordinates.

- Auth: No authentication required.
- Mutates data: no.
- Requires confirmation: no.
- Costed/abuse-controlled: no.

Required inputs:
- `stationId` (integer, required): Public Carregados station id.

Optional inputs:
- `latitude` (number, optional): Caller-provided origin latitude used only to calculate distanceKm.
- `longitude` (number, optional): Caller-provided origin longitude used only to calculate distanceKm.

Output:
- Public station facts, connector/pricing/review context, canonical URL, and distanceKm only when caller origin is supplied.

Example:

```json
{
  "stationId": 123,
  "latitude": -25.43,
  "longitude": -49.27
}
```

Notes:
- Does not return station latitude, longitude, entrance coordinates, or encoded map coordinates.

### `search_public_cars`

Search active public electric-car listings by maker, model, location, price, range, year, or condition.

- Auth: No authentication required.
- Mutates data: no.
- Requires confirmation: no.
- Costed/abuse-controlled: no.

Required inputs:
- None.

Optional inputs:
- `maker` (string, optional): Vehicle maker/brand, for example "byd".
- `model` (string, optional): Vehicle model, for example "dolphin".
- `version` (string, optional): Vehicle version/trim.
- `state` (string, optional): Brazilian state value used by Carregados, for example "parana (pr)".
- `city` (string, optional): City value used by Carregados, for example "curitiba".
- `condition` (string, optional): Listing condition, for example "new" or "used".
- `listingType` ("particular" | "concessionaria", optional): Filter by private or dealership listing type.
- `sellerType` (string, optional): Filter by seller type label.
- `minPrice` (number, optional): Minimum price in BRL.
- `maxPrice` (number, optional): Maximum price in BRL.
- `minYear` (number, optional): Minimum model year.
- `maxYear` (number, optional): Maximum model year.
- `minRange` (number, optional): Minimum range in km.
- `maxRange` (number, optional): Maximum range in km.
- `minOdometer` (number, optional): Minimum odometer in kilometers.
- `maxOdometer` (number, optional): Maximum odometer in kilometers.
- `sort` ("newest" | "price_asc" | "price_desc" | "popular", optional): Result sorting mode.
- `limit` (integer, optional): Page size from 1 to 25.
- `page` (integer, optional): 1-based page number.

Output:
- Search query, active public listing summaries, pagination context, and canonical listing URLs.

Example:

```json
{
  "maker": "byd",
  "model": "dolphin",
  "state": "parana (pr)",
  "sort": "newest"
}
```

Notes:
- Does not return seller private contact fields, owner ids, drafts, inactive listings, or removed listings.

### `get_public_car`

Get details for one active public electric-car listing.

- Auth: No authentication required.
- Mutates data: no.
- Requires confirmation: no.
- Costed/abuse-controlled: no.

Required inputs:
- `carId` (integer, required): Public Carregados car listing id.

Optional inputs:
- None.

Output:
- Public listing facts, vehicle attributes, canonical URL, and safe seller-facing public fields.

Example:

```json
{
  "carId": 123
}
```

Notes:
- Does not return seller private contact fields, owner ids, drafts, inactive listings, or removed listings.

### `get_public_market_data`

Get public Brazil EV sales, charging-station distribution, and recent route-demand signals.

- Auth: No authentication required.
- Mutates data: no.
- Requires confirmation: no.
- Costed/abuse-controlled: no.

Required inputs:
- None.

Optional inputs:
- None.

Output:
- Brazil EV sales, station distribution, listing context, and route-demand aggregates.

Example:

```json
{}
```

Notes:
- Uses public aggregate data only.

### `plan_route`

Plan an EV route with manual vehicle range, battery capacity, waypoints, battery targets, and station preferences.

- Auth: Authentication optional. If supplied, token scope required: routes:plan.
- Mutates data: no.
- Requires confirmation: no.
- Costed/abuse-controlled: yes.

Required inputs:
- `waypoints` (array<{ latitude: number; longitude: number; label?: string }>, required): Ordered route waypoints. The first point is origin and the last point is destination. Accepts 2 to 11 points.

Optional inputs:
- `vehicleId` (integer, optional): Public catalog vehicle id used to fill range and battery defaults.
- `subtypeId` (integer, optional): Optional catalog variant id; requires vehicleId.
- `garageVehicleId` (integer, optional): Owned garage vehicle id used to fill route profile defaults.
- `rangeKm` (number, optional): Manual range in kilometers; required when no catalog or garage vehicle is supplied.
- `batteryCapacityKwh` (number, optional): Manual battery capacity in kWh; required when no catalog or garage vehicle is supplied.
- `initialBatteryPercent` (number, optional): Initial battery percentage. Defaults to 100.
- `arrivalBatteryTargetPercent` (number, optional): Minimum target battery percentage at arrival. Defaults to 15.
- `autoPlan` (boolean, optional): Whether the routing backend may add charging stops. Defaults to true.
- `allowFerries` (boolean, optional): Whether ferry routes are allowed. Defaults to false.
- `blockedStationIds` (integer[], optional): Station ids the planner must avoid. Accepts up to 20.
- `preferredStationIds` (integer[], optional): Station ids the planner should prefer. Accepts up to 10.
- `networkIds` (integer[], optional): Optional charging network ids to constrain or prefer. Accepts up to 10.
- `routeMode` ("fastest" | "fewer_stops", optional): Route optimization mode.

Output:
- Trip-style route overview, charging-stop summary, request/rate-limit metadata, and a links.map handoff labeled "see route on map".

Example:

```json
{
  "waypoints": [
    {
      "latitude": -25.43,
      "longitude": -49.27,
      "label": "Curitiba"
    },
    {
      "latitude": -27.59,
      "longitude": -48.55,
      "label": "Florianopolis"
    }
  ],
  "rangeKm": 300,
  "batteryCapacityKwh": 60,
  "initialBatteryPercent": 90,
  "arrivalBatteryTargetPercent": 15
}
```

Notes:
- Authentication is optional and no confirmation flag is required.
- Anonymous calls are limited by client fingerprint and shared global quota.
- If a token is supplied, it must include routes:plan and the call is audit logged/rate limited by token/user.
- garageVehicleId additionally requires garage:read.

### `get_current_user`

Verify the configured Carregados API token and return the authenticated user and token scopes.

- Auth: Authentication required with any valid user-scoped API token.
- Mutates data: no.
- Requires confirmation: no.
- Costed/abuse-controlled: no.

Required inputs:
- None.

Optional inputs:
- None.

Output:
- Authenticated user id/email and token scope metadata.

Example:

```json
{}
```

Notes:
- Requires a valid user-scoped API token.

### `list_car_listings`

List car listings owned by the authenticated Carregados user.

- Auth: Authentication required. Token scope required: cars:read.
- Mutates data: no.
- Requires confirmation: no.
- Costed/abuse-controlled: no.

Required inputs:
- None.

Optional inputs:
- None.

Output:
- Authenticated user car listings.

Example:

```json
{}
```

Notes:
- Only returns listings owned by the token user.

### `create_car_listing`

Create a complete draft electric-car listing for the authenticated user.

- Auth: Authentication required. Token scope required: cars:write.
- Mutates data: yes.
- Requires confirmation: `confirmed: true` after explicit user confirmation.
- Costed/abuse-controlled: no.

Required inputs:
- `maker` (string, required): Vehicle maker/brand.
- `model` (string, required): Vehicle model.
- `modelYear` (integer, required): Vehicle model year.
- `fabricationYear` (integer, required): Vehicle fabrication/manufacture year.
- `color` (string, required): Vehicle color.
- `odometer` (number, required): Vehicle odometer in kilometers.
- `price` (number, required): Asking price in BRL.
- `city` (string, required): Listing city.
- `state` (string, required): Listing state value, for example "parana (pr)".
- `email` (string, required): Seller contact email stored on the private listing.
- `phone` (string, required): Seller contact phone with 11 digits including area code.

Optional inputs:
- `title` (string, optional): Public listing title.
- `content` (string, optional): Listing description/body text.
- `version` (string, optional): Vehicle version/trim.
- `doorNumber` (integer, optional): Number of doors.
- `bodyType` (string, optional): Body type.
- `listingType` ("particular" | "concessionaria", optional): Seller listing type.
- `sellerType` (string, optional): Seller type label.
- `condition` (string, optional): Vehicle condition, for example "new" or "used".
- `website` (string, optional): Seller or listing website.
- `armored` (boolean, optional): Optional vehicle feature/status flag.
- `isWarrantyActive` (boolean, optional): Optional vehicle feature/status flag.
- `isIpvaPaid` (boolean, optional): Optional vehicle feature/status flag.
- `isRevisionOk` (boolean, optional): Optional vehicle feature/status flag.
- `isRevisionsOnDealer` (boolean, optional): Optional vehicle feature/status flag.
- `isBatteryOk` (boolean, optional): Optional vehicle feature/status flag.
- `isOriginalChargerIncluded` (boolean, optional): Optional vehicle feature/status flag.
- `isExchangeAccepted` (boolean, optional): Optional vehicle feature/status flag.
- `isUniqueOwner` (boolean, optional): Optional vehicle feature/status flag.
- `hasAutopilot` (boolean, optional): Optional vehicle feature/status flag.
- `hasFsd` (boolean, optional): Optional vehicle feature/status flag.
- `hasSunroof` (boolean, optional): Optional vehicle feature/status flag.
- `hasHud` (boolean, optional): Optional vehicle feature/status flag.
- `hasDualMotor` (boolean, optional): Optional vehicle feature/status flag.
- `hasPremiumInterior` (boolean, optional): Optional vehicle feature/status flag.
- `hasAwd` (boolean, optional): Optional vehicle feature/status flag.
- `hasPremiumSound` (boolean, optional): Optional vehicle feature/status flag.
- `hasHeatedSeats` (boolean, optional): Optional vehicle feature/status flag.
- `hasHeatedSteeringWheel` (boolean, optional): Optional vehicle feature/status flag.
- `hasChargingCables` (boolean, optional): Optional vehicle feature/status flag.
- `has360Camera` (boolean, optional): Optional vehicle feature/status flag.
- `hasVoiceAssistant` (boolean, optional): Optional vehicle feature/status flag.
- `hasSmartEntry` (boolean, optional): Optional vehicle feature/status flag.
- `hasElectricTrunk` (boolean, optional): Optional vehicle feature/status flag.
- `confirmed` (boolean, optional): Set true only after explicit user approval; omit to let an MCP client request confirmation.
- `idempotencyKey` (string, optional): Stable retry key for this create request, retained for 24 hours.

Output:
- Created draft car listing plus message/publication fields telling agents that photos and payment must be finished in the browser before publication.

Example:

```json
{
  "maker": "BYD",
  "model": "Dolphin Plus",
  "modelYear": 2025,
  "fabricationYear": 2024,
  "color": "Branco",
  "odometer": 1200,
  "price": 155000,
  "city": "Curitiba",
  "state": "parana (pr)",
  "email": "vendedor@example.com",
  "phone": "41999990000",
  "confirmed": true
}
```

Notes:
- Agents must ask for explicit user confirmation before setting confirmed: true.
- The listing starts as a complete draft. The user must finish photos and payment in the browser before it is public.
- Do not report internal API flags such as isInactive, isRemoved, or isPaid to users; use the returned message/publication fields.

### `update_car_listing`

Update a car listing owned by the authenticated user.

- Auth: Authentication required. Token scope required: cars:write.
- Mutates data: yes.
- Requires confirmation: `confirmed: true` after explicit user confirmation.
- Costed/abuse-controlled: no.

Required inputs:
- `carId` (integer, required): Carregados car listing id owned by the token user.

Optional inputs:
- `title` (string, optional): Public listing title.
- `content` (string, optional): Listing description/body text.
- `maker` (string, optional): Vehicle maker/brand.
- `model` (string, optional): Vehicle model.
- `version` (string, optional): Vehicle version/trim.
- `fabricationYear` (integer, optional): Vehicle fabrication year.
- `modelYear` (integer, optional): Vehicle model year.
- `odometer` (number, optional): Odometer reading in kilometers.
- `doorNumber` (integer, optional): Number of doors.
- `bodyType` (string, optional): Body type.
- `color` (string, optional): Vehicle color.
- `price` (number, optional): Asking price in BRL.
- `listingType` ("particular" | "concessionaria", optional): Seller listing type.
- `sellerType` (string, optional): Seller type label.
- `city` (string, optional): Listing city.
- `state` (string, optional): Listing state value, for example "parana (pr)".
- `condition` (string, optional): Vehicle condition, for example "new" or "used".
- `email` (string, optional): Seller contact email stored on the private listing.
- `phone` (string, optional): Seller contact phone with 11 digits including area code.
- `website` (string, optional): Seller or listing website.
- `armored` (boolean, optional): Optional vehicle feature/status flag.
- `isWarrantyActive` (boolean, optional): Optional vehicle feature/status flag.
- `isIpvaPaid` (boolean, optional): Optional vehicle feature/status flag.
- `isRevisionOk` (boolean, optional): Optional vehicle feature/status flag.
- `isRevisionsOnDealer` (boolean, optional): Optional vehicle feature/status flag.
- `isBatteryOk` (boolean, optional): Optional vehicle feature/status flag.
- `isOriginalChargerIncluded` (boolean, optional): Optional vehicle feature/status flag.
- `isExchangeAccepted` (boolean, optional): Optional vehicle feature/status flag.
- `isUniqueOwner` (boolean, optional): Optional vehicle feature/status flag.
- `hasAutopilot` (boolean, optional): Optional vehicle feature/status flag.
- `hasFsd` (boolean, optional): Optional vehicle feature/status flag.
- `hasSunroof` (boolean, optional): Optional vehicle feature/status flag.
- `hasHud` (boolean, optional): Optional vehicle feature/status flag.
- `hasDualMotor` (boolean, optional): Optional vehicle feature/status flag.
- `hasPremiumInterior` (boolean, optional): Optional vehicle feature/status flag.
- `hasAwd` (boolean, optional): Optional vehicle feature/status flag.
- `hasPremiumSound` (boolean, optional): Optional vehicle feature/status flag.
- `hasHeatedSeats` (boolean, optional): Optional vehicle feature/status flag.
- `hasHeatedSteeringWheel` (boolean, optional): Optional vehicle feature/status flag.
- `hasChargingCables` (boolean, optional): Optional vehicle feature/status flag.
- `has360Camera` (boolean, optional): Optional vehicle feature/status flag.
- `hasVoiceAssistant` (boolean, optional): Optional vehicle feature/status flag.
- `hasSmartEntry` (boolean, optional): Optional vehicle feature/status flag.
- `hasElectricTrunk` (boolean, optional): Optional vehicle feature/status flag.
- `ifMatch` (string, optional): ETag from the matching detail tool; rejects a stale mutation.
- `confirmed` (boolean, optional): Set true only after explicit user approval; omit to let an MCP client request confirmation.

Output:
- Updated owned car listing.

Example:

```json
{
  "carId": 123,
  "price": 139900,
  "confirmed": true
}
```

Notes:
- Agents must ask for explicit user confirmation before setting confirmed: true.
- Ownership is enforced by the API.

### `list_my_locations`

List charging locations created or owned by the authenticated Carregados user.

- Auth: Authentication required. Token scope required: locations:read.
- Mutates data: no.
- Requires confirmation: no.
- Costed/abuse-controlled: no.

Required inputs:
- None.

Optional inputs:
- None.

Output:
- Charging locations created or owned by the token user.

Example:

```json
{}
```

Notes:
- Does not list private data from unrelated stations.

### `create_location`

Create a charging location for Carregados review.

- Auth: Authentication required. Token scope required: locations:write.
- Mutates data: yes.
- Requires confirmation: `confirmed: true` after explicit user confirmation.
- Costed/abuse-controlled: no.

Required inputs:
- `name` (string, required): Internal charging-location name.
- `address` (string, required): Street address or public location description.
- `latitude` (number, required): Station latitude for authenticated creation.
- `longitude` (number, required): Station longitude for authenticated creation.
- `restricted` (boolean, required): Whether access is restricted.
- `enabled` (boolean, required): Whether chargers are currently enabled.
- `open247` (boolean, required): Whether the station is open 24/7.
- `isFree` (boolean, required): Whether charging is free.
- `stations` (array<object>, required): Chargers at the location. Each charger needs outlets with connector ids, for example [{networkId:1442,kilowatts:80,outlets:[{connector:20,connectorName:"CCS2"}]}].

Optional inputs:
- `displayName` (string, optional): Public display name.
- `description` (string, optional): Public station description.
- `hours` (string, optional): Opening hours text.
- `formattedPhoneNumber` (string, optional): Formatted public phone number.
- `phoneNumber` (string, optional): Raw phone number.
- `city` (string, optional): City value.
- `state` (string, optional): State value, for example "parana (pr)".
- `country` (string, optional): Country value.
- `displayCity` (string, optional): Public display city.
- `displayState` (string, optional): Public display state.
- `displayCountry` (string, optional): Public display country.
- `priceKwh` (number, optional): Charging price per kWh in BRL.
- `priceKwhComment` (string, optional): Comment explaining the kWh price.
- `activationPrice` (number, optional): Activation or session fee in BRL.
- `activationPriceComment` (string, optional): Comment explaining the activation/session fee.
- `costDescription` (string, optional): Freeform pricing/cost description.
- `comingSoon` (boolean, optional): Whether the station is marked as coming soon.
- `underRepair` (boolean, optional): Whether the station is marked as under repair.
- `icon_type` (string, optional): Station icon/category type.
- `confirmed` (boolean, optional): Set true only after explicit user approval; omit to let an MCP client request confirmation.
- `idempotencyKey` (string, optional): Stable retry key for this create request, retained for 24 hours.

Output:
- Created charging location plus message/review fields saying the station is being reviewed and should be approved within 24 hours.

Example:

```json
{
  "name": "Carregador Loja Centro",
  "latitude": -25.43,
  "longitude": -49.27,
  "address": "Rua Exemplo, 100",
  "restricted": false,
  "enabled": true,
  "open247": true,
  "isFree": false,
  "stations": [
    {
      "networkId": 1442,
      "kilowatts": 80,
      "outlets": [
        {
          "connector": 20,
          "connectorName": "CCS2"
        }
      ]
    }
  ],
  "city": "Curitiba",
  "state": "parana (pr)",
  "confirmed": true
}
```

Notes:
- Agents must ask for explicit user confirmation before setting confirmed: true.
- The location is submitted for review and does not bypass approval or ownership rules.
- Do not report internal API flags such as isInactive or isUserCreated to users; use the returned message/review fields.

### `update_location`

Update a user-created or owned charging location.

- Auth: Authentication required. Token scope required: locations:write.
- Mutates data: yes.
- Requires confirmation: `confirmed: true` after explicit user confirmation.
- Costed/abuse-controlled: no.

Required inputs:
- `locationId` (integer, required): Carregados location id created or owned by the token user.

Optional inputs:
- `name` (string, optional): Internal charging-location name.
- `displayName` (string, optional): Public display name.
- `address` (string, optional): Street address.
- `description` (string, optional): Public station description.
- `hours` (string, optional): Opening hours text.
- `formattedPhoneNumber` (string, optional): Formatted public phone number.
- `phoneNumber` (string, optional): Raw phone number.
- `city` (string, optional): City value.
- `state` (string, optional): State value, for example "parana (pr)".
- `country` (string, optional): Country value.
- `displayCity` (string, optional): Public display city.
- `displayState` (string, optional): Public display state.
- `displayCountry` (string, optional): Public display country.
- `priceKwh` (number, optional): Charging price per kWh in BRL.
- `priceKwhComment` (string, optional): Comment explaining the kWh price.
- `activationPrice` (number, optional): Activation or session fee in BRL.
- `activationPriceComment` (string, optional): Comment explaining the activation/session fee.
- `costDescription` (string, optional): Freeform pricing/cost description.
- `enabled` (boolean, optional): Whether the location is enabled in owner/user workflows.
- `open247` (boolean, optional): Whether the station is open 24/7.
- `comingSoon` (boolean, optional): Whether the station is marked as coming soon.
- `underRepair` (boolean, optional): Whether the station is marked as under repair.
- `latitude` (number, optional): Station latitude for authenticated creation/update.
- `longitude` (number, optional): Station longitude for authenticated creation/update.
- `icon_type` (string, optional): Station icon/category type.
- `restricted` (boolean, optional): Whether access is restricted.
- `stations` (array<object>, optional): Replacement charger/outlet graph for user-created locations, or id-based upserts for imported locations.
- `ifMatch` (string, optional): ETag from the matching detail tool; rejects a stale mutation.
- `confirmed` (boolean, optional): Set true only after explicit user approval; omit to let an MCP client request confirmation.

Output:
- Updated user-created or owned charging location.

Example:

```json
{
  "locationId": 456,
  "open247": true,
  "priceKwh": 2.1,
  "confirmed": true
}
```

Notes:
- Agents must ask for explicit user confirmation before setting confirmed: true.
- Ownership/user-created access is enforced by the API.

### `search_public_station_map`

Search a viewport or radius for station facts, aggregate status, power, and distance without exact coordinates.

- Auth: No authentication required.
- Mutates data: no.
- Requires confirmation: no.
- Costed/abuse-controlled: no.

Required inputs:
- None.

Optional inputs:
- `latitude` (number, optional): Radius-search center latitude.
- `longitude` (number, optional): Radius-search center longitude.
- `radiusKm` (number, optional): Radius from 0 to 250 km; defaults to 25.
- `north` (number, optional): Viewport north latitude.
- `east` (number, optional): Viewport east longitude.
- `south` (number, optional): Viewport south latitude.
- `west` (number, optional): Viewport west longitude.
- `status` (string[], optional): Operational status filters.
- `open247` (boolean, optional): Filter by 24/7 availability.
- `minPowerKw` (number, optional): Minimum charger power filter.
- `maxPowerKw` (number, optional): Maximum charger power filter.
- `maxPriceKwh` (number, optional): Maximum charging price per kWh.
- `minimumReviews` (integer, optional): Minimum station review count.
- `networkId` (integer, optional): Charging-network id.
- `connectorIds` (integer[], optional): Connector ids that must be available.
- `amenityIds` (integer[], optional): Required amenity ids.
- `poi` (string, optional): Point-of-interest name filter.
- `verified` (boolean, optional): Return verified stations only.
- `photos` ("with" | "without", optional): Require or exclude station photos.
- `limit` (integer, optional): Page size from 1 to 100.
- `page` (integer, optional): 1-based page number.

Output:
- Structured JSON from the corresponding Carregados API endpoint.

Example:

```json
{
  "latitude": -25.43,
  "longitude": -49.27,
  "radiusKm": 25
}
```

Notes:
- Caller-provided search coordinates and station coordinates are not returned.

### `search_public_places`

Search addresses, place names, station names, or coordinate pairs without returning exact coordinates.

- Auth: No authentication required.
- Mutates data: no.
- Requires confirmation: no.
- Costed/abuse-controlled: no.

Required inputs:
- `query` (string, required): Place, address, station, or latitude/longitude query.

Optional inputs:
- `limit` (integer, optional): Maximum results from 1 to 10.
- `countryCodes` (string[], optional): Two-letter country-code filters.
- `includeStations` (boolean, optional): Include matching Carregados stations.

Output:
- Structured JSON from the corresponding Carregados API endpoint.

Example:

```json
{
  "query": "Curitiba, PR",
  "limit": 5
}
```

### `search_public_vehicles`

Search curated EV models and variants with route-ready profiles.

- Auth: No authentication required.
- Mutates data: no.
- Requires confirmation: no.
- Costed/abuse-controlled: no.

Required inputs:
- None.

Optional inputs:
- `query` (string, optional): Make, model, or variant search text.
- `make` (string, optional): Vehicle make filter.
- `minRangeKm` (number, optional): Minimum rated range.
- `connectorIds` (integer[], optional): Required connector ids.
- `limit` (integer, optional): Page size from 1 to 100.
- `page` (integer, optional): 1-based page number.

Output:
- Structured JSON from the corresponding Carregados API endpoint.

Example:

```json
{
  "query": "Dolphin",
  "minRangeKm": 250
}
```

### `get_public_vehicle`

Get a curated EV model or variant and its route profile.

- Auth: No authentication required.
- Mutates data: no.
- Requires confirmation: no.
- Costed/abuse-controlled: no.

Required inputs:
- `vehicleId` (integer, required): Public catalog vehicle id.

Optional inputs:
- `subtypeId` (integer, optional): Optional catalog variant id.

Output:
- Structured JSON from the corresponding Carregados API endpoint.

Example:

```json
{
  "vehicleId": 123,
  "subtypeId": 456
}
```

### `get_car_listing`

Get an owned car listing and its concurrency ETag.

- Auth: Authentication required. Token scope required: cars:read.
- Mutates data: no.
- Requires confirmation: no.
- Costed/abuse-controlled: no.

Required inputs:
- `carId` (integer, required): Owned car listing id.

Optional inputs:
- None.

Output:
- Structured JSON from the corresponding Carregados API endpoint.

Example:

```json
{
  "carId": 123
}
```

### `archive_car_listing`

Remove an owned listing from public results without hard deletion.

- Auth: Authentication required. Token scope required: cars:write.
- Mutates data: yes.
- Requires confirmation: `confirmed: true` after explicit user confirmation.
- Costed/abuse-controlled: no.

Required inputs:
- `carId` (integer, required): Owned car listing id.

Optional inputs:
- `ifMatch` (string, optional): ETag from the matching detail tool; rejects a stale mutation.
- `confirmed` (boolean, optional): Set true only after explicit user approval; omit to let an MCP client request confirmation.

Output:
- Structured JSON from the corresponding Carregados API endpoint.

Example:

```json
{
  "carId": 123,
  "confirmed": true
}
```

### `get_my_location`

Get an owned/user-created location, charger ids, outlet ids, and its ETag.

- Auth: Authentication required. Token scope required: locations:read.
- Mutates data: no.
- Requires confirmation: no.
- Costed/abuse-controlled: no.

Required inputs:
- `locationId` (integer, required): Owned or user-created location id.

Optional inputs:
- None.

Output:
- Structured JSON from the corresponding Carregados API endpoint.

Example:

```json
{
  "locationId": 456
}
```

### `list_garage_vehicles`

List the authenticated user's route-planning garage.

- Auth: Authentication required. Token scope required: garage:read.
- Mutates data: no.
- Requires confirmation: no.
- Costed/abuse-controlled: no.

Required inputs:
- None.

Optional inputs:
- None.

Output:
- Structured JSON from the corresponding Carregados API endpoint.

Example:

```json
{}
```

### `get_garage_vehicle`

Get one garage vehicle, its resolved route profile, and ETag.

- Auth: Authentication required. Token scope required: garage:read.
- Mutates data: no.
- Requires confirmation: no.
- Costed/abuse-controlled: no.

Required inputs:
- `vehicleId` (integer, required): Owned garage vehicle id.

Optional inputs:
- None.

Output:
- Structured JSON from the corresponding Carregados API endpoint.

Example:

```json
{
  "vehicleId": 42
}
```

### `add_garage_vehicle`

Add a curated catalog EV to the authenticated user's garage.

- Auth: Authentication required. Token scope required: garage:write.
- Mutates data: yes.
- Requires confirmation: `confirmed: true` after explicit user confirmation.
- Costed/abuse-controlled: no.

Required inputs:
- `catalogVehicleId` (integer, required): Public catalog vehicle id.

Optional inputs:
- `subtypeId` (integer | null, optional): Catalog variant id.
- `ratedRangeKm` (number | null, optional): Custom range override.
- `batteryCapacityKwh` (number | null, optional): Custom battery override.
- `isPrimary` (boolean, optional): Make this the primary garage vehicle.
- `idempotencyKey` (string, optional): Stable retry key for this create request, retained for 24 hours.
- `confirmed` (boolean, optional): Set true only after explicit user approval; omit to let an MCP client request confirmation.

Output:
- Structured JSON from the corresponding Carregados API endpoint.

Example:

```json
{
  "catalogVehicleId": 123,
  "subtypeId": 456,
  "isPrimary": true,
  "confirmed": true
}
```

### `update_garage_vehicle`

Update an owned garage vehicle's overrides or primary status.

- Auth: Authentication required. Token scope required: garage:write.
- Mutates data: yes.
- Requires confirmation: `confirmed: true` after explicit user confirmation.
- Costed/abuse-controlled: no.

Required inputs:
- `vehicleId` (integer, required): Owned garage vehicle id.

Optional inputs:
- `ratedRangeKm` (number | null, optional): Custom range override or null to clear.
- `batteryCapacityKwh` (number | null, optional): Custom battery override or null to clear.
- `isPrimary` (boolean, optional): Whether this is the primary vehicle.
- `ifMatch` (string, optional): ETag from the matching detail tool; rejects a stale mutation.
- `confirmed` (boolean, optional): Set true only after explicit user approval; omit to let an MCP client request confirmation.

Output:
- Structured JSON from the corresponding Carregados API endpoint.

Example:

```json
{
  "vehicleId": 42,
  "ratedRangeKm": 360,
  "confirmed": true
}
```

### `remove_garage_vehicle`

Remove an owned vehicle from the route-planning garage.

- Auth: Authentication required. Token scope required: garage:write.
- Mutates data: yes.
- Requires confirmation: `confirmed: true` after explicit user confirmation.
- Costed/abuse-controlled: no.

Required inputs:
- `vehicleId` (integer, required): Owned garage vehicle id.

Optional inputs:
- `ifMatch` (string, optional): ETag from the matching detail tool; rejects a stale mutation.
- `confirmed` (boolean, optional): Set true only after explicit user approval; omit to let an MCP client request confirmation.

Output:
- Structured JSON from the corresponding Carregados API endpoint.

Example:

```json
{
  "vehicleId": 42,
  "confirmed": true
}
```

### `list_favorite_stations`

List the authenticated user's favorite stations without exact coordinates.

- Auth: Authentication required. Token scope required: favorites:read.
- Mutates data: no.
- Requires confirmation: no.
- Costed/abuse-controlled: no.

Required inputs:
- None.

Optional inputs:
- None.

Output:
- Structured JSON from the corresponding Carregados API endpoint.

Example:

```json
{}
```

### `set_favorite_station`

Add or remove a station from the authenticated user's favorites.

- Auth: Authentication required. Token scope required: favorites:write.
- Mutates data: yes.
- Requires confirmation: `confirmed: true` after explicit user confirmation.
- Costed/abuse-controlled: no.

Required inputs:
- `stationId` (integer, required): Public station id.
- `favorite` (boolean, required): True to add; false to remove.

Optional inputs:
- `confirmed` (boolean, optional): Set true only after explicit user approval; omit to let an MCP client request confirmation.

Output:
- Structured JSON from the corresponding Carregados API endpoint.

Example:

```json
{
  "stationId": 456,
  "favorite": true,
  "confirmed": true
}
```

### `list_trips`

List saved, recent, or archived trips with cursor pagination.

- Auth: Authentication required. Token scope required: trips:read.
- Mutates data: no.
- Requires confirmation: no.
- Costed/abuse-controlled: no.

Required inputs:
- None.

Optional inputs:
- `kind` ("saved" | "recent" | "archived", optional): Trip collection.
- `cursor` (string, optional): Opaque next-page cursor.
- `limit` (integer, optional): Page size from 1 to 100.

Output:
- Structured JSON from the corresponding Carregados API endpoint.

Example:

```json
{
  "kind": "saved",
  "limit": 25
}
```

### `get_trip`

Get one owned trip and its ETag.

- Auth: Authentication required. Token scope required: trips:read.
- Mutates data: no.
- Requires confirmation: no.
- Costed/abuse-controlled: no.

Required inputs:
- `tripId` (string, required): Owned route/trip id.

Optional inputs:
- None.

Output:
- Structured JSON from the corresponding Carregados API endpoint.

Example:

```json
{
  "tripId": "route_123"
}
```

### `save_trip`

Save a route returned by plan_route.

- Auth: Authentication required. Token scope required: trips:write.
- Mutates data: yes.
- Requires confirmation: `confirmed: true` after explicit user confirmation.
- Costed/abuse-controlled: no.

Required inputs:
- `routeId` (string, required): Route id returned by plan_route.

Optional inputs:
- `idempotencyKey` (string, optional): Stable retry key for this create request, retained for 24 hours.
- `confirmed` (boolean, optional): Set true only after explicit user approval; omit to let an MCP client request confirmation.

Output:
- Structured JSON from the corresponding Carregados API endpoint.

Example:

```json
{
  "routeId": "route_123",
  "confirmed": true
}
```

### `update_trip`

Rename, save, restore, archive, or rate an owned trip.

- Auth: Authentication required. Token scope required: trips:write.
- Mutates data: yes.
- Requires confirmation: `confirmed: true` after explicit user confirmation.
- Costed/abuse-controlled: no.

Required inputs:
- `tripId` (string, required): Owned route/trip id.

Optional inputs:
- `title` (string | null, optional): Trip title or null to reset.
- `saved` (boolean, optional): Saved status.
- `archived` (boolean, optional): Archived status.
- `rating` (integer | null, optional): Rating from 1 to 5, or null.
- `ifMatch` (string, optional): ETag from the matching detail tool; rejects a stale mutation.
- `confirmed` (boolean, optional): Set true only after explicit user approval; omit to let an MCP client request confirmation.

Output:
- Structured JSON from the corresponding Carregados API endpoint.

Example:

```json
{
  "tripId": "route_123",
  "title": "Weekend trip",
  "confirmed": true
}
```

### `archive_trip`

Archive an owned trip without hard deletion.

- Auth: Authentication required. Token scope required: trips:write.
- Mutates data: yes.
- Requires confirmation: `confirmed: true` after explicit user confirmation.
- Costed/abuse-controlled: no.

Required inputs:
- `tripId` (string, required): Owned route/trip id.

Optional inputs:
- `ifMatch` (string, optional): ETag from the matching detail tool; rejects a stale mutation.
- `confirmed` (boolean, optional): Set true only after explicit user approval; omit to let an MCP client request confirmation.

Output:
- Structured JSON from the corresponding Carregados API endpoint.

Example:

```json
{
  "tripId": "route_123",
  "confirmed": true
}
```

### `list_check_ins`

List the authenticated user's station check-ins.

- Auth: Authentication required. Token scope required: checkins:read.
- Mutates data: no.
- Requires confirmation: no.
- Costed/abuse-controlled: no.

Required inputs:
- None.

Optional inputs:
- `cursor` (integer, optional): Next-page check-in id cursor.
- `limit` (integer, optional): Page size from 1 to 100.

Output:
- Structured JSON from the corresponding Carregados API endpoint.

Example:

```json
{}
```

### `create_check_in`

Record the outcome of a charging-station visit.

- Auth: Authentication required. Token scope required: checkins:write.
- Mutates data: yes.
- Requires confirmation: `confirmed: true` after explicit user confirmation.
- Costed/abuse-controlled: no.

Required inputs:
- `stationId` (integer, required): Public station id.
- `outcome` ("success" | "neutral" | "failure", required): Visit outcome.
- `comment` (string | null, required): Visit comment; required for neutral.
- `powerKw` (number | null, required): Observed charge power or null.

Optional inputs:
- `idempotencyKey` (string, optional): Stable retry key for this create request, retained for 24 hours.
- `confirmed` (boolean, optional): Set true only after explicit user approval; omit to let an MCP client request confirmation.

Output:
- Structured JSON from the corresponding Carregados API endpoint.

Example:

```json
{
  "stationId": 456,
  "outcome": "success",
  "comment": "Working well",
  "powerKw": 75,
  "confirmed": true
}
```

### `delete_check_in`

Permanently delete an owned station check-in.

- Auth: Authentication required. Token scope required: checkins:write.
- Mutates data: yes.
- Requires confirmation: `confirmed: true` after explicit user confirmation.
- Costed/abuse-controlled: no.

Required inputs:
- `checkInId` (integer, required): Owned check-in id.

Optional inputs:
- `confirmed` (boolean, optional): Set true only after explicit user approval; omit to let an MCP client request confirmation.

Output:
- Structured JSON from the corresponding Carregados API endpoint.

Example:

```json
{
  "checkInId": 789,
  "confirmed": true
}
```

### `list_notifications`

List or count notifications with filters and cursor pagination.

- Auth: Authentication required. Token scope required: notifications:read.
- Mutates data: no.
- Requires confirmation: no.
- Costed/abuse-controlled: no.

Required inputs:
- None.

Optional inputs:
- `filter` ("all" | "unread" | "read", optional): Notification state filter.
- `cursor` (string, optional): Opaque next-page cursor.
- `limit` (integer, optional): Page size from 1 to 50.
- `countOnly` (boolean, optional): Return counts without a notification page.

Output:
- Structured JSON from the corresponding Carregados API endpoint.

Example:

```json
{
  "filter": "unread",
  "limit": 20
}
```

### `update_notifications`

Mark notifications read/unread or delete them.

- Auth: Authentication required. Token scope required: notifications:write.
- Mutates data: yes.
- Requires confirmation: `confirmed: true` after explicit user confirmation.
- Costed/abuse-controlled: no.

Required inputs:
- `intent` ("mark-as-read" | "mark-as-unread" | "delete", required): Notification mutation.

Optional inputs:
- `notificationIds` (string[], optional): Selected ids; omit only to mark all as read.
- `confirmed` (boolean, optional): Set true only after explicit user approval; omit to let an MCP client request confirmation.

Output:
- Structured JSON from the corresponding Carregados API endpoint.

Example:

```json
{
  "intent": "mark-as-read",
  "notificationIds": [
    "notification_123"
  ],
  "confirmed": true
}
```

### `get_notification_preferences`

Get notification channels, quiet hours, timezone, email cap, and ETag.

- Auth: Authentication required. Token scope required: notifications:read.
- Mutates data: no.
- Requires confirmation: no.
- Costed/abuse-controlled: no.

Required inputs:
- None.

Optional inputs:
- None.

Output:
- Structured JSON from the corresponding Carregados API endpoint.

Example:

```json
{}
```

### `update_notification_preferences`

Update one or more notification delivery settings.

- Auth: Authentication required. Token scope required: notifications:write.
- Mutates data: yes.
- Requires confirmation: `confirmed: true` after explicit user confirmation.
- Costed/abuse-controlled: no.

Required inputs:
- None.

Optional inputs:
- `threadMessagesEmail` (boolean, optional): Email for thread messages.
- `threadMessagesInApp` (boolean, optional): In-app thread messages.
- `favoriteStationDigestEmail` (boolean, optional): Favorite-station digest email.
- `savedTripAlertsEmail` (boolean, optional): Saved-trip alert email.
- `engagementEmailWeeklyCap` (integer, optional): Weekly engagement email cap.
- `timeZone` (string, optional): IANA timezone name.
- `quietHoursStartMinute` (integer | null, optional): Quiet-hours start minute.
- `quietHoursEndMinute` (integer | null, optional): Quiet-hours end minute.
- `ifMatch` (string, optional): ETag from the matching detail tool; rejects a stale mutation.
- `confirmed` (boolean, optional): Set true only after explicit user approval; omit to let an MCP client request confirmation.

Output:
- Structured JSON from the corresponding Carregados API endpoint.

Example:

```json
{
  "savedTripAlertsEmail": true,
  "timeZone": "America/Sao_Paulo",
  "confirmed": true
}
```

Notes:
- Additional boolean channel fields are advertised in the live tool schema.

### `create_highlight_checkout`

Create a Stripe Checkout URL for a station highlight; payment must complete in the browser.

- Auth: Authentication required. Token scope required: destaques:write, checkout:create.
- Mutates data: yes.
- Requires confirmation: `confirmed: true` after explicit user confirmation.
- Costed/abuse-controlled: yes.

Required inputs:
- `locationId` (integer, required): Carregados location id to highlight.

Optional inputs:
- `confirmed` (boolean, optional): Set true only after explicit user approval; omit to let an MCP client request confirmation.

Output:
- Stripe Checkout URL and handoff metadata.

Example:

```json
{
  "locationId": 456,
  "confirmed": true
}
```

Notes:
- Agents must ask for explicit user confirmation before setting confirmed: true.
- The tool only creates a browser checkout URL and never completes payment.

## Interface rules

- MCP mutation tools require authentication and exact user confirmation, using native elicitation when available or `confirmed: true` after approval.
- Route planning is auth optional and does not require confirmation.
- Checkout returns a browser handoff URL; the user completes payment.
- No private seller, payment, or administrator data is exposed through public tools.