@primate-intelligence/mcp

MCP (Model Context Protocol) server for the Primate Vision API by Primate Intelligence. Gives AI agents video scene understanding as tools: register a video, ask a question, get a deterministic answer with confidence and clip timestamps.

Status: built in-repo. Not yet published to npm — run from the repo (node mcp/dist/index.js) until the first public release. A hosted SSE endpoint is planned.

Setup

// claude_desktop_config.json / .mcp.json / mcp.json
{
  "mcpServers": {
    "primate-intelligence": {
      "command": "npx",
      "args": ["@primate-intelligence/mcp"],
      "env": { "PRIMATE_API_KEY": "pv_live_…" }
    }
  }
}

Get a free test key with no signup:

curl -X POST https://api.primateintelligence.ai/v1/sandbox

Security contract: the API key is read from the PRIMATE_API_KEY environment variable only. No tool accepts a key argument — keys never appear in agent transcripts (enforced by a unit test).

Tools (v1.0)

| Tool | Does | |---|---| | 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) | | get_analysis | Fetch analysis status/result (GET /v1/analyses/{id}) | | wait_for_analysis | Poll until terminal state, return the final analysis | | list_models | List available models (GET /v1/models) | | get_usage | Credit balance + period meters (GET /v1/usage) | | get_test_fixture | Stable fixture for integration self-verification (GET /v1/test-fixture) |

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)
2. create_video_from_url with the customer's video URL
3. create_analysis with a question ("Is there a person in this video?")
4. wait_for_analysis → result.answer (yes | no | indeterminate) + result.confidence + result.clips
5. On insufficient_credits: get_usage, report the balance, point the human at billing

Env

| Var | Required | Default | |---|---|---| | PRIMATE_API_KEY | yes | — | | PRIMATE_BASE_URL | no | https://api.primateintelligence.ai |