> ## 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](/docs/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](/docs/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]`.
**Última hora (23 de julio de 2026):** la paginación ahora está basada en 0 y coincide 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](/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 autocorregirla en una ronda viaje. Las claves anidadas dentro de un rango de fechas o un elemento de matriz también se validan.
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 caída silenciosa desapareció: ahora obtiene un error procesable en lugar de un resultado claramente incorrecto.
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. |
| `trips_assign` | Escribir | `trip:update` | Asigne un transportista, conductor y un equipo a un viaje. |
## 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. |
| `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`). |
## 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. |
## 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` y/o `status` (matriz). Proporcione al menos un filtro. |
| `trailers_get_by_id` | Leer | `trailer:read` | Obtenga un solo tráiler por identificación. |
## 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. 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. |
| `invoices_record_financing` | Escribir | `invoice:update` | Registrar una transacción de factoring/financiación. |
## 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. |
| `tenders_accept` | Escribir | `tender:update` | Aceptar una oferta entrante, vinculando cada parada a una empresa. |
| `tenders_accept_updates` | Escribir | `tender:update` | Aceptar todas las actualizaciones pendientes de una licitación. |
| `tenders_reject` | Escribir | `tender:update` | Rechazar una oferta entrante. |
| `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.