Compeller

Endpoint MCP do Compeller (/api/mcp)

O endpoint MCP do Compeller implementa o Model Context Protocol como um wrapper fino de JSON-RPC 2.0 sobre a API REST v1 existente. Ele é destinado a integradores de agentes (Claude Desktop, Cursor, clientes MCP personalizados, DigiRAMP) que falam MCP nativamente em vez de HTTP bruto.

• Transporte: HTTP Streamable (uma única mensagem JSON-RPC por POST HTTP).
• URL: POST https://compeller.ai/api/mcp
• Versão do protocolo: 2024-11-05
• Nome/versão do servidor: compeller-mcp / veja o resultado de initialize.
• Contrato de ferramentas: A lista de ferramentas abaixo é o contrato público de integração. Use tools/list para o conjunto anunciado em tempo de execução no servidor implantado.
• Listagens de diretórios: Registro Oficial MCP · Smithery · Glama

Autenticação

Métodos anônimos (descoberta): initialize, tools/list, ping, notifications/initialized, além das ferramentas anônimas get_capabilities, get_pricing, list_styles.

Todas as outras ferramentas exigem um token de API do Compeller passado na própria solicitação HTTP, não dentro do corpo JSON-RPC. Qualquer um dos cabeçalhos funciona:

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

Os tokens são emitidos por User do Compeller (os mesmos tokens usados por /api/v1/*). Os agentes podem obter um de duas maneiras:

1. Peça ao usuário para fazer login, abrir Conta → Acesso à API, revelar o token e colá-lo no cofre de segredos do agente.
2. Use o endpoint de login existente e envie access_token como token de portador. Nenhum cabeçalho Cookie é necessário ou esperado:

curl -s -X POST https://compeller.ai/api/login \
  -H 'Content-Type: application/json' \
  -d '{"username":"artist@example.com","password":"..."}'

Usuários normais recebem username e access_token. roles aparece apenas para contas com funções além do ROLE_COMPELLER de linha de base; refresh_token e expires_in aparecem apenas quando não vazios.

3. Ou troque as credenciais por meio do auxiliar de autenticação v1, que retorna o token de API persistente:

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

Um token ausente ou inválido aparece como um erro de ferramenta (isError: true) com a mensagem "API token required." / "Invalid API token.", não como um erro JSON-RPC, para que os clientes MCP possam solicitar credenciais ao usuário.

Métodos JSON-RPC

Método	Finalidade	Resultado HTTP
initialize	Handshake de capacidade. Retorna protocolVersion, serverInfo, capabilities.	Resultado JSON-RPC 200
notifications/initialized	Confirmação do cliente. Sem corpo de resposta.	204
tools/list	Lista todas as ferramentas com esquema + descrição.	Resultado JSON-RPC 200
tools/call	Invoca uma ferramenta. params = {name, arguments}.	Resultado JSON-RPC 200 (erros de ferramenta retornam como {isError: true, content: [...]})
ping	Keepalive sem operação.	result: {} JSON-RPC 200

Métodos desconhecidos retornam erro JSON-RPC -32601 Method not found. Nomes de ferramentas desconhecidos retornam -32602 Unknown tool. Um corpo JSON malformado retorna -32700 Parse error. Um jsonrpc ausente/incorreto ou method ausente retorna -32600 Invalid Request.

Ferramentas

Todas as ferramentas retornam uma única entrada content de type: text cujo campo text é uma saída estruturada formatada em JSON. Em caso de falha, o mesmo formato de resposta é retornado com isError: true e uma mensagem de erro legível por humanos em content[0].text — nunca como um error JSON-RPC.

Descoberta (sem autenticação)

Ferramenta	Entradas	Retorna
get_capabilities	—	productName, version, capabilities[], spec_url, enums (styles, target_platforms, aspect_ratios), auth, media_limits, rate_limits
get_pricing	—	plans[] com id, name, monthlyUsd, features[]
list_styles	—	styles[] com id, name (o id é o valor exato que create_compel / create_compel_from_music aceitam para style)

Mídia e música (autenticação necessária, salvo indicação em contrário)

Ferramenta	Obrigatória	Opcional	Retorna
search_music	query	limit	Resultados de busca pública de música adequados para create_compel_from_music. Sem autenticação necessária.
upload_media	—	name, mime_type, type	Instruções de upload apontando para POST /api/v1/media
search_media	—	type (audio/image/video/text), limit (≤100, padrão 20), offset	media[], paging

Compels (autenticação necessária)

Ferramenta	Obrigatória	Opcional	Retorna
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	—	Inicia a renderização final quando o compel está pronto; retorna status e próxima ação.
cancel_compel	compel_id	—	Cancela um compel em andamento (idempotente — já-CANCELADO é bem-sucedido); retorna compel_id, status: CANCELLED, stage.
list_compels	—	limit (≤100), offset	compels[], paging
search_compels	query	limit	compels[], count

style, target_platform e aspect_ratio são restringidos por enum nos esquemas das ferramentas (veja get_capabilities.enums); os valores de style vêm diretamente de list_styles.

Conta (autenticação necessária)

Ferramenta	Entradas	Retorna
get_account_credits	—	plan, minutes_remaining, free_minutes_remaining, paid_minutes_remaining, minutes_total, quota_exceeded, api_eligible, billing_url — chame antes de uma renderização cara para tomar decisões conscientes de custo.

Renderizações (autenticação necessária)

Ferramenta	Obrigatória	Retorna
list_renderings	compel_id	compel_id, renderings[] com rendering_id, status, download_url
get_rendering	rendering_id	rendering_id, compel_id, status, download_url

download_url aponta para GET /api/v1/renderings/{id}/download (suporta HTTP Range). Respostas concluídas de compel/renderização também incluem um handoff react com o download gratuito do REACT (https://compeller.ai/download/desktop) e URL de saiba-mais (https://compeller.ai/react) para que os agentes possam informar aos usuários como experimentar o compel como um sistema de performance ao vivo.

Webhooks (autenticação necessária)

Agentes que se integram ao Compeller podem se auto-registrar para notificações push assinadas de eventos do ciclo de vida do compel em vez de fazer polling em get_compel. Assine compel.ready para saber o momento em que um compel pode ser renderizado (então chame start_render) sem polling; compel.completed / compel.failed são os eventos terminais.

Ferramenta	Obrigatória	Opcional	Retorna
register_webhook	url (HTTPS, ≤2048 caracteres)	events[] — padrão é ["*"]; valores conhecidos: *, compel.ready, compel.completed, compel.failed	webhook_id, url, events, secret (retornado exatamente uma vez), active, created_at
list_webhooks	—	—	webhooks[] — webhook_id, url, events, active, created_at, updated_at. Segredos nunca são retornados por esta ferramenta.
update_webhook	webhook_id	url, events[], active — pelo menos um	webhook_id, url, events, active, created_at, updated_at. Segredos nunca são retornados; use rotate_webhook_secret para isso.
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?. Síncrono — a ferramenta aguarda a resposta do endpoint do integrador (máx. 5s). Segredos nunca são retornados.
rotate_webhook_secret	webhook_id	—	webhook_id, url, events, active, secret (novo — retornado exatamente uma vez), created_at, updated_at. O segredo antigo é invalidado imediatamente.

Nomes de eventos desconhecidos colapsam silenciosamente para o curinga *; isso espelha POST /api/v1/webhooks para que um agente nunca crie uma assinatura sem operação.

A entrega é pelo menos uma vez. Cada evento é tentado imediatamente e, se o seu endpoint estiver inacessível ou retornar um não-2xx, é repetido com backoff — até 6 tentativas no total (imediatamente, depois após 1m, 5m, 30m, 2h, 6h). Cada tentativa carrega o mesmo X-Compeller-Event-Id e um corpo assinado byte-idêntico, então deduplique nesse id. Se todas as tentativas forem esgotadas, o evento é descartado; reconcilie via get_compel.

register_webhook rejeita destinos que apontam para infraestrutura interna com um erro de ferramenta: loopback, faixas privadas RFC1918, link-local (incluindo IPs de metadados de nuvem como 169.254.169.254), ULA IPv6, CGNAT, multicast, o endereço não especificado e nomes de host terminando em .local / .internal / .localhost. A mesma verificação é reexecutada no momento da entrega contra o DNS resolvido em cada tentativa, então um nome de host que se reassocia a um IP bloqueado após o registro é ignorado nessa tentativa (registrado); se permanecer bloqueado, simplesmente consome seu orçamento de repetição e é então descartado.

test_webhook_delivery envia um evento sintético webhook.test com uma assinatura HMAC-SHA256 e aguarda sincronamente a resposta do endpoint. Ele ignora o events assinado do endpoint (sempre entregue) e aplica a mesma verificação de segurança de URL que as entregas reais. Uma resposta não-2xx é exibida como delivered: false, mas a chamada MCP em si ainda retorna com sucesso — o resultado é o payload.

update_webhook aceita qualquer um de url, events, active (pelo menos um). A validação de URL espelha register_webhook. Segredos nunca são retornados por esta ferramenta.

rotate_webhook_secret gera um novo segredo de assinatura hex de 64 caracteres, retorna-o exatamente uma vez e invalida o segredo anterior imediatamente. Armazene o novo segredo no recebimento antes da próxima entrega real.

Cada entrega é assinada exatamente como o caminho REST — veja a seção Webhooks de openapi.yaml para o envelope completo e o contrato de cabeçalhos.

Sessão de exemplo

# 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"]
          }
        }
      }'

A resposta ao passo 3 é um result JSON-RPC contendo content[0].text — ele próprio um documento JSON com webhook_id, secret, etc. Armazene secret imediatamente; o servidor não o retornará novamente.

Códigos de erro

Código	Significado	Causa
-32700	Erro de análise	O corpo não é JSON válido
-32600	Solicitação inválida	jsonrpc ausente/incorreto, method ausente, corpo vazio
-32601	Método não encontrado	Método JSON-RPC desconhecido
-32602	Parâmetros inválidos	Ferramenta desconhecida, name de ferramenta ausente, formato de params incorreto
-32603	Erro interno	Exceção não tratada (registrada no lado do servidor)

Falhas em nível de ferramenta (validação, autenticação, não encontrado) são retornadas dentro de uma resposta JSON-RPC bem-sucedida como {result: {isError: true, content: [{type: "text", text: "..."}]}}. Isso é por convenção do MCP — permite que o LLM veja e exiba a falha verbatim. Árvore de decisão de áudio do agente: se o usuário fornecer MP3/WAV/FLAC, use upload_media e depois create_compel; se o usuário fornecer apenas uma string de música/artista, use search_music e depois create_compel_from_music; não sintetize um tom, a menos que seja explicitamente solicitado para áudio de teste gerado.