@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

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

1. `get_test_fixture` → verify the integration works (test keys return deterministic results, no quota burn)

2. `create_video_from_url` with the video URL

3. `validate_analysis` → confirm the prompt is assessable + preview `estimated_cost_usd` (free)

4. `create_analysis` with the question — *"Is there a person in this video?"* — or `create_analysis_batch` for several

5. `wait_for_analysis` → `result.answer` (`yes` | `no` | `indeterminate`) + `result.confidence` + `result.clips` + `result.detected_count` (count queries) + `result.indeterminate_reason`

6. 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

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.