Connect an AI assistant with MCP

Connect your AI assistant

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

Connect manually

Use an AI client that supports remote MCP over Streamable HTTP and browser-based OAuth sign-in. Integrations are available on Max subscriptions.

Add a remote MCP server in your client using these connection details:

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.

No API key or manually copied access token is needed. The client handles the OAuth connection. A client that supports only API key headers cannot connect to this endpoint.

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. You can upload a video in CaptionBolt and ask again.

Use CaptionBolt tools

The remote server provides these tools:

| Task | Tools | | --- | --- | | 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 | | 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 |

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 give me the download link
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.

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. Download links last at most ten minutes. Ask for fresh links while the project remains within its 14-day access window.

Work with a new video

For a simple workflow, upload your video on the CaptionBolt website, then use MCP to inspect the project and export your saved edits.

For an automated workflow, your application must first complete the REST upload process. Pass the resulting upload ID to create_project as uploadSessionId.

Use mode: "review" to wait for review in CaptionBolt. Explicitly choose mode: "auto-export" to export an MP4 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.

Remote MCP does not upload local files, accept remote video URLs or manage upload sessions. It does not edit 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. Signing out of the CaptionBolt website leaves MCP connected. Neither action 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 | Confirm remote Streamable HTTP and OAuth support, the exact server URL, and that sign-in finished | | The client asks for an API key | Choose its OAuth sign-in option; API keys are for REST, not this MCP endpoint | | Access was disconnected or expired | 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 |

For clients that expose OAuth scopes, supported project scopes are projects:read, projects:write and exports:write. Include offline_access for automatic renewal. This is normally handled by the client; without it, 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 key for a 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.