VideoVector MCP Server

Official Model Context Protocol (MCP) server for VectorMethods VideoVector.

This package lets MCP clients such as Claude Desktop, Cursor, Claude Code, and custom agent runtimes search, inspect, and operate VideoVector media intelligence workflows through the public VideoVector API.

Status

• Primary transport: stdio

• Self-hostable transport: Streamable HTTP at /mcp

• Runtime: Node.js 18+

• Package: @vectormethods/videovector-mcp-server

• Command: videovector-mcp

• Server name: videovector

• MCP Registry name: io.github.VectorMethods/videovector-mcp-server

This repository is the public source of truth for VideoVector MCP server code, tool contracts, examples, and release metadata. Private VectorMethods backend deployment wiring, service accounts, project IDs, billing internals, and website source are intentionally not part of this repository.

Related MCP server: Gemini Omni MCP Server

Install

Use npx from your MCP client:

npx -y @vectormethods/videovector-mcp-server

Or install globally:

npm install -g @vectormethods/videovector-mcp-server

Stdio Usage

VIDEOVECTOR_API_KEY=<your-videovector-api-key> videovector-mcp

Environment variables:

Client Examples

• Claude Desktop: examples/claude-desktop.json

• Cursor: examples/cursor.json

• Generic stdio: examples/custom-stdio.json

• Simplified workflow stdio: examples/simple-stdio.json

• Local Streamable HTTP: examples/streamable-http-local.json

Self-Hosted HTTP

HTTP mode is intended for self-hosted or private network deployments.

npm run build
MCP_TRANSPORT_MODE=http \
VIDEOVECTOR_BASE_URL=https://api.vectormethods.com/api/v2 \
node dist/index.js

Endpoints:

• GET /health

• POST /mcp

The /mcp endpoint is stateless. Each POST is independent and may be routed to any healthy instance. GET /mcp and DELETE /mcp return 405; clients must not send or persist MCP-Session-Id.

HTTP requests must include either:

• Authorization: Bearer <your-videovector-api-key>

• X-API-Key: <your-videovector-api-key>

HTTP hardening variables:

Both stdio and HTTP modes accept canonical production keys only (sk_live_ followed by exactly 48 lowercase hexadecimal characters). Invalid candidates are rejected before normal API use. In HTTP mode, validation uses the side-effect-free GET /auth/validate API operation. Successful keys are cached for 60 seconds, confirmed invalid keys for 10 minutes, and transient failures for five seconds. Same-key checks are singleflighted and backend validation is bounded to 16 concurrent calls plus a 64-request queue with a five-second timeout. Plaintext keys are never written to caches or logs. When both supported HTTP headers are present, X-API-Key takes precedence, matching the VideoVector API.

Do not advertise a public hosted remote MCP endpoint until OAuth and MCP protected-resource metadata are enabled for that deployment.

Tools

For the lowest-friction agent workflow, set VIDEOVECTOR_TOOL_PROFILE=simple. It exposes:

• upload_media: stream a local media file to Playground or a named/index-ID destination

• define_prompt: generate and, by default, save a Prompt Lab prompt

• process_media: process Playground, an index, or selected media with smart, content_aware, or fixed segmentation

• search_media: vector or conditional search over Playground, an index, selected media, or prompt runs with stable cursor pagination

The default full profile preserves those tools plus the complete advanced surface below. upload_media is local-stdio-only and is never advertised by the Streamable HTTP transport. Its path must resolve inside VIDEOVECTOR_UPLOAD_ROOTS (or the process working directory by default), and the server streams and reopens the file for safe idempotent retries instead of buffering it in memory.

The server exposes tools for:

• semantic, image, multimodal, and structured metadata search

• index, video, segment, and prompt discovery

• prompt-run estimation, execution, status, results, retries, and cancellation

• prompt management and schema testing

• cloud connectors, import jobs, exports, and webhooks

The machine-readable tool contract is generated at artifacts/tool-contract.json. Private backend and website releases should vendor this artifact for MCP helper endpoints and documentation updates.

get_export_status is side-effect free: its download_url is only the authenticated API endpoint and it never mints a bearer credential. Use the separate get_export_download_url tool only when a header-free client explicitly needs a short-lived bounded URL. Connector-delivered, processing, failed, and otherwise unavailable exports return download_url: null. Treat any non-null minted URL as a credential and do not log or persist it.

Development

npm ci
npm run verify

Useful scripts:

• npm run typecheck

• npm run lint

• npm run build

• npm test

• npm run generate:contract

• npm run check:contract

• npm run check:examples

Use the MCP Inspector for local manual checks:

npx @modelcontextprotocol/inspector

For stdio, point the Inspector to npx -y @vectormethods/videovector-mcp-server and set VIDEOVECTOR_API_KEY.

Security

Never commit API keys, cloud credentials, connector credentials, webhook secrets, service-account JSON, or .env files.

See SECURITY.md for supported versions, disclosure instructions, and operational guidance.