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. This page covers connecting a client, authentication, and error handling. Every tool has its own entry in the tool reference.

Endpoint

https://api.tella.com/mcp

Discovery metadata

MCP clients and agent directories can discover Tella through these public, machine-readable endpoints:

MCP Server Card: https://api.tella.com/mcp/server-card
AI Catalog: https://www.tella.com/.well-known/ai-catalog.json

The server card describes Tella’s Streamable HTTP endpoint and supported MCP protocol version. The AI Catalog links to the server card so compatible agents can find Tella automatically.

Setup

Connect Tella from Claude’s Connector Directory:

Open Tella in Claude’s Connector Directory.
Select Connect and sign in to Tella.
Authorize Claude to access your Tella workspace.

Once connected, you can ask Claude to find and manage videos, edit clips, organize playlists, and start exports.

Connect the official Tella app from ChatGPT’s app directory:

Open Tella in ChatGPT.
Connect it and finish signing in to Tella. ChatGPT uses your existing Tella workspace permissions.

Once connected, mention @Tella in a chat to find and manage videos, edit clips, organize playlists, and start exports.

Add Tella as a custom connector instead

If you’d rather point ChatGPT at the MCP server directly:

Open Settings → Apps & Connectors, then enable Developer mode under Advanced settings.
Create a connector named Tella and paste the MCP server URL:

https://api.tella.com/mcp

Connect it and finish signing in to Tella.

Muse connects to apps through Connectors. Tella isn’t in Muse’s connector directory yet, so ask Muse to add it as a custom connector. Paste this into a new message:

Add Tella as a connector. Its MCP server is https://api.tella.com/mcp, a remote MCP server over streamable HTTP that uses OAuth. Send me the sign-in link and I'll approve it with my Tella account. Save a skill so anything about my Tella videos, playlists, or edits goes through the Tella tools.

Muse replies with a Tella sign-in link. Approve it, and Muse saves the connector as a skill for future conversations. Nothing runs on your machine: Muse connects from its own cloud environment, so mcp-remote isn’t needed. Step-by-step help: Connect Tella to Muse.

Grok Bot adds MCP servers through Plugins. Tella isn’t in the plugin marketplace yet, so ask your Bot to add it as a custom server in chat:

Add a custom MCP server called tella at https://api.tella.com/mcp

Confirm with Add it, then select Authorize on the connect card the Bot posts and sign in to Tella. Type @ in a chat to attach tella to a task. Bots run on a cloud computer, so the hosted endpoint works as-is and mcp-remote isn’t needed. Step-by-step help: Connect Tella to Grok Bot.

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"
      ]
    }
  }
}

Run this command in your terminal:

codex mcp add tella --url https://api.tella.com/mcp

Or add it to your ~/.codex/config.toml manually:

[mcp_servers.tella]
url = "https://api.tella.com/mcp"

You’ll be prompted to authenticate with your Tella account.

Link passwords in ChatGPT

OpenAI’s app guidelines don’t allow apps to collect passwords, so ChatGPT never sees Tella’s link-password inputs. In ChatGPT — and in other OpenAI-hosted clients, including Codex — the password input and the password option of linkScope are left out of the tool list, and a tool call that sets either one returns an invalid_argument error. Everything else works the same. To put a video or playlist behind a password, set it in the Tella app, or use a client that still offers the input, such as Claude or Cursor.

Authentication

The MCP server uses OAuth 2.1 for authentication. When you first connect, you’ll be redirected to Tella to authorize access. Most tools use your Tella account permissions, so you can only access videos and playlists in workspaces you belong to. The get_video, get_storyboard, get_video_frame, get_video_preview, get_clip_frame, and get_clip_preview tools can also read a video outside your workspace when it has an ungated public link. A public or embed-only playlist does not bypass the video’s own private link, password, or email gate. If your agent uses WorkOS agent registration, its access token can authenticate to this MCP endpoint after a Tella user claims the registration. The agent uses that user’s permissions and the token’s workspace (org_id), or the user’s default workspace if the token has no org_id. An unclaimed registration cannot authenticate. MCP clients can discover Tella’s OAuth configuration from these standard metadata endpoints:

Protected resource: https://api.tella.com/.well-known/oauth-protected-resource
Authorization server: https://www.tella.com/.well-known/oauth-authorization-server

Errors and rate limits

Tool arguments are validated against each tool’s advertised schema before the call runs. Missing required fields, incorrect types, unsupported enum values, and values outside documented limits return an invalid_argument tool error that names the affected field. Every tool advertises an outputSchema. A successful call returns its payload as JSON in a text content block and again as structuredContent, which conforms to that schema, so clients can validate results instead of parsing text. Fields may be added over time; treat the schema as a minimum. Tool errors set isError and carry machine-readable details in _meta and in a trailing text block. They never use structuredContent, which is reserved for payloads that match the outputSchema:

{
  "content": [
    {
      "type": "text",
      "text": "Invalid arguments for get_video: \"id\" is required"
    },
    {
      "type": "text",
      "text": "{\"errorCode\":\"invalid_argument\",\"retryable\":false}"
    }
  ],
  "isError": true,
  "_meta": {
    "com.tella/error": {
      "errorCode": "invalid_argument",
      "retryable": false
    }
  }
}

Use errorCode to identify the failure and only retry automatically when retryable is true. Tella can return not_found, rate_limited, invalid_argument, forbidden, unauthorized, conflict, edit_conflict, unavailable, internal, not_implemented, not_ready, or unknown_tool. edit_conflict means another edit to the same video landed while the call was running, so nothing from the call was applied. Resend it unchanged. External MCP tool calls share the public API limit of 100 requests per minute for each user in a workspace. get_video_analytics is also limited to 30 calls per minute for each workspace. A rate-limited tool result includes errorCode: "rate_limited", retryable: true, and the number of seconds to wait in its text content. See Rate limiting for details.

Retrying tool calls safely

A tool call that creates or changes something can be resent without applying the change twice by giving it an idempotency key in the request’s _meta: any string of at most 255 characters that is unique for your connection, such as a UUID.

{
  "jsonrpc": "2.0",
  "id": 12,
  "method": "tools/call",
  "params": {
    "name": "add_zoom",
    "arguments": {"videoId": "vid_abc123", "clipId": "clp_1", "startTimeMs": 0, "durationMs": 2000},
    "_meta": {"idempotencyKey": "6d1e9f2a-3c4b-4d5e-8f6a-7b8c9d0e1f2a"}
  }
}

The rules match the REST API’s Idempotency-Key header: an identical resend (same tool and arguments) replays the stored result for 24 hours, the same key with different arguments is an invalid_argument error, and a resend while the first call is still running is a conflict error. Retryable rate_limited, edit_conflict and pre-execution unavailable results are not stored, so the call can be retried with the same key. An internal result is stored because it may have happened after a write; check whether the change applied before trying again with a new key.

Tools

Tools are grouped by the resource they work on, the same way as the API reference. Each page lists that area’s tools with their parameters and behaviour.

Managing videos

Organize and share your workspace: list and update videos, manage playlists, tags, and webhook subscriptions, control access, export finished videos, and publish them to social media.

Videos

List, search, read, configure, duplicate, export, and share videos.

Playlists

Playlists and sidebar playlist groups.

Webhooks

List and update your webhook subscriptions.

Social publishing

Publish videos to connected YouTube, LinkedIn, X, Instagram and Facebook accounts.

Analytics

Plays, watch time, retention, geography, and referrers.

Editing videos

Build and refine the video itself: upload sources, add and cut clips, apply layouts, crop screen recordings, and add zooms, blurs, highlights, overlays, and sound effects. Every timestamp is in milliseconds on the clip’s playback timeline, with cuts applied.

Batch edits

Apply up to 200 timeline edits in one call with apply_video_edits.

Sources

Upload video, audio, and image files to use anywhere in a video.

Library

Reusable media plus Tella’s curated sound effects and music.

AI media generation

Generate images and sound effects from a prompt.

Backgrounds

Browse personal, workspace, and default backgrounds.

Chapters

Read and replace chapter markers.

Clips

Add, cut, reorder, preview, and transcribe clips.

Layouts

Compose camera and screen layers, add B-roll, auto layouts.

Cropping

Crop a screen recording to its visible content.

Background music

Set or remove a looping music track.

Zooms

Manual and cursor-tracking zooms, and auto zooms from clicks.

Mouse events

Cursor path and clicks from a screen recording.

Blurs and highlights

Mask regions of the screen to hide or emphasize them.

Overlays

Image and video overlays on top of a clip.

Text overlays

Titles, callouts, and labels.

Sound effects

Curated or uploaded sound effects over a clip.

Get started with Skills

Tella has two kinds of skills for agents. Official skill. The tella skill in tellahq/skills, maintained by Tella, teaches your agent to connect this MCP server, inspect a video before editing, pick the right tool, and verify the result:

npx skills add tellahq/skills

Community skills. The Skills directory offers open-source workflows for editing local video files — cutting dead air, adding zooms, finding B-roll, and publishing your latest Tella recording to YouTube. Most are built by Louise de Sadeleer on the Tella team, with community contributions alongside; they don’t go through the MCP server.

Browse the Skills directory

Install a skill with one command and start editing videos with your AI agent in minutes.

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”
“Create a ‘Customer facing’ tag and add it to my demo videos”
“Show me all videos tagged ‘Onboarding’”
“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”
“Generate zooms for my demo clip wherever I clicked”
“Auto-layout my tutorial clip and keep the camera visible the whole time”
“Turn on Studio Sound for my latest video”
“Add my logo as an overlay in the top-right corner from 5s to 10s”
“Play this whoosh sound effect at 8s when the transition happens”
“List my webhook subscriptions”
“Pause delivery on my webhook endpoint”
“Update my webhook to only send video.created and export.ready events”

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.

​Endpoint

​Discovery metadata

​Setup

​Link passwords in ChatGPT

​Authentication

​Errors and rate limits

​Retrying tool calls safely

​Tools

​Managing videos