Compeller MCP Server

공식

MCP를 통해 노래로 AI 뮤직 비디오와 오디오 반응형 비주얼을 제작합니다.

문서

Compeller MCP 엔드포인트 (`/api/mcp`)

Compeller MCP 엔드포인트는 기존 v1 REST API 위에 얇은 JSON-RPC 2.0 래퍼로 모델 컨텍스트 프로토콜을 구현합니다. 이는 원시 HTTP 대신 MCP를 기본적으로 사용하는 에이전트 통합자(Claude Desktop, Cursor, 커스텀 MCP 클라이언트, DigiRAMP)를 위한 것입니다.

전송: 스트리밍 가능 HTTP (HTTP POST당 단일 JSON-RPC 메시지).
URL: POST https://compeller.ai/api/mcp
프로토콜 버전: 2024-11-05
서버 이름 / 버전: compeller-mcp / initialize 결과 참조.
도구 계약: 아래 도구 목록은 공개 통합 계약입니다. 배포된 서버에서 런타임에 광고되는 집합은 tools/list을 사용하십시오.
디렉터리 목록: 공식 MCP 레지스트리 · Smithery · Glama

인증

익명(검색) 메서드: initialize, tools/list, ping, notifications/initialized, 그리고 익명 도구 get_capabilities, get_pricing, list_styles.

그 외 모든 도구는 HTTP 요청 자체에 Compeller API 토큰을 전달해야 하며, JSON-RPC 본문 내부가 아닙니다. 다음 헤더 중 하나가 작동합니다:

Authorization: Bearer <api-token>
X-API-Token: <api-token>

토큰은 Compeller User별로 발급됩니다(/api/v1/*에서 사용하는 것과 동일한 토큰). 에이전트는 다음 두 가지 방법 중 하나로 획득할 수 있습니다:

사용자에게 로그인을 요청하고, 계정 → API 액세스를 열어 토큰을 공개한 후 에이전트의 비밀 저장소에 붙여넣도록 합니다.
기존 로그인 엔드포인트를 사용하고 베어러 토큰으로 access_token을 전송합니다. 쿠키 헤더는 필요하지 않으며 예상되지 않습니다:

curl -s -X POST https://compeller.ai/api/login \
  -H 'Content-Type: application/json' \
  -d '{"username":"[email protected]","password":"..."}'

일반 사용자는 username과 access_token을 받습니다. roles는 기준 ROLE_COMPELLER을 초과하는 역할을 가진 계정에만 나타나며, refresh_token과 expires_in는 비어 있지 않을 때만 나타납니다.

또는 v1 인증 도우미를 통해 자격 증명을 교환하면 영구 API 토큰이 반환됩니다:

curl -s -X POST https://compeller.ai/api/v1/auth/token \
  -H 'Content-Type: application/json' \
  -d '{"email":"[email protected]","password":"..."}'

토큰이 없거나 유효하지 않은 경우, JSON-RPC 오류가 아닌 도구 오류(isError: true)로 표시되며 메시지는 "API token required." / "Invalid API token."이므로, MCP 클라이언트가 사용자에게 자격 증명을 요청할 수 있습니다.

JSON-RPC 메서드

메서드	목적	HTTP 결과
`initialize`	기능 핸드셰이크. `protocolVersion`, `serverInfo`, `capabilities`을 반환합니다.	200 JSON-RPC 결과
`notifications/initialized`	클라이언트 확인. 응답 본문 없음.	204
`tools/list`	스키마 + 설명과 함께 모든 도구 나열.	200 JSON-RPC 결과
`tools/call`	도구 호출. `params = {name, arguments}`.	200 JSON-RPC 결과 (도구 오류는 `{isError: true, content: [...]}`로 반환됨)
`ping`	No-op 연결 유지.	200 JSON-RPC `result: {}`

알 수 없는 메서드는 JSON-RPC 오류 -32601 Method not found을 반환합니다. 알 수 없는 도구 이름은 -32602 Unknown tool을 반환합니다. 잘못된 JSON 본문은 -32700 Parse error을 반환합니다. jsonrpc이 없거나 잘못되었거나 method이 없으면 -32600 Invalid Request을 반환합니다.

도구

모든 도구는 type: text의 단일 content 항목을 반환하며, 해당 text 필드는 JSON 형식의 구조화된 출력입니다. 실패 시 동일한 응답 형태가 isError: true과 함께 반환되며, 사람이 읽을 수 있는 오류 메시지가 content[0].text에 포함됩니다 — JSON-RPC error로는 절대 반환되지 않습니다.

검색 (인증 불필요)

도구	입력	반환값
`get_capabilities`	—	`productName`, `version`, `capabilities[]`, `spec_url`, `enums` (`styles`, `target_platforms`, `aspect_ratios`), `auth`, `media_limits`, `rate_limits`
`get_pricing`	—	`plans[]` (`id`, `name`, `monthlyUsd`, `features[]` 포함)
`list_styles`	—	`styles[]` (`id`, `name` 포함) (`id`은 `create_compel` / `create_compel_from_music`이 `style`에 대해 허용하는 정확한 값입니다)

미디어 및 음악 (별도 명시 없으면 인증 필요)

도구	필수	선택	반환값
`search_music`	`query`	`limit`	`create_compel_from_music`에 적합한 공개 음악 검색 결과. 인증 불필요.
`upload_media`	—	`name`, `mime_type`, `type`	`POST /api/v1/media`을 가리키는 업로드 지침
`search_media`	—	`type` (`audio`/`image`/`video`/`text`), `limit` (≤100, 기본값 20), `offset`	`media[]`, `paging`

컴펠 (인증 필요)

도구	필수	선택	반환값
`create_compel_from_music`	`track_id`	`title`, `style`, `target_platform`, `aspect_ratio`, `artist_context`	`compel_id`, `status`, `next_action`
`create_compel`	`title`, `primary_media_id`	`style`, `target_platform`, `aspect_ratio`, `artist_context`	`compel_id`, `status: QUEUED`
`get_compel`	`compel_id`	—	`compel_id`, `title`, `status`, `progress_percent`, `stage`, `rendering_id`, `created_at`, `human_url`, `next_action`
`start_render`	`compel_id`	—	컴펠이 준비되면 최종 렌더링을 시작합니다. 상태와 다음 작업을 반환합니다.
`cancel_compel`	`compel_id`	—	진행 중인 컴펠을 취소합니다(멱등성 — 이미 취소됨도 성공). `compel_id`, `status: CANCELLED`, `stage`을 반환합니다.
`list_compels`	—	`limit` (≤100), `offset`	`compels[]`, `paging`
`search_compels`	`query`	`limit`	`compels[]`, `count`

style, target_platform, aspect_ratio은 도구 스키마의 enum에 의해 제한됩니다(get_capabilities.enums 참조). style 값은 list_styles에서 직접 가져옵니다.

계정 (인증 필요)

도구	입력	반환값
`get_account_credits`	—	`plan`, `minutes_remaining`, `free_minutes_remaining`, `paid_minutes_remaining`, `minutes_total`, `quota_exceeded`, `api_eligible`, `billing_url` — 비용 인식 결정을 위해 비용이 많이 드는 렌더링 전에 호출하십시오.

렌더링 (인증 필요)

도구	필수	반환값
`list_renderings`	`compel_id`	`compel_id`, `renderings[]` (`rendering_id`, `status`, `download_url` 포함)
`get_rendering`	`rendering_id`	`rendering_id`, `compel_id`, `status`, `download_url`

download_url은 GET /api/v1/renderings/{id}/download을 가리킵니다(HTTP Range 지원). 완료된 컴펠/렌더링 응답에는 무료 REACT 다운로드(https://compeller.ai/download/desktop)와 자세히 알아보기 URL(https://compeller.ai/react)이 포함된 react 핸드오프도 포함되어, 에이전트가 사용자에게 컴펠을 라이브 퍼포먼스 시스템으로 경험하는 방법을 알려줄 수 있습니다.

웹훅 (인증 필요)

Compeller와 통합하는 에이전트는 get_compel을 폴링하는 대신 컴펠 수명 주기 이벤트에 대한 서명된 푸시 알림을 자체 등록할 수 있습니다. compel.ready을 구독하면 폴링 없이 컴펠이 렌더링 가능한 순간을 알 수 있습니다(그런 다음 start_render 호출). compel.completed / compel.failed는 종료 이벤트입니다.

도구	필수	선택	반환값
`register_webhook`	`url` (HTTPS, ≤2048자)	`events[]` — 기본값은 `[""]`입니다. 알려진 값: ``, `compel.ready`, `compel.completed`, `compel.failed`	`webhook_id`, `url`, `events`, `secret` (정확히 한 번 반환됨), `active`, `created_at`
`list_webhooks`	—	—	`webhooks[]` — `webhook_id`, `url`, `events`, `active`, `created_at`, `updated_at`. 비밀은 이 도구에서 절대 반환되지 않습니다.
`update_webhook`	`webhook_id`	`url`, `events[]`, `active` — 최소 하나	`webhook_id`, `url`, `events`, `active`, `created_at`, `updated_at`. 비밀은 절대 반환되지 않습니다. 이를 위해 `rotate_webhook_secret`을 사용하십시오.
`delete_webhook`	`webhook_id`	—	`webhook_id`, `deleted: true`
`test_webhook_delivery`	`webhook_id`	—	`webhook_id`, `event_id`, `event_type: "webhook.test"`, `delivered`, `response_status?`, `response_body_preview?`, `latency_ms`, `error?`. 동기식 — 도구는 통합자의 엔드포인트가 응답할 때까지 대기합니다(최대 5초). 비밀은 절대 반환되지 않습니다.
`rotate_webhook_secret`	`webhook_id`	—	`webhook_id`, `url`, `events`, `active`, `secret` (신규 — 정확히 한 번 반환됨), `created_at`, `updated_at`. 이전 비밀은 즉시 무효화됩니다.

알 수 없는 이벤트 이름은 자동으로 와일드카드 *로 축소됩니다. 이는 POST /api/v1/webhooks을 반영하므로 에이전트가 no-op 구독을 생성하지 않습니다.

전달은 최소 한 번입니다. 각 이벤트는 즉시 시도되며, 엔드포인트에 연결할 수 없거나 2xx가 아닌 응답을 반환하면 백오프와 함께 재시도됩니다 — 총 최대 6회 시도(즉시, 그 후 1분, 5분, 30분, 2시간, 6시간 후). 모든 시도는 동일한 X-Compeller-Event-Id와 바이트 단위로 동일한 서명된 본문을 전달하므로 해당 ID로 중복 제거하십시오. 모든 시도가 소진되면 이벤트는 삭제됩니다. get_compel을 통해 조정하십시오.

register_webhook은 내부 인프라를 가리키는 대상을 도구 오류와 함께 거부합니다: 루프백, RFC1918 사설 범위, 링크-로컬(169.254.169.254와 같은 클라우드 메타데이터 IP 포함), IPv6 ULA, CGNAT, 멀티캐스트, 미지정 주소, 그리고 .local / .internal / .localhost로 끝나는 호스트 이름. 등록 후 DNS가 확인될 때 모든 시도에서 동일한 검사가 전달 시점에 다시 실행되므로, 등록 후 차단된 IP로 리바인딩하는 호스트 이름은 해당 시도에서 건너뜁니다(기록됨). 차단된 상태가 유지되면 단순히 재시도 예산을 소비한 후 삭제됩니다.

test_webhook_delivery은 HMAC-SHA256 서명이 포함된 합성 webhook.test 이벤트를 전송하고 엔드포인트의 응답을 동기적으로 기다립니다. 엔드포인트가 구독한 events을 무시하고(항상 전달됨) 실제 전달과 동일한 URL 안전 검사를 적용합니다. 2xx가 아닌 응답은 delivered: false로 표시되지만 MCP 호출 자체는 여전히 성공적으로 반환됩니다 — 결과는 페이로드입니다.

update_webhook은 url, events, active 중 하나를 허용합니다(최소 하나). URL 유효성 검사는 register_webhook를 반영합니다. 비밀은 이 도구에서 절대 반환되지 않습니다.

rotate_webhook_secret는 새로운 64자 16진수 서명 비밀을 생성하고, 정확히 한 번 반환하며, 이전 비밀을 즉시 무효화합니다. 다음 실제 전달 전에 수신 즉시 새 비밀을 저장하십시오.

모든 전달은 REST 경로와 정확히 동일하게 서명됩니다 — 전체 봉투 및 헤더 계약은 openapi.yaml의 Webhooks 섹션을 참조하십시오.

예제 세션

# 1. Handshake
curl -s https://compeller.ai/api/mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"my-agent","version":"1.0"}}}'

# 2. List tools
curl -s https://compeller.ai/api/mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'

# 3. Register a webhook (auth required)
curl -s https://compeller.ai/api/mcp \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <api-token>' \
  -d '{
        "jsonrpc":"2.0",
        "id":3,
        "method":"tools/call",
        "params":{
          "name":"register_webhook",
          "arguments":{
            "url":"https://hooks.my-agent.io/compeller",
            "events":["compel.completed","compel.failed"]
          }
        }
      }'

3단계에 대한 응답은 content[0].text를 포함하는 JSON-RPC result입니다 — 그 자체로 webhook_id, secret 등이 포함된 JSON 문서입니다. secret를 즉시 저장하십시오. 서버는 이를 다시 반환하지 않습니다.

오류 코드

코드	의미	원인
`-32700`	구문 분석 오류	본문이 유효한 JSON이 아님
`-32600`	잘못된 요청	`jsonrpc` 누락/잘못됨, `method` 누락, 빈 본문
`-32601`	메서드를 찾을 수 없음	알 수 없는 JSON-RPC 메서드
`-32602`	잘못된 매개변수	알 수 없는 도구, 도구 `name` 누락, 잘못된 `params` 형태
`-32603`	내부 오류	처리되지 않은 예외 (서버 측에 기록됨)

도구 수준 실패(유효성 검사, 인증, 찾을 수 없음)는 성공적인 JSON-RPC 응답 내에서 {result: {isError: true, content: [{type: "text", text: "..."}]}}로 반환됩니다. 이는 MCP 규칙에 따른 것으로, LLM이 실패를 그대로 보고 표시할 수 있도록 합니다.에이전트 오디오 결정 트리: 사용자가 MP3/WAV/FLAC을 제공하면 upload_media 다음에 create_compel를 사용하고, 사용자가 노래/아티스트 문자열만 제공하면 search_music 다음에 create_compel_from_music를 사용하며, 생성된 테스트 오디오를 명시적으로 요청하지 않는 한 톤을 합성하지 마십시오.