VectorMethods

Docs / MCP

MCP integration

Connect AI assistants and operator tools to VideoVector indexes, extraction executions, search, and workflow resources through MCP.

mcp-server/README.mdmcp-server/src/index.tsapi/mcp_controllers.py

Search documentation

Search documentation pages and implementation topics.

Summary

The VideoVector MCP docs show how AI clients can browse indexes, run extraction engines, search media evidence, inspect workflow resources, and validate available tools.

Connect to hosted VideoVector

Use https://api.vectormethods.com/mcp as the remote MCP server URL and choose OAuth in your client. Complete browser sign-in with your VideoVector account, verify your email if requested, and return to the client. No API key or local installation is needed for this connection.

Free accounts can connect and use their Playground workflows and demo browsing/search through MCP. Connecting does not require a trial or paid plan.

OAuth connects the signed-in account to the five published media tools. Ownership, credits, and plan entitlements still apply. MCP does not expose deletion or administration tools. Use a scoped API key when an integration needs a narrower permission boundary.

For ordinary questions, retrieve the existing extraction with get_analysis and answer in context. Use search only for large, already-processed collections that exceed context. analyze saves generated prompts automatically for later reuse; import_media only transfers files and does not extract content.

Transport choices

ConnectionAuthenticationSetup
Hosted Streamable HTTPBrowser OAuthRemote URL above; the client handles discovery and token refresh
Hosted HTTP automationScoped API keySame URL with X-API-Key; existing API-key clients remain supported
Local stdioScoped API keyRun @vectormethods/videovector-mcp-server with VIDEOVECTOR_API_KEY

The hosted endpoint is stateless. Use MCP POST requests, not an SSE URL or an MCP session ID. See custom clients and OAuth discovery for the exact protocol and authorization contract.

Client setup

Local package identifiers

  • package: @vectormethods/videovector-mcp-server
  • command: videovector-mcp
  • server name: videovector
  • API-key environment variable: VIDEOVECTOR_API_KEY

REST helper endpoints

The API also exposes /api/v2/mcp/status, /api/v2/mcp/config, /api/v2/mcp/tools, and /api/v2/mcp/playground for inspection, API-key config generation, and direct tool testing. These are REST helpers, not OAuth registration or token endpoints. The remote client's tools/list response is authoritative for the tools available on its connection.

MCP / claude-desktop

Claude Desktop setup

Connect Claude and Claude Desktop to hosted VideoVector with browser OAuth, or use a local stdio server with an API key.

api/mcp_controllers.pymcp-server/README.mdmcp-server/src/index.ts

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.

MCP / cursor

Cursor setup

Connect Cursor to hosted VideoVector with browser OAuth, or run the local stdio MCP server with a scoped API key.

api/mcp_controllers.pymcp-server/README.mdmcp-server/src/index.ts

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.

MCP / custom-http

Custom clients and HTTP transport

Connect custom MCP clients to hosted VideoVector with OAuth discovery, PKCE, refresh tokens, or existing scoped API keys.

api/mcp_controllers.pyapi/oauth_metadata.pyinfrastructure/workos_oauth.pymcp-server/src/index.tsmcp-server/src/http/oauth-token-verifier.tsmcp-server/README.md

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 authenticates the signed-in account for the operations exposed by the five-tool MCP catalog. Account ownership, credits, and entitlements remain enforced. The catalog has no deletion or administration tools. 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

SettingValue
MCP URL and resourcehttps://api.vectormethods.com/mcp
Protected-resource metadatahttps://api.vectormethods.com/.well-known/oauth-protected-resource/mcp
Compatibility aliashttps://api.vectormethods.com/.well-known/oauth-protected-resource
Authorization-server discoveryAdvertised issuer plus /.well-known/oauth-authorization-server
Authorization flowAuthorization code with PKCE S256
OIDC identity scopesopenid email profile offline_access
MCP credentialAuthorization: Bearer <access_token>

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.

All connections expose five tools: analyze, get_analysis, search, import_media, and browse. There is no profile switch. OAuth excludes cloud sources (saved connectors and inline credentials) and task webhooks. Use API-key HTTP and local stdio for those direct options. Source, destination, and execution options are nested objects; see the published input schemas and examples. Native-file import retry can recover a failed authorized transfer with the original task/file identities; follow the returned recovery instruction.

Included analysis and search JSON downloads remain available through OAuth. Analysis results also include direct segment links; fetch the returned URLs without OAuth headers and follow media redirects. Links expire after one hour; get_analysis renews analysis links without repeating processing.

See tools and result downloads.

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.

MCP / tools-and-playground

Tools, helper endpoints, and playground

Inspect VideoVector MCP tool categories, use helper endpoints for config and tool discovery, and test tool execution through the MCP playground.

api/mcp_controllers.pymcp-server/src/tools/definitions.tsapi/routes.py

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.

MethodPathPurpose
GET/api/v2/mcp/statusInspect package name, install command, tool count, and supported platforms
GET/api/v2/mcp/configGenerate platform-specific config
GET/api/v2/mcp/toolsReturn tool definitions and category groupings
POST/api/v2/mcp/playgroundExecute a tool directly for testing

Five tools

Every supported connection exposes the same five agent-facing tools:

ToolPurpose
analyzeAnalyze media, automatically save the generated prompt for reuse, and return one durable analysis ID
get_analysisRead progress and available results using that same ID, or find the latest completed analysis for a video
searchFind matches in large, already-processed collections whose extraction exceeds the available context
import_mediaTransfer or upload media without extraction; continue with the same import ID
browseList or inspect indexes, videos, analyses, imports, and prompts

Studio uses private app helpers for its file picker, progress, and media inspection. Those helpers are not additional tools for the agent to choose. There is one catalog with no simple/advanced profile switch.

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 and connection's tools/list describe the same five tools. Hosted OAuth supports the same tool names; it excludes cloud sources (saved connectors and inline credentials) and task webhooks. Use an API-key HTTP or local stdio connection for those direct options. Included JSON and segment downloads remain available through OAuth.

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",
  "arguments": {
    "scope": {"index_id": "idx_archive"},
    "query": "reporter outside a station entrance",
    "max_results": 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.

Analysis, progress, and downloads

Call analyze with root instruction or saved prompt_id. Put native attachments in root files (up to eight), or select existing media through source. Local stdio paths belong in source.file_paths. Use source.playground: true to analyze existing Playground media. A new analysis requires media; the host supplies native attachment descriptors. New imports default to Playground; destination chooses an existing index_id or creates/reuses an index_name.

{"instruction":"Describe objects and actions with timestamps","source":{"video_ids":["vid_example"]}}
{"prompt_id":"prompt_example","files":[{"file_id":"host_example","download_url":"https://files.example/lecture.mp4"}],"wait_seconds":0}

The second example reuses a saved analysis format with a host-provided native attachment. Preserve the actual attachment descriptors; the values above are illustrative. source selects the input; destination applies only to new imports. Do not combine existing media selectors with a new destination. Optional analysis settings live under execution; omitted settings inherit the saved prompt configuration.

The response returns one durable analysis_id across upload, import, and processing, along with stage, message, progress, and next_action. Follow next_action with get_analysis using the same ID. A read can wait up to 30 seconds without a revision argument. Use wait_seconds: 0 for an immediate read. The polling interval is not an estimated completion time. Interrupting a client wait does not cancel processing.

Each source publishes its complete segment and whole-media extraction together. Results from different media items become available as those items complete. results.final identifies the final result set, and results.download_url downloads the complete JSON for the included video versions. The one-hour link is pinned: later completed videos appear in a new result link without changing the previous download. Downloading included results does not start another analysis or require a paid export.

results.segment_downloads includes a bounded preview of direct clip links. The full JSON contains download_available on each segment and, when available, its download_url and download_expires_at. These links download the individual segment video, with no extra media lookup tool. Fetch them without OAuth headers and follow the redirect to the signed media download. They expire with the JSON grant; call get_analysis for fresh links.

Save downloaded JSON to a local file when the host supports files, and retain the path and analysis_id for later inspection or context recovery. A client that cannot download files can request detail: "full" and follow the bounded inline result pages using results.pagination.next_cursor. Results contain all requested segment and whole-media metadata. Apply any filtering afterward in your application or through search. Result reads do not repeat processing.

Answer questions, search large collections, and reuse prompts

For ordinary questions about processed media, load the extraction using get_analysis and answer from that content in context. Do not search or analyze again when the needed information is already available.

Reserve search for large, already-processed collections whose extracted content cannot fit in context. It accepts text, a reference image, metadata filters, or their combination. Filters restrict eligible results before ranking. By default it searches each video's latest completed analysis. scope selects exactly one of analysis_ids, video_ids, index_id, index_name, or playground; analysis_ids pins history. Continue with the returned search_id and an optional cursor to read the pinned search. A cursor alone is not accepted. Use its JSON link to save the result set.

analyze automatically saves the reusable prompt generated from instruction and returns its ID in scope.prompt_id. Keep that ID internally and pass it to a later analyze call instead of instruction to reuse the same extraction format. Processing options belong under execution: model selection and image embeddings. Every analysis extracts segment and whole-media fields together. Filter results through downstream search or application code; extraction retains all content.

Import, browse, and callbacks

import_media accepts root native files or source.urls; direct integrations can also use source.connector, source.connector_id, or local stdio source.file_paths. A new import requires media. It performs transfer only, without generating prompts or starting extraction. Continue progress using {"import_id":"imp_example","wait_seconds":30} with import_media; this reads the same task. For failed attachment transfers, follow the returned recovery instruction with the original task/file identities and idempotency key. Native-file import retry is available through OAuth and direct integrations; it recovers the authorized transfer rather than requesting a new analysis. An import_id read cannot be combined with a new source or destination.

browse uses resource to choose indexes, videos, analyses, imports, or prompts. Add ids: ["resource_id"] for detail, or pagination options for lists. Browse reads return immediately. Use get_analysis and import_media(import_id) for bounded progress waits.

{"resource":"indexes"}

API-key HTTP and local stdio callers can add optional webhook: {"url":"https://your-service.example/callback","signing_secret":"your-private-signing-secret"} to a new analysis or import. Callbacks contain only the assigned task's terminal outcome, not progress notifications or download credentials. Verify the HMAC signature against the exact received body using the documented webhook signature headers. They do not automatically resume a host conversation; the returned task ID remains the way to read results.

The hosted transport uses stateless Streamable HTTP with OAuth for compatible remote clients and API-key authentication for existing integrations.