Tools
El servidor MCP de C21 Live Control expone dos capas de tools:
- Business-workflow tools — un pequeño conjunto curado en
snake_case. Cada una envuelve un flujo completo cara al operador (no un verbo REST individual) y se anuncia en todos los perfiles. El rol de la cuenta con la que el servidor inicia sesión puede ocultar, aun así, una tool cuyas operaciones ese rol no puede invocar. - Wrappers CRUD — autogenerados, uno por operación pública de la REST. Sus nombres son el
operationIdliteral de OpenAPI (camelCase). El subconjunto invocable depende del perfil activo (voice/readonly/operator/full— ver Servidor MCP).
Una business-workflow tool puede invocar internamente una o varias operaciones REST; el cliente solo ve el nombre curado. Las dos capas conviven en la misma conexión — un cliente voice ve ambas.
Descubrimiento de tools — search_tools y call_tool
El catálogo CRUD generado es grande, y anunciar cada schema en cada turno infla el contexto del agente. Por eso el servidor pliega las tools generadas de un perfil tras dos meta-tools:
search_tools— busca por palabra clave en el catálogo generado del perfil; devuelve las tools coincidentes con su schema completo.call_tool— invoca una tool generada por su nombre deoperationIdcon argumentos estructurados.
tools/list anuncia las business-workflow tools más estas dos meta-tools; los wrappers generados siguen siendo descubribles mediante search_tools e invocables mediante call_tool. Un cliente que ya conoce el operationId que necesita puede pasarlo a call_tool directamente, sin buscar antes.
Business-workflow tools (snake_case)
Catorce tools, nombradas en lenguaje de operador en lugar de en verbos de API:
| Tool | Workflow |
|---|---|
start_livestream | Arranca un Live stream de extremo a extremo. destinations opcional (lista de nombres de Destination): esos Destinations salen al aire y el resto de Destinations del Live stream queda apagado, conservando sus renditions. Un nombre desconocido hace fallar la llamada sin arrancar y lista los Destinations disponibles. Sin destinations, se reutiliza la matriz del último arranque. Un Live stream que ya está en emisión se rechaza antes de enviar nada: para sus destinos, toggle_destination; para volver a arrancarlo, stop_livestream y arrancar de nuevo. |
stop_livestream | Detiene un Live stream de extremo a extremo. En un Schedule recurrente detiene solo la ocurrencia en emisión — la serie y sus Destinations se conservan; un Schedule puntual se cancela. |
toggle_destination | Enciende o apaga destinos en un Live stream. destinations admite una lista, que se aplica en orden. Encender un destino que no está en la configuración del Live stream lo añade y lo enciende; ningún otro destino cambia de estado. Apagar con remove_from_config: true además lo retira de la configuración, salvo que siga haciendo falta (consulta Encender y apagar destinos). |
update_destination_stream_key | Rota la stream key de un Destination enlazado — pausa y reanuda el Destination automáticamente si la emisión está en marcha. |
channel_slot_usage | Vista de capacidad — ocupación de slots de entrada por Device encoder. |
get_start_targets | Recomienda dónde arrancar un Live stream (grupo de encoders on-prem o C21 Live Cloud) según la capacidad real de cada grupo de encoders y la disponibilidad de sus dispositivos. |
schedule_livestream | Crea un Schedule completamente determinado para un Live stream. destinations opcional funciona igual que en start_livestream y se guarda como matriz de Destinations del Schedule; un nombre desconocido no guarda nada. Sin él, el Schedule enciende todos los Destinations. |
get_livestream_status | Devuelve un objeto de estado runtime coherente de un Live stream, con un bloque arranque mientras arranca (consulta Tiempos de arranque). |
find_destination | Solo lectura: dónde está un destino — sus grupos de destinos, los Live streams que los usan y si están en emisión, dónde está encendido en Live Control y la próxima programación de cada Live stream. No devuelve claves ni URL. |
find_destinations_by_stream_key | Busca los Destinations cuyo stream name, o un parámetro de credencial de este, coincide con un valor dado — sin mostrar el valor de ningún otro Destination. |
verify_destination_stream_key | Comprueba un valor dado contra la stream key configurada de un Destination: coincidencia, slot, lo que muestran las lecturas de ambos y la comprobación de formato del provider del Destination. |
get_destination_stream_key | Devuelve la stream key completa de un Destination, solo a petición explícita. Cada revelación se audita (Destination, slot, usuario, sesión), nunca el valor. |
get_channel_ingest | Devuelve la URL de contribución de un Channel cloud (RTMP push, SRT, UDP-R) tal como un operador la teclea en OBS o vMix. La passphrase SRT no se muestra nunca. |
import_file_from_url | Sube un logo, un archivo de vídeo o una licencia desde el archivo que el usuario adjunta en el chat o desde una URL https que pega. Live Control descarga el archivo (consulta Archivos desde el chat). |
Una business tool que no ha podido hacer lo que se le pedía devuelve un error de tool (isError) con el motivo real del backend; una lectura que no se ha podido hacer nunca se rellena con un valor por defecto. Cuando Live Control rechaza una operación, el texto explica el motivo con los valores en su sitio (consulta Rechazos).
Son la superficie cara al operador sobre la que está montado el perfil voice. Se anuncian en cada perfil, incluido readonly (el perfil readonly bloquea las operaciones REST mutantes, pero los workflows curados siguen visibles — se espera que los clientes en contexto de observación no invoquen los que mutan).
Encender y apagar destinos
toggle_destination recibe un destino (destination_name) o una lista (destinations), que se aplica en orden; el primer rechazo detiene la secuencia.
- Encender. Un destino que no está en la configuración del Live stream se añade a ella y se enciende. Añadirlo requiere permiso para editar grupos de destinos; sin él, la llamada se rechaza antes de escribir nada.
- Apagar con
remove_from_config: true. El destino se apaga y se retira de la configuración del Live stream. Se queda en ella, y la respuesta dice por qué, cuando:- otro Live stream en emisión lo tiene encendido, o tiene una programación aún por llegar que lo enciende — apagado en un Live stream en emisión, no lo retiene;
- otro Live stream parado tiene una programación aún por llegar;
- una programación aún por llegar del mismo Live stream lo enciende, o no lo incluye (un destino que falta en la matriz de una programación arranca encendido);
- no se ha podido leer alguna de esas cosas.
La comprobación se hace justo antes de cada retirada; una programación que otra sesión cree mientras tanto no la impide. Si dos Live streams comparten el mismo grupo de destinos, retirar el destino de uno lo retira de los dos. - Qué se hizo. Cuando una lista se detiene a medias, la respuesta dice qué se aplicó, dónde se detuvo y qué no se intentó; lo aplicado queda aplicado.
Para saber dónde está configurado un destino antes de cambiarlo, llama a find_destination. Su respuesta es lo configurado en Live Control, no lo que confirma el encoder.
Tiempos de arranque
Los tiempos que citan las tools salen de una sola tabla:
| Caso | Tiempo habitual |
|---|---|
| Entrada Youtube Live | Hasta 2 minutos desde que la emisión de YouTube está en directo |
| C21 Live Cloud | Unos 5 minutos |
| Encoder on-premise | 45–60 segundos |
| Encender un destino | 10–20 segundos |
| Parar | Unos 5 segundos |
start_livestream y toggle_destination (al encender) añaden el tiempo habitual a su respuesta: dentro de él, un estado transitorio no es un fallo. Mientras un Live stream arranca, get_livestream_status devuelve un bloque arranque: segundos desde el arranque (segundosDesdeArranque), la fase (fase), el tiempo habitual y si sigue dentro de él (dentroDelPlazo). Con una entrada Youtube Live la cuenta empieza cuando la fuente emite, no al arrancar; el bloque añade origenProgramadoPara (la hora de inicio que anuncia YouTube, mientras se espera una emisión programada) y origenEmiteDesde (desde cuándo emite la fuente), cuando el encoder los informa.
Rechazos
Cuando Live Control rechaza una llamada, el servidor MCP rellena los huecos del mensaje de la API con los valores de data (consulta Paginación y errores), y los errores de validación llevan sus motivos. La respuesta a un toggle_destination rechazado empieza por un resumen corto — código, motivo y cifra — antes de cualquier nombre:
| Código | Motivo |
|---|---|
APIf644 | No queda hueco de salida en el Live stream. La respuesta dice cuántos destinos emiten y los lista; cuál apagar lo decide el operador. |
APIf643 | La configuración de destinos del Live stream ya tiene el máximo de 20 destinos. |
Archivos desde el chat
El servidor MCP ofrece las operaciones con archivos de la web, y ningún archivo pasa por la conversación.
- Descargas —
readAsset,downloadRecordings,downloadSystemLog,downloadDebugLogModuleydownloadDebugLogChanneldevuelven un enlace firmado en lugar del archivo. El navegador abre el enlace directamente, sin iniciar sesión, durante 15 minutos. Live Control solo lo firma si la cuenta puede hacer esa descarga. - Subidas —
import_file_from_urlsube un logo (target: "asset:logos"), un archivo de vídeo ("asset:files") o una licencia ("license"). El archivo es el que el usuario adjunta en el chat, o una URLhttpsque pega. Live Control descarga el archivo y lo valida y guarda igual que la subida de la web. Solo descarga de direcciones públicas, nunca de la red interna, con límites de tamaño y de tiempo. La licencia reinicia el servicio, así que la tool pide confirmación explícita (confirm: true). - Alternativa — Cuando Live Control no puede descargar el archivo (sin salida a internet, o el servidor del archivo no responde) o el chat no entrega el adjunto, la respuesta indica la pantalla de la web que hace la subida: Settings → Assets para logos y archivos, System status → Commands para la licencia.
- No se ofrecen —
uploadAsset,installLicenseyuploadBackupsolo aceptan un fichero multipart, que una llamada MCP no puede llevar. No se registran ysearch_toolsno las encuentra; una llamada a cualquiera de ellas responde con dónde hacerlo.
Los enlaces se construyen sobre la dirección con la que los usuarios abren Live Control, que se fija al instalar con --public-url (consulta Instalar C21 Live Control). Sin ella, la respuesta da la ruta del enlace, para abrirla sobre esa dirección.
Wrappers CRUD (operationId camelCase)
El resto del catálogo se genera desde el spec OpenAPI — una tool por operación, con el operationId como nombre literal. Ejemplos:
| Tool | Operación subyacente |
|---|---|
getAllLivestreams | GET /c21apiv2/livestreams |
getLivestreamById | GET /c21apiv2/livestreams/{livestreamId} |
startLivestream | POST /c21apiv2/livestreams/{livestreamId}/start |
stopLivestream | POST /c21apiv2/livestreams/{livestreamId}/stop |
runtimeApplyLogo | POST /c21apiv2/livestreams/{livestreamId}/runtimeOptions/logo |
runtimeApplyBlackout | POST /c21apiv2/livestreams/{livestreamId}/runtimeOptions/blackout |
runtimeTogglePublishings | POST /c21apiv2/livestreams/{livestreamId}/runtimeOptions/publishings |
getAllChannels | GET /c21apiv2/channels |
getAllPublishings | GET /c21apiv2/publishings |
getAllSchedules | GET /c21apiv2/schedules |
getRecordings | GET /c21apiv2/recordings |
getDevicesLiveStatus | GET /c21apiv2/devices/livestatus |
listAssets | GET /c21apiv2/assets |
Los wrappers CRUD conservan el identificador de API Publishing (en lugar de la etiqueta Destination cara al operador) por la misma razón que la superficie REST: son cadenas literales del operationId — reflejan el schema OpenAPI. La business-workflow toggle es toggle_destination; el wrapper CRUD autogenerado sobre la misma llamada de backend es runtimeTogglePublishings. Ambas llegan a la misma operación.
La fuente de verdad efectiva es el catálogo de tools que el servidor anuncia al conectar — refleja el perfil activo. Para una referencia exhaustiva por operación, consulta el spec OpenAPI.
Tools por recurso
Cada tabla lista las operaciones disponibles contra un recurso. El conjunto de tools que un cliente MCP puede llamar realmente es la intersección de estas operaciones con el perfil activo (y el rol del usuario).
Live streams
| Tool | Propósito |
|---|---|
getAllLivestreams | Lista Live streams. Los parámetros opcionales includeDestinations / includeChannel incorporan en la misma respuesta los Destinations configurados y el Channel de origen de cada stream. |
getLivestreamById | Obtiene un Live stream por id. |
getLivestreamStatus | Obtiene el estado en runtime de un Live stream. |
getLivestreamsStatus | Obtiene el estado en runtime de cada Live stream en una sola llamada. |
getLivestreamStartConfig | Obtiene las precondiciones de arranque (idEncoderGroup, último startConfig[], startAllowed). |
getLivestreamEnriched | Obtiene un Live stream con referencias enriquecidas resueltas. |
addLivestream | Crea un Live stream. |
updateLivestream | Actualiza un Live stream. |
deleteLivestream | Borra un Live stream. |
startLivestream | Arranca un Live stream. |
stopLivestream | Detiene un Live stream. |
runtimeApplyLogo | Aplica o limpia el logo en un Live stream en marcha. |
runtimeApplyBlackout | Aplica o limpia el blackout / reemplazo por fichero en un Live stream en marcha. |
runtimeApplySourceSwitch | Cambia la fuente de un Live stream en marcha. |
runtimeTogglePublishings | Alterna el estado primary / backup de los Destinations enlazados en un Live stream en marcha. |
runtimePushMetadata | Envía metadatos a un Live stream en marcha. |
runtimeSetAdValues | Establece marcadores ad-value en un Live stream en marcha. |
setLivestreamText | Establece el texto de overlay en un Live stream. |
updateLivestreamOptions | Actualiza opciones de runtime del Live stream. |
Toda tool que recibe un id de Live stream en la ruta lo llama livestreamId, también getLivestreamStartConfig, getLivestreamEnriched y executeEditor.
Channels (Sources)
| Tool | Propósito |
|---|---|
getAllChannels | Lista Channels. |
getChannelById | Obtiene un Channel. |
addChannel | Crea un Channel. |
updateChannel | Actualiza un Channel. |
deleteChannel | Borra un Channel. |
Destinations
| Tool | Propósito |
|---|---|
getAllPublishings | Lista Destinations. |
getPublishingById | Obtiene un Destination. |
addPublishing | Crea un Destination. |
updatePublishing | Actualiza un Destination. |
deletePublishing | Borra un Destination. |
getAllPublishingGroups | Lista Destination groups. |
addPublishingGroup | Crea un Destination group. |
updatePublishingGroup | Actualiza un Destination group. |
deletePublishingGroup | Borra un Destination group. |
Encodings
| Tool | Propósito |
|---|---|
getAllEncodings | Lista Encodings. |
getEncodingById | Obtiene un Encoding. |
addEncoding | Crea un Encoding. |
updateEncoding | Actualiza un Encoding. |
deleteEncoding | Borra un Encoding. |
getAllEncodingGroups | Lista Encoding groups. |
addEncodingGroup | Crea un Encoding group. |
updateEncodingGroup | Actualiza un Encoding group. |
deleteEncodingGroup | Borra un Encoding group. |
Schedules
| Tool | Propósito |
|---|---|
getAllSchedules | Lista Schedules. |
getScheduleById | Obtiene un Schedule. |
addSchedule | Crea un Schedule. |
updateSchedule | Actualiza un Schedule — incluida la pausa / reanudación mediante el campo enabled. En un Schedule en emisión, adelantar el fin termina la emisión (consulta Scheduler). |
deleteSchedule | Borra un Schedule: elimina todas las ocurrencias futuras. Un Schedule en emisión solo se borra con confirmStopLive: true, que además detiene el Live stream y deshabilita sus destinos; sin él, la llamada responde 409. |
getScheduleOccurrences | Expande un Schedule en ocurrencias sobre una ventana de fechas. |
skipOccurrence | Cancela una ocurrencia concreta de un Schedule recurrente, incluida la que está en emisión (con confirmStopLive: true). |
restoreSkip | Restaura una ocurrencia omitida que aún no ha llegado. |
listScheduleSkips | Lista las ocurrencias omitidas de un Schedule. |
patchScheduleUntil | Termina la serie de un Schedule recurrente a partir de una fecha. |
Los endpoints dedicados de enable / disable se retiraron: pausar y reanudar un Schedule es updateSchedule con { "enabled": … }.
Planned actions
| Tool | Propósito |
|---|---|
getLivestreamActions | Lista las acciones planificadas de un Live stream. |
addLivestreamAction | Crea una acción planificada sobre un Live stream. |
getAllPlannedActions | Lista acciones planificadas de todos los Live streams, filtrable por ventana temporal y estado. |
getPlannedAction | Obtiene una acción planificada. |
updatePlannedAction | Actualiza o replanifica una acción planificada pendiente. |
deletePlannedAction | Borra una acción planificada. |
enablePlannedAction | Rearma una acción pendiente deshabilitada. |
disablePlannedAction | Pausa una acción pendiente sin borrarla. |
Consulta Planned actions para el modelo de operador, el catálogo de comandos y las reglas de ciclo de vida.
Recordings
| Tool | Propósito |
|---|---|
getRecordings | Lista grabaciones. |
getRecording | Obtiene una grabación. |
getRecordingTracks | Lista las pistas capturadas de una grabación. |
deleteRecording | Borra una grabación. |
Devices
| Tool | Propósito |
|---|---|
getAllDevices | Lista Devices. |
getDeviceById | Obtiene un Device. |
addDevice | Registra un Device (registro one-time con register_username / register_password). |
updateDevice | Actualiza un Device. |
deleteDevice | Borra un Device. |
getDevicesStatus | Obtiene el estado resumen entre Devices. |
getDevicesLiveStatus | Obtiene el estado en vivo de los Live streams corriendo en los Devices. |
getAllDeviceGroups | Lista Device groups. |
createDeviceGroup | Crea un Device group. |
updateDeviceGroup | Actualiza un Device group. |
deleteDeviceGroup | Borra un Device group. |
Assets
| Tool | Propósito |
|---|---|
listAssets | Lista Assets, filtrable por fileType (logos, files, clips). |
readAsset | Obtiene un Asset por el id que devuelve su listado. Responde con un enlace de descarga (consulta Archivos desde el chat). |
deleteAsset | Borra un Asset por el id que devuelve su listado. |
uploadAsset no se ofrece: los logos y los archivos de vídeo se suben con import_file_from_url.
DRM
| Tool | Propósito |
|---|---|
getAllDrmProviders | Lista DRM providers. |
getDrmProviderById | Obtiene un DRM provider. |
addDrmProvider | Registra un DRM provider. |
updateDrmProvider | Actualiza un DRM provider. |
deleteDrmProvider | Borra un DRM provider. |
validateDrmProvider | Valida las credenciales de un DRM provider. |
C21 Live Cloud
| Tool | Propósito |
|---|---|
getAllC21LiveCloudAccounts | Lista cuentas C21 Live Cloud. |
getC21LiveCloudAccountById | Obtiene una cuenta C21 Live Cloud. |
addC21LiveCloudAccount | Registra una cuenta C21 Live Cloud. |
updateC21LiveCloudAccount | Actualiza una cuenta C21 Live Cloud. |
deleteC21LiveCloudAccount | Borra una cuenta C21 Live Cloud. |
validateC21LiveCloudAccount | Revalida una cuenta C21 Live Cloud contra la plataforma upstream. |
MediaCopilot
| Tool | Propósito |
|---|---|
getMediaCopilotAccount | Lee la cuenta MediaCopilot enlazada actualmente a esta instancia de C21 Live Control. |
getMediaCopilotConfig | Lee la configuración de la integración MediaCopilot (URL del tenant, colección por defecto, template por defecto). |
updateMediaCopilotConfig | Escribe la configuración de la integración MediaCopilot. Solo System Administrator. |
getMediaCopilotCollections | Lista las colecciones que expone el tenant MediaCopilot enlazado. Usado por el selector de colección del formulario. |
getMediaCopilotTemplates | Lista las plantillas de procesado que expone el tenant MediaCopilot enlazado. |
getMediaCopilotAssetStatus | Lee el estado de procesado de un Asset entregado previamente a MediaCopilot, por id de Asset. |
La integración MediaCopilot requiere una cuenta MediaCopilot contratada vía Cires21 más la licencia C21LiveEditor en la instancia de Live Control — consulta MediaCopilot para el modelo de integración.
Security
La gestión de API tokens (createApiToken, listApiTokens, revokeApiToken) y la restauración de un backup de configuración (restoreBackup) no se ofrecen nunca desde el servidor MCP, sea cual sea el perfil: un token nuevo acabaría en el historial del chat, y una restauración puede sobrescribir la configuración de red del host. Una llamada a cualquiera de ellas responde con el lugar donde hacerlo — la CLI del servidor para los tokens, la API para los backups. Tampoco se ofrece el backup de la base de datos: un administrador lo conserva en el host (livecontrol backup / livecontrol restore).
Lo que el rol puede invocar
Al arrancar, el servidor pregunta a la API, mediante POST /security/permissions, cuáles de las operaciones que el perfil registraría puede invocar el rol de su cuenta, y oculta el resto de tools/list y de search_tools. Una business tool se oculta cuando se rechaza una de las operaciones sin las que no puede funcionar. Cuando la API no puede responder (un C21 Live Control anterior, un Control todavía arrancando) no se oculta nada y una llamada rechazada sigue fallando como error de tool.
Secretos en las respuestas
Las lecturas nunca entregan al agente un secreto completo. Cuando el stream name de un Destination es una clave (RTMP a YouTube, Twitch, Facebook, Instagram, Kick, X, Castr o Restream, o cualquier valor con la forma de una de sus claves) el agente recibe una huella; cualquier otro stream name se devuelve tal cual, con los parámetros de credencial como token o password enmascarados. Las credenciales dentro de URLs — la contraseña de un userinfo, passphrases SRT, tokens — llegan al agente como *** en todas las respuestas, conservando esquema, host, puerto y ruta; un valor enmascarado reenviado conserva el almacenado. MCP_SECRETS_MODE=strict rechaza las tres tools de stream key anteriores y cualquier escritura que fije una clave o un parámetro de credencial.
Convenciones de shape de retorno
Las operaciones de lista devuelven el envelope estándar {rows, pagination}. Las operaciones de un único recurso devuelven el recurso directamente bajo data. Los errores siguen el envelope estándar documentado en Paginación y errores.
Lo que MCP no expone
- Suscripciones a eventos. No hay una tool de streaming tipo
subscribe_eventshoy. Para observar cambios de estado, sondea el endpointgetLivestreamStatusogetDevicesLiveStatuscorrespondiente. - Gestión de webhooks. El producto no expone una superficie de suscripción a webhooks.