Servidor Alvys MCP para agentes de IA

Integre las capacidades Alvys utilizando el servidor Model Context Protocol (MCP). El servidor MCP proporciona un conjunto de herramientas que los agentes de IA pueden usar para interactuar con las API Alvys. Puede utilizar las herramientas MCP como desarrollador conectando un asistente a su flujo de trabajo, como propietario de negocio que busca información financiera o datos operativos, o como plataforma que conecta a sus propios agentes para realizar tareas en despacho, seguimiento y liquidación. A diferencia de la integración API sin formato, el servidor MCP le brinda a su cliente de IA una superficie única, reconocible y autorizada. Cada llamada a la herramienta se autentica con sus credenciales Alvys, se limita a su inquilino y se audita, para que los agentes obtengan exactamente el acceso que usted les otorga y nada más.

Beta internaEl servidor Alvys MCP se encuentra actualmente en beta. El acceso se otorga previa solicitud: comuníquese con su representante de cuenta (clientes existentes) o con el equipo de asociación Alvys (ISV). Durante la versión beta, el servidor expone herramientas de solo lectura.

¿Qué es MCP?

Model Context Protocol es un estándar abierto que brinda a los asistentes de IA una conexión en vivo a herramientas y datos externos. Piense en ello como un puerto USB para IA: en lugar de pegar datos en una ventana de chat, su cliente de IA se conecta directamente a Alvys y puede buscar, leer y (cuando esté permitido) actuar sobre sus datos operativos en tiempo real. El servidor Alvys MCP se encuentra frente al Alvys Public API. Agrega las propiedades de seguridad que requiere una superficie de herramienta de IA:

Autenticación: cada solicitud lleva un token de portador Auth0; Las llamadas no autenticadas se rechazan.
Aislamiento de inquilinos: su empresa se resuelve desde el propio token, nunca desde la entrada del agente.
Permisos por herramienta: cada herramienta requiere un alcance específico (por ejemplo, load:read), que se aplica en cada llamada.
Lectura/Escritura/Clasificación destructiva: las herramientas de escritura y destructivas están cerradas y desactivadas de forma predeterminada.
Límites de tasa y auditoría: cada llamada a la herramienta se registra y limita.

Para quién es

Eres…	Utilice MCP para…
Un desarrollador	Otorgue a Claude, Cursor o un agente personalizado acceso en vivo a cargas, viajes, conductores y transportistas sin llamadas API escritas a mano.
Un propietario de negocio/operadores	Haga preguntas en lenguaje natural a un asistente de IA sobre su operación: abra cargas, estado de la factura, disponibilidad de conductor e historial de seguimiento.
Una plataforma/ISV	Conecte sus agentes a Alvys para automatizar despacho, transportista la incorporación, el seguimiento y los flujos de trabajo liquidación.

Conexión al servidor MCP de Alvys

El servidor Alvys MCP es un servidor MCP remoto que habla el transporte MCP Streamable HTTP. Usted se conecta apuntando su cliente MCP a la URL del servidor y autenticándose con Auth0.

URL del servidor

Medio ambiente	MCP URL del servidor
Producción	`https://mcp.alvys.com/mcp`

Hay dos formas de autenticarse, según su cliente.

Opción 1: inicio de sesión interactivo (recomendado para aplicaciones de IA)

Lo mejor para clientes de cara humana que admiten servidores remotos MCP con OAuth: Claude, Claude Code, ChatGPT, Cursor y Codex. Usted agrega la URL del servidor una sola vez y su cliente descubre el flujo de inicio de sesión automáticamente a través de los metadatos OAuth del servidor (/.well-known/oauth-protected-resource/mcp). No se almacena ningún secreto de cliente en su cliente MCP: el flujo interactivo utiliza OAuth 2.1 con PKCE.

Configure su herramienta de IA

Elija su cliente a continuación. Todas las rutas terminan igual: se abre una ventana del navegador para iniciar sesión en Alvys, donde inicia sesión y, si se le solicita, selecciona su organización. Su cliente intercambia esa sesión por un token limitado a su empresa y sus permisos, y a partir de ahí puede enumerar y llamar a cualquier herramienta que su cuenta pueda utilizar.

Claude
Claude Code
ChatGPT
Cursor
Codex

Vaya a la configuración de Conectores.
Seleccione Agregar conector personalizado.
Ingrese los datos del conector:
- Nombre: Alvys
- URL: https://mcp.alvys.com/mcp
Seleccione Agregar y complete el inicio de sesión de Alvys cuando se le solicite.
En un chat, abra el menú de adjuntos (+) y active el conector de Alvys.

Agregue el servidor:

claude mcp add --transport http alvys https://mcp.alvys.com/mcp

Ejecute /mcp en Claude Code y seleccione alvys para iniciar el inicio de sesión. La primera vez que lo use, se abre una ventana del navegador para iniciar sesión en Alvys.

Los servidores MCP personalizados se configuran en la aplicación de escritorio de ChatGPT.

Abra Configuración → Servidores MCP → Agregar servidor.
Complete los datos del servidor:
- Nombre: Alvys
- Tipo: Streamable HTTP
- URL: https://mcp.alvys.com/mcp
Seleccione Guardar y luego Reiniciar.
Seleccione Autenticar y complete el inicio de sesión de Alvys.

La aplicación de escritorio de ChatGPT, Codex CLI y la extensión de Codex para IDE comparten un mismo archivo de configuración (~/.codex/config.toml), por lo que esta configuración se aplica a las tres.

Abra la paleta de comandos con Command + Shift + P (Ctrl + Shift + P en Windows).
Busque Open MCP settings y seleccione Add custom MCP.

En mcp.json, agregue el servidor de Alvys:

{
  "mcpServers": {
    "alvys": {
      "url": "https://mcp.alvys.com/mcp"
    }
  }
}

Recargue Cursor y complete el inicio de sesión de Alvys cuando se le solicite.

Agregue el servidor de Alvys a ~/.codex/config.toml:

[mcp_servers.alvys]
url = "https://mcp.alvys.com/mcp"
auth = "oauth"

Inicie el flujo de inicio de sesión:
codex mcp login alvys

Se abre una ventana del navegador para iniciar sesión en Alvys. Codex guarda las credenciales resultantes y las reutiliza en ejecuciones posteriores.

Opción 2: Máquina a máquina (automatización sin intervención humana)

Lo mejor para agentes de servidor a servidor y automatización de back-end sin ningún ser humano involucrado. Este flujo reutiliza el mismo mecanismo OAuth 2.0 credenciales de cliente que Alvys Public API.

Cree (o reutilice) una aplicación API Alvys en Admin → API Access para obtener client_id y client_secret. Seleccione los alcances que coincidan con las herramientas que desea llamar. Consulte Autenticación para obtener el tutorial completo.

Solicitar un token de acceso:

curl --request POST \
     --url 'https://auth.alvys.com/oauth/token' \
     --header 'Content-Type: application/json' \
     --data '{
       "client_id": "YOUR_CLIENT_ID",
       "client_secret": "YOUR_CLIENT_SECRET",
       "audience": "https://api.alvys.com/public/",
       "grant_type": "client_credentials"
     }'

Apunte su cliente MCP a la URL del servidor y pase el token en el encabezado Authorization:
Authorization: Bearer YOUR_ACCESS_TOKEN

El reclamo scope del token determina a qué herramientas puede llamar, y su reclamo de organización abarca cada llamada a los datos de su empresa.

Tu client_id y client_secret son confidenciales. Guárdelos de forma segura y nunca los exponga en el código de interfaz de usuario. Los tokens tienen como alcance exactamente los permisos otorgados a su aplicación.

Verificando la conexión

Una vez conectado, solicite a su cliente MCP que enumere las herramientas disponibles o realice una llamada MCP tools/list. Deberías ver las herramientas Alvys agrupadas por dominio (cargas, viajes, conductores, transportistas y más). Para obtener el catálogo completo, consulte Herramientas MCP disponibles. Una verificación de transporte sin formato (devuelve la lista de herramientas del servidor a través de Streamable HTTP):

curl -sD - -X POST https://mcp.alvys.com/mcp \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

Permisos y seguridad

El servidor MCP aplica el mismo modelo de alcance que Public API. Cada herramienta declara un permiso requerido mediante la convención {resource}:{action}, por ejemplo, load:read, carrier:update o tender:create. Una llamada a una herramienta falla si su token carece del alcance. Las herramientas se clasifican en tres niveles:

Nivel	Ejemplos	Disponibilidad
Leer	`loads_search`, `drivers_get_by_id`, `visibility_inbound_history`	Siempre disponible
Escribir	`tenders_create`, `trips_assign`, `invoices_record_carrier_payment`	Deshabilitado durante la versión beta
Destructivo	cancelar/anular acciones	Deshabilitado por defecto

Barreras de seguridad adicionales aplicadas a cada llamada:

Aislamiento de inquilinos: su empresa se deriva del reclamo de organización de su token; Los agentes no pueden apuntar a otro inquilino.
Limitación de tasa: la limitación de solicitudes por token protege su cuenta y la plataforma.
Límites de tamaño de respuesta: las respuestas de gran tamaño se rechazan para mantener los resultados dentro de la ventana de contexto de un cliente de IA.
Registro de auditoría: cada llamada a la herramienta se registra con la persona que llama, el inquilino y la identificación de seguimiento.

Indicaciones guiadas

Más allá de las herramientas individuales, el servidor incluye indicaciones guiadas: flujos de trabajo de varios pasos que un agente puede seguir de principio a fin:

Aviso	Qué hace
`find_and_cover_load_v1`	Encuentre un carga abierto y cúbralo con un transportista mediante una licitación.
`dispatch_driver_v1`	Verifique la disponibilidad de conductor y asigne un conductor, camión y remolque a un viaje.
`carrier_onboarding_v1`	Busque un transportista de MC/DOT, revise los documentos, cargue el paquete y actívelo.
`settlement_reconciliation_v1`	Concilie las facturas, las deducciones y los pagos de transportista/cliente de carga.
`track_shipment_v1`	Obtenga el historial de seguimiento de entrada y salida de un envío.

Próximos pasos

Herramientas MCP disponibles

Explora el catálogo completo de herramientas, agrupadas por dominio, con el alcance que cada una requiere.

Autenticación

Tutorial completo sobre cómo crear credenciales y emitir tokens de acceso.

Empezando

¿Eres nuevo en la API Alvys? Empiece aquí.

¿Necesitas acceso o ayuda?

Clientes existentes de Alvys: comuníquese con su representante de cuenta.
ISV/socios: comuníquese con el equipo de asociación Alvys.
Soporte técnico: soporte@alvys.com

​¿Qué es MCP?

​Para quién es

​Conexión al servidor MCP de Alvys

​URL del servidor

​Opción 1: inicio de sesión interactivo (recomendado para aplicaciones de IA)

​Configure su herramienta de IA

​Opción 2: Máquina a máquina (automatización sin intervención humana)

​Verificando la conexión

​Permisos y seguridad

​Indicaciones guiadas

​Próximos pasos

Herramientas MCP disponibles

Autenticación

Empezando

¿Qué es MCP?

Para quién es

Conexión al servidor MCP de Alvys

URL del servidor

Opción 1: inicio de sesión interactivo (recomendado para aplicaciones de IA)

Configure su herramienta de IA

Opción 2: Máquina a máquina (automatización sin intervención humana)

Verificando la conexión

Permisos y seguridad

Indicaciones guiadas

Próximos pasos