# Baltix MCP — agent guide

> Version 2. Logistics only. Confirm every write with the merchant.

## Connect

HTTP MCP: `https://app.baltix-pickup-points.com/mcp`

- No Authorization header, no env token, no `headers` in Cursor/Desktop.
- Claude Code: `claude mcp add --transport http baltix https://app.baltix-pickup-points.com/mcp`
- Codex: `[mcp_servers.baltix]` + `url = "https://app.baltix-pickup-points.com/mcp"` — never `bearer_token_env_var`.
- After OAuth, call `tools/list` and only use tools that appear.
- Then read resource `baltix://docs/mcp` (this page).

If a write tool is missing, ask the merchant to reconnect and enable that write group. Do not fall back to REST or Shopify Admin GraphQL.

## Hard rules

- Never print, store, or ask for MCP/API secrets.
- Never change billing, CCS settings, carrier credentials, products, or themes.
- Never invent locker IDs, tracking numbers, or Shopify GIDs.
- `preview_checkout_rates` is a Baltix preview (custom prices + radius). It is not a live Shopify CCS callback (no COD variants, no Swotzy quotes, no checkout rules).
- `list_carrier_connections` never returns credentials. Do not ask for them.
- Return payloads never include the customer portal token. Do not try to reconstruct return URLs from a token.
- Countries: `EE` | `LV` | `LT`. Carriers: `OMNIVA` | `ITELLA_SMARTPOSTI` | `DPD` | `VENIPAK` | `LATVIJAS_PASTS` | `UNISEND_LP_EXPRESS` | `FEDEX` | `DHL`.

## Tools

### search_pickup_points — pickup_points:read

When: nearest lockers. Requires `country` and `carrier` (array, min 1). Prefer lat/lng; else address/city/postal_code.

```json
{"country":"LV","carrier":["OMNIVA","DPD"],"city":"Riga","postal_code":"LV-1010","limit":20}
```

### list_orders / get_order / list_order_packages — orders:read

When: inspect Baltix logistics orders. `list_orders` accepts `updated_after` (RFC 3339), `status`, `limit`, `cursor`. `get_order` needs `orderId` (Baltix id, not #1001).

### list_order_labels / get_label — labels:read

Metadata only (status, tracking). No PDF/ZPL bytes.

### change_order_pickup_point — orders:write

Replace locker. Marks active labels outdated. Does not email the customer. Confirm with merchant. Requires full point payload (carrierCode, code, label, address, location).

### create_pickup_change_link — orders:write

Customer change link, 48h. Sends no email unless Baltix already does elsewhere — this tool does not send.

### replace_order_packages — orders:write

Replace complete allocation. Every ordered quantity must be assigned exactly once.

### create_order_label / create_package_label / cancel_label — labels:write

Single-package → `create_order_label`. Multi-package → `create_package_label`. Pass `idempotencyKey` when retrying. Cancel only if not delivered. Confirm with merchant.

### list_returns / get_return / list_return_dropoff_points — returns:read

Follow inbound status and drop-off options. `list_return_dropoff_points` needs `country`.

### create_return — returns:write

Merchant return on a **delivered** order. Items: Shopify line item GIDs + quantities. 60-day window. Confirm items and reason with the merchant first.

```json
{"orderId":"ord_…","reason":"Too small","items":[{"shopifyLineItemId":"gid://shopify/LineItem/123","quantity":1}]}
```

### list_carrier_connections — carriers:read

Ready = enabled + validation VALID. No secrets.

### get_tracking — tracking:read

`orderId` or `trackingNumber`. Baltix shipment status/history, not a live carrier scrape.

### preview_checkout_rates — ccs:read

Which lockers Baltix would likely offer for an address. Needs `country`. Geocodes if lat/lng omitted. Say "preview" to the merchant, not "checkout rates Shopify will show".

```json
{"country":"LT","address":"Arsenalo g. 1","city":"Vilnius","cart_subtotal":49,"weight_g":1200}
```

## Errors

- `401` — OAuth not finished, or a warehouse key was sent. Reconnect. Do not ask for a token.
- `403 paid_plan_required` — Free plan.
- `403 insufficient_scope` — reconnect and enable the write group.
- `404` — unknown tool, order, return, or tracking.
- `422` — business rule (not delivered, return window, geocode failed, weight limit).
- `429` — ~120 req/min. Slow down.

## Out of scope

Shopify Admin, Themes, Billing, CCS configuration, carrier password forms, warehouse `/api/v1`.
