Convai Analytics

@convai/analytics-mcp

Convai Analytics 用のローカル stdio MCP サーバーです。

このパッケージは、Convai Analytics に推奨されるエージェントインターフェースです。カスタム SDK スクリプトを作成することなく、MCP 対応エージェントが Convai のセッション、レイテンシ、信頼性、使用状況、プロバイダー／モデルのパフォーマンスに関する質問に回答できるようにします。公開されている @convai/analytics TypeScript SDK をラップし、CONVAI_API_KEY を使用して、構造化 JSON と Vega-Lite チャート仕様を返します。

パッケージ：@convai/analytics-mcp

公式 MCP Registry 名：io.github.Conv-AI/convai-analytics-mcp

インストールと実行

export CONVAI_API_KEY="ck_live_your_key_here"
npx -y @convai/analytics-mcp@latest

任意：

export CONVAI_ANALYTICS_BASE_URL="https://analytics-api.convai.com/v1/analytics"

本番環境では CONVAI_ANALYTICS_BASE_URL を設定しないでください。API キーをソースコード、コミットする MCP 設定、スクリーンショット、ログに含めないでください。

MCP 設定を追加または変更した後は、Claude Desktop、Claude Code、Cursor、Codex、または MCP ホストを再起動して、サーバーコマンドと CONVAI_API_KEY を再読み込みしてください。

Claude Desktop

{
  "mcpServers": {
    "convai-analytics": {
      "command": "npx",
      "args": ["-y", "@convai/analytics-mcp@latest"],
      "env": {
        "CONVAI_API_KEY": "ck_live_your_key_here"
      }
    }
  }
}

この設定を保存した後、Claude Desktop を終了して再度開き、新しい MCP サーバーを起動してください。

Cursor／Codex 対応 MCP クライアント

同じ stdio コマンドを使用します：

{
  "command": "npx",
  "args": ["-y", "@convai/analytics-mcp@latest"],
  "env": {
    "CONVAI_API_KEY": "ck_live_your_key_here"
  }
}

Claude Code、Cursor、Codex 対応クライアント、その他の stdio MCP ホストでは、MCP 設定を追加または変更した後、クライアントを再起動するか、新しいセッションを開始してください。

セキュリティモデル

このサーバーは顧客向けであり、公開しても安全な設計になっています：

• @convai/analytics を介して、公開されている Convai Analytics API のみを呼び出します。
• アカウントのオーバーライド、サービス認証情報、データベース URL、その他の内部アクセス経路は受け付けません。
• アカウントのスコープ設定、プランによる制限、クォータの適用は、ホストされた分析 API のサーバー側で行われます。
• ツールの結果はサニタイズされるため、エラーに CONVAI_API_KEY が出力されることはありません。

ツール

コアおよびアカウント関連のツール：

• get_summary
• get_metrics_catalog
• list_sessions
• get_session_timeline
• get_interaction_trace

レイテンシ関連のツール：

• get_p95_latency_over_time
• get_latency_percentile_series
• get_latency_percentile_chart
• get_latency_threshold_chart
• get_latency_heatmap_chart
• get_component_latency_breakdown
• generate_component_latency_chart
• find_component_latency_bottlenecks
• generate_interaction_waterfall
• explain_slow_session

信頼性関連のツール：

• get_error_trend
• generate_error_trend_chart
• get_error_breakdown
• generate_error_breakdown_chart
• get_dropped_error_persist_trend
• generate_dropped_error_persist_chart
• generate_reliability_summary_chart
• generate_reliability_trends_chart

これらの信頼性関連ツールは、現在利用可能なエラーおよび永続化失敗の指標を使用します。エージェントがステータス分布を尋ねた場合、返された行に実際の空でないステータスグループが含まれているときに限り group_by=status を使用してください。それ以外の場合は、その期間ではステータスタグ付きの集計テレメトリを利用できないと報告してください。

使用状況と同時実行数に関するツール：

• get_usage_trends
• generate_usage_trends_chart
• get_character_usage_leaderboard
• generate_character_usage_chart
• generate_session_duration_scatter
• estimate_active_session_concurrency
• generate_active_session_concurrency_chart
• generate_peak_concurrency_chart

プロバイダーとモデルに関するツール：

• get_tts_provider_attribution
• generate_tts_provider_chart
• get_llm_model_latency
• generate_llm_model_latency_chart
• compare_providers

プランによって利用が制限される高度なツール：

• detect_regressions
• advanced_query

プランによって利用が制限されるツールは、402／403 レスポンスに対して、必要なプランをメッセージに含む型付き MCP ツールエラーを返します。

プロンプト

このサーバーは、一般的な顧客からの質問に対応するプロンプトテンプレートを公開します：

• why_was_this_session_slow
• aggregate_latency_distribution
• p95_latency_trend
• component_bottlenecks
• trace_explanation
• error_rate_trends
• provider_comparison
• usage_summary

リソース

• convai://analytics/docs/concepts
• convai://analytics/docs/metrics-reference
• convai://analytics/docs/authentication
• convai://analytics/catalog

CONVAI_API_KEY が利用可能な場合、カタログリソースは呼び出し元のアカウントカタログを取得します。

質問の例

How many interactions and unique end users did I have in the last 30 days?
Break it down by character and generate a usage trend chart.

Show aggregate P50/P95/P99 voice.user_to_bot_latency for production readiness sign-off.
Add a 3000 ms p95 threshold line and summarize the worst buckets.

Explain why session s_123 was slow and generate an interaction waterfall if there is a traceable interaction.

Show reliability trends, errors by component, and dropped error-persistence events.

Estimate active session concurrency and show the peak concurrency chart.

ローカル開発

リポジトリのルートから実行します。

make mcp-install
make mcp-lint
make mcp-test
make mcp-build
make mcp-smoke

独自のキーを使用して本番環境に対するライブスモークテストを行います。

export CONVAI_API_KEY="ck_live_your_key_here"
export CONVAI_ANALYTICS_BASE_URL="https://analytics-api.convai.com/v1/analytics"
export CONVAI_ANALYTICS_E2E_RANGE="last_30d"
cd packages/mcp
npm run e2e:prod

ライブスモークテストでは、最近のトラフィックがないアカウントについてはデータが空でも受け入れ、プランによって制限された 402/403 レスポンスは有効な制限結果として扱います。

検出

正規の MCP レジストリマニフェストは server.json です。このサーバーは npm と Official MCP Registry に公開されています。GitHub MCP Registry、Smithery、Glama、PulseMCP、mcp.so、Docker MCP Catalog などの追加ディレクトリやマーケットプレイスでは、同じパッケージとレジストリメタデータを参照できます。