Valossa Assistant MCP server

Documentation · home

This Model Context Protocol (MCP) server exposes the Valossa Assistant media library to MCP-capable AI clients: import and analyze videos, read transcripts and visual metadata, export and download clips, and ask the Valossa Assistant about your media.

Connecting

You need a Valossa account: create one or sign in on the Valossa web app.

Add Valossa as a connector (also called an "MCP server") in your AI app, then sign in with your Valossa account when it asks — no API key needed. Use this address:

https://mcp-assistant.valossa.com/mcp

Claude Code (CLI)

claude mcp add --transport http valossa https://mcp-assistant.valossa.com/mcp

Then run /mcp in Claude Code and sign in.

Claude Desktop & claude.ai

Settings → Connectors → Add custom connector → paste https://mcp-assistant.valossa.com/mcp → Add, then sign in when prompted.

ChatGPT

Settings → Connectors → Advanced settings → turn on Developer mode, then add a connector with the address https://mcp-assistant.valossa.com/mcp and sign in. (Available on ChatGPT Plus, Pro, Business, Enterprise, and Edu plans.)

Cursor

Settings → Tools & MCP → New MCP server, or add this to ~/.cursor/mcp.json:

{ "mcpServers": { "valossa": { "url": "https://mcp-assistant.valossa.com/mcp" } } }

VS Code (GitHub Copilot)

Run MCP: Add Server from the Command Palette, or add this to .vscode/mcp.json:

{ "servers": { "valossa": { "type": "http", "url": "https://mcp-assistant.valossa.com/mcp" } } }

Windsurf — Settings → MCP, or ~/.codeium/windsurf/mcp_config.json:

{ "mcpServers": { "valossa": { "serverUrl": "https://mcp-assistant.valossa.com/mcp" } } }

Cline — MCP Servers → Remote Servers, or cline_mcp_settings.json:

{ "mcpServers": { "valossa": { "type": "streamableHttp", "url": "https://mcp-assistant.valossa.com/mcp" } } }

opencode — opencode.json:

{ "mcp": { "valossa": { "type": "remote", "url": "https://mcp-assistant.valossa.com/mcp", "enabled": true } } }

OpenAI Codex (CLI) — ~/.codex/config.toml:

[mcp_servers.valossa]
url = "https://mcp-assistant.valossa.com/mcp"

Hermes (Nous Research) — hermes mcp add valossa --url https://mcp-assistant.valossa.com/mcp, or under mcp_servers: in ~/.hermes/config.yaml.

OpenClaw — openclaw mcp add valossa --url https://mcp-assistant.valossa.com/mcp --transport streamable-http, or under mcp.servers in ~/.openclaw/openclaw.json.

Zed — uses the mcp-remote helper in settings.json:

{ "context_servers": { "valossa": { "source": "custom", "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp-assistant.valossa.com/mcp"] } } }

Another app? Add a connector / MCP server with the address https://mcp-assistant.valossa.com/mcp and sign in when prompted.

The first time you connect, a Valossa sign-in page opens; after that your app stays connected automatically.

Authentication & permissions

Login uses OAuth 2.0 against your Valossa Assistant account — the server never sees your password. Each tool is tagged so the client can manage permissions: read-only tools can run without a per-call prompt; writes data tools (uploads, exports, agent questions) consume quota and prompt for confirmation.

Tools

Parameters marked * are required.

Tool	Kind	Description	Parameters
`get_clip_download_url` Get clip download URL	read-only	Return a time-limited signed URL for downloading an exported clip.	`export_id`*
`get_quota_status` Get quota status	read-only	Report the user's current subscription and remaining quota.	none
`get_speech_transcript` Get speech transcript	read-only	Download a video's raw speech transcript, or an edited caption track.	`media_uuid`, `mode`, `caption_id`
`get_video_overview` Get video overview	read-only	Return the Overview section of the video.	`media_uuid`*
`get_video_preview_url` Get video preview URL	read-only	Return a short-lived signed URL for playing a video's preview rendition.	`media_uuid`*
`get_video_saved_clips` Get saved clips	read-only	Return the user's saved clips.	`media_uuid`*
`get_video_shots` Get video shots	read-only	Return the Shots & Keyframes of video with <media_uuid>.	`media_uuid`*
`get_video_transcript` Get video transcript	read-only	Return the Transcript section of video with <media_uuid>. Mode can be either plain (txt), caption (srt) or speaker_segmented (txt).	`media_uuid`*, `mode`
`get_video_visual_scenes` Get visual scenes	read-only	Return the Visual Scenes of video with <media_uuid>	`media_uuid`*
`list_all_videos` List all videos	read-only	List all videos in the user's library with their analysis status.	none
`list_captions` List captions	read-only	List edited caption tracks attached to a media file.	`media_uuid`*
`list_exported_clips` List exported clips	read-only	List the user's exported clips (rendered MP4s), newest first.	none
`ask_question` Ask the Valossa agent	writes data	General question about the user's videos.	`question`*, `media_uuids`, `conversation_id`, `timeout_seconds`
`commit_video_upload` Commit video upload	writes data	Finalize a staged upload: forward the file to Laravel and start analysis.	`ticket`*
`export_clip` Export clip	writes data	Export one or more video segments as an MP4 clip via the clipper service.	`uuids`, `timestamps_ms`, `name`*, `description`, `subtitles`, `smart_crop`, `crop_alignment`, `inner_aspect_ratio`, `caption_style`, `wait`, `timeout_seconds`
`get_best_soundbites` Ask the Valossa agent for best soundbites of video	writes data	Retrieve the most captivating and thought provoking sound bites from the video. Suitable for promotial material from podcasts and interviews.	`media_uuids`, `conversation_id`, `timeout_seconds`
`get_video_highlights` Ask the Valossa agent for video highlights	writes data	Retrieve the most exciting and most interesting recognized moments in the video. Suitable for promotial material from movies and TV shows.	`media_uuids`, `conversation_id`, `timeout_seconds`
`get_video_summary` Ask the Valossa agent to summarize videos	writes data	Retrieve summary/summaries of selected video(s).	`media_uuids`, `conversation_id`, `timeout_seconds`
`get_videos` Retrieve videos with query	writes data	General search for videos (full videos) from Valossa database, using natural-language questions.	`question`*, `media_uuids`, `conversation_id`, `timeout_seconds`
`prepare_video_upload` Prepare video upload	writes data	Begin a video upload by minting a one-time ticket and a raw HTTP PUT URL.	`filename`, `title`, `language`

Uploading a video

Uploads stream straight to the server, never through the model's context:

Call prepare_video_upload → returns a one-time put_url and ticket.

PUT the file to that URL:

curl -X PUT --upload-file video.mp4 "<put_url>"

Call commit_video_upload with the ticket → the server validates the file (format, size ≤ 7 GB, length ≤ 5 h, quota), forwards it to Valossa, and starts analysis.

The endpoint answers the browser CORS preflight, so a browser client can PUT the file directly to upload_url:

const u = JSON.parse(await prepare_video_upload(/* filename, title */));
await fetch(u.upload_url, { method: u.method,              // "PUT"
                           headers: u.required_headers,    // { "Content-Type": … }
                           body: file });                  // a File/Blob
await commit_video_upload(u.upload_id);

A browser can only reach this endpoint if the host page's Content-Security-Policy allows it (connect-src). Some hosted clients restrict connect-src to their own origin and will block the upload — that is a client-side policy, not a server setting. Server-side and desktop/CLI clients are unaffected.

Quota

Imports consume analysis minutes, export_clip consumes clip exports, and ask_agent consumes conversation credits from your Valossa Assistant account. Call get_quota_status to see what's left; quota-exhaustion errors name the operation and link to the billing page.

Discovery

Machine-readable metadata: https://mcp-assistant.valossa.com/.well-known/mcp.json and https://mcp-assistant.valossa.com/.well-known/oauth-protected-resource.

Errors

Actionable problems (out of quota, invalid file, not-yet-analyzed, bad input) return a clear message. Unexpected failures return a generic message with a reference code — quote it to support at https://valossa.com/contact/

Privacy policy

https://valossa.com/privacy-policy/

Terms&Conditions

https://valossa.com/terms-and-conditions/