MCP Server for VSS#
The VSS MCP server exposes Video Search and Summarization (VSS) to AI agents and IDE extensions using the Model Context Protocol (MCP). It is served over Streamable HTTP and presents a set of tools over the VSS Pipeline Manager API.
For a task-oriented walkthrough, from connecting an agent to running real use cases, see Agentic Video Analytics with VSS.
Prerequisites#
Docker and Docker Compose installed (Installation Guide).
A running VSS deployment (the MCP server starts with the stack and probes it at startup).
Network access from the machine running this container to the VSS host.
Quick Start#
All commands below are run from the application root:
cd sample-applications/video-search-and-summarization
The MCP server runs with every VSS deployment: source setup.sh <mode>
(starts it) and source setup.sh --stop (stops it) manage it along with the
rest of the stack. It reads the enabled VSS features from Pipeline Manager at
startup, so no MCP-specific configuration is needed per mode.
Start VSS (any mode). The MCP server comes up with the stack and the final output shows its URL:
source setup.sh --search # or --summary, --dual, --unified
HOST_IPis auto-detected.VSS_IP— the VSS gateway host the MCP server calls and puts in every URL it returns to agents — defaults toHOST_IP; set it in.envor your shell only when the VSS gateway runs on another machine.Connect an Agent. Point any MCP client or agent that supports the Streamable HTTP transport at:
Service
URL
Description
MCP Server
http://<HOST_IP>:12345/mcpStreamable HTTP MCP endpoint, proxied by the nginx gateway
To install a local agent and model on Intel hardware and connect it to VSS, see Build Visual AI Agents with VSS.
Stop. Stop the MCP server together with the rest of VSS:
source setup.sh --stop
Runtime Configuration#
Variable |
Required |
Default |
Description |
|---|---|---|---|
|
No |
|
Host of the VSS gateway, reachable by your agent; every VSS URL is built from it. Not asked for when already set |
|
No |
auto-detected by |
This host’s address; fallback for |
|
No |
|
VSS gateway port |
|
No |
|
Bind address |
|
No |
|
Listening port (pinned in the VSS stack; not published on the host) |
|
No |
|
Streamable HTTP endpoint path (pinned in the VSS stack to match nginx) |
What MCP Clients See#
Available tools#
The Needs column is the VSS feature a tool requires. vss_get_deployment_info reports
the feature set behind the decision. live means search with a frame-embedding index
(--search or --dual); unified mode ingests no live cameras.
Tool |
Needs |
Purpose |
|---|---|---|
|
— |
Which features are on, and how much of the library is indexed (search only) |
|
— |
Library listing, each entry with an |
|
— |
The tags videos and live cameras are labelled with |
|
— |
Turn “the warehouse clip” into a video id |
|
search |
Make a video searchable (call once per video) |
|
search |
Find moments across indexed videos and live cameras, by text, by image, or by an earlier hit ( |
|
search |
A saved search and its latest results; |
|
search |
Saved searches, newest first |
|
search |
Track a person or object live: watch a saved search by its |
|
search |
Stop watching a search; the search stays in history |
|
search |
The image of a search hit’s best-matching frame (or its detected object), from the hit’s |
|
live |
Registered RTSP cameras, with state and ingest stats |
|
live |
One camera’s state, stats and last error |
|
live |
Add one or more RTSP cameras |
|
live |
Pause, resume or retune a camera |
|
live |
Stop and deregister cameras; recorded footage and embeddings are kept |
|
summary |
Summarize a video and return only its final summary, in full ( |
|
summary |
Full timeline (and final summary, if produced) of an already-summarized video |
Video Upload#
POST /videos is intentionally not exposed. Video upload is a long-running multipart operation better handled directly via the VSS REST API. Use the MCP server for discovery, search and status workflows only.