MCP API 연동 가이드

MCP란?

MCP(Model Context Protocol)는 AI 에이전트(Claude, GPT, Cursor 등)가 외부 서비스의 도구를 직접 호출할 수 있게 해주는 표준 프로토콜입니다. Autoagens MCP 서버를 연결하면 AI와 대화하면서 영상을 제작할 수 있습니다.

시작하기

1. 회원가입 후 대시보드 > 설정 > API Keys에서 API Key를 발급받으세요.
2. 아래에서 사용하는 AI 클라이언트에 맞는 설정을 복사하여 붙여넣으세요.
3. AI에게 “영상 만들어줘”라고 말하면 됩니다!

연결 정보

항목	값
MCP 엔드포인트	https://autoagens.com/api/mcp
전송 방식	Streamable HTTP
인증	Authorization: Bearer ak_여러분의_API_KEY

---

Claude Desktop에서 연결하기

Claude Desktop 설정 파일을 열어 아래 내용을 추가하세요.

• Mac: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "autoagens-video": {
      "type": "url",
      "url": "https://autoagens.com/api/mcp",
      "headers": {
        "Authorization": "Bearer ak_여러분의_API_KEY"
      }
    }
  }
}

ak_여러분의_API_KEY 부분을 발급받은 API Key로 교체하세요. 저장 후 Claude Desktop을 재시작하면 연결됩니다.

Claude Code (CLI)에서 연결하기

터미널에서 아래 명령어를 실행하세요:

claude mcp add autoagens-video \
  --transport http \
  https://autoagens.com/api/mcp \
  --header "Authorization: Bearer ak_여러분의_API_KEY"

Cursor에서 연결하기

프로젝트 루트에 .cursor/mcp.json 파일을 만들고 아래 내용을 추가하세요:

{
  "mcpServers": {
    "autoagens-video": {
      "type": "url",
      "url": "https://autoagens.com/api/mcp",
      "headers": {
        "Authorization": "Bearer ak_여러분의_API_KEY"
      }
    }
  }
}

Windsurf / 기타 MCP 클라이언트

MCP Streamable HTTP를 지원하는 모든 클라이언트에서 연결 가능합니다:

URL:    https://autoagens.com/api/mcp
Method: POST
Header: Authorization: Bearer ak_여러분의_API_KEY
Header: Content-Type: application/json
Header: Accept: application/json, text/event-stream

---

연결 확인하기

연결 후 AI에게 다음과 같이 말해보세요:

• “video-guide 프롬프트 읽어줘” — 전체 사용 가이드를 확인할 수 있습니다
• “사용 가능한 도구 목록 보여줘” — 11개 도구 목록을 확인할 수 있습니다

---

사용 가능한 도구

워크플로우 관리

도구	설명
create_workflow	새 영상 워크플로우 생성
save_workflow	워크플로우에 노드/엣지 저장
list_workflows	내 워크플로우 목록 조회

에셋 & 이미지

도구	설명	비용
upload_asset	외부 이미지 URL 또는 base64를 안정적인 에셋으로 업로드. 반환된 assetId를 이후 도구에서 재사용	무료
generate_image	AI 이미지 생성 (텍스트/이미지 기반). 자동으로 에셋 저장되어 assetId 반환	100 코인

영상 생성

도구	설명	비용
create_clip	영상 클립 생성 (비동기). 모든 모드에서 프롬프트 필수. 이전 씬 영상 참조로 연속성 강화 가능	2,500~7,500 코인
compose_video	클립 합성하여 최종 영상 제작 (비동기)	500 코인

상태 확인 & 프레임 추출

도구	설명
get_job_status	클립/합성 작업 상태 조회
extract_frame	완료된 클립에서 프레임 추출. 멀티씬 체이닝에 활용 (동기, 5~15초)

템플릿

도구	설명
list_templates	공개 템플릿 목록
use_template	템플릿을 내 워크플로우로 복사

지원 AI 영상 모델

모델	지원 모드	Duration	특징
veo3-fast	T2V	5~8초	Google Veo 3 빠른 버전, seed/negative_prompt 지원
veo3	T2V	5~8초	Google Veo 3, 최고 품질
kling-v3-pro	I2V, IT2V	3~15초	캐릭터 참조/endImage/negative_prompt/영상 연속성 지원
kling-o3	I2V, IT2V	3~15초	고품질, 캐릭터 참조/endImage/negative_prompt/영상 연속성 지원
kling-v2.6-pro	I2V, IT2V	5 또는 10초	endImage/negative_prompt 지원
ltx-2.3	I2V, IT2V	6~20초 (짝수만)	빠른 생성, endImage 지원

고급 옵션 (모델별 선택 지원)

기능	설명	지원 모델
negativePrompt	원하지 않는 요소 지정	veo3, kling 모델
seed	동일 결과 재현	veo3-fast, veo3
characterReferences	캐릭터 일관성 유지 (정면 이미지 + 참조 이미지)	kling-v3-pro, kling-o3
endImageUrl	끝 프레임 이미지 지정	kling, ltx 모델

영상 연속성 옵션

멀티씬 제작 시 이전 씬의 영상을 참조하여 모션, 카메라, 장면 구도의 연속성을 강화할 수 있습니다.

파라미터	설명
videoUrl / referenceVideoUrl	이전 클립 영상 URL을 직접 전달. 모션/카메라 연속성 참조로 사용
previousClipTaskId	완료된 이전 클립의 taskId. 서버에서 자동으로 videoUrl을 조회
continueMotion	이전 영상의 움직임 상태를 이어받기 (참조 영상 있으면 기본 true)
preserveCamera	이전 영상의 카메라 방향/움직임 유지 (참조 영상 있으면 기본 true)
preserveSceneLayout	이전 영상의 장면 구도/배치 유지 (참조 영상 있으면 기본 true)

현재 백엔드는 참조 영상에서 프레임을 추출하고 프롬프트를 보강하는 방식으로 연속성을 처리합니다. 한국어 프롬프트는 자동으로 영어 번역 후 전달됩니다.

---

영상 제작 플로우

AI에게 “30초 광고 영상 만들어줘”라고 말하면 자동으로 처리되지만, 내부적으로는 다음 순서로 진행됩니다:

1. 워크플로우 생성 — create_workflow로 프로젝트 시작
2. 참조 이미지 준비 — upload_asset으로 외부 이미지를 안정적인 에셋으로 업로드 (무료)
3. 이미지 생성 (선택) — generate_image로 소스 이미지를 AI 생성 (100코인)
4. 클립 생성 — create_clip으로 장면 생성. 모든 모드에서 프롬프트 필수 (비동기, 1~3분)
5. 상태 확인 — get_job_status로 완료 대기 (3~5초 간격 폴링)
6. 영상 합성 — 모든 클립 완료 후 compose_video로 최종 영상 제작 (2~5분)
7. 결과 다운로드 — 완성된 영상 URL 제공

멀티씬 체이닝 (장면 연속성)

프레임 한 장만 넘기면 시각적으로는 이어지지만, 모션/카메라/스토리 연속성은 약할 수 있습니다. 끝 프레임 + 이전 영상 참조를 함께 전달하면 더 자연스러운 연결이 가능합니다.

1. 씬1 create_clip → 완료 대기
2. extract_frame(taskId: "씬1_taskId", position: "end") → frameUrl 획득
3. get_job_status(jobId: "씬1_taskId") → 이전 씬 videoUrl 확보
4. 씬2 create_clip에 다음을 전달:
   • imageUrl: frameUrl — 시각적 연결
   • referenceVideoUrl: "씬1_videoUrl" — 모션/카메라 연속성
   • prompt: "다음 장면 설명" — 필수
5. 반복하여 모든 씬 완료 후 compose_video

또는 previousClipTaskId를 사용하면 서버가 자동으로 이전 클립의 videoUrl을 조회합니다:

create_clip({
  imageUrl: "frameUrl",
  previousClipTaskId: "씬1_taskId",
  prompt: "다음 장면 설명",
  model: "kling-v3-pro",
  duration: 5,
  clipId: "scene-02"
})

비용 안내

작업	비용
에셋 업로드	무료
이미지 생성	100 코인
프레임 추출	무료
클립 생성 (5초)	2,500 코인
클립 생성 (10초)	5,000 코인
클립 생성 (15초)	7,500 코인
영상 합성	500 코인

실패 시 코인은 자동 환불됩니다. 관리자(admin)는 코인 차감 없이 무료로 사용 가능합니다.

자주 묻는 질문

API Key는 어디서 발급받나요?

대시보드 > 설정 > API Keys에서 발급받을 수 있습니다. ak_로 시작하는 키가 생성됩니다.

어떤 AI 클라이언트를 지원하나요?

MCP Streamable HTTP를 지원하는 모든 클라이언트에서 사용 가능합니다. Claude Desktop, Claude Code, Cursor, Windsurf 등에서 테스트 완료되었습니다.

upload_asset과 generate_image의 차이는 무엇인가요?

upload_asset은 이미 존재하는 이미지를 Autoagens에 저장하는 도구입니다 (무료). generate_image는 AI가 새 이미지를 생성 후 에셋으로 저장합니다 (100코인). 두 도구 모두 assetId를 반환합니다.

extract_frame은 어떤 용도인가요?

완료된 영상 클립에서 특정 위치의 프레임을 추출합니다. 멀티씬 체이닝에서 이전 씬의 마지막 프레임을 다음 씬의 시작 이미지로 사용합니다.

이전 씬과 자연스럽게 이어지게 하려면?

extract_frame으로 끝 프레임을 추출하고, referenceVideoUrl 또는 previousClipTaskId로 이전 영상을 함께 전달하세요. 프레임만 넘기는 것보다 영상 참조까지 전달할 때 모션과 카메라 연속성이 더 자연스럽습니다.

한국어 프롬프트도 사용할 수 있나요?

네, 한국어와 영어 모두 지원합니다. 한국어 프롬프트는 자동으로 영어로 번역되어 모델에 전달됩니다.

코인은 어디서 충전하나요?

대시보드 > 코인에서 충전할 수 있습니다.