짧은 제품 데모나 README를 위한 시각적 설명이 필요할 때, 느린 부분은 아이디어가 아닙니다. 느린 부분은 터미널을 벗어나 다른 도구를 열고, 개발자 작업을 비디오 편집 워크플로우로 변환하는 과정입니다.

이 가이드는 터미널 우선(terminal-first) 설정을 안내합니다. Claude Code를 Veo MCP 서버에 연결하여, 프로젝트 작업 공간을 벗어나지 않고도 일상적인 언어로 짧은 AI 생성 비디오를 요청할 수 있습니다.

이 소스 워크플로우는 Claude Code + Veo MCP에 대한 Ace Data Cloud 문서에서 가져왔습니다. Veo는 그곳에서 Google의 AI 비디오 생성 모델로 설명되어 있으며, 1080p 출력과 오디오가 포함된 비디오 생성을 지원합니다. 실제로 빌더들에게 흥미로운 부분은 모델만이 아닙니다. 바로 MCP 레이어입니다. Claude Code는 코딩 세션에서 직접 비디오 도구를 호출할 수 있습니다.

할 수 있는 일

MCP 서버가 연결된 후, Claude Code는 두 가지 Veo 도구를 사용할 수 있습니다:

• veo_generate_video: 텍스트 또는 이미지로부터 비디오 생성
• veo_generate_video_with_audio: 오디오가 포함된 비디오 생성

이는 엔지니어링 작업에서 발생하는 몇 가지 실질적인 사례를 다룹니다:

• 배경이 맑음에서 비로 바뀌는 동안 날씨 데이터를 보여주는 휴대폰 화면과 같은 작은 앱 데모
• 세 개의 처리 노드를 통해 입력창에서 결과 패널로 데이터가 이동하는 README 애니메이션
• 검은색 배경에 코드가 타이핑되고, 키보드 클릭 소리, 성공적인 컴파일, 그리고 녹색 체크 표시가 나타나는 터미널 스타일의 오디오 포함 비디오

핵심은 세심한 디자인 작업을 대체하는 것이 아닙니다. 원하는 장면을 이미 알고 있을 때 가벼운 시각적 자산을 더 쉽게 프로토타이핑할 수 있도록 만드는 것입니다.

작동 방식

이 워크플로우에서 사용되는 MCP 서버 URL은 다음과 같습니다:

Claude Code는 HTTP를 통해 서버에 연결하며, 인증은 Authorization 헤더를 통해 전달됩니다:

claude mcp add veo --transport http https://veo.mcp.acedata.cloud/mcp \
  -H "Authorization: Bearer YOUR_TOKEN"

작지만 중요한 세부 사항: -H 플래그는 반드시 대문자여야 합니다. Claude Code 명령에서 소문자 -h는 HTTP 헤더가 아니라 도움말 (help)을 의미합니다. 연결이 토큰을 수신하지 못하는 것처럼 보인다면 이 부분을 가장 먼저 확인하세요.

토큰은 Ace Data Cloud 플랫폼에 로그인한 후 받을 수 있습니다. 동일한 토큰이 MCP 서버 연결에 사용되므로, Claude Code가 Veo 도구 (tools)를 호출할 때 인증을 수행할 수 있습니다.

적절한 설정 범위 (configuration scope) 선택하기

Claude Code를 사용하면 MCP 설정이 적용될 범위를 결정할 수 있습니다. -s 옵션을 생략하면 기본 범위는 local이며, 이는 명령이 실행되는 프로젝트 디렉토리에만 적용됩니다.

문서화된 범위는 다음과 같습니다:

개인적인 실험을 위해서는 보통 local 범위로 충분합니다. 여러 저장소 (repositories)에서 사용할 도구라면 -s user가 편리합니다. 팀 프로젝트의 경우, 설정이 프로젝트 루트에 위치하므로 -s project를 사용하는 것이 합리적일 수 있습니다.

한 가지 주의사항: 실제 토큰을 공개 저장소 (public repository)에 커밋하지 마세요. 만약 project 범위를 사용하고 git을 통해 설정을 공유한다면, 실제 Bearer 토큰 대신 ${ENV_VAR}와 같은 환경 변수 (environment variable) 플레이스홀더를 사용하세요.

연결 확인하기

MCP 서버를 추가한 후 다음을 실행하세요:

claude mcp list

veo 서버가 다음과 같이 연결된 상태(connected status)로 표시되는지 확인하세요:

veo  ✓ Connected

만약 연결되지 않는다면, 다음 세 가지를 이 순서대로 확인해 보시기 바랍니다:

1. 서버 URL이 정확히 https://veo.mcp.acedata.cloud/mcp 인가요?
2. 인증 헤더 (authorization header)를 위해 대문자 -H를 사용했나요?
3. Bearer 뒤에 토큰이 제대로 있으며, 쉘 (shell)에 의해 실수로 감싸지거나 잘리지 않았나요?

빌더 중심의 프롬프트 시도하기

서버가 연결되면, 별도의 API 요청을 수동으로 작성할 필요가 없습니다. 현재 세션에서 Claude Code가 Veo 도구를 사용하도록 요청할 수 있습니다.

앱 데모를 위한 예시:

날씨 앱을 개발 중입니다. 데모 영상을 생성해 주세요: 휴대폰 화면에 날씨 정보가 표시되고, 배경이 맑음에서 비로 전환됩니다.

문서화를 위한 예시:

README용 애니메이션을 생성해 주세요: 데이터가 왼쪽의 입력창에서 오른쪽의 결과 패널로 흐르며, 중간에 있는 세 개의 처리 노드(processing nodes)를 통과합니다.

오디오가 포함된 터미널 영상을 원한다면, 오디오 기능이 있는 도구를 명시적으로 요청하세요:

veo_generate_video_with_audio를 사용하여 오디오가 포함된 짧은 영상을 생성해 주세요: 검은색 배경에 코드가 자동으로 타이핑되고, 키보드 클릭 소리가 들리며, 컴파일이 성공하여 초록색 ✓ 표시가 나타납니다.

이러한 프롬프트들은 의도적으로 구체적입니다. 제 경험상, 비디오 프롬프트는 단순히 "멋진 데모를 만들어줘"라고 말하는 대신 피사체(subject), 움직임(motion), 환경(environment), 그리고 예상되는 종료 상태(expected ending state)를 묘사할 때 더 잘 작동합니다.

개발자 워크플로우에서의 활용 위치

저는 이 워크플로우를 1차 에셋(first-pass assets) 제작에 사용할 것입니다. 예를 들어 랜딩 페이지 초안을 위한 데모 클립, 빠른 README 시각 자료, 내부 프로토타입(internal prototypes), 또는 기능 브랜치(feature branch)를 위한 짧은 설명 영상 등이 해당됩니다. 이 방식의 가치는 생성 단계가 여러분이 이미 편집하고 있는 코드 및 문서 바로 옆에 위치한다는 점에 있습니다.

정확한 설정 참조를 원하신다면, 원본 Ace Data Cloud 문서는 여기에 있습니다: https://platform.acedata.cloud/documents/claude-code-mcp-veo