# Skydropx MCP

> Servidor MCP oficial de Skydropx, la plataforma de envíos para negocios en México. Conecta Claude, ChatGPT o Gemini a tu cuenta y cotiza, compra guías, rastrea envíos, agenda recolecciones y administra pedidos de tus tiendas con lenguaje natural. 48 herramientas tipadas sobre la API de Skydropx; OAuth 2.1 con PKCE; ninguna compra sin que el usuario elija y confirme una tarifa.

- Landing: https://ia.skydropx.com/
- Servidor MCP (producción, Streamable HTTP): https://mcp.skydropx.com
- Servidor MCP (sandbox): https://sb-mcp.skydropx.com
- Metadatos OAuth: https://mcp.skydropx.com/.well-known/oauth-authorization-server
- App: https://app.skydropx.com · Sitio: https://www.skydropx.com
- Lista completa de herramientas: https://ia.skydropx.com/llms-full.txt

## Qué hace

- Cotiza con todas las paqueterías conectadas (Estafeta, DHL, FedEx, Paquetexpress, 99minutos y más) usando las tarifas negociadas de la cuenta.
- Compra guías y devuelve la etiqueta PDF y el número de rastreo; solo `create_shipment` / `create_shipment_for_order` gastan saldo y requieren una tarifa elegida por el usuario.
- Lee pedidos de Shopify, WooCommerce, Wix, MercadoLibre, Tiendanube y otras tiendas conectadas y genera la guía del pedido.
- Rastrea envíos, agenda y reagenda recolecciones, asegura paquetes (SOS Protección), cancela guías.
- Administra libreta de direcciones, reglas de envío del checkout, códigos de Carta Porte (SAT) y tipos de empaque.
- Consulta saldo, movimientos y un feed de eventos verificable para agentes sin webhooks.

## Cómo conectar

- Claude (claude.ai, escritorio): Ajustes → Conectores → Añadir conector personalizado → URL `https://mcp.skydropx.com`. Claude descubre OAuth automáticamente.
- Claude Code: `claude mcp add --transport http skydropx https://mcp.skydropx.com`
- ChatGPT (Team/Enterprise, GPTs): Ajustes → Conectores → Añadir conector MCP → URL `https://mcp.skydropx.com`, autenticación OAuth.
- Gemini CLI: en `~/.gemini/settings.json`, `mcpServers.skydropx.httpUrl = "https://mcp.skydropx.com"`, `oauth.enabled = true`.

## Garantías

- Esquemas JSON cerrados: argumentos desconocidos se rechazan en el servidor.
- Autorización por herramienta fuera del modelo; el asistente actúa como el operador autenticado, dentro de su cuenta y permisos.
- Anotaciones MCP read-only / destructive / idempotent en cada herramienta; 30 herramientas son de solo lectura.
- Las compras se deduplican por `rate_id` hasta 96 horas para evitar guías dobles.

## Herramientas (48)

### Cotización y tarifas

- `quote_shipment` — Quote a shipment (solo lectura). Quote a shipment: returns available carrier rates for the given origin/destination and parcel(s). A postal_code per address is ENOUGH to quote — estado/municipio/colonia are auto-completed from the CP catalog server-side (auto-selections are reported in `mcp_autofilled`; mention the auto-picked colonia to the user, who can correct it). Do NOT ask the user for colonia before calling this tool. Provide address_from and address_to plus either a single `parcel` or a `parcels` array. Optionally restrict to `requested_carriers`. If something is still missing the tool returns `status: "needs_input"` naming the exact fields. Quoting is ASYNC: rates start as `pending`. If `mcp_next_step.status` is `pending`, call `get_quotation` with the returned id and poll until rates have prices. If it is `priced`, show the rates and let the user choose. Quoting never buys: only after the user explicitly picks and confirms a rate, call `create_shipment` with that `rate_id`.
- `rate_shipment` — Rate a shipment (solo lectura). Get carrier rates for a shipment described as one `shipment` object (same fields as quote_shipment: address_from, address_to, parcel or parcels...). Only quotes — it NEVER buys a label. To buy, let the user choose a rate and call create_shipment.
- `get_quotation` — Get quotation (solo lectura). Retrieve an existing quotation and all of its rates by id. USE THIS to poll a quotation created by `quote_shipment`: quoting is asynchronous, so rates come back `pending` at first. Pass `wait: true` (default) to let the SERVER wait until prices stabilize instead of you polling turn by turn. This is the way to fetch prices after quote_shipment; there is always a way to re-check a quotation.
- `list_carrier_services` — List carrier services (solo lectura). List the carrier services available for shipments (paginated).
- `list_office_points` — List drop-off points (solo lectura). List the carrier office points applicable to a quoted rate: `delivery` (recipient collects at an office → office_delivery_point_id) or `pickup` (sender drops off → office_pickup_point_id) for create_shipment.
- `list_extra_charges` — List extra charges (solo lectura). List extra charges (e.g. overweight adjustments) for the headquarter, paginated.

### Guías y envíos

- `create_shipment` — Create shipment (buy label) (escritura · requiere confirmación). Create (purchase) a shipment from a quotation rate — THIS is the tool that buys the label. Requires `rate_id` (from quote_shipment / get_quotation) chosen BY THE USER. Returns the shipment with its label_url and tracking info. BEFORE calling, gather in ONE question anything missing from the user: phone + email for BOTH parties (if not given at quote time), what is being shipped (plain words → resolve `consignment_note` via list_consignment_notes) and how it is packed (plain words → resolve `package_type` via list_packagings). NEVER guess those two codes, NEVER ask the user for a code, and NEVER fabricate contacts, addresses or references. International shipments also need customs_payment_payer, shipment_purpose and products; office delivery/pickup needs the point id from list_office_points. Purchases are deduplicated per rate_id server-side: while the deduplication record is still valid (up to 96 hours after the purchase), retrying the same rate_id returns the original shipment instead of buying twice; a purchase still in progress answers 409. This is not a permanent guarantee. If this tool returns WRITE_OUTCOME_UNKNOWN, check list_shipments before retrying. If it returns a validation error, fix ONLY the named fields and retry.
- `create_shipment_for_order` — Create shipment for order (escritura · requiere confirmación). Create a shipment (label) for an existing order. Without rate_id it quotes the order, waits until every carrier answered and buys the cheapest priced rate (optionally only from `carrier`); if carriers are still pricing it buys nothing and returns the quotation_id to check with get_quotation. To buy the rate the user chose, pass rate_id together with the quotation_id returned with the rates. Set auto_select=false to only get the priced rates — it never buys, even with a rate_id. Purchase fields (package_type, consignment_note, contacts, etc.) follow create_shipment; never fabricate contacts or addresses.
- `get_shipment` — Get shipment (solo lectura). Retrieve a shipment by id, including packages and addresses.
- `list_shipments` — List shipments (solo lectura). List shipments for the current headquarter, paginated. Optionally filter by ids.
- `cancel_shipment` — Cancel shipment (destructivo). Cancel a shipment by id (requires cancellations to be enabled for the headquarter). Optionally include a reason.
- `protect_shipment` — Insure shipment (escritura · requiere confirmación). Protect a shipment (insurance) for a declared value.
- `track_shipment` — Track shipment (solo lectura). Get tracking status and events for a shipment by carrier name and tracking number.
- `list_order_labels` — List order labels (solo lectura). List shipping labels generated for an order.

### Pedidos y tiendas

- `list_orders` — List orders (solo lectura). List orders for the current headquarter, most recent first, paginated.
- `get_order` — Get order (solo lectura). Retrieve an order by id (or ecommerce reference id).
- `create_order` — Create order (escritura · requiere confirmación). Create an order from an ecommerce-style payload (merchant_store_id, reference, addresses, products, parcels, payment info). Returns the created order.
- `update_order` — Update order (escritura). Update an order by id with a partial order payload; Skydropx re-quotes it.
- `list_merchant_stores` — List connected stores (solo lectura). List the merchant's connected ecommerce stores (Shopify, WooCommerce, Wix...), paginated. Use it FIRST to find the merchant_store_id needed by rules (create_conditional_tariff), store carriers and syncs — never ask the user for a store id without checking here.
- `get_merchant_store` — Get connected store (solo lectura). Retrieve a connected merchant store (ecommerce integration) by id.
- `update_merchant_store` — Update connected store (escritura). Update a connected merchant store's settings by id.
- `list_merchant_store_carriers` — List store carriers (solo lectura). List the carriers enabled for a connected merchant store.

### Reglas de checkout

- `list_conditional_tariffs` — List checkout shipping rules (solo lectura). List the merchant's checkout shipping rules (conditional tariffs): weight/price ranges mapped to an action like free shipping, flat price or live rates. Use it to answer '¿qué reglas de envío tengo?' and before creating/updating rules.
- `create_conditional_tariff` — Create checkout shipping rule (escritura). Create a checkout shipping rule (conditional tariff) for a connected store — e.g. 'envío gratis arriba de $999', 'todo envío mayor a 5 kg cobra tarifa fija'. Requires conditional_tariff.merchant_store_id: get it from list_merchant_stores first. Map the user's words: rangos de peso→min_weight/max_weight (kg), rangos de precio del carrito→min_price/max_price, gratis→action 'free', tarifa fija→action 'flat_rate' + value, precio del carrier→action 'carrier_price'.

### Recolecciones

- `schedule_pickup` — Schedule pickup (escritura · requiere confirmación). Schedule a carrier pickup for an existing shipment within a time window.
- `reschedule_pickup` — Reschedule pickup (escritura). Reschedule the latest pickup of a shipment to a new time window. Creates a new (successor) pickup, so do not repeat the call to retry.
- `pickup_coverage` — Check pickup coverage (solo lectura). Check which pickup dates are available for an existing shipment (coverage is computed from the shipment's carrier and origin address).
- `list_pickups` — List pickups (solo lectura). List scheduled pickups for the current headquarter, paginated.
- `get_pickup` — Get pickup (solo lectura). Retrieve a scheduled pickup by id, including its address.

### Direcciones y catálogos

- `list_address_templates` — List saved addresses (solo lectura). The merchant's saved address book (frequent customers, own warehouses). ALWAYS search here FIRST when the user references a known person or place ('el cliente de siempre', 'mi bodega', a customer name) instead of asking them for address data. Use the matching template's data (or its id as address_template_id) when quoting/shipping.
- `get_address_template` — Get saved address (solo lectura). Retrieve a saved address template by id.
- `create_address_template` — Save address (escritura). Save a new address template to the address book. Address fields go inside `address_attributes`; `alias_name`/`default`/`address_type` are top-level.
- `update_address_template` — Update saved address (escritura). Update a saved address template by id.
- `delete_address_template` — Delete saved address (destructivo). Delete a saved address template by id.
- `verify_address_by_carriers` — Verify address with carriers (escritura). Validate a saved address template against carrier address rules.
- `lookup_postal_code` — Look up postal code (solo lectura). Resolve a postal code (CP) into its estado (area_level1), municipio (area_level2) and the list of colonias (area_level3). Use it to validate a CP or to offer the user the real colonia options. NOT needed before quote_shipment — that tool auto-resolves these fields itself.
- `list_packagings` — List packaging types (solo lectura). List the valid packaging types for shipments (code + name, e.g. 4G = caja de cartón). The user NEVER knows these codes: ask how the item is packed in plain words ('caja', 'sobre', 'tarima'...) and search it with `name`. Results are paginated. NEVER guess a package_type — values like 'package' are invalid.
- `list_consignment_notes` — List consignment note codes (solo lectura). Search the valid consignment-note (carta porte SAT) codes for shipments. The user NEVER knows these codes: ask what they are shipping in plain words (e.g. 'zapatillas') and pass that as `description` to find the matching code (e.g. 53111700). NEVER guess or fabricate a code. The search is partial and accent-insensitive; try a simpler/singular word if there is no match.
- `list_products` — List products (solo lectura). List the headquarter's catalog products, paginated. Optionally filter by destination country.

### Envíos externos y rastreo propio

- `create_external_shipment` — Register external shipment (escritura). Register an external shipment (one fulfilled outside Skydropx) so it can be tracked: carrier_custom_code, tracking_number, recipient + parcel details.
- `import_external_shipments` — Import external shipments (escritura). Bulk-import up to shipments bought outside Skydropx so they are tracked here. Each row needs the tracking number and the carrier name exactly as the user gave them — never invent or guess a carrier. The import runs asynchronously: poll the returned import_id with get_external_shipment_import.
- `get_external_shipment_import` — Get external shipment import (solo lectura). Get the status/result of an external-shipment bulk import by id.
- `push_tracking_event` — Push tracking event (escritura). Ingest a tracking status for an HQ-owned custom carrier shipment (custom carriers have no provider feed, so statuses are pushed here). The status must be one of the trackable statuses accepted by Skydropx; an invalid one is rejected with the allowed list.

### Finanzas y cuenta

- `get_credits` — Get credit balance (solo lectura). Return the current headquarter's credit balance.
- `transaction_stats` — List account transactions (solo lectura). List the account's transactions (movements such as label charges and refunds) one page at a time, optionally filtered by search text, kind and date range. This is a paginated LIST, not aggregated statistics: never present the sum of one page as the account total — use the pagination meta to know how many pages exist and say when you only looked at some. Zero results (total_pages 0) means no matching transactions.
- `get_events_since` — Get events since cursor (solo lectura). Pull events recorded for your account since a cursor, without needing a webhook endpoint. Pass the `cursor` from the previous response to get only newer events; omit it to start from the beginning. Each event is hash-chained (prev_hash/hash); `chain_valid` attests the returned page and its link to your cursor, so tampering is detectable. Poll this on a session or serverless agent that can't receive webhooks.
- `whoami` — Who am I (solo lectura). Return the current Skydropx identity (headquarter/user/country) and verify the authenticated connection to the Skydropx API.
- `disconnect` — Disconnect #{Brand.name} (destructivo · requiere confirmación). Disconnect Skydropx from this assistant. Use ONLY when the user explicitly asks to disconnect or log out of Skydropx. It revokes this connection only: every Skydropx tool stops working here until the user authorizes again. It does not uninstall the connector, delete chat history, or sign the user out of the Skydropx website. Requires confirm: true after the user confirms.

## Vocabulario (es-MX)

guía = etiqueta de envío (label) · paquetería = carrier · cotizar = quote · recolección = pickup · CP = código postal · Carta Porte = complemento fiscal SAT para transporte · SOS Protección = seguro de envío · saldo = créditos prepagados de la cuenta.

## Contacto

Skydropx · https://www.skydropx.com · Docs MCP: https://ia.skydropx.com/