BYGENCY MCP 연동 가이드

개요

MCP(Model Context Protocol)는 Claude 같은 AI에 외부 도구를 연결하는 표준입니다. BYGENCY MCP 서버는 Streamable HTTP(무상태) 방식이며, 아래 4개 도구를 제공합니다.

1. 원클릭 연결 (권장)

토큰 발급·복사 없이, 서버 주소 한 줄로 연결합니다. Claude가 자동으로 BYGENCY 로그인·승인 창을 띄우고(OAuth), 승인하면 그 계정으로 연결됩니다.

1-b. 개인 토큰 방식 (대안)

로그인 창을 띄울 수 없는 환경(서버 스크립트·자동화·Claude API)에서 사용하는 방식입니다. 일반적인 Claude 연결은 위 원클릭 연결을 쓰세요.

연결 주소에는 본인 개인 토큰이 포함됩니다. 이 주소로 생성하면 본인 계정 크레딧에서 차감됩니다. 절대 타인과 공유하지 마세요.

발급·재발급 위치: 스튜디오 → 좌측 하단 프로필 → MCP 연결 탭. 토큰이 유출되면 같은 탭에서 재발급하면 기존 연결이 무효화됩니다.

2. 연결 방법

Claude 데스크톱 · claude.ai (커스텀 커넥터)

설정(Settings) → 커넥터(Connectors) → 커스텀 커넥터 추가 → https://nextbygency.com/api/mcp 입력 → 자동으로 뜨는 로그인 창에서 “연결 허용”. 토큰이 필요 없습니다(원클릭 연결). 개인 토큰 주소를 넣어도 동일하게 동작합니다. ※ Pro/Team/Enterprise 플랜에서 커스텀 커넥터가 지원됩니다.

Cursor

Settings → MCP → Add new MCP server → Type을 HTTP로 두고 URL에 내 연결 주소 입력. 또는 ~/.cursor/mcp.json 에 아래 추가:

{
  "mcpServers": {
    "bygency": { "url": "https://nextbygency.com/api/mcp/<YOUR_TOKEN>" }
  }
}

Claude Code (터미널)

claude mcp add --transport http bygency https://nextbygency.com/api/mcp/<YOUR_TOKEN>

추가 후 /mcp 명령으로 연결 상태를 확인하세요.

Claude API (Messages)

요청에 mcp_servers 를 추가하고 anthropic-beta: mcp-client-2025-04-04 헤더를 넣으세요.

curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: mcp-client-2025-04-04" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-4-5",
    "max_tokens": 1024,
    "messages": [{ "role": "user", "content": "고양이 이미지 만들어줘" }],
    "mcp_servers": [{ "type": "url", "name": "bygency", "url": "https://nextbygency.com/api/mcp/<YOUR_TOKEN>" }]
  }'

3. 도구 레퍼런스

{
  "prompt": "네온 사인이 있는 밤거리",   // 필수
  "model": "nanobanana",              // nanobanana(기본)·gpt·grok
  "reference_image_url": "https://…", // 선택(편집)
  "negative_prompt": "흐릿함, 왜곡"     // 선택
}
→ { "status":"succeeded", "image_url":"https://…",
    "credits_charged": 3, "credits_remaining": 1997 }

{
  "model": "seedance",         // veo·runway·seedance (필수)
  "prompt": "질주하는 스포츠카",  // 필수
  "first_frame_url": "https://…", // 선택 (runway는 필수) · 이어보기: 앞 클립의 last_frame_url
  "last_frame_url": "https://…",  // 선택 · 주면 첫↔끝 사이를 보간(시퀀스가 안정적)
  "seconds": 5,                // veo 5~8, runway/seedance 5·10
  "ratio": "16:9",             // 16:9·9:16·1:1
  "dry_run": false             // true면 과금 없이 미리보기
}
→ { "status":"generating", "task":"/api/generate?provider=…",
    "credits_charged": 15, "credits_remaining": 1982 }

{ "task": "/api/generate?provider=…" }   // generate_video의 task 그대로
→ 진행 중: { "status":"generating", "note":"15~30초 후 다시" }
→ 완료:   { "status":"succeeded", "video_url":"https://…",
           "last_frame_url":"https://…" }   // 이어보기용 마지막 프레임(지원 모델)

// 이어지는 클립 만들기
//  ① check_video_status 의 last_frame_url 을 받는다
//  ② 다음 generate_video 의 first_frame_url 로 그대로 넣는다 → 앞 영상 끝에서 이어짐
//  ③ 끝 지점까지 정하려면 last_frame_url 도 함께 준다(두 그림 사이 보간)

{}  // 인자 없음
→ { "video":[…], "image":[…], "tip":"…" }

4. 원시 JSON-RPC 예시

MCP는 JSON-RPC 2.0을 씁니다. 직접 호출해 연결을 테스트할 수 있습니다.

curl -X POST "https://nextbygency.com/api/mcp/<YOUR_TOKEN>" \
  -H "content-type: application/json" \
  -d '{ "jsonrpc":"2.0", "id":1, "method":"tools/list" }'

curl -X POST "https://nextbygency.com/api/mcp/<YOUR_TOKEN>" \
  -H "content-type: application/json" \
  -d '{
    "jsonrpc":"2.0", "id":2, "method":"tools/call",
    "params": { "name":"generate_image",
      "arguments": { "prompt":"노을 지는 해변", "model":"nanobanana" } }
  }'

연결 상태만 빠르게 보려면 브라우저로 내 주소를 열어 { "status": "ok", "authenticated": true, "credits": … } 가 보이면 정상입니다.

5. 광고 집행까지 — Meta Ads MCP 조합

Meta(페이스북·인스타그램)의 공식 광고 MCP를 함께 연결하면, 별도 개발 없이 Claude 대화 하나로 소재 생성 → 캠페인 생성 → 집행까지 이어집니다. BYGENCY가 생성한 영상 URL은 영구 보관본(R2)이라 광고 소재로 바로 전달됩니다.

⚠️ 집행은 실제 광고비가 나갑니다. 항상 일시정지(paused) 상태로 생성하게 지시하고, Meta 광고 관리자에서 검토 후 직접 켜세요. BYGENCY MCP도 같은 원칙을 Claude에 안내합니다.

5. 크레딧·과금

• 생성 1건마다 연결된 본인 계정에서 크레딧이 차감됩니다(스튜디오와 동일 단가·배수).
• 생성 전에 잔액을 확인해 부족하면 생성을 거부합니다(크레딧 마이너스 없음).
• 영상은 시작 시 1회만 차감되고, check_video_status 반복 호출은 추가 과금이 없습니다.
• dry_run: true 는 실제 호출·과금 없이 페이로드만 미리 봅니다.
• 응답의 credits_charged·credits_remaining 로 차감액·잔액을 확인할 수 있습니다.

6. 오류

문제 해결

연결이 안 될 때 이 순서로 확인하세요.

연결 상태 확인

# 브라우저로 열어도 되고, 터미널에서 확인해도 된다
curl -s "https://nextbygency.com/api/mcp"

# 정상이면 아래처럼 돌아온다
{ "status": "ok", "authenticated": true, "credits": 1982 }