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

Endpoint: https://mcp-assistant.valossa.com/mcp · transport streamable-http · auth OAuth 2.0.

Add it to your MCP client :

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

Or a JSON-config client (Claude Desktop, Cursor, …):

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

On first connect the client opens a Valossa Assistant login page; after that it stores the token and connects 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 the speech transcript for an analyzed media file. Mode can be either plain (txt), caption (srt) or speaker_segmented (txt).	`media_uuid`*, `mode`, `caption_id`
`get_video_overview` Get video overview	read-only	Return the Overview section of the video.	`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 media	read-only	List all media files 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`*
`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 the system 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.

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/