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
| Connection | Authentication | Setup |
|---|---|---|
| Hosted Streamable HTTP | Browser OAuth | Remote URL above; the client handles discovery and token refresh |
| Hosted HTTP automation | Scoped API key | Same URL with X-API-Key; existing API-key clients remain supported |
| Local stdio | Scoped API key | Run @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
- Claude and Claude Desktop
- Cursor
- Custom clients, OAuth, and self-hosted HTTP
- Tools, helper endpoints, and playground
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.
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.
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.
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
| Setting | Value |
|---|---|
| MCP URL and resource | https://api.vectormethods.com/mcp |
| Protected-resource metadata | https://api.vectormethods.com/.well-known/oauth-protected-resource/mcp |
| Compatibility alias | https://api.vectormethods.com/.well-known/oauth-protected-resource |
| Authorization-server discovery | Advertised issuer plus /.well-known/oauth-authorization-server |
| Authorization flow | Authorization code with PKCE S256 |
| OIDC identity scopes | openid email profile offline_access |
| MCP credential | Authorization: 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
401challenges or tool-resultmcp/www_authenticatemetadata. - 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.
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.
| Method | Path | Purpose |
|---|---|---|
GET | /api/v2/mcp/status | Inspect package name, install command, tool count, and supported platforms |
GET | /api/v2/mcp/config | Generate platform-specific config |
GET | /api/v2/mcp/tools | Return tool definitions and category groupings |
POST | /api/v2/mcp/playground | Execute a tool directly for testing |
Five tools
Every supported connection exposes the same five agent-facing tools:
| Tool | Purpose |
|---|---|
analyze | Analyze media, automatically save the generated prompt for reuse, and return one durable analysis ID |
get_analysis | Read progress and available results using that same ID, or find the latest completed analysis for a video |
search | Find matches in large, already-processed collections whose extraction exceeds the available context |
import_media | Transfer or upload media without extraction; continue with the same import ID |
browse | List 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_nameserver_versionpackage_namenpm_install_commanddocumentation_urltools_countsupported_platforms
Tool discovery response
GET /api/v2/mcp/tools returns:
total_counttoolscategories
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_namesuccessresulterrorexecution_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.
Use the playground to validate argument shapes and output structure before you hand the server to an agent or a production client.
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.
