Tools
The C21 Live Control MCP server exposes two layers of tools:
- Business-workflow tools — a small curated set named in
snake_case. Each one wraps a complete operator-facing workflow (rather than a single REST verb) and is advertised on every profile. The role of the account the server logs in with can still hide a tool whose operations that role may not call. - CRUD wrappers — autogenerated tools, one per public REST operation. Their names are the operation's OpenAPI
operationIdverbatim (camelCase). Which subset is callable depends on the active profile (voice/readonly/operator/full— see MCP server).
A business-workflow tool may call into one or more REST operations internally; the client only sees the curated name. The two layers coexist on the same connection — a voice client sees both.
Tool discovery — search_tools and call_tool
The generated CRUD catalogue is large, and advertising every schema on every turn inflates an agent's context. The server therefore collapses the generated tools of a profile behind two meta-tools:
search_tools— search the profile's generated catalogue by keyword; returns the matching tools with their full schemas.call_tool— invoke a generated tool by itsoperationIdname with structured arguments.
tools/list advertises the business-workflow tools plus these two meta-tools; the generated wrappers remain discoverable through search_tools and callable through call_tool. A client that already knows the operationId it needs can pass it to call_tool directly, without searching first.
Business-workflow tools (snake_case)
Fourteen tools, named in operator language rather than after API verbs:
| Tool | Workflow |
|---|---|
start_livestream | Start a Live stream end-to-end. Optional destinations (a list of Destination names): those Destinations go on air and the rest of the Live stream's Destinations stay off, keeping their renditions. An unknown name fails the call without starting and lists the available Destinations. Without destinations, the matrix of the last start is reused. A Live stream already on air is refused before anything is sent: use toggle_destination for its Destinations, or stop_livestream and start it again. |
stop_livestream | Stop a Live stream end-to-end. On a recurring Schedule it stops only the occurrence on air — the series and its Destinations stay intact; a one-off Schedule is cancelled. |
toggle_destination | Switch Destinations on or off on a Live stream. destinations takes a list, applied in order. Switching on a Destination that is not in the Live stream's configuration adds it and switches it on; no other Destination changes state. Switching off with remove_from_config: true also removes it from the configuration, unless it is still needed (see Switching Destinations on and off). |
update_destination_stream_key | Rotate the stream key of a bound Destination — pauses and resumes the Destination automatically when the broadcast is live. |
channel_slot_usage | Capacity overview — input slot occupancy per encoder Device. |
get_start_targets | Recommend where to start a Live stream (on-prem encoder group or C21 Live Cloud) based on each encoder group's real capacity and the availability of its devices. |
schedule_livestream | Create a fully-determined Schedule for a Live stream. Optional destinations works as in start_livestream and is stored as the Schedule's Destination matrix; an unknown name saves nothing. Without it, the Schedule switches on every Destination. |
get_livestream_status | Return a coherent runtime status object for one Live stream, with an arranque block while it is starting (see Start-up times). |
find_destination | Read-only: where a Destination is — its Destination groups, the Live streams that use them and whether they are on air, where it is switched on in Live Control, and each Live stream's next Schedule. It returns no keys or URLs. |
find_destinations_by_stream_key | Find the Destinations whose stream name, or a credential parameter of it, equals a given value — without showing any other Destination's value. |
verify_destination_stream_key | Check a given value against a Destination's configured stream key: match, slot, what reads show of both, and the format check for the Destination's provider. |
get_destination_stream_key | Return a Destination's full stream key, only on explicit request. Every reveal is audited (Destination, slot, user, session), never the value. |
get_channel_ingest | Return the contribution URL of a cloud Channel (RTMP push, SRT, UDP-R) as an operator types it into OBS or vMix. The SRT passphrase is never shown. |
import_file_from_url | Upload a logo, a video file or a license from the file the user attaches in the chat or from an https URL the user pastes. Live Control downloads the file itself (see Files from the chat). |
A business tool that could not do what it was asked reports a tool error (isError) with the backend's own reason; a read that could not be made is never filled in with a default. When Live Control refuses an operation, the text explains why with the values in place (see Refusals).
These are the operator-facing surface the voice profile is built around. They are advertised on every profile, including readonly (the readonly profile blocks mutating REST operations, but the curated workflows above remain visible — clients are expected not to invoke the mutating ones in observation contexts).
Switching Destinations on and off
toggle_destination takes one Destination (destination_name) or a list (destinations), applied in order; the first refusal stops the sequence.
- Switching on. A Destination that is not in the Live stream's configuration is added to it and switched on. Adding needs the permission to edit Destination groups; without it, the call is refused before anything is written.
- Switching off with
remove_from_config: true. The Destination is switched off and removed from the Live stream's configuration. It is kept there, and the answer says why, when:- another Live stream on air has it switched on, or has a Schedule still to come that switches it on — switched off on a Live stream on air, it does not hold it back;
- another Live stream that is stopped has a Schedule still to come;
- a Schedule still to come of the same Live stream switches it on, or does not list it (a Destination missing from a Schedule's matrix starts switched on);
- any of that cannot be read.
The check runs right before each removal; a Schedule another session creates in the meantime does not prevent it. When two Live streams share the same Destination group, removing the Destination from one removes it from both. - What was done. When a list stops halfway, the answer says what was applied, where it stopped and what was not tried; what was applied stays applied.
To find out where a Destination is configured before changing it, call find_destination. Its answer is what is configured in Live Control, not what the encoder confirms.
Start-up times
The times the tools quote come from a single table:
| Case | Usual time |
|---|---|
| YouTube Live input | Up to 2 minutes from when the YouTube broadcast is live |
| C21 Live Cloud | About 5 minutes |
| On-premise encoder | 45–60 seconds |
| Switching on a Destination | 10–20 seconds |
| Stopping | About 5 seconds |
start_livestream and toggle_destination (when switching on) add the usual time to their answer: within it, a transitional state is not a failure. While a Live stream is starting, get_livestream_status returns an arranque block: seconds since the start (segundosDesdeArranque), the phase (fase), the usual time and whether it is still within it (dentroDelPlazo). For a YouTube Live input the count runs from when the source delivers, not from the start; the block adds origenProgramadoPara (the start YouTube announces, while waiting for a scheduled broadcast) and origenEmiteDesde (since when the source delivers), when the encoder reports them.
Refusals
When Live Control refuses a call, the MCP server fills the placeholders of the API message with the values in data (see Pagination and errors), and validation errors carry their reasons. The answer to a refused toggle_destination starts with a short summary — code, reason and figure — before any name:
| Code | Reason |
|---|---|
APIf644 | No free output slot on the Live stream. The answer says how many Destinations are publishing and lists them; which one to switch off is the operator's call. |
APIf643 | The Live stream's Destination configuration already holds the maximum of 20 Destinations. |
Files from the chat
The MCP server offers the file operations of the web, and no file travels through the conversation.
- Downloads —
readAsset,downloadRecordings,downloadSystemLog,downloadDebugLogModuleanddownloadDebugLogChannelanswer a signed link instead of the file. The browser opens the link directly, without signing in, for 15 minutes. Live Control signs it only if the account may make that download. - Uploads —
import_file_from_urluploads a logo (target: "asset:logos"), a video file ("asset:files") or a license ("license"). The file is the one the user attaches in the chat, or anhttpsURL the user pastes. Live Control downloads the file and validates and stores it as the web upload does. It only fetches from public addresses, never from the internal network, within size and time limits. A license restarts the service, so the tool asks for explicit confirmation (confirm: true). - Fallback — When Live Control cannot download the file (no internet access, the file's server does not answer) or the chat does not hand over the attachment, the answer names the web screen that does the upload: Settings → Assets for logos and files, System status → Commands for the license.
- Not offered —
uploadAsset,installLicenseanduploadBackuptake only a multipart file, which an MCP call cannot carry. They are not registered andsearch_toolsdoes not find them; a call to one of them answers with where to do it instead.
The links are built on the address users open Live Control at, set at install time with --public-url (see Install C21 Live Control). Without it, the answer gives the link's path, to open on that address.
CRUD wrappers (camelCase operationId)
The rest of the tool catalogue is generated from the OpenAPI spec — one tool per operation, named after the operationId literally. Examples:
| Tool | Underlying operation |
|---|---|
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 |
The CRUD wrappers retain the API identifier Publishing (rather than the operator-facing label Destination) for the same reason the REST surface does: they are literal operationId strings — they mirror the OpenAPI schema. The business-workflow toggle is toggle_destination; the autogenerated CRUD wrapper around the same backend call is runtimeTogglePublishings. Both reach the same operation.
The effective source of truth is the tool catalogue the server announces on connect — it reflects the active profile. For an exhaustive per-operation reference, consult the OpenAPI spec.
Tools by resource
Each table below lists the CRUD-wrapper tools available against a resource. The set of tools an MCP client can actually call is the intersection of these operations with the active profile (and the user's role).
Live streams
| Tool | Purpose |
|---|---|
getAllLivestreams | List Live streams. Optional includeDestinations / includeChannel embed each stream's configured Destinations and resolved source Channel in the same response. |
getLivestreamById | Fetch one Live stream by id. |
getLivestreamStatus | Fetch the runtime status of one Live stream. |
getLivestreamsStatus | Fetch the runtime status of every Live stream in one call. |
getLivestreamStartConfig | Fetch the start-config preconditions (idEncoderGroup, last startConfig[], startAllowed). |
getLivestreamEnriched | Fetch a Live stream with enriched references resolved. |
addLivestream | Create a Live stream. |
updateLivestream | Update a Live stream. |
deleteLivestream | Delete a Live stream. |
startLivestream | Start a Live stream. |
stopLivestream | Stop a Live stream. |
runtimeApplyLogo | Apply or clear the logo on a running Live stream. |
runtimeApplyBlackout | Apply or clear the blackout / file replacement on a running Live stream. |
runtimeApplySourceSwitch | Switch the source of a running Live stream. |
runtimeTogglePublishings | Toggle the primary / backup state of bound Destinations on a running Live stream. |
runtimePushMetadata | Push metadata to a running Live stream. |
runtimeSetAdValues | Set ad-value markers on a running Live stream. |
setLivestreamText | Set the overlay text on a Live stream. |
updateLivestreamOptions | Update Live stream runtime options. |
Every tool that takes a Live stream id in its path names it livestreamId, getLivestreamStartConfig, getLivestreamEnriched and executeEditor included.
Channels (Sources)
| Tool | Purpose |
|---|---|
getAllChannels | List Channels. |
getChannelById | Fetch one Channel. |
addChannel | Create a Channel. |
updateChannel | Update a Channel. |
deleteChannel | Delete a Channel. |
Destinations
| Tool | Purpose |
|---|---|
getAllPublishings | List Destinations. |
getPublishingById | Fetch one Destination. |
addPublishing | Create a Destination. |
updatePublishing | Update a Destination. |
deletePublishing | Delete a Destination. |
getAllPublishingGroups | List Destination groups. |
addPublishingGroup | Create a Destination group. |
updatePublishingGroup | Update a Destination group. |
deletePublishingGroup | Delete a Destination group. |
Encodings
| Tool | Purpose |
|---|---|
getAllEncodings | List Encodings. |
getEncodingById | Fetch one Encoding. |
addEncoding | Create an Encoding. |
updateEncoding | Update an Encoding. |
deleteEncoding | Delete an Encoding. |
getAllEncodingGroups | List Encoding groups. |
addEncodingGroup | Create an Encoding group. |
updateEncodingGroup | Update an Encoding group. |
deleteEncodingGroup | Delete an Encoding group. |
Schedules
| Tool | Purpose |
|---|---|
getAllSchedules | List Schedules. |
getScheduleById | Fetch one Schedule. |
addSchedule | Create a Schedule. |
updateSchedule | Update a Schedule — including pause / resume through the enabled field. On a Schedule on air, bringing the end forward ends the broadcast (see Scheduler). |
deleteSchedule | Delete a Schedule: removes every future occurrence. A Schedule on air is deleted only with confirmStopLive: true, which also stops the Live stream and disables its Destinations; without it the call answers 409. |
getScheduleOccurrences | Expand a Schedule into its concrete occurrences over a date window. |
skipOccurrence | Cancel a single occurrence of a recurring Schedule, including the one on air (with confirmStopLive: true). |
restoreSkip | Restore a skipped occurrence that has not yet run. |
listScheduleSkips | List the skipped occurrences of a Schedule. |
patchScheduleUntil | End a recurring Schedule's series from a given date onward. |
The dedicated enable / disable endpoints were retired: pausing and resuming a Schedule is updateSchedule with { "enabled": … }.
Planned actions
| Tool | Purpose |
|---|---|
getLivestreamActions | List a Live stream's planned actions. |
addLivestreamAction | Create a planned action on a Live stream. |
getAllPlannedActions | List planned actions across Live streams, filterable by time window and status. |
getPlannedAction | Fetch one planned action. |
updatePlannedAction | Update or reschedule a pending planned action. |
deletePlannedAction | Delete a planned action. |
enablePlannedAction | Re-arm a disabled pending action. |
disablePlannedAction | Pause a pending action without deleting it. |
See Planned actions for the operator model, the command catalogue and the lifecycle rules.
Recordings
| Tool | Purpose |
|---|---|
getRecordings | List Recordings. |
getRecording | Fetch one Recording. |
getRecordingTracks | List the captured tracks of a Recording. |
deleteRecording | Delete a Recording. |
Devices
| Tool | Purpose |
|---|---|
getAllDevices | List Devices. |
getDeviceById | Fetch one Device. |
addDevice | Register a Device (one-time registration with register_username / register_password). |
updateDevice | Update a Device. |
deleteDevice | Delete a Device. |
getDevicesStatus | Fetch summary status across Devices. |
getDevicesLiveStatus | Fetch the live status of the Live streams running on the Devices. |
getAllDeviceGroups | List Device groups. |
createDeviceGroup | Create a Device group. |
updateDeviceGroup | Update a Device group. |
deleteDeviceGroup | Delete a Device group. |
Assets
| Tool | Purpose |
|---|---|
listAssets | List Assets, filterable by fileType (logos, files, clips). |
readAsset | Fetch an Asset by the id its listing returns. Answers a download link (see Files from the chat). |
deleteAsset | Delete an Asset by the id its listing returns. |
uploadAsset is not offered: logos and video files are uploaded with import_file_from_url.
DRM
| Tool | Purpose |
|---|---|
getAllDrmProviders | List DRM providers. |
getDrmProviderById | Fetch one DRM provider. |
addDrmProvider | Register a DRM provider. |
updateDrmProvider | Update a DRM provider. |
deleteDrmProvider | Delete a DRM provider. |
validateDrmProvider | Validate the credentials of a DRM provider. |
C21 Live Cloud
| Tool | Purpose |
|---|---|
getAllC21LiveCloudAccounts | List C21 Live Cloud accounts. |
getC21LiveCloudAccountById | Fetch one C21 Live Cloud account. |
addC21LiveCloudAccount | Register a C21 Live Cloud account. |
updateC21LiveCloudAccount | Update a C21 Live Cloud account. |
deleteC21LiveCloudAccount | Delete a C21 Live Cloud account. |
validateC21LiveCloudAccount | Revalidate a C21 Live Cloud account against the upstream platform. |
MediaCopilot
| Tool | Purpose |
|---|---|
getMediaCopilotAccount | Read the MediaCopilot account currently bound to this C21 Live Control instance. |
getMediaCopilotConfig | Read the MediaCopilot integration configuration (tenant URL, default collection, default template). |
updateMediaCopilotConfig | Write the MediaCopilot integration configuration. System Administrator only. |
getMediaCopilotCollections | List the collections exposed by the bound MediaCopilot tenant. Used by the configuration form's collection picker. |
getMediaCopilotTemplates | List the processing templates exposed by the bound MediaCopilot tenant. |
getMediaCopilotAssetStatus | Read the processing status of an asset previously handed off to MediaCopilot, by asset id. |
The MediaCopilot integration itself requires a MediaCopilot account contracted through Cires21 plus the C21LiveEditor license on the Live Control instance — see MediaCopilot for the integration model.
Security
API token management (createApiToken, listApiTokens, revokeApiToken) and the restore of a configuration backup (restoreBackup) are never offered by the MCP server, whatever the profile: a new token would end up in the chat history, and a restore can overwrite the network settings of the host. A call to one of them answers with the place to do it instead — the server CLI for tokens, the API for backups. The database backup is not offered either: an administrator keeps it on the host (livecontrol backup / livecontrol restore).
What the role may call
At startup the server asks the API, through POST /security/permissions, which of the operations the profile would register the role of its account may invoke, and hides the rest from tools/list and search_tools. A business tool is hidden when one of the operations it cannot do without is refused. When the API cannot answer (an older C21 Live Control, a Control still starting), nothing is hidden and a refused call still fails as a tool error.
Secrets in answers
Reads never hand the agent a secret in full. Where a Destination's stream name is a key (RTMP to YouTube, Twitch, Facebook, Instagram, Kick, X, Castr or Restream, or any value shaped like one of their keys) the agent receives a fingerprint; any other stream name is returned as it is, with credential parameters such as token or password masked. Credentials inside URLs — the password of a userinfo, SRT passphrases, tokens — reach the agent as *** in every answer, keeping scheme, host, port and path; a masked value written back preserves the stored one. MCP_SECRETS_MODE=strict refuses the three stream-key tools above and any write that sets a key or a credential parameter.
Return shape conventions
List operations return the standard {rows, pagination} envelope. Single-resource operations return the resource directly under data. Errors follow the standard envelope documented in Pagination and errors.
What MCP does not expose
- Event subscriptions. There is no
subscribe_events-style streaming tool today. To observe state changes, poll the relevantgetLivestreamStatusorgetDevicesLiveStatusendpoint. - Webhook management. The product does not expose a webhook subscription surface.