MCP 연동

Model Context Protocol로 Claude, ChatGPT, Cursor, OpenAI Agent Builder를 SubDownload에 연결.

개요

Model Context Protocol(MCP)은 AI 어시스턴트가 외부 도구를 직접 호출할 수 있게 해 주는 표준화된 프레임워크입니다. SubDownload의 MCP 서버는 12개의 도구(비동기 AI 전사와 사용자별 Library 포함)를 제공하며, OAuth 2.1 + Dynamic Client Registration(DCR)과 정적 API 키를 모두 지원합니다.

서버 구성

항목	값
서버 URL	https://api.subdownload.com/mcp
인증 메타데이터	/.well-known/oauth-authorization-server
동적 등록	POST /oauth/register
승인	GET /oauth/authorize
Token	POST /oauth/token
Scope	mcp:access
토큰 접두사	oat_(OAuth) 또는 sk_live_(API 키)

클라이언트 설정

클라이언트별 단계별 가이드:

• → Claude(Desktop / Code) — OAuth + DCR, 미리 생성한 자격증명 불필요
• → ChatGPT — 정적 OAuth 클라이언트(Client ID / Secret)
• → OpenAI Agent Builder — API 키 인증

MCP 도구

도구	비용	용도
fetch_transcript	1 크레딧	URL/ID로 스크립트 가져오기(파라미터: video_url, lang).
search_youtube	1 크레딧	영상 또는 채널 검색(파라미터: query, type, limit).
resolve_channel	무료	@handle / URL / UC… ID를 채널 정보로 해석(파라미터: input).
search_channel_videos	1 크레딧	특정 채널에서 영상 검색(파라미터: channel, query, limit).
get_channel_latest_videos	무료	RSS로 최근 ~15개 영상(파라미터: channel).
list_channel_videos	1 크레딧/페이지	업로드 페이지네이션(파라미터: channel 또는 continuation).
list_playlist_videos	1 크레딧/페이지	플레이리스트 페이지네이션(파라미터: playlist 또는 continuation).
transcribe_video	done 시 5 크레딧	자막 없는 영상에 대한 비동기 AI Whisper 전사 시작. task_id와 next_poll_after_seconds 반환(파라미터: video_url, lang).
get_asr_task	무료	ASR 작업 폴링; status=done일 때 segments 반환(파라미터: task_id).
list_library	무료	사용자의 저장된 전사본과 요약 나열(파라미터: favorite, q, limit, offset).
get_library_item	무료	저장 항목을 transcript와 summary 인라인으로 조회(파라미터: id, locale).
save_to_library	토큰 쿼터 1	kind=asr는 저장된 전사본 플래그, kind=summary는 AI 생성 요약 업로드(파라미터: video_id, kind, text, locale, model 등).

오류 처리

실패한 호출은 크레딧을 소비하지 않습니다. 오류는 AI 어시스턴트가 자연스럽게 해석할 수 있는 문구로 반환됩니다. 전체 목록은 오류 코드 참고.