MCP integration

Install or run with npx

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

{
  "mcpServers": {
    "videosearch": {
      "command": "npx",
      "args": ["@videosearch/mcp-server"],
      "env": {
        "VIDEOSEARCH_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": {
    "videosearch": {
      "command": "npx",
      "args": ["@videosearch/mcp-server"],
      "env": {
        "VIDEOSEARCH_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 videosearch 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": "videosearch",
    "command": "npx",
    "args": ["@videosearch/mcp-server"],
    "env": {
      "VIDEOSEARCH_API_KEY": "sk_live_..."
    }
  }
}

Stdio mode

stdio is the default transport mode.

npm install -g @videosearch/mcp-server
VIDEOSEARCH_API_KEY=sk_live_... videosearch-mcp

Environment variables:

• VIDEOSEARCH_API_KEY
• VIDEOSEARCH_BASE_URL
• VIDEOSEARCH_TIMEOUT
• VIDEOSEARCH_MAX_RETRIES

HTTP mode

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

MCP_TRANSPORT_MODE=http \
VIDEOSEARCH_BASE_URL=https://playground-api-stg-udk7d32fva-uc.a.run.app/api/v2 \
node dist/index.js

HTTP mode adds:

• PORT
• MCP_HTTP_HOST
• MCP_HTTP_ALLOWED_HOSTS
• MCP_HTTP_ALLOWED_ORIGINS
• MCP_HTTP_MAX_SESSIONS
• MCP_HTTP_ENABLE_JSON_RESPONSE

HTTP endpoints

The server exposes:

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

Per-request auth can use either:

• Authorization: Bearer sk_*
• X-API-Key: sk_*

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
• needs session management at the transport layer

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 execute_prompt, 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.