MCP integration

Connect with browser OAuth

Add https://api.vectormethods.com/mcp as a custom remote connector in Claude's Customize → Connectors. Use Sign in now and choose Register automatically for the OAuth client. Finish adding the connector, then sign in to VideoVector and return to Claude. Team and Enterprise workspaces may require an owner to add it first. See Claude's current connector instructions.

Remote connectors are configured through Claude's connector UI, including when using Claude Desktop. Do not put a remote URL in claude_desktop_config.json; that file configures local stdio servers.

You do not need an API key or local npm package for OAuth. The client discovers the authorization server and handles token refresh. The connection uses your VideoVector account's permissions, credits, and entitlements. See OAuth access and troubleshooting.

Local stdio alternative

For a local server with an explicitly scoped API key, Claude Desktop can launch the published package with npx:

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

On macOS, merge this entry into ~/Library/Application Support/Claude/claude_desktop_config.json; on Windows, use %APPDATA%\Claude\claude_desktop_config.json. Keep the real key in local configuration only. Restart Claude Desktop after changing the file.

Verify the connection

Enable VideoVector for the conversation and ask Claude to list your indexes. A visible tool list alone only proves discovery; a successful resource read confirms authentication.

Generate local API-key configuration

curl "https://api.vectormethods.com/api/v2/mcp/config?platform=claude-desktop" \
  -H "Authorization: Bearer <verified-firebase-id-token>"

This helper requires a verified VideoVector browser session. If api_key_id is omitted, it reuses a suitable API key or creates one with read and search scopes. The result is local API-key configuration, not OAuth configuration.

Connect with browser OAuth

Add this entry to ~/.cursor/mcp.json for all projects, or .cursor/mcp.json inside a project:

{
  "mcpServers": {
    "videovector": {
      "url": "https://api.vectormethods.com/mcp"
    }
  }
}

Save the configuration, enable the server in Cursor, and complete its OAuth connection prompt. Sign in to VideoVector in the browser, verify your email if requested, and return to Cursor. No API key, authorization header, or client secret belongs in this OAuth configuration. Cursor discovers the authorization server and manages tokens. See Cursor's MCP documentation for current configuration and connection controls.

The connection uses the signed-in VideoVector account. Ask Cursor to list your indexes to verify authenticated access; discovering the tool list alone does not authenticate a resource read.

Local stdio alternative

Use a local process when you need local file-path uploads or an explicitly scoped API key:

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

Set the API key in your environment, then restart Cursor. Choose either this local entry or the remote entry under the videovector name. API-key scopes limit the local integration; account OAuth does not use those scopes.

Generate local API-key configuration

curl "https://api.vectormethods.com/api/v2/mcp/config?platform=cursor" \
  -H "Authorization: Bearer <verified-firebase-id-token>"

Use api_key_id=<key_id> to select an existing key. The helper generates API-key configuration and requires a verified VideoVector browser session; it does not register an OAuth client. See OAuth discovery and troubleshooting.

Hosted OAuth connection

Use https://api.vectormethods.com/mcp as the Streamable HTTP server URL. Choose OAuth in the client and start account linking. Sign in to VideoVector in the browser tab opened by the client, verify your email if requested, and keep the tab open until the client resumes.

The login continuation at https://app.vectormethods.com/oauth/workos/login is part of that flow. It is not a client callback URI or a standalone login URL to bookmark. The client must begin a fresh authorization request. New accounts start on Free; linking requires no paid plan or profile form.

OAuth grants access to the signed-in account, including permitted create, update, delete, and tenant-admin operations. Account ownership, credits, and entitlements remain enforced. OAuth does not grant platform administration, API-key management, or access to Firebase-session-only or internal routes. For narrower automation permissions, use a scoped API key.

OAuth discovery and tokens

Read the metadata's authorization_servers value, then discover that issuer's authorization, token, dynamic-registration, and JWKS endpoints. Do not pin a provider hostname. Register the exact callback URI supplied by the client. Use resource=https://api.vectormethods.com/mcp on both the authorization request and the authorization-code token exchange.

Request offline_access when the client needs refresh tokens. Use the advertised token endpoint's refresh_token grant, retain any replacement refresh token, and preserve the MCP resource audience. Let the client use the token response's expiry; do not hardcode a token lifetime or paste bearer tokens into prompts or permanent config.

The protected-resource document intentionally omits scopes_supported, and hosted tools declare oauth2 with scopes: []. OIDC identity scopes are not VideoVector permissions: do not request API-key scopes such as read, write, search, or admin. Provider support for other grant types does not make client credentials or device codes a substitute for this account-linking flow.

Streamable HTTP requests

Send MCP JSON requests with:

POST /mcp
Authorization: Bearer <access_token>
Content-Type: application/json
Accept: application/json, text/event-stream

The endpoint is stateless. Do not send or retain MCP-Session-Id. GET /mcp and DELETE /mcp return 405; opening the URL in a browser is not an authentication test. Initialization and tool discovery are available before sign-in, while anonymous protected tool calls return 401 with a WWW-Authenticate challenge pointing to the protected-resource metadata.

Existing API-key integrations

The same hosted URL also accepts exactly one of:

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

Do not combine X-API-Key with Authorization. API-key scopes continue to limit these integrations. OAuth access tokens belong in the bearer header, not X-API-Key.

OAuth discovery omits tools that accept or return credentials: create_gcs_connector, create_s3_connector, create_azure_connector, create_webhook, and get_export_download_url. Configure connectors and webhooks in VideoVector, then use the existing resources from MCP. Use returned authenticated app links to access exports. API-key HTTP and stdio clients retain their existing tool surface.

Local stdio and self-hosted HTTP

The local package uses VIDEOVECTOR_API_KEY:

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

VIDEOVECTOR_BASE_URL defaults to https://api.vectormethods.com/api/v2; VIDEOVECTOR_TIMEOUT and VIDEOVECTOR_MAX_RETRIES configure API requests. The /api/v2/mcp/config helper generates API-key configurations, not OAuth registration or tokens.

Operators hosting their own server can set MCP_TRANSPORT_MODE=http and configure host/origin allowlists. OAuth verification must match the backend's supported WorkOS issuer, resource audience, and signed Firebase identity claims: the same bearer token is forwarded and independently verified by the API. Node environment variables alone cannot add another provider to the hosted API. OAuth is disabled by default in the local deployment. Follow the public self-hosting guide for verification and metadata rollout settings. The VectorMethods-hosted endpoint already has OAuth and public discovery enabled.

Troubleshooting

• Interrupted or missing linking request: restart connecting from the MCP client. Do not replay a one-use login continuation or open it in another tab.
• Wrong account: sign out of VideoVector and start a fresh connection with the intended account.
• Email verification required: verify the account's email, then resume or restart the client connection.
• Expired or invalid token: let the client refresh; reconnect if refresh is rejected. Authentication failures can appear as HTTP 401 challenges or tool-result mcp/www_authenticate metadata.
• Plan, credit, quota, or permission error: resolve the stated product requirement. These are not requests to relink OAuth.
• Stale tools or missing result card: refresh the client's discovered tools. MCP Apps rendering depends on the client.

Disconnect the integration in the client when it is no longer needed.

Helper endpoints

For a hosted OAuth connection, use https://api.vectormethods.com/mcp and let the client discover and authenticate the server. The REST helpers below serve API-key configuration and API testing; /mcp/config requires a verified VideoVector browser session and does not register OAuth clients or issue tokens. See OAuth setup.

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.

The REST helper catalog describes the API-key tool contract. Use the remote connection's tools/list response for its actual available tools. OAuth connections omit create_gcs_connector, create_s3_connector, create_azure_connector, create_webhook, and get_export_download_url because those tools accept or return credentials. Configure connectors and webhooks in VideoVector; use authenticated app links for exports. Existing API-key HTTP and stdio clients retain these tools.

OAuth initialization and tool discovery can run before sign-in. Protected tool execution requires authentication. Hosted tool security declarations use oauth2 with scopes: []; API-key permission scopes are not OAuth scopes.

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

API-key calls enforce each tool's required scope, including search, read, write, or admin as appropriate. OAuth calls use the linked account's tenant permissions, while product ownership, plan, and credit checks still apply.

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 compatible remote MCP clients and API-key authentication for existing integrations.