Model Context Protocol (MCP)

Tella’s MCP server provides a standardized interface that allows any compatible AI assistant to access your Tella workspace. List videos, manage playlists, edit clips, upload new clips and B-roll videos, apply layouts, and more — all through natural language.

Endpoint

https://api.tella.com/mcp

Setup

Claude Code
Claude Desktop
Cursor

Run this command in your terminal:

claude mcp add --transport http --scope user tella https://api.tella.com/mcp

Or for one-click install: Add Tella MCP ServerYou’ll be prompted to authenticate with your Tella account.

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "tella": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://api.tella.com/mcp"
      ]
    }
  }
}

Add to your MCP settings:

{
  "mcpServers": {
    "tella": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://api.tella.com/mcp"
      ]
    }
  }
}

Authentication

The MCP server uses OAuth 2.1 for authentication. When you first connect, you’ll be redirected to Tella to authorize access. The connection uses your Tella account permissions — you can only access videos and playlists in workspaces you belong to.

Available tools

Videos

list_videos

get_video

Get video information. Returns summary fields by default. Use include flags for additional data.Parameters:

id (required): Video ID
includeTranscript (optional): Include transcript text
includeChapters (optional): Include chapter markers
includeThumbnails (optional): Include thumbnail URLs
includeExports (optional): Include export status

update_video

Update video metadata and settings.Parameters:

id (required): Video ID
name (optional): Video title
description (optional): Video description
playbackRate (optional): Default playback speed (0.5-2.0)
captionsEnabled (optional): Show captions by default
transcriptEnabled (optional): Show transcript tab
commentsEnabled (optional): Allow comments
downloadsEnabled (optional): Allow downloads
linkScope (optional): Access level — public, private, password, or embedonly
password (optional): Password for protected videos
searchEngineIndexingEnabled (optional): Allow search engine indexing

delete_video

Delete a video (moves to trash).Parameters:

id (required): Video ID

duplicate_video

Create a copy of a video. Supports trimming to extract a time range or specific chapter.Parameters:

id (required): Video ID to duplicate
name (optional): Name for the duplicate
startTime (optional): Trim start time in seconds (use with endTime)
endTime (optional): Trim end time in seconds (use with startTime)
chapterIndex (optional): Extract a specific chapter by 0-based index (cannot be combined with startTime/endTime)

export_video

Start a video export. Returns the export status with workflow ID and download URL when complete.Parameters:

id (required): Video ID
granularity (optional): video (full video, default), clips (one file per clip), or raw (raw recordings)
resolution (optional): 4k for 4K; omit for default
fps (optional): Frames per second — 30 or 60
subtitles (optional): Burn in subtitles
speed (optional): Playback speed — 0.5, 0.75, 1, 1.25, 1.5, 1.75, or 2

add_collaborator_to_video

Add a collaborator to a video. The user must be a member of your workspace.Parameters:

id (required): Video ID
email (required): Email address of the user to add
role (required): Role to grant — editor or viewer

update_collaborator_on_video

Change a collaborator’s role on a video.Parameters:

id (required): Video ID
userId (required): User ID of the collaborator
role (required): New role — editor or viewer

remove_collaborator_from_video

Remove a collaborator from a video.Parameters:

id (required): Video ID
userId (required): User ID of the collaborator to remove

Playlists

list_playlists

List all playlists in your workspace.Parameters:

visibility (optional): Filter by personal or org
cursor (optional): Pagination cursor
limit (optional): Items per page (1-100, default: 20)

create_playlist

Create a new playlist.Parameters:

name (required): Playlist name
description (optional): Playlist description
emoji (optional): Emoji icon
visibility (optional): personal or org
linkScope (optional): Access level — public, private, or password
password (optional): Password for protected playlists

get_playlist

Get detailed information about a playlist.Parameters:

id (required): Playlist ID

update_playlist

Update playlist metadata and settings.Parameters:

id (required): Playlist ID
name (optional): Playlist name
description (optional): Playlist description
emoji (optional): Emoji icon
linkScope (optional): Access level
password (optional): Password for protected playlists
searchEngineIndexingEnabled (optional): Allow search engine indexing

delete_playlist

Delete a playlist.Parameters:

id (required): Playlist ID

add_video_to_playlist

Add a video to a playlist.Parameters:

playlistId (required): Playlist ID
videoId (required): Video ID to add

remove_video_from_playlist

Remove a video from a playlist.Parameters:

playlistId (required): Playlist ID
videoId (required): Video ID to remove

Sources

A source is an uploaded video file that can be turned into a new clip or used as B-roll media inside a layout. Create a source, upload the bytes to the returned pre-signed URL, then reference the sourceId from upload_clip or add_layout / update_layout.

create_source

Create a new video source upload. Returns a sourceId and a pre-signed uploadUrl — PUT the video bytes to uploadUrl (the URL expires after 1 hour). Once uploaded, the sourceId can be used by upload_clip (to add a new clip) or by add_layout / update_layout (as B-roll media of type: "video").Parameters:

kind (optional): Source kind. Only video is supported.
width (required): Width in pixels
height (required): Height in pixels
duration (required): Duration in seconds

Clips

A clip is a section of a video — Tella videos are made up of one or more clips. Each clip has its own cuts, layouts, transcript, and editing tools.

upload_clip

Add a new clip to a video from an uploaded source. Call create_source first, PUT the bytes to the returned uploadUrl, then pass the sourceId here.Parameters:

videoId (required): Video ID
sourceId (required): Source ID returned by create_source
name (optional): Clip name. Defaults to the next Clip N.

list_clips

List clips in a video, ordered by their position.Parameters:

videoId (required): Video ID

get_clip

Get a single clip’s details.Parameters:

videoId (required): Video ID
id (required): Clip ID

update_clip

Update a clip’s name, ordering, cuts, or background.Parameters:

videoId (required): Video ID
id (required): Clip ID
name (optional): New clip name
order (optional): New position within the video
cuts (optional): Replaces the clip’s cuts. Each cut is {startTimeMs, durationMs}. Total cut duration must be less than the clip’s duration.
background (optional): Background {type, color?, imageUrl?, videoUrl?, videoDurationSeconds?, gradientColor1?, gradientColor2?, gradientAngle?}. type is one of solid, image, video, gradient.

delete_clip

Remove a clip from its video.Parameters:

videoId (required): Video ID
id (required): Clip ID

duplicate_clip

Duplicate a clip. The copy is inserted right after the original by default.Parameters:

videoId (required): Video ID
id (required): Clip ID to duplicate
name (optional): Name for the new clip
order (optional): Position for the new clip

reorder_clip

Move a clip to a new position; other clips shift to stay contiguous.Parameters:

videoId (required): Video ID
id (required): Clip ID
order (required): New 0-based position

cut_clip

Cut one or more time ranges from a clip in a single call. Overlapping or adjacent ranges are merged into the clip’s existing cuts. To clear all cuts, call update_clip with cuts: [].Parameters:

videoId (required): Video ID
id (required): Clip ID
cuts (required): Array of {fromMs, toMs} ranges to cut, in ms from the clip’s start. Send all ranges in one call instead of issuing many cut_clip calls.

cut_clip_by_transcript

Cut one or more ranges from a clip by referencing word indices in the uncut transcript. The server resolves each word’s exact start/end ms — no padding is applied. Use get_uncut_transcript to look up word indices.Parameters:

videoId (required): Video ID
id (required): Clip ID
wordRanges (required): Array of {fromWordIndex, toWordIndex} ranges. Both indices are inclusive and come from the clip’s uncut transcript.

get_silences

Detect silent ranges in the clip’s audio.Parameters:

videoId (required): Video ID
id (required): Clip ID
minDurationMs (optional): Minimum silence length to report, in ms. Defaults to 200.

remove_fillers

Auto-detect and cut filler words (“um”, “uh”, etc.) from the clip’s transcript.Parameters:

videoId (required): Video ID
id (required): Clip ID

list_sources

List the underlying recordings (camera, screen, mic) the clip was cut from.Parameters:

videoId (required): Video ID
id (required): Clip ID

get_clip_thumbnail

Get a thumbnail of the clip. Static formats (jpg/png/webp/gif) return inline image content the model can see, plus a signed URL. mp4 returns a URL only.Parameters:

videoId (required): Video ID
id (required): Clip ID
format (optional): jpg (default), png, webp, gif, or mp4
inpointMs (optional): Frame offset from the clip’s start (default 0)
durationMs (optional): Duration of the animated preview. Only valid when format is gif or mp4.
width (optional): Output width in pixels (default 320)
height (optional): Output height in pixels (default 180)
download (optional): Suggest a download disposition on the signed URL

get_video_thumbnail

Get a thumbnail of an entire video. Same format/sizing options as get_clip_thumbnail.Parameters:

id (required): Video ID
format (optional): jpg, png, webp, gif, or mp4
inpointMs (optional): Frame offset from the start of the video
durationMs (optional): Duration of the animated preview (gif/mp4 only)
width / height (optional): Output dimensions

get_source_thumbnail

Get a thumbnail of a specific source recording.Parameters:

videoId (required): Video ID
clipId (required): Clip ID
sourceId (required): Source recording ID
format (optional): jpg, png, webp, gif, or mp4
inpointMs (optional): Frame offset from the source’s start
durationMs (optional): Duration of the animated preview (gif/mp4 only)
width / height (optional): Output dimensions

get_source_waveform

Get the waveform data for a source recording’s audio track.Parameters:

videoId (required): Video ID
clipId (required): Clip ID
sourceId (required): Source recording ID

get_cut_transcript

Transcript for the clip after cuts are applied (what the viewer hears).Parameters:

videoId (required): Video ID
id (required): Clip ID

get_uncut_transcript

Transcript for the clip’s full source, ignoring cuts. Useful when you want to find content that’s been cut out.Parameters:

videoId (required): Video ID
id (required): Clip ID

Layouts

A layout decides how a clip’s camera and screen layers are composed at a given time. Apply a layout to the whole clip (no startTimeMs/durationMs) or to a specific time range. Read the clip first to see its layoutSceneType — that determines which kind values are valid. The layout field is a structured object discriminated by kind:

`kind`	Valid scene types	Variant fields
`fullscreen`	`cameraSubject`, `basicSubject`	`style: regular \| stretch` (camera-subject) or `screenFit: cover \| letterbox` (basic-subject)
`middle`	`cameraSubject`, `basicSubject`	`shape` (camera-subject)
`side-by-side`	`combi` (landscape)	`position: left \| right`, `style: regular \| even \| overlap`, `size` (when `style=overlap`)
`tv-presenter`	`combi` (landscape)	`position: left \| right`, `style: regular \| full \| overlap`
`camera-bubble`	`combi` (all ratios)	`position` (9-way), `shape: circle \| square \| landscape \| portrait`, `size: S \| M \| L`, optional `style: regular \| full`, optional `screenFit` (when `style=full`)
`camera-only`	`combi` (all ratios)	`style: fullscreen \| middle`, `punchIn` (when `style=fullscreen`), `shape` (when `style=middle`)
`screen-only`	`combi` (all ratios)	`style: fullscreen \| middle`, `screenFit` (when `style=fullscreen`)

list_layouts

List the layouts on a clip, including the synthetic base layout (the layout that spans the whole clip).Parameters:

videoId (required): Video ID
id (required): Clip ID

add_layout

Add a layout to a clip. Pass startTimeMs + durationMs for a time range, or omit both for a clip-spanning layout.Parameters:

videoId (required): Video ID
id (required): Clip ID
layout (required): Structured layout object (see table above)
startTimeMs (optional): Start time in ms
durationMs (optional): Duration in ms
transitionStyle (optional): Transition into the layout — spring (default smooth) or hardCut. Only valid on time-ranged layouts.
media (optional): B-roll content displayed during the layout. Only valid on time-ranged layouts whose kind displays the screen slot (i.e. not camera-only or any *-camera-only-* variant). Either:
- {type: "image", imageUrl, width, height} for an image, or
- {type: "video", sourceId} for a video — sourceId comes from create_source after you upload the bytes.

Example:

{
  "videoId": "vid_…",
  "id": "cl_…",
  "layout": {"kind": "side-by-side", "position": "left", "style": "regular"},
  "startTimeMs": 5000,
  "durationMs": 4000
}

update_layout

Update a layout on a clip. Only provided fields change.Parameters:

videoId (required): Video ID
id (required): Clip ID
layoutId (required): Layout ID (use base for the clip-spanning layout)
layout (optional): New structured layout
startTimeMs (optional): New start time
durationMs (optional): New duration
transitionStyle (optional): spring or hardCut. Rejected on the base layout.
media (optional): Replace the layout’s B-roll content. Rejected on the base layout. Same shape as add_layout’s media — {type: "image", imageUrl, width, height} or {type: "video", sourceId}.

remove_layout

Remove a non-base layout from a clip. Use update_layout to change the base layout.Parameters:

videoId (required): Video ID
id (required): Clip ID
layoutId (required): Layout ID

Zooms

Zoom into a specific point on the clip’s screen layer for a time range (the camera is unaffected). Use manualZoom for a fixed focus point or trackingZoom to follow the cursor in the screen recording.

list_zooms

List zooms on a clip.Parameters:

videoId (required): Video ID
id (required): Clip ID

add_zoom

Add a zoom to a clip.Parameters:

videoId (required): Video ID
id (required): Clip ID
type (required): manualZoom or trackingZoom
startTimeMs (required): Start time in ms
durationMs (required): Duration in ms
focusPoint (optional): Required for manualZoom; ignored for trackingZoom. Percentages — {xPct, yPct} (0-100).
scale (optional): Magnification factor (1 = no zoom, 3.5 = max)

update_zoom

Update an existing zoom. Only provided fields change.Parameters:

videoId (required): Video ID
id (required): Clip ID
zoomId (required): Zoom ID
type (optional): manualZoom or trackingZoom
startTimeMs (optional): New start time
durationMs (optional): New duration
focusPoint (optional): New focus point
scale (optional): New magnification

remove_zoom

Remove a zoom from a clip.Parameters:

videoId (required): Video ID
id (required): Clip ID
zoomId (required): Zoom ID

Blurs and highlights

Mask a rectangular region of the clip’s screen layer to either blur it (hide sensitive info) or highlight it (draw attention). Both share the same shape: a rectangle defined by a top-left point and dimensions, both in percentages.

list_blurs / list_highlights

List blur or highlight masks on a clip.Parameters:

videoId (required): Video ID
id (required): Clip ID

add_blur / add_highlight

Add a blur or highlight mask to a clip.Parameters:

videoId (required): Video ID
id (required): Clip ID
startTimeMs (required): Start time in ms
durationMs (required): Duration in ms
point (required): Top-left corner — {xPct, yPct} (0-100)
dimensions (required): Rectangle size — {widthPct, heightPct} (0-100)

update_blur / update_highlight

Update an existing blur or highlight.Parameters:

videoId (required): Video ID
id (required): Clip ID
maskId (required): Mask ID
startTimeMs (optional): New start time
durationMs (optional): New duration
point (optional): New top-left
dimensions (optional): New size

remove_blur / remove_highlight

Remove a blur or highlight from a clip.Parameters:

videoId (required): Video ID
id (required): Clip ID
maskId (required): Mask ID

Example prompts

Once connected, you can ask your AI assistant things like:

“List all my Tella videos”
“Get the transcript for video xyz”
“Create a playlist called ‘Product Updates’ and add my latest 3 videos”
“Make my onboarding video public and enable downloads”
“Trim the first 5 seconds off the intro clip”
“Add a side-by-side layout to the demo clip from 10s to 20s with the camera on the left”
“Add a B-roll image of our product logo at 30s for 4 seconds”
“Upload this video file as a new clip at the end of my onboarding video”
“Add this product demo clip as B-roll between 12s and 20s of the intro”
“Find the silent gaps in my latest clip longer than 1.5 seconds”
“Remove all the filler words from the keynote clip”
“Blur the email address in the bottom-left of the screen between 12s and 18s”
“Zoom into the top-right of the screen at 25s for 3 seconds”

Troubleshooting

Authentication issues

If you’re having trouble authenticating, try clearing your MCP auth cache:

rm -rf ~/.mcp-auth

Then reconnect to trigger a fresh OAuth flow.

Connection issues

Ensure you’re using a compatible MCP client. The server uses HTTP transport.

Getting Started

Guides

API Reference

Webhooks

Model Context Protocol (MCP)

Endpoint

Setup

Authentication

Available tools

Videos

Playlists

Sources

Clips

Layouts

Zooms

Blurs and highlights

Example prompts

Troubleshooting

Authentication issues

Connection issues

Getting Started

Guides

API Reference

Webhooks

Documentation Index

​Endpoint

​Setup

​Authentication

​Available tools

​Videos

​Playlists

​Sources

​Clips

​Layouts

​Zooms

​Blurs and highlights

​Example prompts

​Troubleshooting

​Authentication issues

​Connection issues

Endpoint

Setup

Authentication

Available tools

Videos

Playlists

Sources

Clips

Layouts

Zooms

Blurs and highlights

Example prompts

Troubleshooting

Authentication issues

Connection issues