MCP 連携

Model Context Protocol (MCP) を使うと、AI アシスタントから Zenovay アナリティクスに直接クエリを実行できます。「今週の訪問者数は？」「上位ページは？」といった質問を投げかけるだけで、IDE やチャットを離れることなくダッシュボードのライブデータを取得できます。

クイックスタート

接続は 1 分もかかりません。MCP クライアントにサーバー URL を追加するだけで、あとは OAuth が処理してくれます。

1. MCP サーバーを追加

AI クライアントに Zenovay サーバーの URL を追加します。API キーや手動設定は不要です。

{
"mcpServers": {
  "zenovay-analytics": {
    "url": "https://api.zenovay.com/mcp"
  }
}
}

{
"mcpServers": {
  "zenovay-analytics": {
    "url": "https://api.zenovay.com/mcp"
  }
}
}

{
"servers": {
  "zenovay-analytics": {
    "type": "http",
    "url": "https://api.zenovay.com/mcp"
  }
}
}

{
"mcpServers": {
  "zenovay-analytics": {
    "serverUrl": "https://api.zenovay.com/mcp"
  }
}
}

Claude Code CLI から追加することもできます。

claude mcp add --transport http zenovay-analytics https://api.zenovay.com/mcp

2. アクセスを認可

初回接続時に MCP クライアントがブラウザウィンドウを開き、Zenovay の認可ページが表示されます。このページでは次の操作を行えます。

• チームを選択(複数のチームに所属している場合)
• ツールカテゴリごとに権限を設定(なし / 読み取り / 書き込み)
• 認可をクリックしてアクセスを許可

これは初回のみの設定です。MCP クライアントは OAuth トークンを保存し、自動的に更新します。

3. クエリを実行

認可が完了したら、AI アシスタントに次のような質問ができます。

• 「ウェブサイト一覧を表示して」
• 「今週の zenovay.com の訪問者数は？」
• 「トラフィック上位 10 ページは？」
• 「今週と先週の直帰率を比較して」
• 「トラフィックの異常があれば見せて」
• 「過去 30 日間のアナリティクスを CSV でエクスポート」
• 「サインアップページの新しいゴールを作成」
• 「すべてのゴールとコンバージョン率を表示」
• 「オフィスネットワークの IP 除外を追加」

OAuth 認可の仕組み

MCP クライアントが https://api.zenovay.com/mcp に接続すると、自動的に次の処理が行われます。

1. ディスカバリ — クライアントが /.well-known/oauth-authorization-server から OAuth メタデータを取得
2. 登録 — Dynamic Client Registration によりクライアントが自身を登録(初回のみ)
3. 認可 — ブラウザウィンドウが開き、Zenovay の同意画面が表示される
4. トークン交換 — 認可後、クライアントが認可コードをアクセストークンに交換
5. 接続完了 — 以降の MCP リクエストはすべて OAuth トークンを使用。期限切れになると自動的に更新されます。

接続済みアプリケーションの確認や失効は、Zenovay ダッシュボードの Settings > Usage から行えます。

接続の詳細

権限

認可時に、ツールカテゴリごとにアクセスレベルを選択します。

ツールのカテゴリ

レート制限

1 日あたりのクエリ上限はチーム単位(接続済みのすべてのアプリケーションで共有)です。

ほとんどのツールは1 クエリを消費します。自然言語ツール query_analytics は AI 処理のため3 クエリを消費します。

使用量は毎日 00:00 UTC にリセットされます。残量は get_api_usage ツール、またはダッシュボードの Settings > Usage からいつでも確認できます。

プラン制限の適用

一部の MCP ツールは有料プラン専用です。get_session_replays、get_heatmap_data、get_revenue、get_retention_data などのツールは Pro 以上、export_data は Scale 以上のサブスクリプションが必要です。アナリティクスのクエリは、プランのデータ保持期間に応じて自動的にクランプされます(例: Free は 1 年、Pro は 2 年)。

{
"jsonrpc": "2.0",
"id": 1,
"error": {
  "code": -32002,
  "message": "This feature requires a paid plan. Upgrade at https://app.zenovay.com/plans"
}
}

接続済みアプリケーションの管理

接続中の MCP クライアントの OAuth トークンを確認・失効できます。

1. Zenovay ダッシュボードの Settings > Usage に移動
2. MCP Requests セクションまでスクロール
3. 日次使用量、レート制限、接続済みアプリケーション数を確認
4. アクセスを失効する場合は API Keys に移動してトークンを管理

トークンを失効すると、MCP クライアントは即座に切断されます。再接続には再度認可が必要です。

エラー処理

何らかの問題が発生した場合、サーバーは JSON-RPC エラーを返します。

トラブルシューティング

Claude Code で「Needs authentication」と表示される

OAuth フローが完了していない状態です。claude mcp list でステータスを確認し、新しいセッションを開始してください。ブラウザでの認可を求められます。

認可時にブラウザが開かない

MCP クライアントが OAuth 2.1 に対応しているか確認してください。古いクライアントを使用している場合は更新を確認してください。サーバー URL(https://api.zenovay.com/mcp)のみで OAuth ディスカバリが自動的にトリガーされるはずです。

「Invalid or expired OAuth token」エラー

トークンの有効期限が切れ、自動更新に失敗しました。サーバーをいったん削除して再追加してください。

claude mcp remove zenovay-analytics
claude mcp add --transport http zenovay-analytics https://api.zenovay.com/mcp

レート制限エラー

get_api_usage または Settings > Usage で現在の使用量を確認してください。query_analytics ツールは 3 クエリを消費します。可能であれば get_visitors(1 クエリ)のような専用ツールを使用してください。

AI アシスタント向けプロンプト

AI アシスタントが MCP サーバーを自動検出しない場合、以下のプロンプトを貼り付けると接続を助けられます。

Connect to the Zenovay Analytics MCP server at https://api.zenovay.com/mcp

Authentication: OAuth 2.1 (automatic). When you first connect, a browser window will open for me to authorize access. No API key is needed.

Setup:
- Server URL: https://api.zenovay.com/mcp
- Transport: HTTP (Streamable HTTP, JSON-RPC 2.0)
- OAuth discovery: https://api.zenovay.com/.well-known/oauth-authorization-server

After connecting, call list_websites first to get my website IDs — every analytics tool requires a website_id parameter.

Available tool categories:
- Analytics (8 tools): visitors, pages, traffic sources, geographic data, real-time
- Advanced (13 tools): funnels, goals, sessions, heatmaps, errors, revenue, uptime
- AI Insights (4 tools): AI-generated insights, anomalies, weekly digest, recommendations
- Management (29 tools): website settings, goals, funnels, tracking, reports
- Settings (16 tools): IP exclusions, notifications, team members, domains
- Webhooks (6 tools): webhook CRUD, deliveries, automation rules

Rate limits: Free 25/day, Pro 100/day, Scale 500/day, Enterprise 10,000/day. The query_analytics tool costs 3 queries; all others cost 1.

次のステップ

• Tools Reference — すべてのツールのパラメータと例を含む完全なドキュメント
• Permissions & Limits — アクセスモード、レート制限、エラーコード