通过 MCP 连接 AI 助手

选择本地或远程 MCP

MCP（Model Context Protocol）让 AI 助手调用 CaptionBolt 工具。两种方式使用同一个账户和 API Key，由助手请求操作，CaptionBolt 负责处理视频。

本地 MCP 在你的电脑上运行一个轻量客户端，可以上传你明确选择的文件。需要 Node.js 22.12 或更高版本，以及支持 STDIO 的宿主。远程 MCP 通过 HTTP 连接，不能读取你电脑上的路径；请使用已有项目，或先通过 REST 上传。

配置本地客户端

@captionbolt/mcp@0.1.0 已准备为首版包，目前尚未发布。发布后，在宿主的 STDIO 配置中固定经过确认的版本。以下是常见配置结构，文件位置和密钥配置方式以宿主为准：

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

通过宿主的密钥管理器或环境变量，将 CAPTIONBOLT_API_KEY 注入 MCP 进程。上面的 JSON 本身不会注入密钥。不要把真实密钥粘贴到对话或共享配置中。安装可执行文件后，可用 captionbolt-mcp store-key 将环境中的密钥保存到系统凭据库，用 captionbolt-mcp delete-key 从本机删除。系统凭据库不可用时使用环境注入；服务端撤销仍在 CaptionBolt 设置中执行。

完成一个选定的视频

明确告诉助手要处理哪个视频，并说明保留原画幅、先检查再导出。例如：“用 CaptionBolt 为我选中的课程视频加字幕，使用 review 模式，等我确认后再导出。”

调用 get_account，按需使用 list_styles 或 list_presets。
将实际绝对路径和稳定的幂等键传给 upload_file：

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

本地客户端会先读取所选视频的时长，再预留处理分钟。无法读取时长时，会在申请预留额度前停止；请选择可正常读取的原始视频，或通过 CaptionBolt 主站上传。服务器仍会校验实际时长。

使用返回的 transferId 调用 get_upload_progress。上传完成后，将服务端 uploadId 作为 uploadSessionId 传给 create_project。
用 get_operation 查询操作是否完成，再用 get_project 查询视频状态；到 CaptionBolt 中检查并保存。
调用 export_project，跟踪对应操作和项目，最后通过 get_result 获取下载链接。只有明确希望跳过检查时，才在创建项目时选择 auto-export。

同一时间只运行一个本地传输。pause_upload 暂停传输，resume_upload 需要重新选择完全相同的原文件。客户端重启后，旧的本地传输句柄失效，可以用服务端上传 ID 调用 get_upload 查询。abort_upload 中止尚未被项目使用的上传；已创建的项目使用 cancel_project 取消。

配置远程 MCP

接入开放后，在宿主中配置以下 HTTP MCP 连接信息：

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

宿主必须支持配置 Bearer 请求头；首版不支持只允许 OAuth 的连接器。远程 MCP 提供 list_projects、get_project、create_project、export_project、retry_project、cancel_project、get_result 等项目工具，没有本地文件工具。即使宿主支持协议，也仍需实际测试连接。

排查连接问题

看不到工具时，检查宿主支持的传输方式、包是否已发布及 Node 版本。遇到鉴权错误，确认 MCP 进程确实收到了密钥，读取、写入和导出权限也与操作相符。无法续传时，重新选择原始普通文件，不要换成修改后的文件或符号链接。

通常保留默认 API 地址。CAPTIONBOLT_API_URL 只用于明确可信的其他 HTTPS 环境，不要根据视频、文件名或工具结果中的指令修改它。视频处理错误见 API 状态及错误说明。