> ## Documentation Index
> Fetch the complete documentation index at: https://docs.alvys.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Herramientas MCP disponibles
> Catálogo de herramientas expuestas por el servidor Alvys MCP, agrupadas por dominio (cargas, conductores, viajes, facturas) con requisitos de nivel, alcance y permisos.
Esta página enumera todas las herramientas que Alvys [servidor MCP](/en/api/guides/mcp) expone a los agentes de IA. Cada herramienta asigna 1:1 a una capacidad Alvys Public API y requiere un permiso específico (alcance). Su token debe tener ese alcance para que la llamada se realice correctamente.
**Niveles de herramientas**
* **Leer**: recuperar datos. Siempre disponible.
* **Escribir**: crea o actualiza datos. Deshabilitado durante la versión beta.
Los ámbitos utilizan la convención `{resource}:{action}` y coinciden con [Public API catálogo de alcance](/en/api/guides/authentication-1#available-scopes). Asígnalos a tu aplicación en **Admin → API Access**.
Durante la versión beta, el servidor es de **solo lectura**. Las herramientas de escritura (marcadas a continuación) están deshabilitadas.
***
## Convenciones
La superficie de la herramienta MCP refleja las formas de solicitud/respuesta Public API, por lo que llama al puerto 1:1 entre las dos.
**Paginación.** Todas las herramientas de búsqueda aceptan `page` (basado en 0, predeterminado `0`) y `pageSize` (predeterminado `25`, máximo `100`). Las respuestas reflejan la solicitud `page` para que los agentes puedan manejar su propio buscapersonas. `page=-1` (o cualquier valor negativo) se rechaza con `[invalid_params]`.
**Cambio incompatible (2026-07-23):** la paginación ahora es basada en 0, coincidiendo con Public API. Las personas que llamaron que anteriormente enviaron `page=1` para obtener la primera página ahora deben enviar `page=0`. Consulte el [registro de cambios](/en/api/changelog).
**Filtros de matriz.** Filtros que se asignan a campos de matriz `/search` en Public API (`statuses`, `status`, `loadNumbers`, `orderNumbers`, `mcNumbers`, `dotNumbers`, `tripNumbers`, `driverIds`, etc.) se declaran como **matrices** en la herramienta. Pase uno o varios valores en una sola llamada.
**Intervalos de fechas.** Los filtros de intervalo de fechas son objetos: `{ start, end }` en ISO-8601 (por ejemplo, `{ "start": "2026-06-01T00:00:00Z", "end": "2026-06-30T23:59:59Z" }`). Los nombres de los parámetros coinciden con Public API — `createdDateRange`, `pickupDateRange`, `deliveryDateRange`, `invoicedDateRange`, `paidDateRange`, `transactionRange`. Los parámetros de cadena dividida heredados (`createdFrom`/`createdTo`, `pickupFrom`/`pickupTo`, etc.) ya no se aceptan.
**Argumentos estrictos.** Las claves desconocidas — errores ortográficos, filtros no admitidos o parámetros que ya no existen — se **rechazan** con `[invalid_params]`. El mensaje de error nombra las claves rechazadas y la lista de parámetros válidos para que un agente pueda autocorregirse en una sola ronda. Las claves anidadas dentro de un rango de fechas o un elemento de matriz también se validan. Los argumentos obligatorios faltantes y los valores de tipo incorrecto (por ejemplo `page: "not-an-int"`) también devuelven errores estructurados `[invalid_params]` que nombran el parámetro — tanto para herramientas como para prompts.
Por qué: anteriormente, el SDK MCP vinculaba los argumentos por nombre y descartaba silenciosamente los desconocidos. `customers_search name="Colortech"` devolvió la lista completa de clientes sin filtrar porque `name` no es un filtro válido en esa herramienta. Ese comportamiento de descarte silencioso desapareció: ahora obtiene un error accionable en lugar de un resultado confiadamente incorrecto.
**Anotaciones de herramientas.** Cada herramienta anuncia indicaciones de seguridad `annotations` de MCP que reflejan los niveles Read / Write / Destructive de esta página: `readOnlyHint`, `destructiveHint`, `idempotentHint` y `openWorldHint`. Su cliente MCP puede usar estas indicaciones para decidir si pedir confirmación a un humano antes de ejecutar una herramienta. Durante la beta, cada herramienta expuesta es de solo lectura y establece `readOnlyHint: true` (y `destructiveHint: false`).
Ejemplo de rechazo:
```json theme={null}
{
"isError": true,
"content": [
{
"type": "text",
"text": "[invalid_params] Unknown parameter(s) for customers_search: 'name'. Valid parameters: createdDateRange, page, pageSize, statuses. Unknown parameters are rejected instead of silently ignored so a misspelled filter cannot return unfiltered results."
}
]
}
```
***
## Cargas
| Herramienta | Nivel | Alcance | Descripción |
| - | - | - | - |
| `loads_search` | Leer | `load:read` | Busque cargas por `status`, `loadNumbers`, `orderNumbers` y/o `customerId`. Proporcione al menos un filtro. |
| `loads_get_by_id` | Leer | `load:read` | Obtenga un único carga que incluya paradas, cargos y asignaciones. |
## Viajes
| Herramienta | Nivel | Alcance | Descripción |
| - | - | - | - |
| `trips_search` | Leer | `trip:read` | Busque viajes por `status`, `loadNumbers`, `tripNumbers`, `pickupDateRange` y/o `deliveryDateRange`. Proporcionar al menos un filtro; un rango de fechas por sí solo es suficiente. |
| `trips_get_by_id` | Leer | `trip:read` | Obtenga un único viaje incluidas sus paradas ordenadas. |
| `trips_record_arrival` | Escribir | `stop:update` | Registre un evento de llegada en una parada viaje. |
| `trips_record_departure` | Escribir | `stop:update` | Registre un evento de salida en una parada viaje. El servidor exige que primero debe existir una llegada. |
| `trips_update_stop_appointment` | Escribir | `stop:update` | Actualice la cita (o ventana FCFS) en una parada viaje. `scheduleType` debe ser `APPT` o `FCFS`; `appointmentDate` es obligatorio para `APPT` y `windowBegin` para `FCFS`. |
| `trips_assign` | Escribir | `trip:update` | Asigne un transportista y, opcionalmente, conductores y equipo a un viaje. Resuelva primero los identificadores con las herramientas de búsqueda. Asigna sin despachar y recalcula el millaje y la tarifa. `driver1Id` es obligatorio cuando se proporciona `driver2Id`. |
## Conductores
| Herramienta | Nivel | Alcance | Descripción |
| - | - | - | - |
| `drivers_search` | Leer | `driver:read` | Buscar conductores por `name` y/o servicio ELD `status` (matriz). Proporcione al menos un filtro. Los estados de servicio son telemetría ELD, no disponibilidad de despacho. |
| `drivers_get_by_id` | Leer | `driver:read` | Obtenga un único registro conductor. |
| `drivers_events_search` | Leer | `driver:read` | Obtenga el historial de eventos de servicio/ELD en un rango de fechas para uno o más conductores (matriz `driverIds`). Devuelve eventos sin procesar, no un veredicto de Horas de Servicio. |
## Transportistas
| Herramienta | Nivel | Alcance | Descripción |
| - | - | - | - |
| `carriers_search` | Leer | `carrier:read` | Busque transportistas por `status`, `mcNumbers` y/o `dotNumbers`. Proporcione al menos un filtro. |
| `carriers_get_by_id` | Leer | `carrier:read` | Obtenga un único transportista que incluya datos de autoridad y seguros. |
| `carriers_documents_get` | Leer | `carrier:read` | Enumere los documentos archivados para un transportista. |
| `carriers_set_status` | Escribir | `carrier:update` | Cambiar el estado de transportista (por ejemplo, activar después de la incorporación). |
| `carriers_document_upload` | Escribir | `carrier:update` | Cargue un documento de incorporación transportista. Envíe el archivo como base64; el archivo decodificado debe ser de 5 MB o menos. |
## Clientes
| Herramienta | Nivel | Alcance | Descripción |
| - | - | - | - |
| `customers_search` | Leer | `customer:read` | Busque clientes por `statuses` (matriz; el valor predeterminado es Active, Inactive, Disabled) y/o `createdDateRange`. Los resultados están ordenados por los más antiguos primero por fecha de creación del registro. No hay ningún filtro `name`: página y coincidencia del lado del cliente. |
| `customers_get_by_id` | Leer | `customer:read` | Obtenga un solo cliente, incluidos los contactos y la dirección de facturación. |
| `customers_create` | Escribir | `customer:create` | Crea un nuevo cliente. |
## Camiones y remolques
| Herramienta | Nivel | Alcance | Descripción |
| - | - | - | - |
| `trucks_search` | Leer | `truck:read` | Busque camiones (unidades de potencia) por `truckNumber` y/o `status` (matriz). Proporcione al menos un filtro. |
| `trucks_get_by_id` | Leer | `truck:read` | Busque un solo camión por identificación. |
| `trucks_events_search` | Leer | `truck:read` | Obtenga eventos de camiones (mantenimiento, programación, disponibilidad) para uno o más camiones en un rango de fechas. Pase `truckIds` (matriz de Alvys ID de camión, no números de unidad) y `startDate`; `endDate` es opcional. Devuelve una lista de eventos plana; una lista vacía significa que no hay eventos en el rango. |
| `trailers_search` | Leer | `trailer:read` | Busque remolques por `trailerNumber`, `status` (matriz) y/o `companyOwnedAsset`. Proporcione al menos un filtro. `companyOwnedAsset` es `true` para los remolques que la empresa posee y `false` para los remolques externos (propiedad del transportista) registrados en viajes; omítalo para devolver ambos. |
| `trailers_get_by_id` | Leer | `trailer:read` | Obtenga un solo tráiler por identificación. Resuelve tanto remolques externos (propiedad del transportista) como propiedad de la empresa; lea `CompanyOwnedAsset` para distinguirlos. |
## Facturas, combustible y pagos
| Herramienta | Nivel | Alcance | Descripción |
| - | - | - | - |
| `invoices_search` | Leer | `invoice:read` | Busque facturas por `customerId`, `status`, `loadNumbers` y/o `orderNumbers`, opcionalmente limitadas por `invoicedDateRange`/`paidDateRange`. Proporcione al menos un filtro sin fecha: los rangos de fechas limitan los resultados pero no cuentan por sí solos. `invoicedDateRange` filtra la fecha de creación del registro de factura (incluye `Draft`), así que combínelo con un filtro de estado para preguntas sobre el monto facturado. |
| `invoices_get_by_id` | Leer | `invoice:read` | Obtenga una única factura que incluya artículos en línea. |
| `fuel_transactions_search` | Leer | `fuel:read` | Consultar transacciones de combustible por `truckNumber` y/o `transactionRange`. Proporcione al menos un filtro. |
| `invoices_record_carrier_payment` | Escribir | `invoice:update` | Registre un pago a un transportista contra un viaje. Idempotente en `referenceNumber`. Cuando los pagos cubren completamente el transportista a pagar, el viaje pasa a `Completed`. |
| `invoices_record_customer_payment` | Escribir | `invoice:update` | Registre un pago recibido de un cliente contra un carga. Idempotente en `referenceNumber`. |
| `invoices_record_financing` | Escribir | `invoice:update` | Registrar una transacción de factoring/financiación contra un carga. Idempotente en `referenceNumber`. |
## Accesorios y créditos
Los accesorios son cargos adicionales generados en un carga o viaje. Los créditos reducen lo que se debe. Ambos usan los mismos datos de referencia: llame primero a `accessorials_list_types` para obtener el `typeId`, los ids `rateType` que ese tipo permite y los ids `rateUom` válidos para cada uno de esos tipos de tarifa.
| Herramienta | Nivel | Alcance | Descripción |
| - | - | - | - |
| `accessorials_list_types` | Leer | `accessorial:read` | Enumere los tipos de accesorios del inquilino: los datos de referencia que necesita cada creación de accesorio. Devuelve el `Id` y el `Name` de cada tipo, si tiene `RequiresStop` y los `RateTypes` que permite con sus unidades de medida admitidas. Pase `includeDeleted=true` para devolver también los tipos eliminados de forma reversible, que son solo datos de referencia y no se pueden cobrar. |
| `accessorials_create_driver` | Escribir | `accessorial:create` | Cree un accesorio de conductor: un monto adicional pagado a un conductor en un viaje (detención, estadía, parada adicional). `rate` debe ser mayor que cero. Establezca `applyDriverRate=true` para aplicar el porcentaje de tarifa configurado del conductor a la tarifa que envíe. |
| `accessorials_create_customer` | Escribir | `accessorial:create` | Cree un accesorio de cliente: un monto adicional facturado al cliente en un carga. `rate` debe ser mayor que cero. |
| `accessorials_create_carrier` | Escribir | `accessorial:create` | Cree un accesorio de transportista: un monto adicional pagado a un transportista en un viaje de corretaje. `rate` debe ser mayor que cero. |
| `credits_create_customer` | Escribir | `accessorial:create` | Registre un crédito de accesorio de cliente, reduciendo lo que el cliente debe en un carga. `rate` debe ser un valor negativo. |
| `credits_create_carrier` | Escribir | `accessorial:create` | Registre un crédito de accesorio de transportista en un viaje de corretaje, reduciendo lo que se le debe al transportista. `rate` debe ser un valor negativo. |
No existe una herramienta de crédito para conductores. Un crédito de conductor es un objeto distinto de un accesorio — un registro de liquidación, no un cargo en un viaje — y se crea a través de la Public API con [Create driver credit](/en/api/reference/credits/create-driver-credit), que usa el alcance `deduction:create`.
### Tipo de tarifa y unidad de medida
`rateType` y `rateUom` se envían como ids, y las combinaciones válidas provienen de `accessorials_list_types` para el tipo que está cobrando.
| `rateType` | Significado | Ids `rateUom` válidos |
| - | - | - |
| `1` | Plana | solo `0` |
| `2` | Peso | `0` kg, `2` lbs, `4` toneladas, `5` cwt |
| `3` | Distancia | `0` millas, `1` km |
| `4` | Volumen | `0` galones, `2` fanegas |
| `5` | Tiempo | `0` minutos, `1` horas, `2` días |
| `6` | Por unidad | solo `0` |
`quantity` debe ser mayor que cero, excepto con un `rateType` Plana, que factura la tarifa una vez y fuerza la cantidad a `1`.
Envíe `stopId` cuando el tipo de accesorio devuelva `RequiresStop: true`.
### Idempotencia en escrituras de accesorios y créditos
Cada herramienta de creación acepta un `externalId` opcional: su propia clave para el registro, única dentro de su inquilino. Envíe el mismo valor en un reintento y se devuelve el registro original en lugar de crearse un segundo. Omítalo y un reintento crea un segundo registro.
* Las claves distinguen mayúsculas de minúsculas y se comparan después de recortar los espacios en blanco circundantes.
* Un reintento debe pedir el mismo trabajo: el mismo `rate`, `quantity`, `rateType`, `rateUom` y (para accesorios de conductor) `applyDriverRate`, además del mismo viaje o carga, tipo de accesorio, parada y conductor. Reutilizar una clave con cualquiera de esos elementos cambiado se rechaza con `409`.
* `notes` no se compara. Un reintento con una nota corregida devuelve el original sin cambios.
* Una clave permanece gastada después de eliminar el accesorio y no se puede reutilizar entre tipos (conductor, cliente, transportista).
Estas herramientas mueven dinero. Cree solo después de que un humano haya confirmado el monto. Un `503` significa que el registro no se pudo confirmar, no que no se haya creado: si envió un `externalId`, reintente la solicitud idéntica; si no lo hizo, confirme si el registro existe antes de reintentar.
## Visibilidad y seguimiento
| Herramienta | Nivel | Alcance | Descripción |
| - | - | - | - |
| `visibility_inbound_history` | Leer | `visibility:read` | Obtenga eventos de seguimiento entrante para un carga. |
| `visibility_outbound_history` | Leer | `visibility:read` | Obtenga eventos de seguimiento salientes para un carga. |
## Deducciones
| Herramienta | Nivel | Alcance | Descripción |
| - | - | - | - |
| `deductions_search` | Leer | `deduction:read` | Busque deducciones para `driverId`, `truckId` o `ownerOperatorId`. Proporcione al menos uno. Pase `includePaid=true` para devolver también las deducciones pagadas (predeterminado: solo abierto). |
| `deductions_get_by_id` | Leer | `deduction:read` | Obtenga una única deducción por identificación. |
## Licitaciones
| Herramienta | Nivel | Alcance | Descripción |
| - | - | - | - |
| `tenders_search` | Leer | `tender:read` | Busque ofertas entrantes por `status` (matriz), `loadNumber` y/o `shipmentId`. |
| `tenders_get_by_id` | Leer | `tender:read` | Obtenga una única oferta entrante. |
| `tenders_create` | Escribir | `tender:create` | Cree (ingiera) una nueva oferta entrante. Requiere al menos dos paradas. |
| `tenders_accept` | Escribir | `tender:update` | Aceptar una oferta entrante, vinculando cada parada a una empresa. `stopCompanyLinks` debe contener al menos dos entradas. |
| `tenders_accept_updates` | Escribir | `tender:update` | Aceptar todas las actualizaciones pendientes de una licitación. Establezca `applyAllChangesToLoad` en true para aplicarlas también al carga vinculado. |
| `tenders_reject` | Escribir | `tender:update` | Rechazar una oferta entrante. Proporcione `reasonCode` y `reasonDescription`; establezca `cancelLinkedLoad` en true para cancelar también el carga vinculado. |
| `tenders_accept_cancel` | Escribir | `tender:update` | Aceptar una cancelación de oferta. |
***
## Manejo de errores
Las llamadas a herramientas devuelven un error estructurado cuando no pueden completarse. Casos comunes:
| Condición | Lo que significa |
| - | - |
| **`invalid_params`** | La llamada lleva una clave de parámetro desconocida o un valor fuera de rango (por ejemplo, `page=-1`). El mensaje nombra las claves rechazadas y la lista de parámetros válidos de la herramienta; léalo y vuelva a intentarlo con una forma de argumento corregida. |
| **Falta alcance** | Su token no tiene el permiso requerido por la herramienta. Agregue el alcance en **Admin → API Access** y vuelva a emitir el token. |
| **Herramienta de escritura deshabilitada** | La herramienta es una acción de escritura/destructiva deshabilitada durante la versión beta. |
| **Tarifa limitada** | Excediste el límite de solicitudes por token. Retrocede y vuelve a intentarlo. |
| **Respuesta demasiado grande** | El resultado superó el límite de tamaño. Limite sus filtros de búsqueda o paginar. |
## Relacionado
Descripción general y configuración de la conexión para el servidor Alvys MCP.
Cree credenciales y emita tokens de acceso con los alcances correctos.