{
  "markdown": "# @primate-intelligence/mcp\n\n[![npm](https://img.shields.io/npm/v/@primate-intelligence/mcp.svg)](https://www.npmjs.com/package/@primate-intelligence/mcp)\n[![license](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)\n\nMCP ([Model Context Protocol](https://modelcontextprotocol.io)) server for the **Primate Vision video analysis API** — a video understanding API by [Primate Intelligence](https://primateintelligence.ai) ([docs](https://primateintelligence.ai/docs) · [llms.txt](https://primateintelligence.ai/llms.txt)).\n\nGives 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.\n\n## Try it for free\n\nA free test key requires no email, no card, no signup:\n\n```bash\ncurl -X POST https://api.primateintelligence.ai/v1/sandbox\n```\n\nYour AI agent can do this for you — right from Claude. Point it at\n[primateintelligence.ai/llms.txt](https://primateintelligence.ai/llms.txt) and it can\ndiscover, provision, integrate, and self-verify with zero human steps.\n\n## Two ways to connect\n\n### 1. Remote server (recommended) — OAuth, nothing to install\n\nStreamable HTTP endpoint with full OAuth 2.1 + Dynamic Client Registration + PKCE:\n\n```\nhttps://api.primateintelligence.ai/mcp\n```\n\nIn 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.\n\n### 2. Local stdio server\n\n```jsonc\n// claude_desktop_config.json · .mcp.json · mcp.json · .cursor/mcp.json\n{\n  \"mcpServers\": {\n    \"primate-intelligence\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@primate-intelligence/mcp\"],\n      \"env\": { \"PRIMATE_API_KEY\": \"pv_live_…\" }\n    }\n  }\n}\n```\n\n## Tools\n\n| Tool | Does | Read-only |\n|---|---|:--:|\n| `create_video_from_url` | Register a video from a public https URL (`POST /v1/videos`) | — |\n| `create_analysis` | Ask a question about a video (`POST /v1/analyses`) | — |\n| `validate_analysis` | Dry-run a prompt: assessability + cost estimate, zero credits (`validate_only: true`) | ✓ |\n| `create_analysis_batch` | 2–10 prompts on one video; each after the first billed at 50% (`POST /v1/analyses/batch`) | — |\n| `get_analysis` | Fetch analysis status/result (`GET /v1/analyses/{id}`) | ✓ |\n| `wait_for_analysis` | Poll until terminal state; returns `{ analysis, retry }` | ✓ |\n| `list_models` | List available models (`GET /v1/models`) | ✓ |\n| `get_usage` | Credit balance + period meters (`GET /v1/usage`) | ✓ |\n| `get_credits` | Balance + per-analysis transaction ledger (`GET /v1/credits`) | ✓ |\n| `get_test_fixture` | Stable fixture for integration self-verification (`GET /v1/test-fixture`) | ✓ |\n\nEvery 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`](https://api.primateintelligence.ai/v1/openapi.json) — the spec is the source of truth.\n\n## Typical agent flow\n\n1. `get_test_fixture` → verify the integration works (test keys return deterministic results, no quota burn)\n2. `create_video_from_url` with the video URL\n3. `validate_analysis` → confirm the prompt is assessable + preview `estimated_cost_usd` (free)\n4. `create_analysis` with the question — *\"Is there a person in this video?\"* — or `create_analysis_batch` for several\n5. `wait_for_analysis` → `result.answer` (`yes` | `no` | `indeterminate`) + `result.confidence` + `result.clips` + `result.detected_count` (count queries) + `result.indeterminate_reason`\n6. On `insufficient_credits`: call `get_credits`, report the balance + recent debits, point the human at billing\n\n## Security contract\n\nThe 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.\n\nErrors 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.\n\n## Configuration\n\n| Var | Required | Default |\n|---|---|---|\n| `PRIMATE_API_KEY` | yes | — |\n| `PRIMATE_BASE_URL` | no | `https://api.primateintelligence.ai` |\n\n## Development\n\n```bash\nnpm install\nnpm test        # vitest — tool surface, security contract, polling, error shape\nnpm run build   # tsc → dist/\n```\n\n## Links\n\n- [Quickstart for AI agents](https://primateintelligence.ai/docs/agents) — the zero-human-intervention integration path\n- [API docs](https://primateintelligence.ai/docs)\n- [OpenAPI 3.1 spec](https://api.primateintelligence.ai/v1/openapi.json)\n- [Error registry](https://primateintelligence.ai/docs/errors)\n- [llms.txt](https://primateintelligence.ai/llms.txt) — machine-readable index for agents\n- [Privacy policy](https://primateintelligence.ai/privacy) · [Terms](https://primateintelligence.ai/terms)\n\n## License\n\nMIT © Primate AI, Inc.\n",
  "bytes": 5279,
  "sha": "fb5d476ce52ae1fa89e78e3b0bcfe0d56034f553d5a669f0f65b807d729f4cd5",
  "repo_slug": "primate-intelligence/primate-intelligence-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_ai_primateintelligence_mcp_11ae8b9b/readme"
}