> ## Documentation Index
> Fetch the complete documentation index at: https://www.tella.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Model Context Protocol (MCP)

> Connect Claude, ChatGPT, Cursor, Codex, and other AI assistants to your Tella workspace.

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](#tools).

## 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

<Tabs>
  <Tab title="Claude">
    Connect Tella from Claude's Connector Directory:

    1. Open [Tella in Claude's Connector Directory](https://claude.ai/directory/tella).
    2. Select **Connect** and sign in to Tella.
    3. 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.
  </Tab>

  <Tab title="ChatGPT">
    Add Tella as a custom connector:

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

    ```
    https://api.tella.com/mcp
    ```

    3. Connect it and finish signing in to Tella. ChatGPT uses your existing Tella workspace permissions.
  </Tab>

  <Tab title="Claude Code">
    Run this command in your terminal:

    ```bash theme={null}
    claude mcp add --transport http --scope user tella https://api.tella.com/mcp
    ```

    Or for one-click install: [Add Tella MCP Server](claude://mcp/add?transport=http\&name=tella\&url=https://api.tella.com/mcp)

    You'll be prompted to authenticate with your Tella account.
  </Tab>

  <Tab title="Claude Desktop">
    Add to your `claude_desktop_config.json`:

    ```json theme={null}
    {
      "mcpServers": {
        "tella": {
          "command": "npx",
          "args": [
            "mcp-remote",
            "https://api.tella.com/mcp"
          ]
        }
      }
    }
    ```
  </Tab>

  <Tab title="Cursor">
    Add to your MCP settings:

    ```json theme={null}
    {
      "mcpServers": {
        "tella": {
          "command": "npx",
          "args": [
            "mcp-remote",
            "https://api.tella.com/mcp"
          ]
        }
      }
    }
    ```
  </Tab>

  <Tab title="Codex">
    Run this command in your terminal:

    ```bash theme={null}
    codex mcp add tella --url https://api.tella.com/mcp
    ```

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

    ```toml theme={null}
    [mcp_servers.tella]
    url = "https://api.tella.com/mcp"
    ```

    You'll be prompted to authenticate with your Tella account.
  </Tab>
</Tabs>

## 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.

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.

Tool errors include machine-readable details in `structuredContent`:

```json theme={null}
{
  "content": [
    {
      "type": "text",
      "text": "Invalid arguments for get_video: \"id\" is required"
    }
  ],
  "isError": true,
  "structuredContent": {
    "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`, `unavailable`, `internal`, `not_implemented`, `not_ready`, or `unknown_tool`.

External MCP tool calls share the public API limit of 100 requests per minute for each user in a 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](/docs/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.

```json theme={null}
{
  "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`](/docs/authentication#idempotent-requests) 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` 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, and export finished videos.

<CardGroup cols={2}>
  <Card title="Videos" icon="video" href="/docs/mcp-tools/videos">
    List, search, read, configure, duplicate, export, and share videos.
  </Card>

  <Card title="Playlists" icon="list" href="/docs/mcp-tools/playlists">
    Playlists and sidebar playlist groups.
  </Card>

  <Card title="Tags" icon="tag" href="/docs/mcp-tools/tags">
    Workspace and private tags, and tagging videos.
  </Card>

  <Card title="Webhooks" icon="bell" href="/docs/mcp-tools/webhooks">
    List and update your webhook subscriptions.
  </Card>

  <Card title="Analytics" icon="chart-line" href="/docs/mcp-tools/analytics">
    Plays, watch time, retention, geography, and referrers.
  </Card>
</CardGroup>

### 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.

<CardGroup cols={2}>
  <Card title="Batch edits" icon="layer-group" href="/docs/mcp-tools/batch-edits">
    Apply up to 200 timeline edits in one call with `apply_video_edits`.
  </Card>

  <Card title="Sources" icon="upload" href="/docs/mcp-tools/sources">
    Upload video, audio, and image files to use anywhere in a video.
  </Card>

  <Card title="Library" icon="photo-film" href="/docs/mcp-tools/library">
    Reusable media plus Tella's curated sound effects and music.
  </Card>

  <Card title="AI media generation" icon="wand-magic-sparkles" href="/docs/mcp-tools/ai-media-generation">
    Generate images and sound effects from a prompt.
  </Card>

  <Card title="Backgrounds" icon="image" href="/docs/mcp-tools/backgrounds">
    Browse personal, workspace, and default backgrounds.
  </Card>

  <Card title="Chapters" icon="bookmark" href="/docs/mcp-tools/chapters">
    Read and replace chapter markers.
  </Card>

  <Card title="Clips" icon="film" href="/docs/mcp-tools/clips">
    Add, cut, reorder, preview, and transcribe clips.
  </Card>

  <Card title="Layouts" icon="table-columns" href="/docs/mcp-tools/layouts">
    Compose camera and screen layers, add B-roll, auto layouts.
  </Card>

  <Card title="Cropping" icon="crop" href="/docs/mcp-tools/cropping">
    Crop a screen recording to its visible content.
  </Card>

  <Card title="Background music" icon="music" href="/docs/mcp-tools/background-music">
    Set or remove a looping music track.
  </Card>

  <Card title="Zooms" icon="magnifying-glass-plus" href="/docs/mcp-tools/zooms">
    Manual and cursor-tracking zooms, and auto zooms from clicks.
  </Card>

  <Card title="Mouse events" icon="arrow-pointer" href="/docs/mcp-tools/mouse-events">
    Cursor path and clicks from a screen recording.
  </Card>

  <Card title="Blurs and highlights" icon="eye-slash" href="/docs/mcp-tools/blurs-and-highlights">
    Mask regions of the screen to hide or emphasize them.
  </Card>

  <Card title="Overlays" icon="images" href="/docs/mcp-tools/overlays">
    Image and video overlays on top of a clip.
  </Card>

  <Card title="Text overlays" icon="font" href="/docs/mcp-tools/text-overlays">
    Titles, callouts, and labels.
  </Card>

  <Card title="Sound effects" icon="volume-high" href="/docs/mcp-tools/sound-effects">
    Curated or uploaded sound effects over a clip.
  </Card>
</CardGroup>

## Get started with Skills

Tella has two kinds of skills for agents.

**Official skill.** The `tella` skill in [tellahq/skills](https://github.com/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:

```bash theme={null}
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.

<Card title="Browse the Skills directory" icon="wand-magic-sparkles" href="https://www.tella.com/skills" horizontal>
  Install a skill with one command and start editing videos with your AI agent in minutes.
</Card>

## 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:

```bash theme={null}
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.


## Related topics

- [Tella MCP Server](/docs/help/integrations/mcp-server.md)
- [AI onboarding](/docs/ai-onboarding.md)
- [Clips](/docs/mcp-tools/clips.md)
- [Agent skills guide](/docs/help/integrations/agent-skills.md)
- [Auto layouts](/docs/help/editing/use-auto-layouts.md)