MCP integration

Install or run with npx

Claude Desktop can launch the server with npx, so a global install is optional.

{
  "mcpServers": {
    "videovector": {
      "command": "npx",
      "args": ["@vectormethods/videovector-mcp-server"],
      "env": {
        "VIDEOVECTOR_API_KEY": "sk_live_..."
      }
    }
  }
}

Config path

The helper controller returns this default config path for macOS:

~/Library/Application Support/Claude/claude_desktop_config.json

The setup instructions embedded in the controller also document the Windows equivalent.

Verification

After saving the config and restarting Claude Desktop, verify the connection by asking Claude which VideoVector tools are available.

Generated config endpoint

Use the helper endpoint when you want a platform-specific config payload:

curl "/api/v2/mcp/config?platform=claude-desktop" \
  -H "Authorization: Bearer <verified-jwt>"

If you omit api_key_id, the server will reuse a suitable key or create a new one with read and search scopes.

Cursor configuration

{
  "mcpServers": {
    "videovector": {
      "command": "npx",
      "args": ["@vectormethods/videovector-mcp-server"],
      "env": {
        "VIDEOVECTOR_API_KEY": "sk_live_..."
      }
    }
  }
}

Config path

The helper endpoint returns:

~/.cursor/mcp.json

Verification flow

1. Save or merge the config.
2. Restart Cursor.
3. Open the MCP panel and verify that the videovector server is connected.

Generated config endpoint

curl "/api/v2/mcp/config?platform=cursor" \
  -H "Authorization: Bearer <verified-jwt>"

Use api_key_id=<key_id> when you want to pin the config to an existing API key instead of letting the helper choose or create one.

Custom stdio configuration

The generic helper response uses this shape:

{
  "server": {
    "name": "videovector",
    "command": "npx",
    "args": ["@vectormethods/videovector-mcp-server"],
    "env": {
      "VIDEOVECTOR_API_KEY": "sk_live_..."
    }
  }
}

Stdio mode

stdio is the default transport mode.

npm install -g @vectormethods/videovector-mcp-server
VIDEOVECTOR_API_KEY=sk_live_... videovector-mcp

Environment variables:

• VIDEOVECTOR_API_KEY
• VIDEOVECTOR_BASE_URL
• VIDEOVECTOR_TIMEOUT
• VIDEOVECTOR_MAX_RETRIES

HTTP mode

Set MCP_TRANSPORT_MODE=http to expose the server over Streamable HTTP transport.

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

HTTP mode adds:

• PORT
• MCP_HTTP_HOST
• MCP_HTTP_ALLOWED_HOSTS
• MCP_HTTP_ALLOWED_ORIGINS
• MCP_HTTP_ENABLE_JSON_RESPONSE
• MCP_OAUTH_ENABLED (default false)
• MCP_OAUTH_METADATA_ENABLED (default false)
• MCP_OAUTH_ISSUER
• MCP_OAUTH_JWKS_URL
• MCP_OAUTH_RESOURCE
• MCP_OAUTH_CLOCK_SKEW_SECONDS (default 60)

The Streamable HTTP transport is stateless. Every POST /mcp creates one request-scoped server and transport, returns no MCP session ID, and closes the context after the response or client abort.

HTTP endpoints

The server exposes:

• GET /health
• POST /mcp
• GET /mcp
• DELETE /mcp

Per-request auth uses exactly one credential:

• Authorization: Bearer sk_*
• X-API-Key: sk_*
• Authorization: Bearer <OAuth access token> when hosted OAuth is enabled

Combining X-API-Key and Authorization is rejected. API keys retain their configured product scopes. A valid hosted WorkOS OAuth grant instead represents the signed-in Firebase account with full tenant-level access, including tenant-admin operations; it does not grant platform-admin, Firebase-only, API-key-management, or internal-service access.

Hosted tool security schemes intentionally advertise an empty OAuth scope array because custom API-key scopes do not apply to account OAuth. Access tokens are verified locally against the pinned issuer, resource audience, and JWKS, then the same bearer token is forwarded to the API. The MCP service does not call UserInfo or per-request introspection.

Deploy token verification with MCP_OAUTH_ENABLED=true first. Keep MCP_OAUTH_METADATA_ENABLED=false until the complete linking flow has passed staging, then enable metadata last. The protected-resource document is served at /.well-known/oauth-protected-resource/mcp, with /.well-known/oauth-protected-resource as a compatibility alias. The WorkOS API key used to complete Firebase account linking is server-only and is never a Node MCP or browser environment variable.

When to choose HTTP

Use HTTP transport when the MCP server:

• runs remotely instead of inside a desktop client
• needs origin or host allowlists
• needs readiness probes
• must work across multiple stateless service instances

Helper endpoints

Tool categories

The tool definition file groups public tools into categories such as:

• Search
• Discovery
• Video and segment inspection
• Extraction executions
• Extraction engine management
• Cloud connectors
• Import jobs
• Index management
• Video management
• Exports
• Webhooks

Representative workflows include:

• searching an index with search_videos, search_videos_by_image, or multimodal_search
• building extraction engines with create_prompt and test_prompt_schema
• executing and monitoring extraction runs with process_media, get_prompt_run_status, and get_prompt_run_results
• operating imports, exports, connectors, and webhooks without leaving the MCP client

Status response

GET /api/v2/mcp/status returns fields such as:

• server_name
• server_version
• package_name
• npm_install_command
• documentation_url
• tools_count
• supported_platforms

Tool discovery response

GET /api/v2/mcp/tools returns:

• total_count
• tools
• categories

Each tool includes a public input schema that mirrors the MCP SDK Tool definition shape.

Playground execution

The playground endpoint accepts:

{
  "tool_name": "search_videos",
  "arguments": {
    "index_id": "idx_archive",
    "query": "reporter outside a station entrance",
    "top_k": 5
  }
}

The response includes:

• tool_name
• success
• result
• error
• execution_time_ms

The controller also enforces explicit scope rules. Read-only tools require read-level capability, and mutating tools require write.

Structured playground payloads

For several tool families, the controller wraps results in structuredContent plus text content so clients can render both machine-readable and human-readable output cleanly.

Generation, execution, and matches

For fast on-demand testing, invoke the find skill with a goal and up to 100 attached videos. Its find tool handles native attachments, authorized local stdio paths, or an inline multi-file picker. The skill follows the import job and Playground execution, then presents Matches and All extracted results. Each new command uploads again and creates a fresh prompt and execution; transport retries resume the same invocation. Use the advanced tools below for deliberate reuse of saved prompts and uploaded media.

Find includes a segment transcription field, keeps advanced transcription and image embeddings off, and uses content-aware extraction. All supplied videos remain one Playground run. Host command namespaces vary; Claude Code exposes /videovector:find, while OpenAI hosts show the installed skill in their command picker. Hosted tools declare OpenAI native file inputs and share an MCP Apps picker when the host cannot forward a video.

Use define_prompt to turn a goal into extraction schemas. When the goal calls for finding, filtering, or shortlisting matches, the same generation also adds an optional selection filter. The saved prompt carries that filter into process_media; extraction-only requests remain unfiltered.

Video and audio support content_aware (the default) and fixed segmentation. Save settings through create_prompt or update_prompt under execution_config. process_media and estimate_prompt_run accept the same settings as top-level overrides; omitted or null overrides inherit the engine configuration. Fixed mode requires the corresponding segment duration in seconds from 1 to 300.

Generated instructions express supported intent qualitatively, such as concise social clips or useful context around a target moment. Content-aware video and audio use chronological coverage and 10-second to 15-minute prompt guidance, without enforcing those durations on the model's output.

process_media returns immediately. Poll get_prompt_run_status, then call get_prompt_run_results with the returned run ID. Results include separate filtered and unfiltered pages by default, so matches and the underlying extraction stay available together. Use result_level: "segment" (the default) or "video", and optionally narrow to video_id.

Each page has its own pagination.next_cursor. Follow it with view: "filtered" and filtered_cursor, or view: "unfiltered" and unfiltered_cursor. Pages default to 10 rows and allow at most 50. Selection status distinguishes pending processing, no configured filter, failed selection, and ready results including zero matches. Result reads do not repeat generation or processing.

The simple profile includes generation, processing, status, and results. The former execute_prompt MCP tool has been replaced by process_media. Omitted execution overrides use the saved engine settings in both indexed media and Playground. The hosted transport remains stateless Streamable HTTP with OAuth for OpenAI clients.