MCP API 연동 가이드
Claude Desktop, Claude Code, Cursor 등 AI 클라이언트에서 MCP로 영상을 제작하는 방법
MCP란?
MCP(Model Context Protocol)는 AI 에이전트(Claude, GPT, Cursor 등)가 외부 서비스의 도구를 직접 호출할 수 있게 해주는 표준 프로토콜입니다. Autoagens MCP 서버를 연결하면 AI와 대화하면서 영상을 제작할 수 있습니다.
시작하기
- 회원가입 후 대시보드 > 설정 > API Keys에서 API Key를 발급받으세요.
- 아래에서 사용하는 AI 클라이언트에 맞는 설정을 복사하여 붙여넣으세요.
- 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초 광고 영상 만들어줘”라고 말하면 자동으로 처리되지만, 내부적으로는 다음 순서로 진행됩니다:
- 워크플로우 생성 —
create_workflow로 프로젝트 시작 - 참조 이미지 준비 —
upload_asset으로 외부 이미지를 안정적인 에셋으로 업로드 (무료) - 이미지 생성 (선택) —
generate_image로 소스 이미지를 AI 생성 (100코인) - 클립 생성 —
create_clip으로 장면 생성. 모든 모드에서 프롬프트 필수 (비동기, 1~3분) - 상태 확인 —
get_job_status로 완료 대기 (3~5초 간격 폴링) - 영상 합성 — 모든 클립 완료 후
compose_video로 최종 영상 제작 (2~5분) - 결과 다운로드 — 완성된 영상 URL 제공
에셋(Asset) 기반 워크플로우란?
upload_asset 또는 generate_image가 반환하는 assetId는 Autoagens 서버에 저장된 안정적인 이미지 참조입니다. 외부 URL이 만료되거나 변경될 수 있는 것과 달리, assetId는 항상 유효합니다.
멀티씬 체이닝 (장면 연속성)
프레임 한 장만 넘기면 시각적으로는 이어지지만, 모션/카메라/스토리 연속성은 약할 수 있습니다. 끝 프레임 + 이전 영상 참조를 함께 전달하면 더 자연스러운 연결이 가능합니다.
- 씬1
create_clip→ 완료 대기 extract_frame(taskId: "씬1_taskId", position: "end")→frameUrl획득get_job_status(jobId: "씬1_taskId")→ 이전 씬videoUrl확보- 씬2
create_clip에 다음을 전달:imageUrl: frameUrl— 시각적 연결referenceVideoUrl: "씬1_videoUrl"— 모션/카메라 연속성prompt: "다음 장면 설명"— 필수
- 반복하여 모든 씬 완료 후
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로 이전 영상을 함께 전달하세요. 프레임만 넘기는 것보다 영상 참조까지 전달할 때 모션과 카메라 연속성이 더 자연스럽습니다.
한국어 프롬프트도 사용할 수 있나요?
네, 한국어와 영어 모두 지원합니다. 한국어 프롬프트는 자동으로 영어로 번역되어 모델에 전달됩니다.
코인은 어디서 충전하나요?
대시보드 > 코인에서 충전할 수 있습니다.