MCP 서버 연결

transcript1의 원격 Model Context Protocol 서버를 AI 어시스턴트에 연결하세요. YouTube, X, TikTok, Instagram, Facebook, Bluesky의 영상 링크나 업로드한 오디오·영상 파일을 텍스트로 변환하고, 완성된 스크립트를 어시스턴트가 읽을 수 있어요. 그 밖에 지원하는 공개 녹화 영상과 제한 사항은 지원 링크와 변환 옵션에서 확인하세요.

공개 게시물만 사용할 수 있으며 영상이 여러 개면 첫 번째 영상만 변환해요. YouTube와 X의 자막 지원은 그대로예요. TikTok, Bluesky, Dailymotion, LinkedIn에서도 영상 원본 언어의 자막을 사용할 수 있어요. auto에서는 사용할 자막이 없으면 AI 음성 텍스트 변환(STT)으로 전환해요. 분당 요금은 같아요.

YouTube 외 플랫폼의 자막은 자동 생성 자막도 세그먼트별 타임스탬프만 있어요(words: null). captions(자막만)는 오디오 다운로드나 STT를 실행하지 않아요. 화자 분리를 켜거나 source=stt를 지정하면 자막 대신 음성을 변환해요. 자세한 기준은 지원 링크와 변환 옵션을 확인하세요.

• 서버 주소: https://api.transcript1.com/mcp (Streamable HTTP)
• 연결 인증: Claude와 ChatGPT에서는 OAuth 2.1로 transcript1에 로그인하고 접근을 승인해요. Cursor, VS Code, Claude Code, 에이전트에서는 API 키를 Authorization: Bearer t1_... 헤더로 보내세요. 키는 “API keys” 페이지에서 발급받을 수 있어요.

MCP 도구는 연결한 계정의 인증 정보로 /v1 REST API를 호출해요. 입력값 검증, 크레딧 차감, 오류 코드도 REST API와 같아요. MCP 전용 한도나 분량이 따로 있는 것은 아니며, 다른 요청과 계정의 요청 한도·분량을 함께 사용해요.

사용할 수 있는 도구

응답 형식과 기본 설정

• 기본 format은 text예요. 세그먼트마다 한 줄로 출력하며 타임스탬프를 붙여요. 화자 분리를 했다면 [00:01:02] Speaker 1: Good morning.처럼 화자도 표시해요. srt, vtt, json 형식도 선택할 수 있어요.
• wait_seconds는 기본 50초이며 0~55초로 지정할 수 있어요. 기다린 뒤에도 처리 중이면 응답에 상태와 id가 나와요. 이 ID로 get_transcription을 호출해 다시 기다리세요.
• 긴 스크립트는 여러 페이지로 나눠요. max_chars는 기본 60,000이며 1,000~100,000 사이에서 지정할 수 있어요. 세그먼트 중간에서 끊지 않고 응답에 next_from_seconds를 넣어요. 다음 페이지를 받으려면 이 값을 from_seconds로 보내세요.
• 모든 응답에서 transcript_source로 출처를 확인할 수 있어요. 값은 youtube_captions, x_captions, tiktok_captions, bluesky_captions, dailymotion_captions, linkedin_captions, speech_to_text예요. caption_kind: null은 자막의 출처를 모른다는 뜻이에요. 업로더가 올린 자막으로 해석하면 안 돼요.

다시 보내기 전에 기존 작업 확인하기

transcribe는 항상 reuse_recent를 사용해요. 전체 영상 링크와 같은 옵션으로 24시간 안에 다시 요청하면 이전 작업을 반환하고 추가 차감하지 않아요. 단축 링크는 이 방식으로 재사용할 수 없어요. 기존 작업을 재사용했는지는 응답에 표시해요. 이미 접수한 작업의 진행 상황은 새로 제출하지 말고 get_transcription이나 list_transcriptions로 확인하세요.

파일 업로드 흐름

파일 데이터 자체는 MCP로 보낼 수 없어요. create_upload를 호출하면 작업 id, 청크 URL 템플릿, X-Upload-Token, 청크 목록을 받아요. 어시스턴트는 MCP 외부에서 HTTP PUT으로 청크를 보내고, 전송을 마치면 complete_upload를 호출해요. 응답에는 직접 파일을 올릴 수 있는 대시보드 업로드 페이지도 안내해요. 전송 규약은 파일 업로드를 확인하세요.

웹훅은 REST API로 사용

MCP 도구는 웹훅 파라미터를 받지 않아요. 완료 알림이 필요하면 REST API의 웹훅을 사용하세요.

Claude

Claude에서는 커스텀 커넥터로 원격 MCP 서버를 등록하세요.

1. Claude의 커넥터 설정에서 커스텀 커넥터 추가를 선택하세요.
2. 이름에 transcript1, 서버 URL에 https://api.transcript1.com/mcp를 넣으세요.
3. 로그인 화면이 나오면 transcript1 계정으로 로그인하고 접근을 허용하세요. 요청하는 권한은 transcriptions:read, transcriptions:write예요.

연결 후 “https://www.youtube.com/watch?v=dQw4w9WgXcQ 영상을 텍스트로 변환해 줘”라고 요청해 보세요. 커스텀 커넥터 지원 여부는 Claude 요금제에 따라 달라요.

ChatGPT

ChatGPT에서도 MCP 서버를 커스텀 커넥터로 등록할 수 있어요.

1. ChatGPT 커넥터 설정에서 MCP 서버용 커스텀 커넥터를 추가하세요.
2. 서버 주소에 https://api.transcript1.com/mcp를 넣으세요.
3. transcript1 계정으로 로그인한 뒤 접근을 허용하세요.

사용 가능 여부는 ChatGPT 요금제와 워크스페이스 설정에 따라 달라요. 개발자 모드를 켜야 할 수도 있어요.

Cursor에 MCP 연결하기

Cursor에 transcript1 추가 링크로 서버를 바로 설치할 수 있어요.

직접 설정하려면 .cursor/mcp.json에 아래 내용을 넣으세요. Authorization 헤더에는 API 키를 지정하세요.

{
  "mcpServers": {
    "transcript1": {
      "url": "https://api.transcript1.com/mcp",
      "headers": {
        "Authorization": "Bearer t1_YOURKEY"
      }
    }
  }
}

VS Code

VS Code에 transcript1 추가 링크로 서버를 바로 설치할 수 있어요.

수동으로 설정하려면 워크스페이스의 .vscode/mcp.json에 아래 내용을 넣으세요.

{
  "servers": {
    "transcript1": {
      "type": "http",
      "url": "https://api.transcript1.com/mcp",
      "headers": {
        "Authorization": "Bearer t1_YOURKEY"
      }
    }
  }
}

Claude Code에 MCP 연결하기

아래 명령의 t1_YOURKEY에 발급받은 API 키를 넣고 실행하세요.

claude mcp add --transport http transcript1 https://api.transcript1.com/mcp --header "Authorization: Bearer t1_YOURKEY"

다른 MCP 클라이언트에서 연결하기

원격 MCP 서버를 지원한다면 다른 클라이언트에서도 연결할 수 있어요. 서버 URL은 https://api.transcript1.com/mcp, 인증 헤더는 Authorization: Bearer t1_...로 설정하세요.

명령어로 연결하기: Claude Desktop 등

MCP 서버를 명령어로 실행하는 클라이언트라면 TRANSCRIPT1_API_KEY를 설정하고 npx -y @transcript1/mcp를 실행하세요. 이 패키지가 원격 transcript1 서버에 연결해요. Node.js 18 이상이 필요해요.

Claude Desktop은 claude_desktop_config.json에 아래 설정을 추가하세요. t1_YOURKEY에는 “API keys” 페이지에서 발급받은 키를 넣으세요.

{
  "mcpServers": {
    "transcript1": {
      "command": "npx",
      "args": ["-y", "@transcript1/mcp"],
      "env": { "TRANSCRIPT1_API_KEY": "t1_YOURKEY" }
    }
  }
}

Agent Skill

Agent Skill은 transcript1 사용 방법을 적은 짧은 SKILL.md 파일이에요. 스킬을 지원하는 에이전트에 https://transcript1.com/.well-known/agent-skills/transcript1/SKILL.md의 파일을 추가하세요.

스킬을 자동으로 탐색하는 에이전트는 https://transcript1.com/.well-known/agent-skills/index.json에서 이 파일을 찾을 수 있어요.

도구 호출이 실패한 경우

도구 호출이 실패하면 REST API와 같은 code에 오류 설명과 해결 방법을 덧붙여요. 어시스턴트는 이 안내를 보고 다음 행동을 정할 수 있어요. 형식은 <code>: <message>. <next step>이며, 사용 가능한 분량을 다 쓰면 다음처럼 나와요.

insufficient_minutes: 20 minutes needed, 3 remaining. Top up at https://transcript1.com/dashboard/billing

코드별 의미는 오류 처리에서 확인하세요. 변환 도중 실패한 작업도 media_private, no_captions 같은 원인 코드로 같은 형식의 오류를 반환해요.