ai.primateintelligence/mcp
Video scene understanding for AI agents via the Primate Vision API.
Open source Repository Open in the app JSON README (API)
About
Video scene understanding for AI agents via the Primate Vision API.
Details
- Kind
- MCP servers
- Topic
- No topic detected
- Publisher
- ai.primateintelligence
- Origin
- official
- Category
- ferramentas
- Transport
- http
- Version
- 0.4.0
- Last push
- 2026-08-01T21:41:38Z
- Repository state
- ativo
- Language
- TypeScript
- License
- MIT
- Added
- 2026-08-29 03:00:36
- Updated
- 2026-08-29 03:00:36
- Origin id
ai.primateintelligence/mcp
README
# @primate-intelligence/mcp
[](https://www.npmjs.com/package/@primate-intelligence/mcp)
[](./LICENSE)
MCP ([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)).
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:
```bash
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](https://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
```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`](https://api.primateintelligence.ai/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
| Var | Required | Default |
|---|---|---|
| `PRIMATE_API_KEY` | yes | — |
| `PRIMATE_BASE_URL` | no | `https://api.primateintelligence.ai` |
## Development
```bash
npm install
npm test # vitest — tool surface, security contract, polling, error shape
npm run build # tsc → dist/
```
## Links
- [Quickstart for AI agents](https://primateintelligence.ai/docs/agents) — the zero-human-intervention integration path
- [API docs](https://primateintelligence.ai/docs)
- [OpenAPI 3.1 spec](https://api.primateintelligence.ai/v1/openapi.json)
- [Error registry](https://primateintelligence.ai/docs/errors)
- [llms.txt](https://primateintelligence.ai/llms.txt) — machine-readable index for agents
- [Privacy policy](https://primateintelligence.ai/privacy) · [Terms](https://primateintelligence.ai/terms)
## License
MIT © Primate AI, Inc.