MCP Integration
Connect Claude, ChatGPT, Cursor, and OpenAI Agent Builder to SubDownload via Model Context Protocol.
Overview
Model Context Protocol (MCP) is a standardized framework that lets AI assistants call external tools directly. SubDownload's MCP server exposes 12 tools — including async AI transcription and a per-user Library — and supports OAuth 2.1 with Dynamic Client Registration (DCR) as well as static API keys.
Server Configuration
| Property | Value |
|---|---|
| Server URL | https://api.subdownload.com/mcp |
| Auth metadata | /.well-known/oauth-authorization-server |
| Dynamic registration | POST /oauth/register |
| Authorize | GET /oauth/authorize |
| Token | POST /oauth/token |
| Scope | mcp:access |
| Token prefix | oat_ (OAuth) or sk_live_ (API key) |
Client Setup
See the step-by-step guides:
- → Claude (Desktop / Code) — OAuth with DCR, no pre-created credentials
- → ChatGPT — static OAuth client (Client ID / Secret)
- → OpenAI Agent Builder — API key authentication
MCP Tools
| Tool | Cost | Purpose |
|---|---|---|
fetch_transcript | 1 credit | Fetch transcript by video URL/ID (params: video_url, lang). |
search_youtube | 1 credit | Search videos or channels (params: query, type, limit). |
resolve_channel | free | Resolve @handle / URL / UC… ID to channel info (param: input). |
search_channel_videos | 1 credit | Search videos within a channel (params: channel, query, limit). |
get_channel_latest_videos | free | Most recent ~15 videos via RSS (param: channel). |
list_channel_videos | 1 credit/page | Paginated uploads (params: channel or continuation). |
list_playlist_videos | 1 credit/page | Paginated playlist (params: playlist or continuation). |
transcribe_video | 5 credits on done | Start async AI Whisper transcription for videos without captions. Returns task_id + next_poll_after_seconds (params: video_url, lang). |
get_asr_task | free | Poll an ASR task; returns segments when status=done (param: task_id). |
list_library | free | List the user's saved transcripts and summaries (params: favorite, q, limit, offset). |
get_library_item | free | Read a saved item with transcript and summary inlined (params: id, locale). |
save_to_library | 1 token-quota unit | kind=asr flags a saved transcript; kind=summary uploads the AI's generated summary (params: video_id, kind, text, locale, model, …). |
Error Handling
Failed tool calls never consume credits. Errors return user-friendly messages AI assistants can interpret naturally. See Error Codes for the full list.