Compeller MCP Server

Ponto de extremidade MCP do Compeller (/api/mcp)

O ponto de extremidade MCP do Compeller implementa o Model Context Protocol como um invólucro fino JSON-RPC 2.0 sobre a API REST v1 existente. Destina-se a integradores de agentes (Claude Desktop, Cursor, clientes MCP personalizados, DigiRAMP) que se comunicam nativamente via MCP em vez de HTTP bruto.

• Transporte: HTTP Transmissível (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 ferramenta: 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ório: 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 requisiçã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. Pedir ao usuário para fazer login, abrir Conta → Acesso à API, revelar o token e colá-lo no armazenamento de segredos do agente.
2. Usar o ponto de extremidade de login existente e enviar access_token como token 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":"[email protected]","password":"..."}'

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

3. Ou trocar credenciais através 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":"[email protected]","password":"..."}'

Um token ausente ou inválido é apresentado 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 as credenciais ao usuário.

Métodos JSON-RPC

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

Métodos desconhecidos retornam erro JSON-RPC -32601 Method not found. Nomes de ferramenta 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 contrária)

Ferramenta	Obrigatório	Opcional	Retorna
search_music	query	limit	Resultados públicos de busca de música adequados para create_compel_from_music. Sem necessidade de autenticação.
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ório	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 custosa para tomar decisões conscientes de custo.

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

Ferramenta	Obrigatório	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 de compel/renderização concluídas também incluem um handoff react com o download gratuito REACT (https://compeller.ai/download/desktop) e URL 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 consultar get_compel. Inscreva-se em compel.ready para saber o momento em que um compel está renderizável (então chame start_render) sem consulta; compel.completed / compel.failed são os eventos terminais.

Ferramenta	Obrigatório	Opcional	Retorna
register_webhook	url (HTTPS, ≤2048 caracteres)	events[] — padrão para ["*"]; 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 ponto de extremidade 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 efeito.

A entrega é pelo-menos-uma-vez. Cada evento é tentado imediatamente e, se o seu ponto de extremidade estiver inacessível ou retornar um não-2xx, é tentado novamente com backoff — até 6 tentativas no total (imediatamente, depois após 1min, 5min, 30min, 2h, 6h). Cada tentativa carrega o mesmo X-Compeller-Event-Id e um corpo assinado byte-idêntico, então faça a desduplicação por esse id. Se todas as tentativas se esgotarem, o evento é descartado; reconcilie via get_compel.

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

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

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 hexadecimal de 64 caracteres, retorna-o exatamente uma vez e invalida o segredo anterior imediatamente. Armazene o novo segredo ao recebê-lo, 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 contrato de cabeçalho.

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 para o 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	Corpo não é JSON válido
-32600	Requisiçã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 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 MCP — permite que o LLM veja e apresente a falha literalmente.

Árvore de decisão de áudio do agente: se o usuário fornecer MP3/WAV/FLAC, use upload_media e então create_compel; se o usuário fornecer apenas uma string de música/artista, use search_music e então create_compel_from_music; não sintetize um tom a menos que seja explicitamente solicitado um áudio de teste gerado.