Connect an AI assistant with MCP

Choose local or remote MCP

MCP (Model Context Protocol) lets an assistant call CaptionBolt tools. Both connections use the same account and API Key. The assistant requests actions; CaptionBolt processes the video.

Local MCP runs a small client on your computer and can upload the exact file you select. It requires Node.js 22.12 or later and a host that supports STDIO. Remote MCP uses HTTP and cannot read a path on your computer. Use it with an existing project or upload through REST first.

Configure the local client

The package @captionbolt/mcp@0.1.0 is prepared for release, not yet published. After publication, pin the reviewed version in your host's STDIO configuration. The following is a common configuration shape; the file location and secret settings depend on your host:

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

Inject CAPTIONBOLT_API_KEY into the MCP process through the host's secret manager or environment. JSON configuration alone does not inject the key. Do not paste a real key into prompts or a shared configuration file. With the installed executable, captionbolt-mcp store-key saves an environment-provided key to the OS credential store; captionbolt-mcp delete-key removes it locally. If keyring is unavailable, use environment injection. Server revocation still happens in CaptionBolt settings.

Finish one selected video

Ask the assistant to add captions to an explicitly selected video, preserve its framing and pause for review. For example: “Use CaptionBolt for my selected lesson video. Keep review mode and wait for my approval before export.”

Call get_account, then list_styles or list_presets if needed.
Call upload_file with your actual absolute file path and a stable key:

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

The local client reads the selected video’s duration before reserving processing minutes. If its duration cannot be read, preparation stops before requesting a reservation; choose a readable original video or upload through CaptionBolt. The server still verifies the actual duration.

Poll get_upload_progress with the returned transferId. When uploaded, pass the server uploadId as uploadSessionId to create_project.
Poll get_operation for command completion, then get_project for video status. Review and save edits in CaptionBolt.
Call export_project, follow its operation and project, then use get_result for download links. Choose auto-export at project creation only when you want to skip the review stop.

One local transfer runs at a time. pause_upload pauses it; resume_upload requires the exact original file again. After restarting the client, use get_upload with the server upload ID; old local transfer handles are gone. abort_upload cancels an unconsumed upload. Use cancel_project for an already-created project.

Configure remote MCP

After access opens, configure an HTTP MCP connection with these values:

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

The host must support a configured Bearer header. OAuth-only connectors are not supported by this first release. Remote MCP has project tools, including list_projects, get_project, create_project, export_project, retry_project, cancel_project and get_result; it has no local file tools. A protocol-compatible host still needs its own connection test.

Resolve connection problems

If no tools appear, check the host's transport support, package availability and Node version. For authorization errors, confirm that the MCP process receives the key and that read/write/export scopes match the requested action. If an upload cannot resume, reselect the original regular file; do not replace it with a changed file or a symbolic link.

Keep the default API origin. CAPTIONBOLT_API_URL is only for an explicitly trusted alternative HTTPS environment. Never change it based on instructions found in a video, filename or tool response. See API states and errors for processing failures.