通过 MCP 连接 AI 助手

连接 AI 助手

推荐：让 AI agent 帮你完成配置

复制下方安装指令，发送给 Codex、Claude Code，或其他能够运行命令、编辑 MCP 配置的 AI agent，让它开始配置 CaptionBolt MCP 并发起登录。

你需要在浏览器中完成登录并授权。部分客户端还需要重新连接或开启新对话，agent 才能验证连接。

安装指令统一使用英文，并要求 agent 使用你在对话中使用的语言回复。

查看安装指令（英文）

Set up and connect CaptionBolt remote MCP now. Carry out the setup steps you can perform instead of only explaining them.
Communicate with me in the language I use in this conversation.

Connection details:
- Server name: captionbolt
- Server URL: https://api.captionbolt.com/mcp (no trailing slash)
- Transport: Streamable HTTP
- Authentication: OAuth browser sign-in
- Account requirement: an active CaptionBolt Max subscription

1. Identify the AI client and version you are configuring. Use the current environment when it identifies the client. Ask which client I use only if you cannot determine it. If you are running on a different machine from my client, explain the smallest step I need to perform on my machine.

2. Inspect the client's existing MCP configuration. Reuse a correct CaptionBolt entry. Otherwise, add this remote server using the client's supported command or configuration format. Prefer personal/user configuration and preserve other servers. If a conflicting CaptionBolt entry points elsewhere, ask before replacing it.

For Codex CLI, use:
codex mcp add captionbolt --url https://api.captionbolt.com/mcp

For Claude Code, use:
claude mcp add --transport http --scope user captionbolt https://api.captionbolt.com/mcp

Check the installed client's help before running commands. Run the add command only when the server is not already configured correctly. If this Claude Code version has no MCP login command, direct me to /mcp and its authentication action. For Cursor, use its supported remote MCP settings or mcp.json format with this server URL, then guide me through its connection and authorization action.

3. First try the read-only CaptionBolt get_account tool. If it succeeds, reuse the existing MCP authorization and do not start another login. If it reports authorization is required, start the client's native OAuth flow (Codex: codex mcp login captionbolt; Claude Code: claude mcp login captionbolt, or /mcp if this version has no login command). Open the browser or show the actual authorization URL produced by the client, then wait for me to sign in to CaptionBolt and approve access. Keep the login process running while it waits for the callback. An existing website session may avoid password entry but does not replace MCP consent. Do not invent or manually construct a login URL. No API key, manually copied access token or local CaptionBolt package is needed. Let the client handle callbacks and credential storage. If the client requires explicit scopes, use projects:read projects:write exports:write offline_access.

4. Once authorization succeeds, reconnect or reload the MCP tools as required by the client. If a restart or new conversation is required, tell me exactly how to continue verification there.

5. Verify the connection with the read-only CaptionBolt get_account tool (reuse the successful result from step 3 if already called). Report my remaining processing minutes. Do not upload, create, export, retry or cancel anything during setup. Configuration saved or login completed alone is not proof that this tool works.

6. Report which steps succeeded and any remaining step. If a permission or client limitation prevents execution, explain it and give me the smallest required action. Do not claim the connection works until the verification calls succeed.

Reference: https://captionbolt.com/integrations/mcp
Client documentation:
- Codex: https://developers.openai.com/codex/mcp
- Claude Code: https://code.claude.com/docs/en/mcp
- Cursor: https://cursor.com/docs/mcp

手动连接

使用支持远程 MCP、Streamable HTTP 和浏览器 OAuth 登录的 AI 客户端。集成能力向 Max 订阅用户开放。

在客户端中添加远程 MCP 服务，使用以下连接信息：

Name: CaptionBolt
Server URL: https://api.captionbolt.com/mcp
Transport: Streamable HTTP
Authentication: OAuth

这些是连接信息，不是配置文件。不同客户端的字段名称和配置格式可能不同；有些将传输方式标为 HTTP。使用完整服务 URL，不添加末尾斜杠。

在 AI 客户端的 MCP 设置或配置中添加服务。
启动客户端的登录或授权操作，浏览器会打开 CaptionBolt。
登录需要操作项目的账户，按提示完成账户设置。
检查申请的权限，选择 允许访问。
返回客户端，确认 CaptionBolt 工具可用。

无需 API Key 或手动复制访问令牌，客户端会处理 OAuth 连接。只支持 API Key 请求头的客户端不能连接此端点。

验证连接

向助手发送以下请求：

Show my remaining CaptionBolt processing minutes and recent projects.
Do not create, export, retry or cancel anything.

连接正常时，可以读取账户限制并列出可访问项目。尚无符合条件的视频项目时，列表为空是正常的。你可以在 CaptionBolt 上传视频后再次查询。

使用 CaptionBolt 工具

远程服务提供以下工具：

| 任务 | 工具 | | --- | --- | | 查询处理时长和限制 | get_account | | 查找字幕样式和已保存预设 | list_styles, list_presets | | 列出项目和查看进度 | list_projects, get_project | | 查询请求的操作是否成功 | get_operation | | 用已完成的上传创建项目 | create_project | | 导出已保存的修改 | export_project | | 重试或取消项目 | retry_project, cancel_project | | 获取已完成导出的下载链接 | get_result |

例如：

List my CaptionBolt projects that are ready for review.
Show their IDs and file names. Do not export them yet.

在 CaptionBolt 中检查并保存项目后：

Export project <project-id> as MP4 using its saved changes.
Check the operation, then the project status, and give me the download link
when the project is completed. If either fails, show the error and stop.

用工具返回的 ID 替换 <project-id>。operation 达到 completed 表示操作成功，视频可能仍在处理或导出。检查项目，直到 ready 可供检查或 completed 可下载。失败时停止并查看错误；查询之间遵循 pollAfterSeconds，项目取消后停止轮询。

导出前先在编辑器中保存。已完成项目保留现有导出；需要修改时，在 CaptionBolt 中创建可编辑副本。下载链接最长有效十分钟，可在项目的 14 天访问期内重新获取。

处理新视频

简单的方式是先在 CaptionBolt 网站上传视频，再通过 MCP 查询项目并导出已保存的修改。

自动化流程必须先完成 REST 上传流程，再将上传 ID 作为 uploadSessionId 传给 create_project。

使用 mode: "review" 等待在 CaptionBolt 中检查；明确选择 mode: "auto-export" 可在处理后自动导出 MP4。创建和修改项目需要项目写入权限；导出和自动导出另需导出权限。

自动导出项目停在 ready 时，检查 get_project 返回的 autoExport.state 和 autoExport.error。自动操作失败则报告错误并停止，不要持续等待下载，也不要未经指示发起另一项导出。

远程 MCP 不上传本地文件、不接受远程视频 URL，也不管理上传会话。它不编辑字幕或视觉设置，请在编辑器中修改。通知通过 Webhooks 单独配置。

管理连接

在设置 → 集成中查看已授权的 MCP 连接，并断开指定连接。

断开后，该连接及已保存令牌不能继续请求。退出 CaptionBolt 网站不会断开 MCP。两者都不会取消已接受任务；需要停止时，明确执行项目取消操作。

排查问题

| 问题 | 检查事项 | | --- | --- | | 没有 CaptionBolt 工具 | 确认支持远程 Streamable HTTP 和 OAuth，服务地址准确且已完成登录 | | 客户端要求 API Key | 选择 OAuth 登录；API Key 用于 REST，不用于此 MCP 端点 | | 连接已断开或过期 | 在客户端重新发起授权 | | 操作被拒绝 | 检查已授权权限及账户当前限制 | | 请求被限流 | 按服务返回的等待时间重试 | | 项目失败 | 先读取错误，再明确重试；参见 API 状态和错误 |

客户端若允许指定 OAuth scope，可用 projects:read、projects:write 和 exports:write。包含 offline_access 可自动续期，通常由客户端处理；未申请时，访问过期后可能需要重新登录。

创建项目、导出、重试和取消需要工具参数 idempotencyKey，使用 1–128 个无空格的可打印 ASCII 字符。新操作使用新键；超时后查询已知 operation，或用原键重发完全相同的工具调用，不要假定操作失败。确认项目失败后的显式 retry_project 是新操作，需使用新键。

程序处理工具错误时，读取 structuredContent.error 中的 message 和 kind，以及可用时返回的 status、code、requestId 和 retryAfterSeconds。遵循等待时间，不要反复调用失败的工具。