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

# MCP Server

> Connect Hoox to Claude, Cursor, and any MCP-compatible client — generate videos, manage avatars and voices using natural language

The official [Model Context Protocol](https://modelcontextprotocol.io) server for Hoox. Any MCP-compatible client can generate videos and assets, manage avatars and voices, and export MP4 files using natural language.

The server is hosted by Hoox — nothing to install and no API key to manage:

```text theme={null}
https://app.hoox.video/api/mcp
```

When your client connects for the first time, a browser window opens on app.hoox.video: sign in, choose the workspace to connect (if you belong to several), and click **Authorize**. Every tool then operates on that workspace and consumes its credits. To switch workspace, disconnect and reconnect.

<Info>
  A **Pro** plan or higher is required on the connected workspace.
</Info>

## Setup

### Claude (web, desktop and mobile)

1. Go to **Settings → Connectors → Add custom connector**
2. Paste `https://app.hoox.video/api/mcp` and confirm
3. Complete the sign-in flow when prompted

<Info>
  On Claude **Team** and **Enterprise** plans, an admin can add the connector once
  from the admin settings and make it available to the whole organization. Each
  member still signs in with their own Hoox account the first time they use it.
</Info>

### Claude Code

```bash theme={null}
claude mcp add --transport http hoox https://app.hoox.video/api/mcp
```

Then run `/mcp` inside Claude Code to authenticate.

### Cursor and other MCP clients

Add the server URL to your client's MCP configuration:

```json theme={null}
{
  "mcpServers": {
    "hoox": {
      "url": "https://app.hoox.video/api/mcp"
    }
  }
}
```

## Example prompts

<Info>
  Hoox credits are required to use the MCP tools.
</Info>

<AccordionGroup>
  <Accordion title="Generate a full video">
    ```text theme={null}
    Use Hoox to generate a 60-second vertical product demo video for our new DTC skincare serum.
    Export the final video to MP4 and return the download URL.
    ```
  </Accordion>

  <Accordion title="List avatars and voices">
    ```text theme={null}
    List the male avatars available with a professional style.
    Also list female English voices with a conversational tag.
    ```
  </Accordion>

  <Accordion title="Create a custom avatar">
    ```text theme={null}
    Create an avatar from this description: man in a conference room in a suit.
    ```
  </Accordion>

  <Accordion title="Generate assets">
    ```text theme={null}
    Check the pricing, then generate 2 images of a skincare serum bottle on a
    marble bathroom shelf, morning light, and put them in a "Serum campaign" folder.
    ```
  </Accordion>

  <Accordion title="Duplicate a video">
    ```text theme={null}
    Duplicate the video vid_xxx by changing the voice to a male English voice,
    then export the result as MP4.
    ```
  </Accordion>

  <Accordion title="Full script-to-MP4 workflow">
    ```text theme={null}
    Generate a 45-second script about our new DTC skincare serum,
    then start the video generation and export the result as MP4.
    ```
  </Accordion>
</AccordionGroup>

## Available tools

#### Workspace

| Tool             | Description                                                   |
| ---------------- | ------------------------------------------------------------- |
| `get_space_info` | Get the connected workspace: name, plan and remaining credits |

#### Voices

| Tool          | Description                                                    |
| ------------- | -------------------------------------------------------------- |
| `list_voices` | List available voices with optional filters (language, gender) |
| `get_voice`   | Get full details for a voice by ID                             |

#### Avatars

| Tool                | Description                                                |
| ------------------- | ---------------------------------------------------------- |
| `list_avatars`      | List available avatar looks with optional metadata filters |
| `get_avatar`        | Get full details for an avatar and its looks               |
| `create_avatar`     | Create a new avatar from a prompt or reference images      |
| `edit_avatar`       | Create a new look for an existing avatar                   |
| `get_avatar_status` | Check the generation status of an avatar look              |

#### Folders

| Tool            | Description                                  |
| --------------- | -------------------------------------------- |
| `list_folders`  | List the workspace's asset and video folders |
| `create_folder` | Create a folder to organize assets or videos |

#### Script

| Tool              | Description                                     |
| ----------------- | ----------------------------------------------- |
| `generate_script` | Generate a video narration script from a prompt |

#### Video generation

| Tool                    | Description                                       |
| ----------------------- | ------------------------------------------------- |
| `start_generation`      | Start an AI video generation job                  |
| `get_generation_status` | Check the status and progress of a generation job |

#### Export

| Tool                | Description                              |
| ------------------- | ---------------------------------------- |
| `start_export`      | Start exporting a generated video to MP4 |
| `get_export_status` | Check the status of an export job        |

#### Video management

| Tool              | Description                                                          |
| ----------------- | -------------------------------------------------------------------- |
| `duplicate_video` | Duplicate a completed video, optionally changing the voice or avatar |

#### Assets

| Tool                | Description                                                |
| ------------------- | ---------------------------------------------------------- |
| `list_asset_models` | List available image/video generation models               |
| `get_asset_model`   | Get a model's capabilities and input schema                |
| `get_asset_pricing` | Compute the credit cost of a generation before starting it |
| `start_asset`       | Start an image or video asset generation                   |
| `get_asset_status`  | Check the status of an asset generation                    |

## Typical workflow

```text theme={null}
1. get_space_info                     →  check remaining credits
2. list_voices / list_avatars        →  pick a voice & avatar
3. generate_script (optional)        →  get narration text
4. start_generation                  →  get job_id
5. get_generation_status (polling)   →  get video_id
6. start_export                      →  get export job_id
7. get_export_status (polling)       →  get MP4 download URL
```

## Troubleshooting

<AccordionGroup>
  <Accordion title="&#x22;Pro plan required&#x22; during sign-in">
    The MCP server can only connect workspaces on a **Pro** plan or higher. If none of your workspaces is eligible, upgrade at [app.hoox.video](https://app.hoox.video).
  </Accordion>

  <Accordion title="Connected to the wrong workspace">
    The workspace is chosen once, on the authorization screen. Disconnect the Hoox connector in your client, reconnect, and pick another workspace.
  </Accordion>

  <Accordion title="Error insufficient_credits (402)">
    Your workspace has run out of credits. Top up from the Hoox dashboard under **Settings → Billing**.
  </Accordion>

  <Accordion title="Tool not showing up in the client">
    Check the connector status in your client's settings and re-run the sign-in flow if needed. After updating the configuration, restart the client.
  </Accordion>

  <Accordion title="Generation stuck in &#x22;processing&#x22;">
    Video generation can take 1–5 minutes depending on duration and options. Use `get_generation_status` to monitor progress. If the job is stuck for more than 10 minutes, check the `error` field in the status response.
  </Accordion>
</AccordionGroup>