Compeller MCP Server

Compeller MCPエンドポイント (/api/mcp)

Compeller MCPエンドポイントは、既存のv1 REST APIを薄くラップするJSON-RPC 2.0としてModel Context Protocolを実装しています。生の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。

その他のツールはすべて、JSON-RPCボディ内ではなく、HTTPリクエスト自体で渡されるCompeller APIトークンが必要です。以下のいずれかのヘッダーが機能します:

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

トークンはCompeller User ごとに発行されます（/api/v1/* で使用されるものと同じトークン）。エージェントは次の2つの方法のいずれかで取得できます:

1. ユーザーにログインしてもらい、アカウント → APIアクセス を開き、トークンを表示してエージェントのシークレットストアに貼り付けてもらいます。
2. 既存のログインエンドポイントを使用し、ベアラートークンとして access_token を送信します。Cookieヘッダーは不要であり、期待されていません:

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 は空でない場合にのみ表示されます。

3. または、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エラーとしてではなく、メッセージ "API token required." / "Invalid API token." を持つツールエラー（isError: true）として表面化されるため、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	ノーオペレーションキープアライブ。	200 JSON-RPC result: {}

不明なメソッドはJSON-RPCエラー -32601 Method not found を返します。不明なツール名は -32602 Unknown tool を返します。不正な形式のJSONボディは -32700 Parse error を返します。jsonrpc がない/間違っている、または method がない場合は -32600 Invalid Request を返します。

ツール

すべてのツールは、text フィールドがJSON形式の構造化出力である単一の type: text エントリの content を返します。失敗時には、同じレスポンス形状が 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	—	id、name、monthlyUsd、features[] を含む plans[]
list_styles	—	id、name を含む styles[]（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

Compels（認証が必要）

ツール	必須	オプション	戻り値
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	—	compelの準備ができたら最終レンダリングを開始し、ステータスと次のアクションを返します。
cancel_compel	compel_id	—	進行中のcompelをキャンセルします（冪等 — すでにCANCELLEDの場合は成功）。compel_id、status: CANCELLED、stage を返します。
list_compels	—	limit（≤100）、offset	compels[]、paging
search_compels	query	limit	compels[]、count

style、target_platform、aspect_ratio は、ツールスキーマ（get_capabilities.enums を参照）の enum によって制約されます。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、rendering_id、status、download_url を含む renderings[]
get_rendering	rendering_id	rendering_id、compel_id、status、download_url

download_url は GET /api/v1/renderings/{id}/download を指します（HTTP Rangeをサポート）。 完了したcompel/レンダリングレスポンスには、無料のREACTダウンロード（https://compeller.ai/download/desktop）と詳細URL（https://compeller.ai/react）を含む react ハンドオフも含まれるため、エージェントはユーザーにcompelをライブパフォーマンスシステムとして体験する方法を伝えることができます。

Webhook（認証が必要）

Compellerと統合するエージェントは、get_compel をポーリングする代わりに、compelライフサイクルイベントの署名付きプッシュ通知を自己登録できます。compel.ready をサブスクライブすると、compelがレンダリング可能になった瞬間をポーリングなしで知ることができ（その後 start_render を呼び出す）、compel.completed / compel.failed は終端イベントです。

ツール	必須	オプション	戻り値
register_webhook	url（HTTPS、≤2048文字）	events[] — デフォルトは ["*"]。既知の値: *、compel.ready、compel.completed、compel.failed	webhook_id、url、events、secret（正確に1回返される）、active、created_at
list_webhooks	—	—	webhooks[] — webhook_id、url、events、active、created_at、updated_at。シークレットはこのツールによって決して返されません。
update_webhook	webhook_id	url、events[]、active — 少なくとも1つ	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（新規 — 正確に1回返される）、created_at、updated_at。古いシークレットは即座に無効化されます。

不明なイベント名はワイルドカード * にサイレントに折りたたまれます。これは POST /api/v1/webhooks を反映しているため、エージェントがノーオペレーションサブスクリプションを作成することはありません。

配信は少なくとも1回です。 各イベントは即座に試行され、エンドポイントが到達不能であるか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 のいずれか（少なくとも1つ）を受け入れます。URL検証は register_webhook を反映します。シークレットはこのツールによって返されることはありません。

rotate_webhook_secret は新しい64文字の16進署名シークレットを生成し、正確に1回返し、以前のシークレットを即座に無効化します。次の実際の配信前に、受信時に新しいシークレットを保存してください。

すべての配信は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 を使用します。生成されたテスト音声を明示的に要求されない限り、トーンを合成しないでください。