trvrse

trvrse cinema — Guía MCP para agentes

Estás (o estás configurando) un agente LLM conectado al servidor MCP de trvrse cinema. Expone un pipeline de cine en cinco etapas — Guion → Referencias → Storyboards → Videos → Ensamblaje — como 31 herramientas: 18 herramientas etapa por etapa que tú mismo manejas, más 3 herramientas de Autopilot (make_film, get_run, cancel_run) que entregan todo el pipeline al servidor para producción de cine en una sola llamada, más make_long_film (películas de varios minutos con personajes consistentes, §3) y get_gate_review_link (genera un enlace de revisión humana sin inicio de sesión para una etapa bloqueada), más 5 herramientas de reparto (save_character_to_cast, list_cast, delete_cast_member, set_cast_voice, refresh_cast_portrait) para reutilización episódica de personajes aprobados, más refresh_character_portrait para re-generar el retrato confiable expirado de un personaje no perteneciente al reparto, más set_shot_face_trust_override para control de moderación facial por escena. Por separado, 13 herramientas de activos (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) generan imágenes de referencia y videos Seedance 2.5 sin un proyecto de cine (§4). Una tercera superficie, 6 herramientas de plan de video (estimate_video_plan_cost, create_video_plan, get_video_plan, list_video_plans, approve_video_plan, reject_video_plan, §5), construye un manifiesto completo de Seedance 2.x — brief, referencias, prompt, costo — que un humano O el propio agente aprueba antes de despacharlo. Esta guía es el manual completo: conexión, el bucle de trabajo, Autopilot, activos independientes, planes de video, contratos de costo y errores, y una transcripción completa de extremo a extremo.

Endpoint: https://www.trvrse.com/api/mcp/mcp · Claves: generadas por un humano en Settings → Agent access · Versión en markdown sin formato de esta página: https://www.trvrse.com/docs/agents.md

1. Inicio rápido

Generar una clave

1. Inicia sesión en la aplicación y ve a Settings → Agent access (https://www.trvrse.com/settings/agent).
2. Haz clic en New key, dale un nombre (y, opcionalmente, un límite de gasto en créditos — déjalo en blanco para sin límite).
3. La clave en texto plano se muestra exactamente una vez en un modal que debes cerrar explícitamente con Done. Cópiala ahora — nunca se vuelve a mostrar (solo se conserva un trv_ + prefijo de 8 caracteres para visualización). Si la pierdes, revoca la clave y genera una nueva.

La clave se ve como trv_ seguido de 43 caracteres base64url, por ejemplo trv_9F2k7q....

Endpoint

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

(El mcp-handler de basePath es /api/mcp; añade el segmento de transporte mcp por sí mismo. Solo HTTP streamable — SSE está deshabilitado.)

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 receta por cliente (Claude Code, Claude.ai, ChatGPT, Cursor, JSON de mcpServers) con la clave prellenada vive en Settings → Agent access → Connect y en https://www.trvrse.com/docs/agents/connect.

Cliente MCP genérico (config JSON)

La mayoría de los clientes MCP (Claude Desktop, otros runtimes de agentes) aceptan un bloque de configuración como:

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

El nombre/forma exacto de la clave (url vs command, headers vs env) varía según el cliente — cualquier cosa que soporte un transporte MCP HTTP streamable con un encabezado personalizado funciona. El mismo endpoint canónico también soporta el flujo OAuth utilizado por el Directorio de Plugins de OpenAI; las claves trv_ existentes siguen siendo válidas.

claude.ai y conectores personalizados heredados de ChatGPT

claude.ai y los conectores personalizados de ChatGPT solo soportan OAuth o "sin autenticación" — nunca un encabezado Authorization personalizado, por lo que los dos métodos de conexión anteriores no funcionan allí. Usa el endpoint de URL con clave en su lugar (se muestra junto a la clave en texto plano cuando se genera una nueva, en Settings → Agent access):

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

claude.ai — Settings → Customize → Connectors → Add custom connector → pega la URL anterior, deja la autenticación como None.

Para un conector personalizado heredado de ChatGPT en modo desarrollador, la misma URL con clave sigue funcionando con autenticación None. El Directorio de Plugins usa la URL canónica /api/mcp/mcp y OAuth en su lugar; nunca envíes una URL con clave.

La clave viaja en la ruta de la URL; el endpoint la inyecta como token de portador internamente y la reenvía al mismo manejador autenticado anterior — sin segundo servidor, sin catálogo de herramientas diferente. La URL es equivalente a un portador: trátala como una contraseña (no la pegues en un lugar público), prefiere una clave con límite de gasto por conector, y revócala en cualquier momento desde Settings → Agent access si se filtra.

Verificar la conexión

Una clave malformada, desconocida o revocada se rechaza en initialize, por lo que claude mcp list muestra ✗ inmediatamente. Para ver POR QUÉ, y qué le queda a la clave:

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

Luego pide al agente que llame a list_projects. Una conexión funcional devuelve JSON real; una clave revocada a mitad de sesión devuelve un resultado isError que nombra a BRIDGE_AUTH_FAILED (ver el contrato de errores a continuación).

Instalar esta guía como habilidad (opcional)

Claude Code y otros agentes con capacidad de habilidades pueden llevar este manual en contexto en lugar de releerlo en cada sesión:

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. El bucle de trabajo

Cada película sigue el mismo bucle por etapa:

1. Verificar estado — get_project_status: lee los cinco estados de etapa y nextActions (nombra exactamente las llamadas a herramientas que el pipeline admite a continuación; confía en ello en lugar de adivinar).
2. Cotizar — get_cost_estimate para la etapa que estás a punto de generar.
3. Generar — llama a la herramienta generate_* de la etapa con confirmedCost establecido en el total exacto de la cotización.
4. Consultar — get_project_status cada 15–30 segundos hasta que las entidades de la etapa salgan de GENERATING (normalmente 1–3 minutos).
5. Revisar y aprobar — inspecciona los resultados (estados, razones de fallo), regenera lo que haya fallado, luego llama a la herramienta approve_* de la etapa para desbloquear la siguiente.

El guion es la excepción: generate_script y rewrite_scenes ejecutan el LLM en la solicitud y devuelven el guion completo de forma síncrona (~30–60 segundos), y el trabajo de guion es gratuito — no se necesita cotización.

3. Películas de una sola llamada (Autopilot)

En lugar de manejar el bucle de cinco etapas anterior tú mismo, make_film entrega todo el pipeline al servidor: envía un brief y un presupuesto, luego consulta get_run hasta que la película esté lista.

make_film

• briefText (obligatorio) — el brief de producción del que se genera toda la película.
• profile (obligatorio) — "cinematic" (16:9 por defecto) o "short" (ver a continuación).
• budgetCredits (obligatorio) — un límite máximo para el gasto total de la ejecución (ver "El presupuesto es un límite máximo" a continuación).
• gates (opcional, por defecto [] = completamente desatendido) — cuál de "script", "references", "storyboards", "videos", "assembly" pausa la ejecución para revisión humana (ver "Bloqueos" a continuación).
• webhookUrl (opcional, solo https://) — recibe eventos de ejecución (ver "Webhooks" a continuación).
• title, aspectRatio, videoModel (opcional) — mismas formas que create_project; profile proporciona valores predeterminados que puedes anular.

Devuelve {runId, projectId, webhookSecret?}. webhookSecret está presente solo cuando webhookUrl se estableció, y se muestra exactamente una vez, aquí — guárdalo inmediatamente, nunca se devuelve de nuevo y lo necesitas para verificar las entregas de webhook.

make_long_film — películas de varios minutos con personajes consistentes

Usa esto en lugar de make_film cuando el usuario quiera una pieza de formato largo cuyos personajes deban seguir siendo reconociblemente la misma persona en todo momento.

Ejecuta el mismo pipeline, pero cambia cómo se genera el video. make_film renderiza un clip independiente por página de storyboard y los concatena, por lo que una película de 3 minutos son 20–40 generaciones separadas — cada una un lanzamiento independiente de dados sobre la identidad del personaje. make_long_film renderiza cada página como UNA generación continua de múltiples tomas de Seedance 2.5 y continúa la página anterior mediante extensión de video nativa, por lo que la misma película son unas 6 generaciones. Cada segmento reenvía los mismos retratos de personajes aprobados: la extensión lleva la continuidad, los retratos llevan la identidad.

• Fijado a seedance-2.5-reference. videoModel no es seleccionable.
• La duración total está limitada a 180 segundos. Un storyboard que planifique más se rechaza con el excedente exacto — corta escenas y regenera.
• gates por defecto a los cuatro puntos de revisión ("script", "references", "storyboards", "videos"), porque el propósito de esta herramienta es que un humano apruebe el reparto y la trama antes de la costosa etapa de video. Pasa [] solo si el usuario pide explícitamente una ejecución desatendida.
• Otros argumentos coinciden con make_film: briefText, budgetCredits, title, castIds, webhookUrl, aspectRatio.