Advanced

Model context protocol

The TwelveLabs Model Context Protocol (MCP) server connects your AI assistant to video understanding capabilities. You can search videos, generate summaries, and extract insights using simple natural language prompts.

Note

If you use Claude Code, the Claude Code plugin is an alternative that adds TwelveLabs slash commands directly to your Claude Code workflow.

The following diagram illustrates the architecture of the TwelveLabs MCP server and how different parts interact:

Key features:

  • Video search: Search through indexed videos using natural language queries to find specific moments and scenes.
  • Video analysis: Generate titles, topics, hashtags, summaries, chapters, and highlights from your video content.
  • Video embeddings: Create and retrieve video embeddings for advanced AI applications and custom workflows.
  • Onboarding assistance: Get guided help to onboard faster on the TwelveLabs platform.
  • Chainable workflows: Combine multiple video analysis tools in sequence to create complex Retrieval-Augmented Generation (RAG) workflows.
  • Universal compatibility: Works with any MCP-compatible client, including but not limited to Cursor, VS Code, Claude Code, Gemini CLI, and Goose.

Use cases:

  • Meeting analysis: Summarize meeting recordings and find specific discussion points using natural language queries.
  • Sports highlights: Search through game footage to find specific plays like “fourth-quarter three-pointers.”
  • Media production: Locate scenes where products appear in videos and generate promotional content summaries.
  • Training content: Search webinars and presentations for specific topics like “final chart presentation” or key learning moments.

Prerequisites

  • To use the platform, you need an API key:

    1

    If you don’t have an account, sign up for a free account.

    2

    Go to the API Keys page.

    3

    If you need to create a new key, select the Create API Key button. Enter a name and set the expiration period. The default is 12 months.

    4

    Select the Copy icon next to your key to copy it to your clipboard.

  • An MCP-compatible client such as Cursor, VS Code, Claude Code, Gemini CLI, or Goose. For the full list, see the TwelveLabs MCP Server page.

Set up the TwelveLabs MCP server

1

Go to the TwelveLabs MCP Server page.

2

Select the Connect to my AI assistant button.

3

Select your MCP client from the list and follow the client-specific instructions.

Verify the installation

Test that your client recognizes the TwelveLabs MCP server:

1

Ask your assistant: “List the available tools from TwelveLabs.”

2

Confirm that your assistant displays a list that matches the tools described in the Tools section.

If the TwelveLabs tools don’t appear when you ask to list them, try these steps:

1

Check your API key: Verify that you entered your TwelveLabs API key correctly in the configuration.

2

Review the configuration: Open your MCP client settings and confirm the server configuration matches the installation guide exactly.

3

Check client logs: Look for error messages in your client’s logs or console output that might indicate connection issues.

4

Join our Discord server: If you still can’t get the server working, reach out to us in our Discord community for help with your setup.

Use the MCP server

You can now ask your AI assistant to perform video understanding tasks using natural language. Below are several examples of what you can do:

Manage indexes

  • “Create a new index for our training materials”
  • “List all available indexes”
  • “Delete the <YOUR_INDEX_ID> index”

Upload videos

  • “Index the meeting recording from this URL: <YOUR_URL>”

Search for specific moments

  • Identify where the presenter displays a diagram on the screen in the video titled “2025 Cost of a Data Breach: AI Risks, Shadow AI, & Solutions.”
  • “Search for all scenes where this product appears”
  • “Locate fourth-quarter three-pointers in the game footage”

Generate video summaries

  • “Summarize this video in 3 sentences”
  • “Generate highlights from this presentation”
  • “Create a brief overview of this training video”

Ask questions about videos

  • “What topics does the speaker cover in this video?”
  • “When does the demo section begin?”
  • “What are the key takeaways from this interview?”

Tools

The server provides the following MCP tools:

Tool NameDescriptionAPI
create-indexCreate an index.POST /indexes
list-indexesList indexes.GET /indexes
delete-indexDelete an indexDELETE /v1.3/indexes/:index-id
list-videosList all videos in the specified index.GET /indexes/:index-id/videos
start-video-indexing-taskUpload and index a video.POST /tasks
get-video-indexing-tasksRetrieve a video indexing task.GET /tasks/:task_id
searchSearch through the videos in the specified index using natural language queries.POST /search
analyze-videoAnalyze videos to generate text based on their content.POST /analyze
start-video-embeddings-taskCreate video embeddings for advanced processing and similarity searchPOST /embed/tasks
get-video-embeddings-tasksRetrieve the status of a video embedding taskGET /embed/tasks/:task_id/status
retrieve-video-embeddingsRetrieve the actual embedding data from completed tasks or indexed videos- GET /embed/tasks/:task_id
- GET /indexes/:index-id/videos/:video-id

Next steps

After you complete the setup, you can build custom workflows that combine video analysis with other tools and integrate the capabilities of the TwelveLabs Video Understanding Platform into your existing AI applications.