> ## 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.
# Servidor Alvys MCP para agentes de IA
> Conecte los agentes de IA directamente a Alvys a través del servidor Model Context Protocol (MCP), una puerta de enlace gobernada y autenticada a Alvys Public API.
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 interna**
El 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](/en/api/guides/getting-started). 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
| Entorno | URL del servidor MCP |
| -------------- | --------------------------- |
| **Producción** | `https://mcp.alvys.com/mcp` |
### Soporte de versiones de protocolo
**No necesita elegir una versión de protocolo ni hay nada que configurar.** Los clientes y servidores MCP negocian la revisión automáticamente al conectar, de modo que su cliente usa la revisión más reciente que ambas partes entienden.
El servidor Alvys MCP implementa la revisión MCP **`2026-07-28`** y aún acepta estas revisiones anteriores:
| Revisión MCP | Compatible | Notas |
| ------------ | ---------- | ---------------------------------------------------------------------------------- |
| `2026-07-28` | ✅ | Actual. Sin sesión — la revisión viaja en cada solicitud. |
| `2025-11-25` | ✅ | Negociada mediante el handshake `initialize`. |
| `2025-06-18` | ✅ | Negociada mediante el handshake `initialize`. |
| `2025-03-26` | ✅ | Negociada mediante el handshake `initialize`. |
| `2024-11-05` | ✅ | Negociada mediante el handshake `initialize`. Obsoleta por MCP, aún aceptada aquí. |
**Si su cliente funciona hoy, seguirá funcionando.** Actualizar el servidor a `2026-07-28` no eliminó el soporte de ninguna revisión. No necesita actualizar su cliente, cambiar su configuración ni migrar a una URL diferente.
Implicaciones prácticas:
* **Clientes antiguos** — sin acción. Su cliente negocia una revisión anterior y se comporta exactamente igual que antes.
* **Clientes nuevos** — sin acción. Su cliente negocia `2026-07-28` y obtiene automáticamente las funciones del protocolo más reciente.
* **Las herramientas, alcances y URL son idénticos en todas las revisiones.** La revisión negociada cambia la mecánica del protocolo, no lo que su agente puede hacer.
Si un cliente no logra conectar, es muy poco probable que la revisión de protocolo sea la causa — compruebe primero la autenticación y la selección de organización (consulte las dos opciones a continuación) y luego contacte a [support@alvys.com](mailto:support@alvys.com).
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.
1. Vaya a la [configuración de Conectores](https://claude.ai/settings/connectors).
2. Seleccione **Agregar conector personalizado**.
3. Ingrese los datos del conector:
* **Nombre**: `Alvys`
* **URL**: `https://mcp.alvys.com/mcp`
4. Seleccione **Agregar** y complete el inicio de sesión de Alvys cuando se le solicite.
5. En un chat, abra el menú de adjuntos (**+**) y active el conector de Alvys.
1. Agregue el servidor:
```bash theme={null}
claude mcp add --transport http alvys https://mcp.alvys.com/mcp
```
2. 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.
1. Abra **Configuración → Servidores MCP → Agregar servidor**.
2. Complete los datos del servidor:
* **Nombre**: `Alvys`
* **Tipo**: **Streamable HTTP**
* **URL**: `https://mcp.alvys.com/mcp`
3. Seleccione **Guardar** y luego **Reiniciar**.
4. 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.
1. Abra la paleta de comandos con Command + Shift + P (Ctrl + Shift + P en Windows).
2. Busque **Open MCP settings** y seleccione **Add custom MCP**.
3. En `mcp.json`, agregue el servidor de Alvys:
```json theme={null}
{
"mcpServers": {
"alvys": {
"url": "https://mcp.alvys.com/mcp"
}
}
}
```
4. Recargue Cursor y complete el inicio de sesión de Alvys cuando se le solicite.
1. Agregue el servidor de Alvys a `~/.codex/config.toml`:
```toml theme={null}
[mcp_servers.alvys]
url = "https://mcp.alvys.com/mcp"
auth = "oauth"
```
2. Inicie el flujo de inicio de sesión:
```bash theme={null}
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.
1. 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](/en/api/guides/authentication-1) para obtener el tutorial completo.
2. Solicitar un token de acceso:
```bash theme={null}
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"
}'
```
3. 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](/en/api/guides/available-mcp-tools).
Una verificación de transporte sin formato (devuelve la lista de herramientas del servidor a través de Streamable HTTP):
```bash theme={null}
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
Explora el catálogo completo de herramientas, agrupadas por dominio, con el alcance que cada una requiere.
Tutorial completo sobre cómo crear credenciales y emitir tokens de acceso.
¿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](mailto:support@alvys.com)