# MCP

Source: https://airi.live/docs/mcp
Language: es. The other: https://airi.live/docs/mcp.md?lang=en
Index: https://airi.live/llms.txt — every page in one file: https://airi.live/llms-full.txt

Conecta tu asistente de IA a tu cuenta: sube un vídeo, codifícalo, cífralo y publica un reproductor sin salir de la conversación. Un comando para instalarlo, y nada que mantener.

## Qué es

[MCP](https://modelcontextprotocol.io) es el protocolo con el que un asistente de IA usa herramientas externas. `@airi.live/mcp` es nuestro servidor: expone tu cuenta como **32 herramientas** que Claude, Cursor o cualquier cliente compatible puede llamar — subir un fichero, presupuestar una codificación, lanzarla, esperar a que termine, crear un reproductor y devolverte el embed.

Corre **en tu máquina**, no en la nuestra. Tu credencial no sale de ahí, y los bytes de una subida van del disco al bucket directamente, sin pasar por nuestro servidor ni por el asistente.

> **No es un producto aparte:** Son las mismas rutas que usa este panel y las mismas que usarías con `curl`. Lo que añade es la forma: descripciones que un modelo entiende, y tres herramientas que hacen varias llamadas seguidas porque encadenarlas a mano es donde se rompen las cosas.

## Instalarlo

Primero saca una credencial en [Desarrolladores](/app/developers), marcando los permisos que quieras darle al asistente. Después, un comando:

Claude Code:

```
claude mcp add airi --env AIRI_KMS_TOKEN=kms_live_... -- npx -y @airi.live/mcp
```

Para Claude Desktop, Cursor, Windsurf y cualquier cliente que se configure con JSON:

```
{
  "mcpServers": {
    "airi": {
      "command": "npx",
      "args": ["-y", "@airi.live/mcp"],
      "env": { "AIRI_KMS_TOKEN": "kms_live_..." }
    }
  }
}
```

Necesitas Node 20 o superior. No hay nada que instalar: `npx` lo descarga la primera vez y lo actualiza solo.

| Opción | Variable | Por defecto |
| --- | --- | --- |
| `--token` | `AIRI_KMS_TOKEN` | — (obligatorio) |
| `--namespace` | `AIRI_KMS_NAMESPACE` | el de tu credencial |
| `--url` | `AIRI_KMS_URL` | `https://kms.airi.live` |
| `--allow-admin` | `AIRI_MCP_ALLOW_ADMIN=true` | desactivado |
| `--timeout` | `AIRI_KMS_TIMEOUT_MS` | `60000` |

Las dos formas funcionan y la opción gana sobre la variable, pero **el token va mejor en el bloque `env`**: un argumento aparece en la lista de procesos de tu máquina y una variable de entorno no. `npx @airi.live/mcp --help` lo lista todo.

## Usarlo

A partir de ahí le hablas en tu idioma. Por ejemplo: *«sube ~/Vídeos/keynote.mp4, codifícalo a 1080p y 720p con DRM, y dame un embed para pegar en la web»*.

Lo que ejecuta por debajo:

```
airi_storage_upload   path=~/Vídeos/keynote.mp4        → id del fichero
airi_encoding_quote   heights=[1080,720] duration=600 → $0.16
airi_encoding_start   package=hls+dash drm=true       → id del trabajo
airi_encoding_job     wait=true                       → completado
airi_player_create    name="Web"                      → id del player
airi_player_embed     file=<id>                       → URL firmada + <iframe>
```

| Grupo | Herramientas |
| --- | --- |
| Almacenamiento | subir, listar, ver, firmar URL, borrar, uso |
| Codificación | presupuestar, calidades, lanzar, consultar, listar, cancelar, empaquetar |
| Reproductores | crear, listar, actualizar, borrar, embed |
| Claves DRM | crear, obtener, listar, rotar, periodos |
| Políticas | definir, listar, resolver, borrar |
| Consumo | saldo, licencias, estadísticas |
| Lo demás | descubrir endpoints, llamar a la API |

Tres hacen más de una llamada, porque la API está pensada para navegadores y un asistente no lo es. `airi_storage_upload` recibe una ruta y devuelve el fichero ya sellado — declaración, subida multiparte, recogida de ETags y cierre, todo dentro. `airi_encoding_job` con `wait` espera a que el trabajo termine, así que codificar es un paso y no un bucle de consultas. Y `airi_player_embed` devuelve el `<iframe>` listo junto al reproductor resuelto.

Las dos últimas son una salida de emergencia: leen la [referencia de la API](https://kms.airi.live/docs) en vivo y ejecutan lo que encuentren. Un endpoint nuevo está disponible el día que se publica, sin esperar a que actualicemos el paquete.

## Qué no puede hacer

Le estás dando acceso a tu cuenta a un modelo de lenguaje. Hay dos cosas que el servidor se niega a hacer aunque se lo pidas, y conviene que las sepas antes de instalarlo.

> **No le entrega tus claves de contenido al modelo:** La `key` y el `iv` son el secreto AES que descifra tu vídeo, y el resultado de una herramienta queda **literal en el historial del asistente** — que se guarda, se reenvía y a menudo viaja a un tercero. Las herramientas de claves devuelven el identificador, las cajas PSSH y las URLs de licencia, y ocultan el resto. Se puede pedir explícitamente con `includeKeyMaterial` para cifrar en local con shaka-packager; codificar con `drm: true` no lo necesita nunca.

> **No toca tu saldo ni tu cuenta:** `/v1/admin` (acredita saldos, crea credenciales), `/v1/auth` (emite tokens de sesión) y `/cas` (la llamada del proveedor de DRM) están vetados **independientemente de lo que permita tu token**. Lo que puede hacer un agente y lo que puede hacer una credencial son preguntas distintas, y la respuesta a la primera no debería depender de lo generosa que fuera la segunda.

Todo lo demás sí es alcanzable, porque es el trabajo. Borrar y codificar llevan la marca `destructiveHint` del protocolo, así que tu cliente puede pedirte confirmación antes de ejecutarlas, y las descripciones dicen sin rodeos qué no tiene vuelta atrás: un `contentId` es permanente en el proveedor de DRM, un fichero borrado no se recupera, y cancelar una codificación detiene el cobro pero no al codificador.

## Dale sólo lo que necesita

El límite real es la credencial: el servidor no puede conceder lo que tu token no tiene. Crea una **para el asistente**, en vez de reutilizar la tuya, marcando sólo los permisos del trabajo que le vas a pedir.

| Permiso | Qué habilita |
| --- | --- |
| Almacenamiento | subir, listar, firmar y borrar ficheros |
| Codificación | presupuestar, lanzar y cancelar trabajos |
| Reproductores | crear y editar reproductores y sus embeds |
| Claves y políticas | DRM, políticas de licencia, saldo y consumo |

Un asistente de sólo lectura es una credencial marcada sin escritura: podrá mirarlo todo y no cambiar nada. Y revocarla desde [Desarrolladores](/app/developers) la corta en la siguiente llamada, no dentro de un minuto.

> **El gasto sigue siendo tuyo:** Codificar y crear claves cuestan dinero, y el asistente los ejecuta con tu saldo. Codificar reserva el importe **antes** de arrancar, así que una petición desmedida se para contra tu saldo y no contra tu tarjeta. Aun así, dale permiso de codificación sólo si esperas que codifique.

## Si algo no va

| Lo que ves | Qué pasa |
| --- | --- |
| `UNAUTHORIZED` | El token está mal o fue revocado. Saca otro en [Desarrolladores](/app/developers) |
| `FORBIDDEN` | A la credencial le falta ese permiso. Créala de nuevo marcando el que corresponda |
| `INSUFFICIENT_FUNDS` | Sin saldo. Leer sigue funcionando; subir, codificar y crear claves no |
| «needs a concrete namespace» | Tu token no está fijado a un espacio: añade `--namespace` |
| El servidor no arranca | `npx @airi.live/mcp --help` desde una terminal te dice qué falta |

Los errores llegan al asistente con su código y una pista de qué hacer, así que en general se corrige solo y te lo cuenta. Si no, los registros del cliente MCP llevan lo que el servidor escribió.