Herramientas MCP disponibles

Esta página enumera todas las herramientas que Alvys servidor 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. 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.

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:

{
  "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` 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. 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, 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

Protocolo de contexto modelo

Descripción general y configuración de la conexión para el servidor Alvys MCP.

Autenticación

Cree credenciales y emita tokens de acceso con los alcances correctos.

​Convenciones

​Cargas

​Viajes

​Conductores

​Transportistas

​Clientes

​Camiones y remolques

​Facturas, combustible y pagos

​Accesorios y créditos

​Tipo de tarifa y unidad de medida

​Idempotencia en escrituras de accesorios y créditos

​Visibilidad y seguimiento

​Deducciones

​Licitaciones

​Manejo de errores

​Relacionado

Protocolo de contexto modelo

Autenticación

Convenciones

Cargas

Viajes

Conductores

Transportistas

Clientes

Camiones y remolques

Facturas, combustible y pagos

Accesorios y créditos

Tipo de tarifa y unidad de medida

Idempotencia en escrituras de accesorios y créditos

Visibilidad y seguimiento

Deducciones

Licitaciones

Manejo de errores

Relacionado