MCP Server for VSS#

The VSS MCP server exposes the Video Search and Summarization (VSS) REST API to AI agents and IDE extensions using the Model Context Protocol (MCP). It reads the live VSS OpenAPI spec at startup and registers a selected subset of endpoints as MCP tools and resources.

Note: The MCP server currently supports Search mode only. Summary and combined Search + Summary modes will be supported in a future release.

The server is controlled by a filter file, a small JSON document that lists exactly which VSS endpoints to expose and whether each appears as a tool or a resource. The bundled search.json filter covers the Search mode:

Prerequisites#

  • The VSS application must be running and reachable before starting this server.

  • Docker and Docker Compose installed (Installation Guide).

  • Network access from the machine running this container to the VSS host.

Quick Start#

Navigate to the mcp/ directory first, all commands below assume you are there:

cd sample-applications/video-search-and-summarization/mcp

Docker Compose builds the MCP server and starts MCP Inspector alongside it for interactive testing and debugging.

  1. Create your .env file:

    cp .env.example .env

  2. Edit .env — set the VSS backend IP and HOST IP:

    VSS_IP=<your-vss-ip>
HOST_IP=<your-host-ip>

    Note: The VSS_IP variable is automatically appended to no_proxy inside the containers by compose.yaml, so the MCP server can always reach the VSS backend directly without going through the proxy.

  3. Build and start:

    docker compose up --build -d

  4. Access the services:

    Service

    URL

    Description

    MCP Server

    http://<HOST_IP>:8000/mcp

    Streamable HTTP MCP endpoint

    MCP Inspector

    http://<HOST_IP>:6274

    Web UI for testing the MCP server

  5. Connect Inspector to MCP Server:

    • Open http://<HOST_IP>:6274 in your browser.

    • Select Streamable HTTP transport.

    • Enter http://<HOST_IP>:8000/mcp as the URL.

    • Click Connect.

  6. Stop:

    docker compose down

Runtime Configuration#

Variable

Required

Default

Description

API_SPEC_URL

Yes

-

URL to the VSS OpenAPI/Swagger JSON document

API_BASE_URL

Yes

-

Base URL of the running VSS REST service

FILTER_FILE_PATH

Yes

-

Path to the filter config file inside the container

REQUEST_TIMEOUT

No

60

Outbound request timeout in seconds

LOG_LEVEL

No

INFO

Python log level (DEBUG, INFO, WARNING, …)

MCP_HOST

No

0.0.0.0

Bind address

MCP_PORT

No

8000

Listening port

MCP_PATH

No

/mcp

Streamable HTTP endpoint path

What MCP Clients See#

At startup the server reads the VSS OpenAPI spec and the filter file, then registers exactly the operations listed in the filter.

Tools (state-changing or parameterised operations), examples from search.json:

Tool name

VSS endpoint

vss_run_search_query

POST /search/query

vss_get_all_videos

GET /videos

vss_get_video

GET /videos/{videoId}

vss_create_video_search_embeddings

POST /videos/search-embeddings/{videoId}

vss_get_tags

GET /tags

vss_delete_tag

DELETE /tags/{tagId}

Tool names are built from prefix + name in the filter file, forming names like "vss_run_search_query".

Resources (read-only, GET only) are named from prefix + name in the filter file. For example, a resource with prefix: "vss" and name: "app_features" is reachable as:

resource://vss_app_features

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.