Ptengine MCP 接続ガイド
Claude・ChatGPT・Codex・Cursor などの AI アシスタントから、MCP プロトコル経由で Ptengine のデータを直接照会できます。コーディングは不要です。一度認可すれば、PV/UV・ファネル・ユーザー行動パス・A/B テストなどのデータを、会話の中で自然言語のまま分析できます。
Ptengine MCP は現在段階的に提供しており、クエリ権限はプロファイルごとの有効化が必要です。権限が有効になっていないプロファイルでは、MCP の接続・認可が成功してもデータは返されません。ご利用をご希望の場合は、利用申請フォームからお申し込みいただくか、担当者までお問い合わせください。
概要
Ptengine MCP Server は、Model Context Protocol に基づくリモートツールサービスです。AI クライアントを接続すると、読み取り専用の分析ツール群を呼び出せるようになり、Ptengine アカウントのデータを AI との対話に取り込めます。
利用開始までの 4 ステップ：
接続 — AI クライアントに Ptengine MCP Server を追加する
認可 — ブラウザで一度だけ OAuth 認可を行う（Google / GitHub へのログインと同じ流れ）
質問 — 自然言語でデータについて質問すると、AI が適切なツールを自動選択する
再利用 — 認可情報は自動でキャッシュ・更新されるため、次回からはそのまま使える
MCP Server アドレス
MCP Server URL
https://mcp.ptengine.com/open-api/v1/mcp
利用できるツール
すべてのツールは読み取り専用です。集計済みの分析結果のみを返し、アカウントの設定は一切変更しません。
クエリ・分析
Run-Query
統一クエリの入口。queryType に応じて各分析機能へルーティング
List-Query-Types
サポートされているクエリタイプの一覧と概要を取得
Get-Query-Schema
特定のクエリタイプのパラメータ仕様を取得
データ探索
List-Profiles
アクセス可能なプロファイル（サイト）の一覧
List-Catalog
プロファイル単位のカタログを取得する統一入口。kind で対象を指定
Get-Current-Account
現在の認可アカウントを確認（whoami）：アカウント id・メール・認可方式・スコープ
List-Catalog で指定できる kind：
pages
トラフィック上位ページ（URL キーワードでの絞り込みも可能）
events
イベントカタログ（ビジネス用語の別名を含む）
event_properties
イベントプロパティ（プロパティ別のグループ化 / 絞り込みに使用）
user_properties
ユーザープロパティ（標準 + CRM / データコネクタ連携分）
experiences
A/B テスト / エンゲージメント（goals・versions を含む）
goals
goal とコンバージョンの統合カタログ
page_groups
ページグループ（ページグループ型コンバージョンが参照する group id → 名称）
ツールの変更について：List-Pages・List-Events・List-Event-Properties・List-User-Properties・List-Experiences・List-Goals は List-Catalog(kind=…) に統合されました。旧ツールは既存の設定との互換性のため残されています（deprecated 扱い）が、List-Catalog への移行を推奨します。List-Page-Groups は廃止されたため、List-Catalog(kind=page_groups) をご利用ください。
Get-User-Journey・Get-Experience-Report の 2 つの独立ツールも廃止され、Run-Query のクエリタイプ user_journey・experience_report に統合されました（下表参照）。
サポートされているクエリタイプ（Run-Query）
page_insight
単一ページの指標を 1 つのディメンションで分解（デバイス/流入元/訪問タイプ/UTM/日別/週別）
「デバイス別 / 流入元別 / 日別で分解して」
page_block_metrics
単一ページのブロック単位ヒートマップ指標（表示/離脱/滞在）、デバイス別
「ファーストビュー各ブロックの表示と離脱は？」
experience_abtest_report
単一 A/B テストの バージョン × goal + 改善率。ディメンション分解も可能
「テスト X でコンバージョンは何 % 改善した？ / スマホではどのバージョンが勝った？」
experiment_attributed_funnel
複数テストがイベントファネルに与えた寄与（first/last/all）
「テスト A/B/C は ログイン→購入 ファネルをどれだけ押し上げた？」
experience_report
単一テストの全体合計レポート（バージョン分解なし・改善率なし）。単一ディメンション分解も可能
「テスト X の全体の結果は？ / デバイス別の推移を見せて」
traffic_insight
サイト全体の基本パフォーマンス：固定 12 指標（訪問/新規訪問率/直帰/滞在/PV/クリック/離脱など）。単一ディメンションでの分解も可能
「直近 30 日のサイト全体の状況は？ / 流入元別で分解して」
event_insight
イベント単位の行動：発生回数・発生ユーザー数・コンバージョン率。イベントプロパティの集計（合計/平均など）や単一ディメンション分解も可能
「カート追加イベントは直近 7 日で何回・何人？ / チャネル別で分解して」
funnel_insight
順序付きイベントファネル：ステップごとのコンバージョン率・離脱・平均所要時間。単一ディメンション分解も可能
「閲覧→カート追加→購入 のどのステップで離脱している？」
path_insight
特定のページ/イベントを起点としたセッション内の遷移パス（起点の後にどこへ行ったか / どこから来たか）
「このページを見た後、ユーザーはどこへ行った？」
page_transitions
起点を指定しないページ→ページの遷移エッジ（サイト内でどのページが相互に送客しているか）
「サイト内のページ間の遷移関係を見せて」
page_element_metrics
単一ページの要素単位 表示/クリック/クリック率 + goal コンバージョン
「ページ内各要素のクリック率とコンバージョンは？」
experience_search
テストカタログの検索（名前キーワード / ステータス / 作成日時）。name + id + status を返す
「名前に X を含むテストを探して / 実行中のテストは？」
user_overview
個別ユーザーのプロフィール概要
「このユーザーはどんな人？」
user_timeline
個別ユーザーの直近行動タイムライン（直近 20 セッションのサマリー）
「このユーザーは最近何をしている？」
user_session_detail
個別ユーザーの特定セッション内のイベント系列
「このユーザーはあの訪問で具体的に何をした？」
user_journey
個別ユーザーのセッション横断・イベント単位の完全ジャーニー
「このユーザーは最初から最後まで何をした？」
user_list
ユーザーリストの検索（氏名 / メール / userId）。ページング・並び替えに対応
「メールが xxx のユーザーを探して / 最近活動しているユーザーは？」
権限とセキュリティ
読み取り専用 — 照会のみ可能。設定の変更、テストの新規作成、配信の変更はできません
最小権限 — 現在すべてのツールが必要とするのは
query:readの 1 スコープのみデータ範囲 — AI が参照できるのはあなたのアカウントに権限があるプロファイルのみ。MCP によって権限が拡大されることはありません
ユーザーごとの個別認可 — トークンはあなたのアカウントに紐づきます。共有せず、メンバーそれぞれが認可を行ってください
接続方法
Claude
公式ドキュメント：Claude カスタム connector ガイド（Web 版とデスクトップアプリで手順は共通です）
Settings → Connectors → Add custom connector を開き、Name に Ptengine、URL に https://mcp.ptengine.com/open-api/v1/mcp を入力し、Connect をクリックしてブラウザで認可を完了します。
Team / Enterprise アカウントでは、組織の Owner が Organization settings → Connectors で事前に追加する必要があります。その後、メンバーが各自 Connect で認可します。
Claude Code
公式ドキュメント：Claude Code MCP docs
追加後、Claude Code 内で /mcp を実行し、ブラウザで Ptengine の認可を完了します（最初のツール呼び出し時にも認可ページが自動で開きます）。
ChatGPT
公式ドキュメント：ChatGPT Developer mode
Settings → Security and login を開き、Developer mode を有効にします（トグルが表示されない場合は組織の管理者にご確認ください）
Settings → Plugins（または
chatgpt.com/plugins）を開き、+ から connector を新規作成します：Name にPtengine、MCP Server URL にhttps://mcp.ptengine.com/open-api/v1/mcp、Authentication は OAuth を選択しますブラウザで Ptengine の認可を完了します（任意：ワークスペースに公開すると、チームメンバーもそのまま追加できます）
Codex
公式ドキュメント：Codex MCP docs
方法 A：画面から追加
Settings → MCP Servers → + Add Server を開き、Name に Ptengine、種類は Streamable HTTP、URL に https://mcp.ptengine.com/open-api/v1/mcp を入力して Save をクリックします。
方法 B：設定ファイルから追加
~/.codex/config.toml を編集します：
保存後、次のコマンドを実行してブラウザで認可を完了します：
Cursor
公式ドキュメント：Cursor MCP docs
~/.cursor/mcp.json を編集します（または Cursor Settings → Tools & Integrations から MCP Server を新規作成）：
保存後に Cursor を再起動し、Tools & Integrations の一覧で Ptengine の Login をクリックすると（または最初のツール呼び出し時に）、ブラウザでの認可を経てすぐに利用できます。
認可の仕組み
Ptengine MCP は、主要な SaaS と同じ標準の OAuth 2.0 + PKCE を採用しています：
クライアントの初回呼び出し時に、認可エンドポイントの自動検出と登録が行われる（ユーザーの操作は不要）
ブラウザで Ptengine の認可ページが開く → 内容を確認して認可する
クライアントに戻り、アクセストークンが発行される
トークンは短期有効で、期限前に自動更新されるため、再認可は不要
質問の例
「https://example.com/landing の直近 1 週間のパフォーマンスを見せて」 → 対象ページの PV/UV・直帰率・コンバージョンなどの指標を返す
「流入元別に分解して」 → 同じページの指標を流入元ディメンションで分解して比較
「過去 30 日の PV 推移は？」 → 日別の時系列データを返す
「アカウント内の上位 5 ページ、直近 30 日の状況は？」 → まずトラフィック上位ページを取得し、順に照会して比較
「テスト X の結果はどう？」 → 対象の A/B テストを特定し、完全なレポートを返す
よくあるご質問
接続も認可も成功したのに、データが返ってこない — 対象プロファイルで MCP クエリ権限が有効になっているかご確認ください（現在段階的に提供中のため、利用申請フォームからのお申し込みが必要です）。
認可後に読み込みが終わらない / リダイレクトに失敗する — クライアントの認可キャッシュを削除して再試行してください。Claude Code は
rm -rf ~/.claude/mcp-auth/ptengine、Cursor は終了後に~/.cursor/mcp-auth/を削除します。呼び出しが 401 を返す — トークンの期限切れと更新失敗が原因です。もう一度認可を行ってください。
呼び出しが 403
insufficient_scopeを返す — 認可時に権限のチェックを外したことが原因です。再認可し、権限にチェックを入れてください。特定のプロファイルが見えない — Ptengine アカウント自体にそのプロファイルへの権限があるかご確認ください。MCP が権限を拡大することはありません。
同僚も使えますか？ — 認可は 1 人ずつ行います。トークンは共有せず、各自のアカウントで OAuth 認可を行ってください。
最終更新