trvrse

trvrse cinema — guia MCP para agentes

Você está (ou está configurando) um agente LLM conectado ao servidor MCP trvrse cinema. Ele expõe um pipeline de filme em cinco estágios — Roteiro → Referências → Storyboards → Vídeos → Montagem — como 31 ferramentas: 18 ferramentas estágio por estágio que você mesmo conduz, mais 3 ferramentas Autopilot (make_film, get_run, cancel_run) que entregam todo o pipeline ao servidor para produção de filme em uma única chamada, mais make_long_film (filmes de vários minutos com personagens consistentes, §3) e get_gate_review_link (gerar um link de revisão humana sem login para um estágio bloqueado), mais 5 ferramentas de elenco (save_character_to_cast, list_cast, delete_cast_member, set_cast_voice, refresh_cast_portrait) para reutilização episódica de personagens aprovados, mais refresh_character_portrait para reemitir o retrato confiável expirado de um personagem fora do elenco, mais set_shot_face_trust_override para controle de moderação facial por cena. Separadamente, 13 ferramentas de ativos (estimate_generation_cost, generate_image, edit_image, generate_storyboard, promote_storyboard_panel, upload_image, list_images, generate_video, get_video_job, get_tool_call, list_videos, cancel_video_job, get_credit_balance) geram imagens de referência e vídeos Seedance 2.5 sem um projeto de cinema (§4). Uma terceira superfície, 6 ferramentas de plano de vídeo (estimate_video_plan_cost, create_video_plan, get_video_plan, list_video_plans, approve_video_plan, reject_video_plan, §5), constrói um manifesto completo Seedance 2.x — brief, referências, prompt, custo — que um humano OU o próprio agente aprova antes do envio. Este guia é o manual completo: conexão, o loop de trabalho, Autopilot, ativos independentes, planos de vídeo, contratos de custo e erro, e uma transcrição completa de ponta a ponta.

Endpoint: https://www.trvrse.com/api/mcp/mcp · Chaves: emitidas por um humano em Configurações → Acesso do agente · Versão markdown bruta desta página: https://www.trvrse.com/docs/agents.md

1. Início rápido

Emitir uma chave

1. Entre no aplicativo e vá para Configurações → Acesso do agente (https://www.trvrse.com/settings/agent).
2. Clique em Nova chave, dê um nome (e, opcionalmente, um limite de gastos em créditos — deixe em branco para sem limite).
3. A chave em texto puro é mostrada exatamente uma vez em um modal que você deve dispensar explicitamente com Concluído. Copie agora — ela nunca mais é mostrada (apenas um trv_ + prefixo de 8 caracteres é mantido para exibição). Se você a perder, revogue a chave e emita uma nova.

A chave parece trv_ seguido por 43 caracteres base64url, por exemplo, trv_9F2k7q....

Endpoint

https://www.trvrse.com/api/mcp/mcp

(O mcp-handler do basePath é /api/mcp; ele anexa o segmento de transporte mcp por conta própria. Apenas Streamable HTTP — SSE está desabilitado.)

Claude Code

claude mcp add --transport http --scope user trvrse https://www.trvrse.com/api/mcp/mcp \
  -H "Authorization: Bearer trv_YOUR_KEY_HERE"

Cada receita por cliente (Claude Code, Claude.ai, ChatGPT, Cursor, JSON mcpServers) com a chave pré-preenchida está em Configurações → Acesso do agente → Conectar e em https://www.trvrse.com/docs/agents/connect.

Cliente MCP genérico (config JSON)

A maioria dos clientes MCP (Claude Desktop, outros runtimes de agente) aceita um bloco de configuração como:

{
  "mcpServers": {
    "trvrse": {
      "url": "https://www.trvrse.com/api/mcp/mcp",
      "transport": "http",
      "headers": {
        "Authorization": "Bearer trv_YOUR_KEY_HERE"
      }
    }
  }
}

O nome/formato exato da chave (url vs command, headers vs env) varia por cliente — qualquer coisa que suporte um transporte MCP streamable-HTTP com um cabeçalho personalizado funciona. O mesmo endpoint canônico também suporta o fluxo OAuth usado pelo Diretório de Plugins da OpenAI; chaves trv_ existentes permanecem válidas.

claude.ai e conectores personalizados legados do ChatGPT

claude.ai e conectores personalizados do ChatGPT suportam apenas OAuth ou "sem autenticação" — nunca um cabeçalho Authorization personalizado, então os dois métodos de conexão acima não funcionam lá. Use o endpoint de URL com chave (mostrado junto com a chave em texto puro quando uma nova é emitida, em Configurações → Acesso do agente):

https://www.trvrse.com/api/mcp/k/trv_YOUR_KEY_HERE/mcp

claude.ai — Configurações → Personalizar → Conectores → Adicionar conector personalizado → cole a URL acima, deixe autenticação como Nenhuma.

Para um conector personalizado legado do ChatGPT em modo desenvolvedor, a mesma URL com chave continua funcionando com autenticação Nenhuma. O Diretório de Plugins usa a URL /api/mcp/mcp canônica e OAuth; nunca envie uma URL com chave.

A chave viaja no caminho da URL; o endpoint a injeta como token de portador internamente e encaminha para o mesmo manipulador autenticado acima — sem segundo servidor, sem catálogo de ferramentas diferente. A URL é equivalente a um portador: trate-a como uma senha (não a cole em algum lugar público), prefira uma chave com limite de gastos por conector e revogue-a a qualquer momento em Configurações → Acesso do agente se vazar.

Verificação de sanidade da conexão

Uma chave malformada, desconhecida ou revogada é recusada em initialize, então claude mcp list mostra ✗ imediatamente. Para ver POR QUE, e o que resta na chave:

curl -sS https://www.trvrse.com/api/mcp/health -H "Authorization: Bearer trv_YOUR_KEY_HERE"
# 200 {"ok":true,"keyName":"…","spendCap":500,"spent":0,"remaining":500,"lastSeen":null,"lastSeenClient":null}
# 401 {"ok":false,"reason":"malformed"|"unknown"|"revoked"}   429 rate-limited

Então peça ao agente para chamar list_projects. Uma conexão funcional retorna JSON real; uma chave revogada no meio da sessão retorna um resultado isError nomeando BRIDGE_AUTH_FAILED (veja o contrato de erro abaixo).

Instalar este guia como habilidade (opcional)

Claude Code e outros agentes com suporte a habilidades podem carregar este manual no contexto em vez de relê-lo a cada sessão:

SKILLS_DIR=~/.claude
mkdir -p "$SKILLS_DIR/skills/trvrse-cinema" && \
  curl -fsSL https://www.trvrse.com/docs/agents/skill.md \
  -o "$SKILLS_DIR/skills/trvrse-cinema/SKILL.md"

2. O loop de trabalho

Todo filme segue o mesmo loop por estágio:

1. Verificar estado — get_project_status: leia os cinco status de estágio e nextActions (ele nomeia exatamente as chamadas de ferramenta que o pipeline admite em seguida; confie nele em vez de adivinhar).
2. Cotar — get_cost_estimate para o estágio que você está prestes a gerar.
3. Gerar — chame a ferramenta generate_* do estágio com confirmedCost definido como o total exato da cotação.
4. Polling — get_project_status a cada 15–30 segundos até que as entidades do estágio saiam de GENERATING (normalmente 1–3 minutos).
5. Revisar e aprovar — inspecione os resultados (status, motivos de falha), regenere o que falhou, então chame a ferramenta approve_* do estágio para desbloquear o próximo estágio.

O roteiro é a exceção: generate_script e rewrite_scenes executam o LLM na própria requisição e retornam o roteiro completo de forma síncrona (~30–60 segundos), e o trabalho de roteiro é gratuito — sem necessidade de cotação.

3. Filmes em uma chamada (Autopilot)

Em vez de conduzir o loop de cinco estágios acima você mesmo, make_film entrega todo o pipeline ao servidor: envie um brief e um orçamento, então faça polling de get_run até o filme estar pronto.

make_film

• briefText (obrigatório) — o brief de produção a partir do qual todo o filme é gerado.
• profile (obrigatório) — "cinematic" (16:9 padrão) ou "short" (veja abaixo).
• budgetCredits (obrigatório) — um teto rígido para o gasto total da execução (veja "Orçamento é um teto rígido" abaixo).
• gates (opcional, padrão [] = totalmente sem supervisão) — quais de "script", "references", "storyboards", "videos", "assembly" pausam a execução para revisão humana (veja "Bloqueios" abaixo).
• webhookUrl (opcional, apenas https://) — recebe eventos de execução (veja "Webhooks" abaixo).
• title, aspectRatio, videoModel (opcionais) — mesmos formatos que create_project; profile fornece padrões que você pode substituir.

Retorna {runId, projectId, webhookSecret?}. webhookSecret está presente apenas quando webhookUrl foi definido, e é mostrado exatamente uma vez, aqui — salve imediatamente, nunca mais é retornado e você precisa dele para verificar entregas de webhook.

make_long_film — filmes de vários minutos com personagens consistentes

Use isto em vez de make_film quando o usuário quiser uma peça de formato longo cujos personagens devem permanecer reconhecivelmente a mesma pessoa durante todo o filme.

Ele executa o mesmo pipeline, mas muda como o vídeo é gerado. make_film renderiza um clipe independente por página de storyboard e os concatena, então um filme de 3 minutos são 20–40 gerações separadas — cada uma um lançamento independente de dados na identidade do personagem. make_long_film renderiza cada página como UMA geração contínua de múltiplas tomadas Seedance 2.5 e continua a página anterior através de extensão de vídeo nativa, então o mesmo filme tem cerca de 6 gerações. Cada segmento reenvia os mesmos retratos de personagem aprovados: a extensão carrega continuidade, os retratos carregam identidade.

• Fixado em seedance-2.5-reference. videoModel não é selecionável.
• O tempo total de execução é limitado a 180 segundos. Um storyboard que planeja mais é recusado com o excesso exato — corte cenas e regenere.
• gates tem como padrão todos os quatro pontos de revisão ("script", "references", "storyboards", "videos"), porque o objetivo desta ferramenta é que um humano aprove o elenco e o enredo antes da etapa cara de vídeo. Passe [] apenas se o usuário pedir explicitamente uma execução sem supervisão.
• Outros argumentos correspondem a make_film: briefText, budgetCredits, title, castIds, webhookUrl, aspectRatio.