Connect an AI assistant with MCP

Connect your AI assistant

Set up CaptionBolt's local MCP server for me and connect my account. Do the steps you can perform instead of only explaining them, and reply in the language I use in this conversation.

Facts:
- Server name: captionbolt. It is a local STDIO MCP server started with the command npx and the arguments --yes @captionbolt/mcp@0.3.2
- It must run on the computer that has my videos and my browser; WSL on that computer counts. It needs Node.js 22.12 or later and an active CaptionBolt Max subscription.
- Sign-in command: npx --yes @captionbolt/mcp@0.3.2 login
  It prints an authorization URL and tries to open it in my browser, waits up to five minutes for me to approve access, then saves the authorization on this computer. Running it first also downloads the package. The URL returns to a local address, so it only works in a browser on this computer.
- On native Windows, a client that cannot start npx directly needs the command cmd with the arguments /c npx --yes @captionbolt/mcp@0.3.2
- Verify with the read-only get_account tool; remaining minutes = credits.availableCreditsSec / 60.
- Clients that cannot run local servers use the remote server https://api.captionbolt.com/mcp instead; it cannot upload files from my computer or save results there.

Steps:
1. Identify my AI client, operating system and shell, and adapt every command, configuration format and file path to them. Check the Node.js version. If you are not running on my computer (for example over SSH, in a container or in a cloud workspace), tell me the smallest step to run there.
2. Start the sign-in command in the background and read its output. As soon as it shows the authorization URL, send me a message that contains that exact URL as plain text, before you run any other command or read any file. Tell me to approve access in the browser window it opened, or to open the URL on this computer if none appeared. I cannot see command output, so never refer to "the link above". Then let the command keep running until it reports success; if you cannot keep a command running, ask me to run it in my own terminal. If it reports that CaptionBolt is already authorized, continue. If it reports that an eligible integration account is required, tell me a Max subscription is needed and stop.
3. Add the server to my client's personal MCP configuration and keep other servers; prefer the client's own command for adding MCP servers. Update a captionbolt entry that uses another @captionbolt/mcp version; ask before replacing one that points elsewhere. A typical entry, to adapt to my client: {"mcpServers": {"captionbolt": {"command": "npx", "args": ["--yes", "@captionbolt/mcp@0.3.2"]}}}
4. Reload the MCP tools as my client requires, then call get_account and report my remaining minutes. If I must restart the client or open a new conversation first, tell me exactly what to do and give me one sentence to send there, such as "Call CaptionBolt get_account and show my remaining minutes."
5. Tell me what succeeded and anything left for me. Once it works, tell me I can ask in my own words, for example "Add captions to <path to my video>".

Rules:
- Do not upload, create, export, retry or cancel anything during setup.
- Ask before installing or upgrading software such as Node.js.
- Do not invent a login URL or ask for my password, an API key or a copied token. If a sandbox blocks network access, the browser or the credential store, ask me for permission or ask me to run the command myself.
- A saved configuration or a finished sign-in is not proof; only a successful get_account call is.

Reference: https://captionbolt.com/integrations/mcp

Install manually

CaptionBolt's local MCP server is the npm package @captionbolt/mcp. It works with AI clients that can run a local STDIO MCP server, such as Codex, Claude Code, Claude Desktop, Cursor and VS Code. It needs Node.js 22.12 or later. Integrations are available on Max subscriptions.

First, sign in once from a terminal on the computer that has your videos. This also downloads the package:

npx --yes @captionbolt/mcp@0.3.2 login

1. Your browser opens CaptionBolt. If it does not, open the authorization URL printed in the terminal.
2. Sign in with the account whose projects you want to use. Complete account setup if prompted.
3. Review the requested permissions and select Allow access.
4. Wait until the terminal confirms that your account is verified.

Then add the server to your AI client's MCP configuration. Many clients use this format:

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

Your client's configuration format may differ; use the same command and arguments. On native Windows, a client that cannot start npx directly needs the command cmd with the arguments /c npx --yes @captionbolt/mcp@0.3.2.

WSL counts as the same computer: install the server in the AI client running inside WSL, and refer to Windows files with paths such as /mnt/c/Users/<name>/Videos/interview.mp4. The sign-in link opens in your Windows browser.

Finally, restart your AI client or start a new conversation so it loads the CaptionBolt tools.

Your authorization is saved in your system's credential store and renews automatically. On Linux and WSL without a keyring, it is saved in ~/.config/captionbolt/mcp-credentials.json, readable only by you. No API key or copied token is needed. To remove it from this computer, run the same command with logout instead of login.

Check the connection

Ask your assistant:

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

A working connection can read your account limits and list your accessible projects. An empty project list is expected if you have no eligible video projects yet.

Caption a video on your computer

Ask in your own words and name the file:

Add captions to ~/Videos/interview.mp4

Your assistant starts uploading that file. While it uploads, the assistant asks which caption style to use and suggests a few recommended styles and any presets you saved in CaptionBolt. Reply with a number, describe the look you want or let the assistant choose.

When processing finishes, the captioned video is saved next to the original, for example as interview.captioned.mp4. An existing file is never replaced; a numbered name is used instead. Your assistant also shares the project's Editor link. Open it to correct words or change the style, then export again in CaptionBolt.

Subtitle files such as SRT, VTT, ASS and TXT are exported with the video. Ask for them in the same request or later:

Add captions to ~/Videos/interview.mp4 and also save the SRT file.

To check captions in the Editor before exporting, ask for review first.

The local server reads only the file you name. It does not scan your folders, and the video goes directly to CaptionBolt storage rather than into the AI conversation. MP4, MOV, WebM and AVI files are supported. Processing uses your account's minutes and limits, just like a website upload.

Use CaptionBolt tools

The local server provides these tools:

| Task | Tools | | --- | --- | | Upload a video from your computer | upload_file, get_upload_progress | | Pause, resume or cancel an upload | pause_upload, resume_upload, get_upload, abort_upload | | Save a finished export on your computer | download_result, get_download_progress | | Check processing minutes and limits | get_account | | Find caption styles and your saved presets | list_styles, list_presets | | List projects and inspect progress | list_projects, get_project | | Wait for processing to finish | wait_for_project | | Check whether a requested action succeeded | get_operation | | Create a project from a completed upload | create_project | | Export saved edits | export_project | | Retry or cancel a project | retry_project, cancel_project | | Get download links for a finished export | get_result |

You can also work with projects created on the website. For example:

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

After reviewing and saving a project in CaptionBolt:

Export project <project-id> as MP4 using its saved changes.
Check the operation, then the project status, and save the video on my
computer when the project is completed. If either fails, show the error and stop.

Replace <project-id> with an ID returned by the tools. An operation reaching completed means the requested action succeeded; the video may still be processing or exporting. Check the project until it reaches ready for review or completed for download. Stop and inspect the error if it fails. Use the returned pollAfterSeconds between checks, and stop polling a cancelled project.

mode: "review" waits at ready so you can review the project in CaptionBolt; mode: "auto-export" exports the MP4 and the subtitle files your plan allows after processing, without that stop. Creating and changing projects requires project write permission; export and auto-export also require export permission.

If an auto-export project stays at ready, inspect autoExport.state and autoExport.error in get_project. If the automatic action failed, report the error and stop; do not keep polling for a download or start another export without instructions.

Exported changes must be saved in the Editor first. Completed projects keep their existing export; create an editable copy in CaptionBolt if you need to make further changes. Asking such a project for a format it lacks returns an error at once. Download links last at most ten minutes. Ask for fresh links while the project remains within its 14-day access window.

Connect without a local install

Use remote MCP when your AI client cannot run local servers, such as a web-based assistant. Remote MCP has the same project tools, but it cannot upload files from your computer or save results there. Your client must support remote MCP over Streamable HTTP and browser-based OAuth sign-in.

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

These are connection details, not a configuration file. Your client's field names or configuration format may differ. Some clients label the transport simply HTTP. Use the exact server URL, without a trailing slash.

1. Add the server in your AI client's MCP settings or configuration.
2. Start the client's sign-in or authorization action. It opens a browser to CaptionBolt.
3. Sign in with the account whose projects you want to use. Complete account setup if prompted.
4. Review the requested permissions and select Allow access.
5. Return to your client and check that CaptionBolt tools are available.

The client handles the OAuth connection; a client that supports only API key headers cannot connect to this endpoint. With remote MCP, upload your video on the CaptionBolt website, then use MCP to inspect the project and export your saved edits. An automated workflow must first complete the REST upload process, then pass the resulting upload ID to create_project as uploadSessionId.

Remote MCP does not accept remote video URLs or manage upload sessions. Neither server edits captions or visual settings; make those changes in the Editor. Configure notifications separately through Webhooks.

Manage your connection

Open Settings → Integrations to view your authorized MCP connections and disconnect one.

Disconnecting blocks further requests from that connection, including saved tokens. Running logout only removes the local server's authorization from your computer; disconnect in Settings to revoke it. Signing out of the CaptionBolt website leaves MCP connected. None of these actions cancels work already accepted; use a project cancellation action if you want to stop it.

Troubleshooting

| Problem | What to check | | --- | --- | | CaptionBolt tools do not appear | For the local server, check Node.js 22.12 or later and the command and arguments, then restart your client. For remote MCP, confirm Streamable HTTP and OAuth support and the exact server URL | | A tool reports AUTH_REQUIRED | Run the login command again in a terminal, then retry | | Sign-in reports that the credential store is unavailable | Unlock your macOS Keychain or Windows Credential Manager, or connect with remote MCP | | The browser does not open | Open the authorization URL printed in the terminal, on the same computer | | After you allow access, the browser cannot reach 127.0.0.1 | Open the link on the computer that runs login, while the command is still running; run login again if it stopped | | The client cannot start npx or node | Desktop apps may not use your terminal's PATH. Use the full path to npx or add the Node.js folder to the server's PATH; on native Windows, use cmd with /c npx … | | The client asks for an API key | Use the local server or the client's OAuth sign-in; API keys are for REST, not MCP | | Access was disconnected or expired | Run login again for the local server, or start authorization again in your client | | An action is denied | Check the permissions you approved and your account's current limits | | Requests are rate limited | Wait for the retry interval returned by the service | | A project fails | Read its error before explicitly retrying; see API states and errors |

The local server requests the project scopes projects:read, projects:write and exports:write plus offline_access for automatic renewal. For remote clients that expose OAuth scopes, use the same scopes; without offline_access, you may need to sign in again when access expires.

Project creation, export, retry and cancellation require an idempotencyKey tool argument. Use 1–128 printable ASCII characters without spaces. Use a new random value, such as a UUID, for each new action. After a timeout, poll a known operation or resend the identical tool call with its original key; do not assume the action failed. An explicit retry_project after a confirmed project failure is a new action and needs a new key.

For programmatic error handling, tool failures expose structuredContent.error with message and kind. status, code, requestId and retryAfterSeconds are included when available. Follow the returned retry interval rather than repeatedly calling a failing tool.