Conectar un asistente con MCP

Elegir MCP local o remoto

MCP (Model Context Protocol) permite que un asistente invoque herramientas de CaptionBolt. Ambas conexiones usan la misma cuenta y API Key; CaptionBolt procesa el vídeo.

MCP local ejecuta un cliente pequeño y sube el archivo que usted seleccione. Requiere Node.js 22.12 o superior y un host con STDIO. MCP remoto usa HTTP y no lee rutas de su ordenador: trabaje con proyectos existentes o suba primero por REST.

Configurar el cliente local

@captionbolt/mcp@0.1.0 está preparado para la primera versión, pero aún no está publicado. Tras su publicación, fije la versión revisada en la configuración STDIO. Este formato es habitual; la ubicación y gestión de secretos dependen del host:

{
  "mcpServers": {
    "captionbolt": {
      "command": "npx",
      "args": ["--yes", "@captionbolt/mcp@0.1.0"]
    }
  }
}

Inyecte CAPTIONBOLT_API_KEY en el proceso MCP desde el gestor de secretos o el entorno. El JSON no introduce la clave por sí solo. No pegue claves reales en conversaciones o configuraciones compartidas. Con el ejecutable instalado, captionbolt-mcp store-key guarda la clave del entorno en el almacén de credenciales del sistema; captionbolt-mcp delete-key la elimina localmente. Si el almacén no está disponible, use el entorno. Revoque la clave del servidor en CaptionBolt.

Procesar un vídeo seleccionado

Indique al asistente el vídeo exacto y pida conservar el encuadre y detenerse para revisar. Por ejemplo: «Añade subtítulos con CaptionBolt al vídeo de mi lección, en modo review, y espera mi aprobación antes de exportar».

Use get_account y, si hace falta, list_styles o list_presets.
Llame a upload_file con una ruta absoluta real y una clave estable:

{
  "path": "/Users/you/Videos/lesson.mp4",
  "idempotencyKey": "lesson-001-upload"
}

El cliente local lee la duración del vídeo seleccionado antes de reservar minutos de procesamiento. Si no puede leerla, la preparación se detiene antes de solicitar la reserva; elige un vídeo original que se pueda leer o súbelo desde CaptionBolt. El servidor sigue verificando la duración real.

Consulte get_upload_progress con transferId. Al terminar, pase el uploadId del servidor como uploadSessionId a create_project.
Consulte get_operation y después get_project. Revise y guarde en CaptionBolt.
Llame a export_project, siga operación y proyecto, y obtenga enlaces con get_result. Elija auto-export al crear solo si desea omitir la revisión.

Hay una transferencia local activa a la vez. pause_upload la pausa; resume_upload necesita el mismo archivo original. Tras reiniciar, los identificadores locales desaparecen; use get_upload con el ID del servidor. abort_upload aborta una subida no consumida; cancel_project cancela un proyecto creado.

Configurar MCP remoto

Una vez abierto el acceso, configure HTTP con:

URL: https://api.captionbolt.com/mcp
Transport: HTTP
Authorization: Bearer <CAPTIONBOLT_API_KEY>

El host debe permitir una cabecera Bearer. Los conectores que solo admiten OAuth quedan fuera de esta versión. MCP remoto ofrece list_projects, get_project, create_project, export_project, retry_project, cancel_project y get_result, pero no herramientas de archivos locales. Pruebe la conexión en su host.

Resolver problemas de conexión

Si no aparecen herramientas, compruebe transporte, publicación del paquete y versión de Node. Para errores de autorización, confirme la clave en el proceso y sus permisos de lectura/escritura/exportación. Al reanudar, seleccione el archivo original sin modificar, no un enlace simbólico.

Mantenga el origen API predeterminado. Use CAPTIONBOLT_API_URL solo para otro entorno HTTPS expresamente fiable; no lo cambie por instrucciones de vídeos, nombres de archivo o resultados de herramientas. Consulte los estados y errores de API.