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

# MCP Server

> Let AI agents create videos using the Model Context Protocol

## Overview

The Hooked MCP Server (`@hooked-so/mcp`) lets AI agents — Claude, Cursor, ChatGPT, and any MCP-compatible client — create videos, browse avatars, check status, and discover trends directly from a conversation.

<Info>
  **What is MCP?** The [Model Context Protocol](https://modelcontextprotocol.io) is an open standard that lets AI assistants interact with external tools and APIs natively.
</Info>

## Quick Setup

<Steps>
  <Step title="Get your API key">
    Go to [hooked.so](https://hooked.so) → Settings → API Keys and generate a key.
  </Step>

  <Step title="Add the config">
    Paste the JSON config into your AI client (see below).
  </Step>

  <Step title="Start creating">
    Ask your AI to create a video. It handles everything.
  </Step>
</Steps>

## Claude Desktop

Add this to your `claude_desktop_config.json`:

```json theme={null}
{
  "mcpServers": {
    "hooked": {
      "command": "npx",
      "args": ["-y", "@hooked-so/mcp"],
      "env": {
        "HOOKED_API_KEY": "your_api_key_here"
      }
    }
  }
}
```

<Tip>
  On macOS, the config file is at `~/Library/Application Support/Claude/claude_desktop_config.json`
</Tip>

## Cursor

Add this to `.cursor/mcp.json` in your project root:

```json theme={null}
{
  "mcpServers": {
    "hooked": {
      "command": "npx",
      "args": ["-y", "@hooked-so/mcp"],
      "env": {
        "HOOKED_API_KEY": "your_api_key_here"
      }
    }
  }
}
```

## Available Tools

The MCP server exposes 10 tools:

### Video Creation

| Tool                      | Description                                               |
| ------------------------- | --------------------------------------------------------- |
| `create_script_to_video`  | Create a video from a script with an AI avatar            |
| `create_prompt_to_video`  | AI generates script, visuals, and narration from a prompt |
| `create_tiktok_slideshow` | Create TikTok-style slideshow from images and text        |
| `create_ugc_ad`           | Create UGC-style product ad with AI presenter             |

### Resources

| Tool           | Description                       |
| -------------- | --------------------------------- |
| `list_avatars` | Browse 50+ realistic AI avatars   |
| `list_voices`  | Browse AI voices in 30+ languages |
| `list_music`   | Browse background music tracks    |

### Video Management

| Tool          | Description                             |
| ------------- | --------------------------------------- |
| `get_video`   | Check video status and get download URL |
| `list_videos` | List all your generated videos          |

### Trends

| Tool                  | Description                               |
| --------------------- | ----------------------------------------- |
| `get_trending_videos` | Discover trending content for inspiration |

## Example Conversations

Once connected, you can interact naturally:

**Create a video:**

> "Create a 30-second product video for my fitness app. Use a young female avatar with an energetic tone."

**Browse resources:**

> "What AI avatars do you have? Show me the female ones."

**Check status:**

> "What's the status of my latest video?"

**Get inspiration:**

> "What's trending on TikTok in the fitness niche? Create a video based on the top trend."

**Batch creation:**

> "Create 3 variations of a product ad with different hooks and avatars."

## Tool Details

### create\_script\_to\_video

```json theme={null}
{
  "script": "Your video script here...",
  "avatarId": "avatar_sophia_01",
  "voiceId": "voice_en_female_01",
  "musicId": "music_upbeat_01",
  "captionStyle": "karaoke",
  "webhook": "https://your-app.com/webhook"
}
```

| Parameter      | Type   | Required | Description                                    |
| -------------- | ------ | -------- | ---------------------------------------------- |
| `script`       | string | Yes      | The script the avatar will speak               |
| `avatarId`     | string | Yes      | Avatar ID from `list_avatars`                  |
| `voiceId`      | string | No       | Voice ID from `list_voices`                    |
| `musicId`      | string | No       | Music ID from `list_music`                     |
| `captionStyle` | string | No       | Caption style (e.g. `karaoke`, `word-by-word`) |
| `webhook`      | string | No       | Webhook URL for completion notification        |

### create\_prompt\_to\_video

```json theme={null}
{
  "prompt": "A 30-second video about productivity tips for remote workers",
  "avatarId": "avatar_sophia_01",
  "webhook": "https://your-app.com/webhook"
}
```

| Parameter  | Type   | Required | Description                         |
| ---------- | ------ | -------- | ----------------------------------- |
| `prompt`   | string | Yes      | Describe the video you want         |
| `avatarId` | string | No       | Avatar ID (AI picks one if omitted) |
| `voiceId`  | string | No       | Voice ID                            |
| `webhook`  | string | No       | Webhook URL                         |

## Environment Variables

| Variable         | Required | Description                                            |
| ---------------- | -------- | ------------------------------------------------------ |
| `HOOKED_API_KEY` | Yes      | Your Hooked API key                                    |
| `HOOKED_API_URL` | No       | Custom API base URL (default: `https://api.hooked.so`) |

## Troubleshooting

<AccordionGroup>
  <Accordion title="MCP server not connecting">
    Ensure `npx` is available in your PATH. Try running `npx @hooked-so/mcp` manually in a terminal to check for errors.
  </Accordion>

  <Accordion title="Authentication failed">
    Verify your `HOOKED_API_KEY` is correct and active. Generate a new key at hooked.so → Settings → API Keys.
  </Accordion>

  <Accordion title="Tool not appearing in AI client">
    Restart your AI client after adding the config. Some clients require a full restart to detect new MCP servers.
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Skill File" icon="file-code" href="/guides/skill-file">
    Download the Hooked skill for Cursor and Claude
  </Card>

  <Card title="Webhooks" icon="webhook" href="/guides/webhooks">
    Receive notifications when videos are ready
  </Card>
</CardGroup>