primateintelligence

@primate-intelligence/mcp

Primate Vision video analysis API（Primate Intelligenceによる動画理解 API）の MCP（Model Context Protocol）サーバーです（ドキュメント・llms.txt）。

AI エージェントに、動画シーンを理解するためのツールを提供します。動画を登録し、平易な英語で質問すると、信頼度スコアとクリップのタイムスタンプ付きで、確定的な回答を取得できます。説明を幻覚で作り出すことはありません。回答は証拠に基づく yes ／ no ／ indeterminate です。

無料で試す

無料のテストキーの取得に、メールアドレス、カード、登録は必要ありません。

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

AI エージェントが Claude から直接、これらの作業を代行できます。 primateintelligence.ai/llms.txt を指定すると、人間の操作なしで検出、プロビジョニング、統合、自己検証を行えます。

2 つの接続方法

1. リモートサーバー（推奨）— OAuth、インストール不要

OAuth 2.1 + 動的クライアント登録 + PKCE に完全対応した Streamable HTTP エンドポイントです。

https://api.primateintelligence.ai/mcp

Claude.ai ／ Claude Desktop で、Settings → Connectors → Add custom connector を選択し、URL を貼り付けてサインインします。API キーを扱う必要はありません。OAuth フローによってトークンが発行・ローテーションされます。

2. ローカル stdio サーバー

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

ツール

ツール	説明	読み取り専用
create_video_from_url	公開された https URL から動画を登録します（POST /v1/videos）	—
create_analysis	動画について質問します（POST /v1/analyses）	—
validate_analysis	プロンプトをドライランし、評価可能性とコストを見積もります。クレジットは消費しません（validate_only: true）	✓
create_analysis_batch	1 本の動画に対して 2～10 件のプロンプトを実行します。2 件目以降は 50% の料金です（POST /v1/analyses/batch）	—
get_analysis	分析のステータス／結果を取得します（GET /v1/analyses/{id}）	✓
wait_for_analysis	終端状態になるまでポーリングし、{ analysis, retry } を返します	✓
list_models	利用可能なモデルを一覧表示します（GET /v1/models）	✓
get_usage	クレジット残高と期間ごとの使用状況を取得します（GET /v1/usage）	✓
get_credits	残高と分析ごとの取引履歴を取得します（GET /v1/credits）	✓
get_test_fixture	統合の自己検証に使う安定したフィクスチャを取得します（GET /v1/test-fixture）	✓

各ツールには MCP アノテーション（title、readOnlyHint、destructiveHint、idempotentHint、openWorldHint）が付与され、outputSchema が宣言されており、それに準拠した structuredContent を返します。データを削除するツールはありません。ツールの説明とスキーマは、GET /v1/openapi.json の OpenAPI ドキュメントと一致しています。仕様が信頼できる唯一の情報源です。

エージェントの一般的なワークフロー

1. get_test_fixture → 統合が機能することを検証します（テストキーはクォータを消費せず、確定的な結果を返します）
2. 動画の URL を指定して create_video_from_url を実行します
3. validate_analysis → プロンプトが評価可能であることを確認し、estimated_cost_usd を事前に確認します（無料）
4. 質問 — 「この動画に人物はいますか？」 — を指定して create_analysis を実行します。複数の質問には create_analysis_batch を使います
5. wait_for_analysis → result.answer（yes ／ no ／ indeterminate）+ result.confidence + result.clips + result.detected_count（件数の質問の場合）+ result.indeterminate_reason
6. insufficient_credits の場合：get_credits を呼び出し、残高と最近の引き落としを報告して、人間に請求ページを案内します

セキュリティ契約

API キーは、PRIMATE_API_KEY 環境変数のみから読み取られます。キー、トークン、シークレットを引数として受け取るツールはありません。そのため、認証情報がエージェントのトランスクリプト、ツール呼び出しログ、モデルコンテキストに残ることはありません。いずれかのツールスキーマに認証情報に該当するパラメーターが追加されるとビルドが失敗するユニットテストによって、この仕様を徹底しています。

エラーでは、機械可読なエラー code、docs_url、request_id が示されるため、エージェントは人間の介入なしに自己修正できます。

設定

変数	必須	デフォルト
PRIMATE_API_KEY	はい	—
PRIMATE_BASE_URL	いいえ	https://api.primateintelligence.ai

開発

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

リンク

• AI エージェント向けクイックスタート — 人間の介入なしで統合する手順
• API ドキュメント
• OpenAPI 3.1 仕様
• エラーレジストリ
• llms.txt — エージェント向けの機械可読インデックス
• プライバシーポリシー · 利用規約

ライセンス

MIT © Primate AI, Inc.