@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:

Terminal

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:

Code

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

jsonc

// 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_url with the video URL
validate_analysis → confirm the prompt is assessable + preview estimated_cost_usd (free)
create_analysis with the question — "Is there a person in this video?" — or create_analysis_batch for several
wait_for_analysis → result.answer (yes | no | indeterminate) + result.confidence + result.clips + result.detected_count (count queries) + result.indeterminate_reason
On insufficient_credits: call get_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