Primate Vision MCP server
✓ VerifiedEnables AI agents to perform deterministic video scene understanding and analysis using plain English questions.
Also known as Primate-Intelligence/primate-intelligence-mcp, primate-intelligence-mcp, @primate-intelligence/mcp
- Stars
- 0
- Tools
- 10
- Downloads, 30 days
- —
- Latest version
- 0.4.0
- Last commit
- Aug 1, 2026
- License
- MIT
What is Primate Vision MCP?
Primate Vision enables AI agents to perform deterministic video scene understanding and analysis using plain English questions. It exposes 10 tools, such as create_video_from_url, create_analysis, validate_analysis.
Summary generated from the project's README
About Primate Vision MCP server
Analyzing video content through plain English questions is what this server enables for AI agents. It connects to the Primate Vision video analysis API to provide deterministic scene understanding, ensuring answers are limited to yes, no, or indeterminate rather than hallucinated descriptions. Users receive specific evidence including confidence scores and clip timestamps for every query.
Developers can connect via a remote OAuth 2.1 endpoint for Claude Desktop or by running a local stdio server using npx and a PRIMATE_API_KEY environment variable. The toolset includes functions to register videos from URLs, run single or batch analyses, and validate prompts for assessability and cost before execution. It also provides utilities to monitor credit balances, check usage, and poll for analysis completion.
This integration is designed for autonomous agents that need to verify video data without human intervention. The server maintains high security by ensuring credentials never enter tool-call logs or model context, as the API key is strictly handled through environment variables.
Written from the project's README. Every use case is checked against a quote from it.
How to install Primate Vision MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall Primate Vision MCP in Claude Code
$ claude mcp add --env 'PRIMATE_API_KEY=<YOUR_PRIMATE_API_KEY>' primate-intelligence-mcp -- npx -y @primate-intelligence/mcpInstall Primate Vision MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"primate-intelligence-mcp": {
"command": "npx",
"args": [
"-y",
"@primate-intelligence/mcp"
],
"env": {
"PRIMATE_API_KEY": "<YOUR_PRIMATE_API_KEY>"
}
}
}
}Install Primate Vision MCP in VS Code
.vscode/mcp.json
{
"servers": {
"primate-intelligence-mcp": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@primate-intelligence/mcp"
],
"env": {
"PRIMATE_API_KEY": "<YOUR_PRIMATE_API_KEY>"
}
}
}
}Install Primate Vision MCP in VS Code CLI
$ code --add-mcp '{"name":"primate-intelligence-mcp","type":"stdio","command":"npx","args":["-y","@primate-intelligence/mcp"],"env":{"PRIMATE_API_KEY":"<YOUR_PRIMATE_API_KEY>"}}'Install Primate Vision MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"primate-intelligence-mcp": {
"command": "npx",
"args": [
"-y",
"@primate-intelligence/mcp"
],
"env": {
"PRIMATE_API_KEY": "<YOUR_PRIMATE_API_KEY>"
}
}
}
}Install Primate Vision MCP in Codex
$ codex mcp add primate-intelligence-mcp --env 'PRIMATE_API_KEY=<YOUR_PRIMATE_API_KEY>' -- npx -y @primate-intelligence/mcpInstall Primate Vision MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.primate-intelligence-mcp] command = "npx" args = ["-y", "@primate-intelligence/mcp"] [mcp_servers.primate-intelligence-mcp.env] PRIMATE_API_KEY = "<YOUR_PRIMATE_API_KEY>"
Install Primate Vision MCP in Gemini CLI
$ gemini mcp add -s user -e 'PRIMATE_API_KEY=<YOUR_PRIMATE_API_KEY>' primate-intelligence-mcp npx -- -y @primate-intelligence/mcpInstall Primate Vision MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"primate-intelligence-mcp": {
"command": "npx",
"args": [
"-y",
"@primate-intelligence/mcp"
],
"env": {
"PRIMATE_API_KEY": "<YOUR_PRIMATE_API_KEY>"
}
}
}
}Primate Vision MCP tools 10
Detected from the READMEcreate_video_from_urlcreate_analysisvalidate_analysiscreate_analysis_batchget_analysiswait_for_analysislist_modelsget_usageget_creditsget_test_fixture
| create_video_from_url | — | |
| create_analysis | — | |
| validate_analysis | — | |
| create_analysis_batch | — | |
| get_analysis | — | |
| wait_for_analysis | — | |
| list_models | — | |
| get_usage | — | |
| get_credits | — | |
| get_test_fixture | — |
Configuration
PRIMATE_API_KEYRequiredSecretPrimate Vision API key (get a free one at https://primateintelligence.ai/docs/agents)
| Name | Description | |
|---|---|---|
| PRIMATE_API_KEY | Primate Vision API key (get a free one at https://primateintelligence.ai/docs/agents) | RequiredSecret |
Automated checks
Ran Nov 14, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachableprimate-intelligence/primate-intelligence-mcp is public and reachablegithub.com/primate-intelligence/primate-intelligence-mcp ↗Pass
- Package names this repository as its source@primate-intelligence/mcp names primate-intelligence/primate-intelligence-mcp as sourcenpmjs.com/package/@primate-intelligence/mcp ↗Pass
- Build provenance (Sigstore attestation)No build attestation published for this releaseNot checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-08-01github.com/primate-intelligence/primate-intelligence-mcp ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from @primate-intelligence/mcpPass
- No critical advisory in the package or its dependencies4 resolved dependencies checked; no critical advisoryosv.dev ↗Pass
- No hidden instructions to the model10 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNo tool named like delete, drop or execPass
- Remote endpoint answers the MCP handshakeHTTPS endpoint answered 401 (sign-in required)Pass
README
View on GitHub@primate-intelligence/mcp
MCP (Model Context Protocol) server for the Primate Vision video analysis API — a video understanding API by Primate Intelligence (docs · llms.txt).
Gives AI agents video scene understanding as tools: register a video, ask a question in plain English, get a deterministic answer with a confidence score and clip timestamps. No hallucinated descriptions — the answer is yes / no / indeterminate with evidence.
Try it for free
A free test key requires no email, no card, no signup:
curl -X POST https://api.primateintelligence.ai/v1/sandbox
Your AI agent can do this for you — right from Claude. Point it at primateintelligence.ai/llms.txt and it can discover, provision, integrate, and self-verify with zero human steps.
Two ways to connect
1. Remote server (recommended) — OAuth, nothing to install
Streamable HTTP endpoint with full OAuth 2.1 + Dynamic Client Registration + PKCE:
https://api.primateintelligence.ai/mcp
In Claude.ai / Claude Desktop: Settings → Connectors → Add custom connector, paste the URL, sign in. No API key handling — the OAuth flow issues and rotates tokens for you.
2. Local stdio server
// claude_desktop_config.json · .mcp.json · mcp.json · .cursor/mcp.json
{
"mcpServers": {
"primate-intelligence": {
"command": "npx",
"args": ["-y", "@primate-intelligence/mcp"],
"env": { "PRIMATE_API_KEY": "pv_live_…" }
}
}
}
Tools
| Tool | Does | Read-only |
|---|---|---|
create_video_from_url |
Register a video from a public https URL (POST /v1/videos) |
— |
create_analysis |
Ask a question about a video (POST /v1/analyses) |
— |
validate_analysis |
Dry-run a prompt: assessability + cost estimate, zero credits (validate_only: true) |
✓ |
create_analysis_batch |
2–10 prompts on one video; each after the first billed at 50% (POST /v1/analyses/batch) |
— |
get_analysis |
Fetch analysis status/result (GET /v1/analyses/{id}) |
✓ |
wait_for_analysis |
Poll until terminal state; returns { analysis, retry } |
✓ |
list_models |
List available models (GET /v1/models) |
✓ |
get_usage |
Credit balance + period meters (GET /v1/usage) |
✓ |
get_credits |
Balance + per-analysis transaction ledger (GET /v1/credits) |
✓ |
get_test_fixture |
Stable fixture for integration self-verification (GET /v1/test-fixture) |
✓ |
Every tool carries MCP annotations (title, readOnlyHint, destructiveHint, idempotentHint, openWorldHint), declares an outputSchema, and returns structuredContent conforming to it. No tool deletes data. Tool descriptions and schemas mirror the OpenAPI document at GET /v1/openapi.json — the spec is the source of truth.
Typical agent flow
get_test_fixture→ verify the integration works (test keys return deterministic results, no quota burn)create_video_from_urlwith the video URLvalidate_analysis→ confirm the prompt is assessable + previewestimated_cost_usd(free)create_analysiswith the question — "Is there a person in this video?" — orcreate_analysis_batchfor severalwait_for_analysis→result.answer(yes|no|indeterminate) +result.confidence+result.clips+result.detected_count(count queries) +result.indeterminate_reason- On
insufficient_credits: callget_credits, report the balance + recent debits, point the human at billing
Security contract
The API key is read from the PRIMATE_API_KEY environment variable only. No tool accepts a key, token, or secret as an argument — so credentials never land in agent transcripts, tool-call logs, or model context. This is enforced by a unit test that fails the build if any tool schema grows a credential-shaped parameter.
Errors surface the machine-readable error code, a docs_url, and the request_id so an agent can self-correct without a human in the loop.
Configuration
| Var | Required | Default |
|---|---|---|
PRIMATE_API_KEY |
yes | — |
PRIMATE_BASE_URL |
no | https://api.primateintelligence.ai |
Development
npm install
npm test # vitest — tool surface, security contract, polling, error shape
npm run build # tsc → dist/
Links
- Quickstart for AI agents — the zero-human-intervention integration path
- API docs
- OpenAPI 3.1 spec
- Error registry
- llms.txt — machine-readable index for agents
- Privacy policy · Terms
License
MIT © Primate AI, Inc.
Primate Vision MCP questions
How do I add Primate Vision MCP to Claude Code?
Run claude mcp add --env 'PRIMATE_API_KEY=<YOUR_PRIMATE_API_KEY>' primate-intelligence-mcp -- npx -y @primate-intelligence/mcp in your terminal. Add --scope user to make it available in every project.
How do I add Primate Vision MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does Primate Vision MCP provide?
It exposes 10 tools, including create_video_from_url, create_analysis, validate_analysis, create_analysis_batch, get_analysis.
What kind of answers does the video analysis provide?
The API provides deterministic answers (yes, no, or indeterminate) along with confidence scores and clip timestamps to prevent hallucinations.
Is it possible to estimate the cost of an analysis before running it?
Yes, you can use the validate_analysis tool to perform a dry-run that assesses the prompt and provides a cost estimate for free.