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.
`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

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

​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

Visibilidad y seguimiento

Deducciones

Licitaciones

Manejo de errores

Relacionado