AI 영상 생성 MCP 서버

VidFlux 영상 MCP 서버란?

Model Context Protocol(MCP)은 AI 어시스턴트가 외부 도구를 호출할 때 쓰는 개방형 표준입니다. VidFlux MCP는 호스팅된 엔드포인트로, AI 어시스턴트에게 텍스트→영상, 이미지→영상, 모션 컨트롤 작업 시작, 진행 상황 확인, 완성된 MP4 받기 같은 영상 생성 도구를 제공합니다. 프롬프트 작성, 모델·길이·화면 비율 선택, 렌더링 대기까지 어시스턴트가 알아서 처리하고, 채팅이나 에디터를 벗어나지 않고 파일을 받을 수 있습니다.

엔드포인트 뒤에서는 vidflux.ai 영상 생성기와 똑같은 파이프라인이 돌아가므로 모델 버전, 요금, 환불 규칙이 모두 같고, 모든 작업은 계정 기록에도 남습니다.

지원하는 AI 영상 모델

model 인자에 모델 ID를 넣으면 됩니다. 크레딧은 기본 설정 기준이며, 길이가 길거나 해상도가 높거나 오디오를 켜면 더 비쌉니다. dry_run으로 어떤 설정이든 정확한 가격을 미리 확인할 수 있습니다.

키프레임·썸네일용 이미지 모델

시작 프레임, 상품 이미지, 썸네일을 만들거나 수정한 뒤 위의 이미지→영상 모델로 움직이게 할 수 있습니다.

빠른 시작: 3단계로 연결

1. VidFlux에 로그인한 뒤 「설정 → API & MCP」에서 API 키를 만드세요. 신규 계정에는 무료 체험 크레딧이 지급됩니다.
2. 아래 설정 중 하나로 AI 클라이언트에 서버를 추가하세요.
3. 영상을 요청하면 끝입니다. 예: “Seedance 2로 라테아트를 붓는 5초짜리 9:16 슬로모션 영상을 만들어서 ./assets에 저장해 줘”.

MCP 클라이언트 설정

vf_your_api_key를 본인 키로 바꾸세요. 환경 변수를 지원하는 클라이언트라면 설정 파일에 직접 쓰지 말고 VIDFLUX_API_KEY에 보관하는 것을 권장합니다.

Claude Code

claude mcp add --transport http vidflux https://vidflux.ai/api/mcp \
  --header "Authorization: Bearer vf_your_api_key"

# verify
claude mcp list

Claude Desktop

Claude Desktop에서 API 키로 원격 서버에 연결하려면 mcp-remote를 사용합니다(Node.js 필요). claude_desktop_config.json을 수정한 뒤 Claude를 재시작하세요:

{
  "mcpServers": {
    "vidflux": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote", "https://vidflux.ai/api/mcp",
        "--header", "Authorization: Bearer vf_your_api_key"
      ]
    }
  }
}

Cursor

~/.cursor/mcp.json(전체 프로젝트) 또는 .cursor/mcp.json(해당 프로젝트)에 추가하세요:

{
  "mcpServers": {
    "vidflux": {
      "url": "https://vidflux.ai/api/mcp",
      "headers": { "Authorization": "Bearer vf_your_api_key" }
    }
  }
}

OpenAI Codex CLI

export VIDFLUX_API_KEY=vf_your_api_key
codex mcp add vidflux --url https://vidflux.ai/api/mcp \
  --bearer-token-env-var VIDFLUX_API_KEY

VS Code (GitHub Copilot agent mode)

.vscode/mcp.json에 추가하세요:

{
  "servers": {
    "vidflux": {
      "type": "http",
      "url": "https://vidflux.ai/api/mcp",
      "headers": { "Authorization": "Bearer vf_your_api_key" }
    }
  }
}

Windsurf

~/.codeium/windsurf/mcp_config.json에 추가하세요:

{
  "mcpServers": {
    "vidflux": {
      "serverUrl": "https://vidflux.ai/api/mcp",
      "headers": { "Authorization": "Bearer vf_your_api_key" }
    }
  }
}

Cline, Roo Code 및 기타 클라이언트

사용자 지정 헤더가 있는 Streamable HTTP 서버를 지원하는 클라이언트라면 같은 URL과 헤더로 연결됩니다. stdio만 지원하는 클라이언트는 Claude Desktop용 mcp-remote 설정을 그대로 쓰면 됩니다.

MCP 도구

영상 생성은 비동기로 진행됩니다. 에이전트의 일반적인 흐름은 다음과 같습니다:

list_models            → seedance-2 (9:16, audio)
generate_video {model: "seedance-2", prompt: "...", aspect_ratio: "9:16",
                duration: 5, dry_run: true}
                       → {"credits_required": 425, "sufficient": true}
generate_video {...same arguments without dry_run}
                       → {"id": "3f1c9e0a-...", "status": "processing"}
get_task {task_id: "3f1c9e0a-..."}   (every 15 s)
                       → {"status": "completed", "video_url": "https://...mp4"}

요금: 사용한 만큼 크레딧 차감

• 서버 연결과 list_models, get_task, get_credits 호출은 무료입니다.
• 영상 한 편에 드는 크레딧은 vidflux.ai와 같습니다(위 표 참고). 크레딧 팩은 500크레딧 $4.98부터이며, 큰 팩일수록 크레딧당 가격이 낮고 구매한 크레딧은 만료되지 않습니다.
• dry_run: true를 넣으면 생성 없이 인자를 검증하고 정확한 가격과 잔액 충분 여부를 알려 줍니다.
• 실패하거나 거절된 작업의 크레딧은 자동으로 환불됩니다.

크레딧 팩과 요금제 보기

이렇게 활용할 수 있어요

VidFlux MCP vs 각사 공식 API vs 셀프 호스팅 MCP

문제 해결

연결됨으로 표시되는데 영상 도구가 보이지 않아요

클라이언트를 재시작하거나 MCP 서버를 다시 불러오고, Agent 모드인지 확인하세요(Cursor, VS Code). Claude Code에서는 /mcp로 도구 목록을 볼 수 있습니다.

401 Unauthorized 또는 “Missing or invalid API key” 오류

헤더는 정확히 Authorization: Bearer vf_… 형식이어야 합니다. 키가 폐기되지 않았는지, 복사할 때 따옴표나 공백이 섞이지 않았는지 확인하세요.

402 INSUFFICIENT_CREDITS 오류

잔액이 dry_run이 알려 준 가격보다 적습니다. 크레딧을 충전하거나 더 짧거나 해상도가 낮거나 저렴한 모델을 선택하세요.

영상이 오래 processing 상태로 남아 있어요

대부분의 영상은 1~5분 안에 완성되지만, Seedance 2.5 장편이나 4K Gemini Omni는 더 걸릴 수 있습니다. get_task로 계속 확인하세요. 실패하면 오류가 반환되고 크레딧은 환불됩니다.

Claude Desktop에서 spawn npx ENOENT 오류

mcp-remote는 Node.js 18 이상이 필요합니다. Node.js를 설치하거나 command에 npx의 전체 경로를 넣으세요.

참조 이미지가 거부돼요

image_urls에는 공개된 HTTPS 이미지 URL(JPG, PNG, WebP)을 넣어야 합니다. 로컬 파일 경로나 로그인이 필요한 링크는 읽을 수 없습니다.

자주 묻는 질문