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

# Usar Youka desde asistentes de IA (MCP)

> Conecta Claude Code, Cursor, Codex o cualquier cliente MCP a Youka y crea videos de karaoke y de letras chateando.

Youka tiene un servidor MCP. [MCP](https://modelcontextprotocol.io) (Model Context Protocol) es la forma estándar en la que los asistentes de IA se conectan a herramientas externas. Una vez que lo conectas, puedes pedirle a tu asistente cosas como "make a karaoke video of \~/Music/song.mp3" y crea el proyecto en tu cuenta de Youka, espera a que termine y te da el enlace del editor o un enlace de descarga.

El servidor funciona con cualquier cliente MCP que admita servidores remotos (Streamable HTTP) con un encabezado personalizado, como Claude Code, Cursor y Codex.

> [!NOTE]
>
> Las apps oficiales de Youka para ChatGPT y Claude llegarán pronto. Hasta entonces, usa un
> cliente de esta página con una clave de API de Youka.

## Lo que necesitas

* Una cuenta de Youka con créditos. El servidor MCP usa los mismos créditos que la app web. Consulta [Understanding credits](https://docs.youka.io/es/web/understanding-credits.md).
* Una clave de API de Youka. Crea una en [online.youka.io/account](https://online.youka.io/account) en **API keys**. Consulta [Authentication](https://docs.youka.io/es/api/authentication.md).

Detalles del servidor:

| Ajuste | Valor |
| - | - |
| URL | `https://mcp.youka.io/mcp` |
| Transporte | Streamable HTTP |
| Auth | `Authorization: Bearer YOUR_API_KEY` |

> [!WARNING]
>
> Tu clave de API da acceso total a tu cuenta de Youka y a sus créditos. No la incluyas
> en archivos y repositorios compartidos. Si una clave se filtra, elimínala en la página de tu
> cuenta y crea una nueva.

## Conecta tu asistente

> [tab] Claude Code
>
> Ejecuta esto en tu terminal, reemplazando `YOUR_API_KEY` por tu clave:
>
> ```bash theme={null}
> claude mcp add --transport http youka https://mcp.youka.io/mcp \
>   --header "Authorization: Bearer YOUR_API_KEY"
> ```
>
> Comprueba que se conectó:
>
> ```bash theme={null}
> claude mcp list
> ```
>
> Deberías ver `youka: https://mcp.youka.io/mcp (HTTP) - ✔ Connected`.
>
> De forma predeterminada, el servidor se añade solo para la carpeta actual. Añade `--scope user` para usar Youka en todas las carpetas.

> [tab] Cursor
>
> Abre `~/.cursor/mcp.json` (para todos los proyectos) o `.cursor/mcp.json` en la carpeta de tu proyecto, y añade el servidor `youka`:
>
> ```json theme={null}
> {
>   "mcpServers": {
>     "youka": {
>       "url": "https://mcp.youka.io/mcp",
>       "headers": {
>         "Authorization": "Bearer ${env:YOUKA_API_KEY}"
>       }
>     }
>   }
> }
> ```
>
> Establece `YOUKA_API_KEY` en el entorno desde el que se inicia Cursor, o reemplaza `${env:YOUKA_API_KEY}` por tu clave. Luego abre la sección MCP de la configuración de Cursor y comprueba que `youka` esté habilitado.

> [tab] Codex
>
> Ejecuta:
>
> ```bash theme={null}
> codex mcp add youka --url https://mcp.youka.io/mcp \
>   --bearer-token-env-var YOUKA_API_KEY
> ```
>
> O añade esto tú mismo a `~/.codex/config.toml`:
>
> ```toml theme={null}
> [mcp_servers.youka]
> url = "https://mcp.youka.io/mcp"
> bearer_token_env_var = "YOUKA_API_KEY"
> ```
>
> Codex lee la clave desde la variable de entorno `YOUKA_API_KEY`, así que establécela antes de iniciar Codex:
>
> ```bash theme={null}
> export YOUKA_API_KEY="YOUR_API_KEY"
> ```
>
> Ejecuta `codex mcp list` para comprobar que `youka` esté habilitado.

> [tab] Other clients
>
> Cualquier cliente MCP que admita servidores remotos con encabezados personalizados funciona. Usa:
>
> * **URL:** `https://mcp.youka.io/mcp`
> * **Transporte:** Streamable HTTP (a veces llamado "HTTP")
> * **Encabezado:** `Authorization: Bearer YOUR_API_KEY`
>
> El servidor no usa sesiones, así que no se necesita ninguna otra configuración.

## Pruébalo

Pídele a tu asistente en lenguaje natural. Por ejemplo:

```text theme={null}
How many Youka credits do I have?
```

```text theme={null}
Make a karaoke video of ~/Music/song.mp3. Transcribe the lyrics automatically.
```

```text theme={null}
Make a lyric video of ./demo.wav using my "Neon" preset, then export it in 1080p and give me the download link.
```

```text theme={null}
In my latest Youka project, the second verse should be "..." instead of "...". Fix the lyrics and sync them again.
```

Una solicitud típica de karaoke va así:

**1. Upload**

El asistente le pide a Youka un enlace de carga y sube tu archivo. La subida
es gratuita.

**2. Check the cost**

Comprueba cuántos créditos usará el proyecto y lo compara con tu
saldo.

**3. Create the project**

Youka elimina las voces y sincroniza la letra. Esto tarda unos minutos. El
asistente comprueba el estado hasta que el proyecto esté listo.

**4. Edit or export**

Obtienes un enlace para abrir el proyecto en el editor de Youka. Si pides el
archivo de video, el asistente lo exporta y te da un enlace de descarga.

Crear un proyecto nunca renderiza un video por sí solo. Tú decides cuándo exportar, así que puedes corregir la letra o el estilo primero, ya sea en el chat o en el [Youka editor](https://docs.youka.io/es/web/using-studio.md).

## Lo que el asistente puede hacer

| Herramienta | Qué hace | Usa créditos |
| - | - | - |
| `get_account` | Muestra tu cuenta, saldo de créditos y límites de subida. | No |
| `list_presets` | Enumera tus [presets](https://docs.youka.io/es/web/presets.md) de estilo guardados. | No |
| `prepare_upload` | Crea un enlace de carga para un archivo de audio o video en tu computadora. | No |
| `quote_project` | Muestra cuánto costará un proyecto nuevo. | No |
| `create_karaoke_video` | Crea un proyecto de karaoke editable (voces eliminadas, letra sincronizada) a partir de un archivo. | Sí |
| `create_lyric_video` | Crea un proyecto editable de video con letras (audio original, letra sincronizada) a partir de un archivo. | Sí |
| `list_projects` | Enumera tus proyectos, del más reciente al más antiguo. | No |
| `get_project` | Muestra el estado de un proyecto (processing, ready o failed), letra, stems, exportaciones y enlace del editor. | No |
| `sync_lyrics` | Sincroniza de nuevo la letra corregida o vuelve a transcribir la canción. | Sí |
| `get_task` | Muestra el estado de una sincronización de letra. | No |
| `quote_export` | Muestra cuánto costará una exportación. | No |
| `export_video` | Renderiza el proyecto tal como está guardado, incluyendo tus ediciones en el editor. | Sí |
| `get_export` | Muestra el estado de una exportación y, cuando está lista, un enlace de descarga. | No |

## Créditos y seguridad

* **Los mismos créditos que la app web.** Crear un proyecto, volver a sincronizar la letra y exportar cuestan lo mismo que en [online.youka.io](https://online.youka.io).
* **El costo se comprueba primero.** Si no tienes suficientes créditos, Youka rechaza la solicitud y lo indica. No se cobra nada.
* **Sin cargos duplicados.** Si el asistente reintenta una solicitud tras un timeout, Youka reconoce el reintento y devuelve el resultado original en lugar de cobrar de nuevo.
* **Los créditos se compran en Youka.** El asistente no puede comprar créditos. Para añadir más, consulta [Buy more credits](https://docs.youka.io/es/web/buy-credits.md).
* **Las herramientas de pago solo se ejecutan cuando tú lo pides.** Se le indica al asistente que cree proyectos, sincronice letras o exporte solo cuando se lo pidas.

## Solución de problemas

> [accordion] 401 Unauthorized, or the server shows as failed
>
> Falta la clave de API o no es válida. Comprueba que el encabezado sea exactamente
> `Authorization: Bearer yk_...`, con un espacio después de `Bearer` y sin
> espacios extra ni comillas dentro de la clave. Si eliminaste la clave en la página de tu cuenta, crea una nueva
> y actualiza tu cliente. En configuraciones de Codex y Cursor que leen
> `YOUKA_API_KEY`, asegúrate de que la variable esté definida en el entorno desde el que se inicia
> la app.

> [accordion] Not enough credits
>
> Pídele al asistente tu saldo o consúltalo en
> [online.youka.io](https://online.youka.io). Luego [buy more
> credits](https://docs.youka.io/es/web/buy-credits.md) y vuelve a intentarlo.

> [accordion] The project failed
>
> Pídele al asistente que muestre el proyecto. Incluye el error. Asegúrate de que el
> archivo sea un archivo de audio o video compatible y que esté dentro de los límites de subida que muestra
> tu cuenta.

> [accordion] The lyrics are wrong
>
> Dile al asistente la letra correcta y pídele que la sincronice de nuevo, o abre
> el enlace del editor y [edit the lyrics](https://docs.youka.io/es/web/edit-lyrics.md) tú mismo. Luego
> exporta de nuevo.

## Documentación relacionada

* [AI agents](https://docs.youka.io/es/agents.md) — usa la Youka CLI y skill desde un agente
* [Authentication](https://docs.youka.io/es/api/authentication.md) — crea y usa claves de API
* [Understanding credits](https://docs.youka.io/es/web/understanding-credits.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.