Docs

MCP Server

Use the YT AI Thumbnail API with AI agents via Model Context Protocol.

MCP Server Integration

The YT AI Thumbnail API includes an MCP (Model Context Protocol) server that enables AI agents like Claude to generate thumbnails and manage your resources programmatically.

What is MCP?

Model Context Protocol (MCP) is an open protocol that allows AI assistants to interact with external tools and services. With our MCP server, AI agents can:

Generate thumbnails based on conversations
Analyze YouTube videos
Manage your styles, faces, and brands
Create and organize collections

Setting Up the MCP Server

For Claude Desktop

Add to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "yt-ai-thumbnail": {
      "url": "https://yourdomain.com/api/mcp",
      "headers": {
        "Authorization": "Bearer api_your_key_here"
      }
    }
  }
}

For Other MCP Clients

Connect to the MCP endpoint:

URL: https://yourdomain.com/api/mcp
Authorization: Bearer api_your_key_here

Available Tools

Once connected, the AI agent has access to these tools:

`generate_thumbnail`

Generate a YouTube thumbnail from a prompt.

Parameters:

prompt (required) - Description of the thumbnail
youtube_url (optional) - YouTube video URL to analyze
style_id (optional) - Style to apply
face_ids (optional) - Faces to include
brand_id (optional) - Brand for colors

`analyze_video`

Analyze a YouTube video and get thumbnail concepts.

Parameters:

youtube_url (required) - YouTube video URL

`list_thumbnails`

Get a list of your generated thumbnails.

`list_faces`

Get a list of your uploaded faces.

`create_face`

Create a new face from an image URL.

Parameters:

name (required) - Name for the face
image_url (required) - URL of the face image

`list_styles`

Get a list of your saved styles.

`create_style`

Create a new style from an image or YouTube URL.

Parameters:

name (required) - Name for the style
image_url or youtube_url (one required) - Source for the style

`list_brands`

Get a list of your brands.

`generate_seo_titles`

Generate SEO-optimized video titles.

Parameters:

youtube_url (required) - YouTube video URL

`generate_seo_description`

Generate SEO-optimized video description.

Parameters:

youtube_url (required) - YouTube video URL

`get_credits`

Get your current credit balance.

Example Conversations

Generating a Thumbnail

User: Create a thumbnail for my video about productivity tips

Claude (using MCP): I'll generate a thumbnail for your productivity video.

[Uses generate_thumbnail tool]

Here's your thumbnail! It features a clean desk setup with a clock and checklist, using bright colors to grab attention.

Analyzing a Video

User: What thumbnail concepts would work for https://youtube.com/watch?v=...?

Claude (using MCP): Let me analyze that video.

[Uses analyze_video tool]

Based on the video content, here are 5 thumbnail concepts that would work well:

Reaction Shot - Surprised expression with...
Before/After Split - Showing the transformation... ...

Authentication

The MCP server uses the same API key authentication as the REST API. Include your API key in the Authorization header when configuring the MCP connection.

Rate Limits

MCP requests count toward your API rate limits. Each tool call is treated as one API request.

Credits

Tool calls that generate images (like generate_thumbnail) consume credits just like the REST API.

Error Handling