Primate Intelligence

Análise de vídeo em tempo real para agentes de IA — envie uma URL de vídeo, faça uma pergunta em inglês simples, obtenha uma resposta determinística sim/não com pontuação de confiança e timestamps do clipe.

GitHub

Documentação

@primate-intelligence/mcp

Servidor MCP (Model Context Protocol) para a API de análise de vídeo Primate Vision — uma API de compreensão de vídeo da Primate Intelligence (documentação · llms.txt).

Oferece a agentes de IA compreensão de cenas de vídeo como ferramentas: registre um vídeo, faça uma pergunta em inglês simples, obtenha uma resposta determinística com pontuação de confiança e timestamps de clipes. Sem descrições alucinadas — a resposta é yes / no / indeterminate com evidências.

Experimente gratuitamente

Uma chave de teste gratuita não exige e-mail, cartão ou cadastro:

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

Seu agente de IA pode fazer isso por você — direto do Claude. Aponte-o para primateintelligence.ai/llms.txt e ele pode descobrir, provisionar, integrar e autoverificar com zero etapas humanas.

Duas formas de conectar

1. Servidor remoto (recomendado) — OAuth, nada para instalar

Endpoint HTTP streamable com OAuth 2.1 completo + Dynamic Client Registration + PKCE:

https://api.primateintelligence.ai/mcp

No Claude.ai / Claude Desktop: Configurações → Conectores → Adicionar conector personalizado, cole a URL, faça login. Sem manipulação de chave de API — o fluxo OAuth emite e rotaciona tokens para você.

2. Servidor stdio local

// 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_…" }
    }
  }
}

Ferramentas

Ferramenta	Função	Somente leitura
`create_video_from_url`	Registrar um vídeo a partir de uma URL https pública (`POST /v1/videos`)	—
`create_analysis`	Fazer uma pergunta sobre um vídeo (`POST /v1/analyses`)	—
`validate_analysis`	Teste de prompt: avaliabilidade + estimativa de custo, zero créditos (`validate_only: true`)	✓
`create_analysis_batch`	2–10 prompts em um vídeo; cada um após o primeiro cobrado a 50% (`POST /v1/analyses/batch`)	—
`get_analysis`	Buscar status/resultado da análise (`GET /v1/analyses/{id}`)	✓
`wait_for_analysis`	Poll até estado terminal; retorna `{ analysis, retry }`	✓
`list_models`	Listar modelos disponíveis (`GET /v1/models`)	✓
`get_usage`	Saldo de créditos + medidores de período (`GET /v1/usage`)	✓
`get_credits`	Saldo + ledger de transações por análise (`GET /v1/credits`)	✓
`get_test_fixture`	Fixture estável para autoverificação de integração (`GET /v1/test-fixture`)	✓

Cada ferramenta carrega anotações MCP (title, readOnlyHint, destructiveHint, idempotentHint, openWorldHint), declara um outputSchema e retorna structuredContent em conformidade com ele. Nenhuma ferramenta exclui dados. Descrições e schemas das ferramentas espelham o documento OpenAPI em GET /v1/openapi.json — a especificação é a fonte da verdade.

Fluxo típico do agente

get_test_fixture → verificar se a integração funciona (chaves de teste retornam resultados determinísticos, sem consumo de cota)
create_video_from_url com a URL do vídeo
validate_analysis → confirmar que o prompt é avaliável + pré-visualizar estimated_cost_usd (grátis)
create_analysis com a pergunta — "Há uma pessoa neste vídeo?" — ou create_analysis_batch para várias
wait_for_analysis → result.answer (yes | no | indeterminate) + result.confidence + result.clips + result.detected_count (consultas de contagem) + result.indeterminate_reason
Em insufficient_credits: chamar get_credits, relatar o saldo + débitos recentes, apontar o humano para cobrança

Contrato de segurança

A chave de API é lida da variável de ambiente PRIMATE_API_KEY apenas. Nenhuma ferramenta aceita chave, token ou segredo como argumento — então credenciais nunca aparecem em transcrições de agente, logs de chamadas de ferramenta ou contexto do modelo. Isso é garantido por um teste unitário que falha o build se qualquer schema de ferramenta ganhar um parâmetro com formato de credencial.

Erros exibem o erro legível por máquina code, um docs_url e o request_id para que um agente possa se autocorrigir sem intervenção humana.

Configuração

Variável	Obrigatória	Padrão
`PRIMATE_API_KEY`	sim	—
`PRIMATE_BASE_URL`	não	`https://api.primateintelligence.ai`

Desenvolvimento

npm install
npm test        # vitest — tool surface, security contract, polling, error shape
npm run build   # tsc → dist/