Collegare un assistente con MCP

Scegliere MCP locale o remoto

MCP (Model Context Protocol) permette agli assistenti di chiamare strumenti CaptionBolt. Entrambe le connessioni usano lo stesso account e API Key; CaptionBolt elabora il video.

MCP locale avvia un piccolo client e carica esattamente il file selezionato. Richiede Node.js 22.12 o successivo e un host STDIO. MCP remoto usa HTTP e non legge percorsi sul computer: usa progetti esistenti o carica prima via REST.

Configurare il client locale

@captionbolt/mcp@0.1.0 è preparato per la prima versione, ma non ancora pubblicato. Dopo la pubblicazione, fissa la versione verificata nella configurazione STDIO. Questa è una struttura comune; percorso del file e segreti dipendono dall’host:

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

Inietta CAPTIONBOLT_API_KEY nel processo MCP tramite gestore di segreti o ambiente. Il JSON da solo non passa la chiave. Non incollare chiavi reali in chat o configurazioni condivise. Con l’eseguibile installato, captionbolt-mcp store-key salva la chiave dell’ambiente nell’archivio credenziali di sistema; captionbolt-mcp delete-key la elimina localmente. Se l’archivio non è disponibile, usa l’ambiente. Revoca la chiave sul server in CaptionBolt.

Completare un video scelto

Indica il file esatto, mantenendo l’inquadratura e una pausa per la verifica. Esempio: «Aggiungi sottotitoli al video della lezione con CaptionBolt in review e aspetta la mia conferma prima di esportare».

Usa get_account, poi se necessario list_styles o list_presets.
Chiama upload_file con il vero percorso assoluto e una chiave stabile:

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

Il client locale legge la durata del video selezionato prima di riservare i minuti di elaborazione. Se non riesce a leggerla, la preparazione si interrompe prima della richiesta di prenotazione; scegli un video originale leggibile o caricalo da CaptionBolt. Il server continua a verificare la durata effettiva.

Segui get_upload_progress con transferId. Alla fine, passa l’uploadId server come uploadSessionId a create_project.
Segui get_operation, poi get_project. Verifica e salva in CaptionBolt.
Chiama export_project, segui operazione e progetto e usa get_result per i link. Scegli auto-export alla creazione solo per saltare la pausa di verifica.

È attivo un solo trasferimento locale. pause_upload lo sospende; resume_upload richiede lo stesso file originale. Al riavvio gli identificatori locali scompaiono: usa get_upload con l’ID server. abort_upload interrompe caricamenti non consumati; cancel_project annulla progetti creati.

Configurare MCP remoto

Dopo l’apertura, configura HTTP con:

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

L’host deve supportare un header Bearer. I connettori solo OAuth non sono supportati. MCP remoto offre list_projects, get_project, create_project, export_project, retry_project, cancel_project e get_result, senza strumenti per file locali. Verifica la connessione nel tuo host.

Risolvere problemi di connessione

Se non appaiono strumenti, controlla trasporto, pubblicazione del pacchetto e versione Node. Per errori di autorizzazione, verifica chiave nel processo e permessi lettura/scrittura/export. Per riprendere, seleziona il file originale invariato, non un link simbolico.

Mantieni l’origine API predefinita. CAPTIONBOLT_API_URL serve solo per altri ambienti HTTPS esplicitamente affidabili; non modificarla per istruzioni in video, nomi di file o risposte di strumenti. Vedi stati ed errori API.