> ## 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.

# Use Youka from AI assistants (MCP)

> Connect Claude Code, Cursor, Codex, or any MCP client to Youka and create karaoke and lyric videos by chatting.

Youka has an MCP server. [MCP](https://modelcontextprotocol.io) (Model Context Protocol) is the standard way AI assistants connect to outside tools. Once you connect it, you can ask your assistant things like "make a karaoke video of \~/Music/song.mp3" and it creates the project in your Youka account, waits for it to finish, and gives you the editor link or a download link.

The server works with any MCP client that supports remote (Streamable HTTP) servers with a custom header, such as Claude Code, Cursor, and Codex.

> [!NOTE]
>
> Official Youka apps for ChatGPT and Claude are coming soon. Until then, use a
> client from this page with a Youka API key.

## What you need

* A Youka account with credits. The MCP server uses the same credits as the web app. See [Understanding credits](https://docs.youka.io/en/web/understanding-credits.md).
* A Youka API key. Create one at [online.youka.io/account](https://online.youka.io/account) under **API keys**. See [Authentication](https://docs.youka.io/en/api/authentication.md).

Server details:

| Setting | Value |
| - | - |
| URL | `https://mcp.youka.io/mcp` |
| Transport | Streamable HTTP |
| Auth | `Authorization: Bearer YOUR_API_KEY` |

> [!WARNING]
>
> Your API key gives full access to your Youka account and its credits. Keep it
> out of shared files and repositories. If a key leaks, delete it on your
> account page and create a new one.

## Connect your assistant

> [tab] Claude Code
>
> Run this in your terminal, replacing `YOUR_API_KEY` with your key:
>
> ```bash theme={null}
> claude mcp add --transport http youka https://mcp.youka.io/mcp \
>   --header "Authorization: Bearer YOUR_API_KEY"
> ```
>
> Check that it connected:
>
> ```bash theme={null}
> claude mcp list
> ```
>
> You should see `youka: https://mcp.youka.io/mcp (HTTP) - ✔ Connected`.
>
> By default the server is added for the current folder only. Add `--scope user` to use Youka in every folder.

> [tab] Cursor
>
> Open `~/.cursor/mcp.json` (for every project) or `.cursor/mcp.json` in your project folder, and add the `youka` server:
>
> ```json theme={null}
> {
>   "mcpServers": {
>     "youka": {
>       "url": "https://mcp.youka.io/mcp",
>       "headers": {
>         "Authorization": "Bearer ${env:YOUKA_API_KEY}"
>       }
>     }
>   }
> }
> ```
>
> Set `YOUKA_API_KEY` in the environment Cursor starts from, or replace `${env:YOUKA_API_KEY}` with your key. Then open the MCP section of Cursor's settings and check that `youka` is enabled.

> [tab] Codex
>
> Run:
>
> ```bash theme={null}
> codex mcp add youka --url https://mcp.youka.io/mcp \
>   --bearer-token-env-var YOUKA_API_KEY
> ```
>
> Or add this to `~/.codex/config.toml` yourself:
>
> ```toml theme={null}
> [mcp_servers.youka]
> url = "https://mcp.youka.io/mcp"
> bearer_token_env_var = "YOUKA_API_KEY"
> ```
>
> Codex reads the key from the `YOUKA_API_KEY` environment variable, so set it before you start Codex:
>
> ```bash theme={null}
> export YOUKA_API_KEY="YOUR_API_KEY"
> ```
>
> Run `codex mcp list` to check that `youka` is enabled.

> [tab] Other clients
>
> Any MCP client that supports remote servers with custom headers works. Use:
>
> * **URL:** `https://mcp.youka.io/mcp`
> * **Transport:** Streamable HTTP (sometimes called "HTTP")
> * **Header:** `Authorization: Bearer YOUR_API_KEY`
>
> The server does not use sessions, so no other settings are needed.

## Try it

Ask your assistant in plain language. For example:

```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.
```

A typical karaoke request goes like this:

**1. Upload**

The assistant asks Youka for an upload link and uploads your file. Uploading
is free.

**2. Check the cost**

It checks how many credits the project will use and compares that with your
balance.

**3. Create the project**

Youka removes the vocals and syncs the lyrics. This takes a few minutes. The
assistant checks the status until the project is ready.

**4. Edit or export**

You get a link to open the project in the Youka editor. If you ask for the
video file, the assistant exports it and gives you a download link.

Creating a project never renders a video by itself. You decide when to export, so you can fix the lyrics or style first, either in chat or in the [Youka editor](https://docs.youka.io/en/web/using-studio.md).

## What the assistant can do

| Tool | What it does | Uses credits |
| - | - | - |
| `get_account` | Shows your account, credit balance, and upload limits. | No |
| `list_presets` | Lists your saved style [presets](https://docs.youka.io/en/web/presets.md). | No |
| `prepare_upload` | Creates an upload link for one audio or video file on your computer. | No |
| `quote_project` | Shows what a new project will cost. | No |
| `create_karaoke_video` | Creates an editable karaoke project (vocals removed, synced lyrics) from one file. | Yes |
| `create_lyric_video` | Creates an editable lyric-video project (original audio, synced lyrics) from one file. | Yes |
| `list_projects` | Lists your projects, newest first. | No |
| `get_project` | Shows a project's status (processing, ready, or failed), lyrics, stems, exports, and editor link. | No |
| `sync_lyrics` | Syncs corrected lyrics again, or transcribes the song again. | Yes |
| `get_task` | Shows the status of a lyrics sync. | No |
| `quote_export` | Shows what an export will cost. | No |
| `export_video` | Renders the project as currently saved, including your edits in the editor. | Yes |
| `get_export` | Shows an export's status and, when it's ready, a download link. | No |

## Credits and safety

* **Same credits as the web app.** Creating a project, syncing lyrics again, and exporting cost the same as they do on [online.youka.io](https://online.youka.io).
* **Cost is checked first.** If you don't have enough credits, Youka refuses the request and says so. Nothing is charged.
* **No double charges.** If the assistant retries a request after a timeout, Youka recognizes the retry and returns the original result instead of charging again.
* **Credits are bought on Youka.** The assistant can't buy credits. To add more, see [Buy more credits](https://docs.youka.io/en/web/buy-credits.md).
* **Paid tools run only when you ask.** The assistant is told to create projects, sync lyrics, or export only when you ask for it.

## Troubleshooting

> [accordion] 401 Unauthorized, or the server shows as failed
>
> The API key is missing or invalid. Check that the header is exactly
> `Authorization: Bearer yk_...`, with one space after `Bearer` and no extra
> spaces or quotes inside the key. If you deleted the key on your account page, create a new
> one and update your client. For Codex and Cursor setups that read
> `YOUKA_API_KEY`, make sure the variable is set in the environment the app
> starts from.

> [accordion] Not enough credits
>
> Ask the assistant for your balance, or check it on
> [online.youka.io](https://online.youka.io). Then [buy more
> credits](https://docs.youka.io/en/web/buy-credits.md) and ask again.

> [accordion] The project failed
>
> Ask the assistant to show the project. It includes the error. Make sure the
> file is a supported audio or video file within the upload limits shown by
> your account.

> [accordion] The lyrics are wrong
>
> Tell the assistant the correct lyrics and ask it to sync them again, or open
> the editor link and [edit the lyrics](https://docs.youka.io/en/web/edit-lyrics.md) yourself. Then
> export again.

## Related docs

* [AI agents](https://docs.youka.io/en/agents.md) — use the Youka CLI and skill from an agent
* [Authentication](https://docs.youka.io/en/api/authentication.md) — create and use API keys
* [Understanding credits](https://docs.youka.io/en/web/understanding-credits.md)


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