MCP Server

Tools

Catálogo de tools MCP que anuncia el servidor C21 Live Control.

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 operationId literal 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 de operationId con 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:

ToolWorkflow
start_livestreamArranca 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_livestreamDetiene 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_destinationEnciende 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_keyRota la stream key de un Destination enlazado — pausa y reanuda el Destination automáticamente si la emisión está en marcha.
channel_slot_usageVista de capacidad — ocupación de slots de entrada por Device encoder.
get_start_targetsRecomienda 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_livestreamCrea 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_statusDevuelve un objeto de estado runtime coherente de un Live stream, con un bloque arranque mientras arranca (consulta Tiempos de arranque).
find_destinationSolo 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_keyBusca 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_keyComprueba 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_keyDevuelve 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_ingestDevuelve 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_urlSube 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:

CasoTiempo habitual
Entrada Youtube LiveHasta 2 minutos desde que la emisión de YouTube está en directo
C21 Live CloudUnos 5 minutos
Encoder on-premise45–60 segundos
Encender un destino10–20 segundos
PararUnos 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ódigoMotivo
APIf644No 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.
APIf643La 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, downloadDebugLogModule y downloadDebugLogChannel devuelven 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_url sube 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 URL https que 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, installLicense y uploadBackup solo aceptan un fichero multipart, que una llamada MCP no puede llevar. No se registran y search_tools no 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:

ToolOperación subyacente
getAllLivestreamsGET /c21apiv2/livestreams
getLivestreamByIdGET /c21apiv2/livestreams/{livestreamId}
startLivestreamPOST /c21apiv2/livestreams/{livestreamId}/start
stopLivestreamPOST /c21apiv2/livestreams/{livestreamId}/stop
runtimeApplyLogoPOST /c21apiv2/livestreams/{livestreamId}/runtimeOptions/logo
runtimeApplyBlackoutPOST /c21apiv2/livestreams/{livestreamId}/runtimeOptions/blackout
runtimeTogglePublishingsPOST /c21apiv2/livestreams/{livestreamId}/runtimeOptions/publishings
getAllChannelsGET /c21apiv2/channels
getAllPublishingsGET /c21apiv2/publishings
getAllSchedulesGET /c21apiv2/schedules
getRecordingsGET /c21apiv2/recordings
getDevicesLiveStatusGET /c21apiv2/devices/livestatus
listAssetsGET /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

ToolPropósito
getAllLivestreamsLista Live streams. Los parámetros opcionales includeDestinations / includeChannel incorporan en la misma respuesta los Destinations configurados y el Channel de origen de cada stream.
getLivestreamByIdObtiene un Live stream por id.
getLivestreamStatusObtiene el estado en runtime de un Live stream.
getLivestreamsStatusObtiene el estado en runtime de cada Live stream en una sola llamada.
getLivestreamStartConfigObtiene las precondiciones de arranque (idEncoderGroup, último startConfig[], startAllowed).
getLivestreamEnrichedObtiene un Live stream con referencias enriquecidas resueltas.
addLivestreamCrea un Live stream.
updateLivestreamActualiza un Live stream.
deleteLivestreamBorra un Live stream.
startLivestreamArranca un Live stream.
stopLivestreamDetiene un Live stream.
runtimeApplyLogoAplica o limpia el logo en un Live stream en marcha.
runtimeApplyBlackoutAplica o limpia el blackout / reemplazo por fichero en un Live stream en marcha.
runtimeApplySourceSwitchCambia la fuente de un Live stream en marcha.
runtimeTogglePublishingsAlterna el estado primary / backup de los Destinations enlazados en un Live stream en marcha.
runtimePushMetadataEnvía metadatos a un Live stream en marcha.
runtimeSetAdValuesEstablece marcadores ad-value en un Live stream en marcha.
setLivestreamTextEstablece el texto de overlay en un Live stream.
updateLivestreamOptionsActualiza 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)

ToolPropósito
getAllChannelsLista Channels.
getChannelByIdObtiene un Channel.
addChannelCrea un Channel.
updateChannelActualiza un Channel.
deleteChannelBorra un Channel.

Destinations

ToolPropósito
getAllPublishingsLista Destinations.
getPublishingByIdObtiene un Destination.
addPublishingCrea un Destination.
updatePublishingActualiza un Destination.
deletePublishingBorra un Destination.
getAllPublishingGroupsLista Destination groups.
addPublishingGroupCrea un Destination group.
updatePublishingGroupActualiza un Destination group.
deletePublishingGroupBorra un Destination group.

Encodings

ToolPropósito
getAllEncodingsLista Encodings.
getEncodingByIdObtiene un Encoding.
addEncodingCrea un Encoding.
updateEncodingActualiza un Encoding.
deleteEncodingBorra un Encoding.
getAllEncodingGroupsLista Encoding groups.
addEncodingGroupCrea un Encoding group.
updateEncodingGroupActualiza un Encoding group.
deleteEncodingGroupBorra un Encoding group.

Schedules

ToolPropósito
getAllSchedulesLista Schedules.
getScheduleByIdObtiene un Schedule.
addScheduleCrea un Schedule.
updateScheduleActualiza 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).
deleteScheduleBorra 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.
getScheduleOccurrencesExpande un Schedule en ocurrencias sobre una ventana de fechas.
skipOccurrenceCancela una ocurrencia concreta de un Schedule recurrente, incluida la que está en emisión (con confirmStopLive: true).
restoreSkipRestaura una ocurrencia omitida que aún no ha llegado.
listScheduleSkipsLista las ocurrencias omitidas de un Schedule.
patchScheduleUntilTermina 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

ToolPropósito
getLivestreamActionsLista las acciones planificadas de un Live stream.
addLivestreamActionCrea una acción planificada sobre un Live stream.
getAllPlannedActionsLista acciones planificadas de todos los Live streams, filtrable por ventana temporal y estado.
getPlannedActionObtiene una acción planificada.
updatePlannedActionActualiza o replanifica una acción planificada pendiente.
deletePlannedActionBorra una acción planificada.
enablePlannedActionRearma una acción pendiente deshabilitada.
disablePlannedActionPausa 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

ToolPropósito
getRecordingsLista grabaciones.
getRecordingObtiene una grabación.
getRecordingTracksLista las pistas capturadas de una grabación.
deleteRecordingBorra una grabación.

Devices

ToolPropósito
getAllDevicesLista Devices.
getDeviceByIdObtiene un Device.
addDeviceRegistra un Device (registro one-time con register_username / register_password).
updateDeviceActualiza un Device.
deleteDeviceBorra un Device.
getDevicesStatusObtiene el estado resumen entre Devices.
getDevicesLiveStatusObtiene el estado en vivo de los Live streams corriendo en los Devices.
getAllDeviceGroupsLista Device groups.
createDeviceGroupCrea un Device group.
updateDeviceGroupActualiza un Device group.
deleteDeviceGroupBorra un Device group.

Assets

ToolPropósito
listAssetsLista Assets, filtrable por fileType (logos, files, clips).
readAssetObtiene un Asset por el id que devuelve su listado. Responde con un enlace de descarga (consulta Archivos desde el chat).
deleteAssetBorra 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

ToolPropósito
getAllDrmProvidersLista DRM providers.
getDrmProviderByIdObtiene un DRM provider.
addDrmProviderRegistra un DRM provider.
updateDrmProviderActualiza un DRM provider.
deleteDrmProviderBorra un DRM provider.
validateDrmProviderValida las credenciales de un DRM provider.

C21 Live Cloud

ToolPropósito
getAllC21LiveCloudAccountsLista cuentas C21 Live Cloud.
getC21LiveCloudAccountByIdObtiene una cuenta C21 Live Cloud.
addC21LiveCloudAccountRegistra una cuenta C21 Live Cloud.
updateC21LiveCloudAccountActualiza una cuenta C21 Live Cloud.
deleteC21LiveCloudAccountBorra una cuenta C21 Live Cloud.
validateC21LiveCloudAccountRevalida una cuenta C21 Live Cloud contra la plataforma upstream.

MediaCopilot

ToolPropósito
getMediaCopilotAccountLee la cuenta MediaCopilot enlazada actualmente a esta instancia de C21 Live Control.
getMediaCopilotConfigLee la configuración de la integración MediaCopilot (URL del tenant, colección por defecto, template por defecto).
updateMediaCopilotConfigEscribe la configuración de la integración MediaCopilot. Solo System Administrator.
getMediaCopilotCollectionsLista las colecciones que expone el tenant MediaCopilot enlazado. Usado por el selector de colección del formulario.
getMediaCopilotTemplatesLista las plantillas de procesado que expone el tenant MediaCopilot enlazado.
getMediaCopilotAssetStatusLee 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_events hoy. Para observar cambios de estado, sondea el endpoint getLivestreamStatus o getDevicesLiveStatus correspondiente.
  • Gestión de webhooks. El producto no expone una superficie de suscripción a webhooks.
Copyright © 2026