Compeller

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

Compeller MCP エンドポイントは、既存のv1 REST APIの上に薄いJSON-RPC 2.0ラッパーとしてModel Context Protocolを実装しています。これは、生のHTTPではなくMCPをネイティブに話すエージェント統合者（Claude Desktop、Cursor、カスタムMCPクライアント、DigiRAMP）を対象としています。

• トランスポート: Streamable 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":"artist@example.com","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":"artist@example.com","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	ノーオペレーションキープアライブ。	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

コンペル（認証が必要）

ツール	必須	オプション	戻り値
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	—	進行中のコンペルをキャンセルします（冪等 — すでにCANCELLEDの場合は成功）。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	rendering_id、status、download_url を含む compel_id、renderings[]
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 — 少なくとも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（新規 — 正確に一度だけ返されます）、created_at、updated_at。古いシークレットは即座に無効化されます。

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

配信はat-least-onceです。 各イベントは即座に試行され、エンドポイントに到達できないか非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進署名シークレットを発行し、正確に一度だけ返し、前のシークレットを即座に無効化します。次の実際の配信の前に、受信時に新しいシークレットを保存してください。

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