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

# AI 어시스턴트에서 Youka 사용하기 (MCP)

> Claude Code, Cursor, Codex 또는 어떤 MCP 클라이언트든 Youka에 연결해 채팅으로 가라오케 및 가사 비디오를 만드세요.

Youka에는 MCP 서버가 있습니다. [MCP](https://modelcontextprotocol.io) (Model Context Protocol)는 AI 어시스턴트가 외부 도구에 연결하는 표준 방식입니다. 한 번 연결하면 어시스턴트에게 “\~/Music/song.mp3로 가라오케 비디오 만들어줘” 같은 요청을 할 수 있고, 그러면 Youka 계정에서 프로젝트를 생성하고 완료될 때까지 기다린 뒤 편집기 링크나 다운로드 링크를 제공합니다.

이 서버는 Claude Code, Cursor, Codex처럼 사용자 지정 헤더를 포함한 원격(Streamable HTTP) 서버를 지원하는 모든 MCP 클라이언트에서 동작합니다.

> [!NOTE]
>
> ChatGPT와 Claude용 공식 Youka 앱은 곧 제공될 예정입니다. 그때까지는 이 페이지의
> 클라이언트를 Youka API 키와 함께 사용하세요.

## 준비물

* 크레딧이 있는 Youka 계정. MCP 서버는 웹 앱과 동일한 크레딧을 사용합니다. [크레딧 이해하기](https://docs.youka.io/ko/web/understanding-credits.md)를 참고하세요.
* Youka API 키. [online.youka.io/account](https://online.youka.io/account)의 **API keys**에서 생성하세요. [Authentication](https://docs.youka.io/ko/api/authentication.md)을 참고하세요.

서버 정보:

| 설정 | 값 |
| - | - |
| URL | `https://mcp.youka.io/mcp` |
| Transport | Streamable HTTP |
| Auth | `Authorization: Bearer YOUR_API_KEY` |

> [!WARNING]
>
> API 키는 Youka 계정과 해당 크레딧에 대한 전체 접근 권한을 제공합니다. 공유 파일이나
> 리포지토리에 포함되지 않도록 주의하세요. 키가 유출되면 계정 페이지에서 삭제하고 새로
> 생성하세요.

## 어시스턴트 연결하기

> [tab] Claude Code
>
> 터미널에서 아래를 실행하고, `YOUR_API_KEY`를 본인 키로 바꾸세요:
>
> ```bash theme={null}
> claude mcp add --transport http youka https://mcp.youka.io/mcp \
>   --header "Authorization: Bearer YOUR_API_KEY"
> ```
>
> 연결되었는지 확인합니다:
>
> ```bash theme={null}
> claude mcp list
> ```
>
> `youka: https://mcp.youka.io/mcp (HTTP) - ✔ Connected`가 표시되어야 합니다.
>
> 기본값으로 서버는 현재 폴더에만 추가됩니다. 모든 폴더에서 Youka를 사용하려면 `--scope user`를 추가하세요.

> [tab] Cursor
>
> `~/.cursor/mcp.json`(모든 프로젝트용) 또는 프로젝트 폴더의 `.cursor/mcp.json`을 열고 `youka` 서버를 추가하세요:
>
> ```json theme={null}
> {
>   "mcpServers": {
>     "youka": {
>       "url": "https://mcp.youka.io/mcp",
>       "headers": {
>         "Authorization": "Bearer ${env:YOUKA_API_KEY}"
>       }
>     }
>   }
> }
> ```
>
> Cursor를 시작하는 환경에서 `YOUKA_API_KEY`를 설정하거나, `${env:YOUKA_API_KEY}`를 본인 키로 바꾸세요. 그런 다음 Cursor 설정의 MCP 섹션을 열어 `youka`가 활성화되어 있는지 확인합니다.

> [tab] Codex
>
> 다음을 실행하세요:
>
> ```bash theme={null}
> codex mcp add youka --url https://mcp.youka.io/mcp \
>   --bearer-token-env-var YOUKA_API_KEY
> ```
>
> 또는 `~/.codex/config.toml`에 직접 아래를 추가하세요:
>
> ```toml theme={null}
> [mcp_servers.youka]
> url = "https://mcp.youka.io/mcp"
> bearer_token_env_var = "YOUKA_API_KEY"
> ```
>
> Codex는 `YOUKA_API_KEY` 환경 변수에서 키를 읽으므로, Codex를 시작하기 전에 설정하세요:
>
> ```bash theme={null}
> export YOUKA_API_KEY="YOUR_API_KEY"
> ```
>
> `codex mcp list`를 실행해 `youka`가 활성화되어 있는지 확인합니다.

> [tab] Other clients
>
> 사용자 지정 헤더가 있는 원격 서버를 지원하는 모든 MCP 클라이언트에서 동작합니다. 아래를 사용하세요:
>
> * **URL:** `https://mcp.youka.io/mcp`
> * **Transport:** Streamable HTTP(때로는 "HTTP"라고도 함)
> * **Header:** `Authorization: Bearer YOUR_API_KEY`
>
> 이 서버는 세션을 사용하지 않으므로 다른 설정은 필요 없습니다.

## 사용해 보기

자연어로 어시스턴트에게 요청하세요. 예:

```text theme={null}
내 Youka 크레딧이 몇 개 남아 있어?
```

```text theme={null}
~/Music/song.mp3로 가라오케 비디오 만들어줘. 가사는 자동으로 전사해줘.
```

```text theme={null}
./demo.wav로 내 "Neon" 프리셋을 사용해서 가사 비디오를 만든 다음, 1080p로 내보내고 다운로드 링크를 줘.
```

```text theme={null}
내 최신 Youka 프로젝트에서 2절은 "..."가 아니라 "..."여야 해. 가사를 수정하고 다시 싱크 맞춰줘.
```

일반적인 가라오케 요청 흐름은 다음과 같습니다:

**1. 업로드**

어시스턴트가 Youka에 업로드 링크를 요청하고 파일을 업로드합니다. 업로드는
무료입니다.

**2. 비용 확인**

프로젝트에 필요한 크레딧을 확인하고, 이를 현재 잔액과 비교합니다.

**3. 프로젝트 생성**

Youka가 보컬을 제거하고 가사를 싱크합니다. 몇 분 정도 걸립니다. 어시스턴트가
프로젝트가 준비될 때까지 상태를 확인합니다.

**4. 편집 또는 내보내기**

Youka 편집기에서 프로젝트를 열 수 있는 링크를 받습니다. 비디오 파일을 요청하면
어시스턴트가 내보내기를 수행하고 다운로드 링크를 제공합니다.

프로젝트 생성만으로는 비디오가 렌더링되지 않습니다. 언제 내보낼지는 사용자가 결정하므로, 채팅에서든 [Youka editor](https://docs.youka.io/ko/web/using-studio.md)에서든 먼저 가사나 스타일을 수정할 수 있습니다.

## 어시스턴트가 할 수 있는 일

| 도구 | 기능 | 크레딧 사용 |
| - | - | - |
| `get_account` | 계정, 크레딧 잔액, 업로드 제한을 표시합니다. | No |
| `list_presets` | 저장한 스타일 [presets](https://docs.youka.io/ko/web/presets.md)를 나열합니다. | No |
| `prepare_upload` | 컴퓨터에 있는 오디오 또는 비디오 파일 1개에 대한 업로드 링크를 생성합니다. | No |
| `quote_project` | 새 프로젝트의 비용을 표시합니다. | No |
| `create_karaoke_video` | 파일 1개로 편집 가능한 가라오케 프로젝트(보컬 제거, 가사 싱크)를 생성합니다. | Yes |
| `create_lyric_video` | 파일 1개로 편집 가능한 가사 비디오 프로젝트(원본 오디오, 가사 싱크)를 생성합니다. | Yes |
| `list_projects` | 프로젝트를 최신순으로 나열합니다. | No |
| `get_project` | 프로젝트 상태(processing, ready, failed), 가사, stems, exports, 편집기 링크를 표시합니다. | No |
| `sync_lyrics` | 수정된 가사를 다시 싱크하거나, 곡을 다시 전사합니다. | Yes |
| `get_task` | 가사 싱크 작업의 상태를 표시합니다. | No |
| `quote_export` | 내보내기 비용을 표시합니다. | No |
| `export_video` | 편집기에 저장된 현재 상태(편집 내용 포함) 그대로 프로젝트를 렌더링합니다. | Yes |
| `get_export` | 내보내기 상태를 표시하고, 준비되면 다운로드 링크를 제공합니다. | No |

## 크레딧 및 안전

* **웹 앱과 동일한 크레딧.** 프로젝트 생성, 가사 재싱크, 내보내기 비용은 [online.youka.io](https://online.youka.io)에서와 동일합니다.
* **비용을 먼저 확인.** 크레딧이 부족하면 Youka가 요청을 거부하고 그 사실을 알려줍니다. 과금은 발생하지 않습니다.
* **중복 과금 없음.** 타임아웃 후 어시스턴트가 요청을 재시도하더라도, Youka가 재시도를 인식하고 다시 과금하지 않고 원래 결과를 반환합니다.
* **크레딧은 Youka에서 구매.** 어시스턴트는 크레딧을 구매할 수 없습니다. 추가하려면 [Buy more credits](https://docs.youka.io/ko/web/buy-credits.md)를 참고하세요.
* **유료 도구는 요청할 때만 실행.** 사용자가 요청할 때에만 프로젝트 생성, 가사 싱크, 내보내기를 수행하도록 어시스턴트에 안내되어 있습니다.

## 문제 해결

> [accordion] 401 Unauthorized, or the server shows as failed
>
> API 키가 없거나 유효하지 않습니다. 헤더가 정확히
> `Authorization: Bearer yk_...` 형태인지 확인하세요. `Bearer` 뒤에는 공백이 1개만 있어야 하고,
> 키 안에는 불필요한 공백이나 따옴표가 없어야 합니다. 계정 페이지에서 키를 삭제했다면 새 키를
> 만들고 클라이언트 설정을 업데이트하세요. `YOUKA_API_KEY`를 읽는 Codex 및 Cursor 설정의 경우,
> 앱이 시작되는 환경에 해당 변수가 설정되어 있는지 확인하세요.

> [accordion] Not enough credits
>
> 어시스턴트에게 잔액을 물어보거나
> [online.youka.io](https://online.youka.io)에서 확인하세요. 그런 다음 [buy more
> credits](https://docs.youka.io/ko/web/buy-credits.md)로 크레딧을 추가하고 다시 요청하세요.

> [accordion] The project failed
>
> 어시스턴트에게 프로젝트를 보여달라고 요청하세요. 오류가 함께 표시됩니다.
> 파일이 지원되는 오디오 또는 비디오 형식인지, 그리고 계정에 표시된 업로드 제한을
> 충족하는지 확인하세요.

> [accordion] The lyrics are wrong
>
> 어시스턴트에게 올바른 가사를 알려주고 다시 싱크해 달라고 요청하거나,
> 편집기 링크를 열어 직접 [edit the lyrics](https://docs.youka.io/ko/web/edit-lyrics.md)하세요. 그런 다음
> 다시 내보내세요.

## 관련 문서

* [AI agents](https://docs.youka.io/ko/agents.md) — 에이전트에서 Youka CLI와 스킬 사용하기
* [Authentication](https://docs.youka.io/ko/api/authentication.md) — API 키 생성 및 사용
* [Understanding credits](https://docs.youka.io/ko/web/understanding-credits.md)


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