> For the complete documentation index, see [llms.txt](https://helps.ptengine.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://helps.ptengine.com/ai/mcp.md).

# Ptengine MCP 接続ガイド

Claude・ChatGPT・Codex・Cursor などの AI アシスタントから、MCP プロトコル経由で Ptengine のデータを直接照会できます。コーディングは不要です。一度認可すれば、PV/UV・ファネル・ユーザー行動パス・A/B テストなどのデータを、会話の中で自然言語のまま分析できます。

{% hint style="warning" %}
Ptengine MCP は現在段階的に提供しており、クエリ権限は**プロファイルごとの有効化**が必要です。権限が有効になっていないプロファイルでは、MCP の接続・認可が成功してもデータは返されません。ご利用をご希望の場合は、[利用申請フォーム](https://ptmafia.notion.site/9e56643a981983aeb35c0100c860d3bd)からお申し込みいただくか、担当者までお問い合わせください。
{% endhint %}

## 概要

Ptengine MCP Server は、[Model Context Protocol](https://modelcontextprotocol.io/) に基づくリモートツールサービスです。AI クライアントを接続すると、**読み取り専用**の分析ツール群を呼び出せるようになり、Ptengine アカウントのデータを AI との対話に取り込めます。

利用開始までの 4 ステップ：

1. **接続** — AI クライアントに Ptengine MCP Server を追加する
2. **認可** — ブラウザで一度だけ OAuth 認可を行う（Google / GitHub へのログインと同じ流れ）
3. **質問** — 自然言語でデータについて質問すると、AI が適切なツールを自動選択する
4. **再利用** — 認可情報は自動でキャッシュ・更新されるため、次回からはそのまま使える

## 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`：

| kind               | 取得できる内容                                     |
| ------------------ | ------------------------------------------- |
| `pages`            | トラフィック上位ページ（URL キーワードでの絞り込みも可能）             |
| `events`           | イベントカタログ（ビジネス用語の別名を含む）                      |
| `event_properties` | イベントプロパティ（プロパティ別のグループ化 / 絞り込みに使用）           |
| `user_properties`  | ユーザープロパティ（標準 + CRM / データコネクタ連携分）            |
| `experiences`      | A/B テスト / エンゲージメント（goals・versions を含む）      |
| `goals`            | goal とコンバージョンの統合カタログ                        |
| `page_groups`      | ページグループ（ページグループ型コンバージョンが参照する group id → 名称） |

{% hint style="info" %}
**ツールの変更について**：`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` に統合されました（下表参照）。
{% endhint %}

### サポートされているクエリタイプ（`Run-Query`）

| queryType                      | 用途                                                                     | 質問例                                            |
| ------------------------------ | ---------------------------------------------------------------------- | ---------------------------------------------- |
| `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 ガイド](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp)（Web 版とデスクトップアプリで手順は共通です）

**Settings → Connectors → Add custom connector** を開き、Name に `Ptengine`、URL に `https://mcp.ptengine.com/open-api/v1/mcp` を入力し、**Connect** をクリックしてブラウザで認可を完了します。

{% hint style="info" %}
Team / Enterprise アカウントでは、組織の Owner が **Organization settings → Connectors** で事前に追加する必要があります。その後、メンバーが各自 **Connect** で認可します。
{% endhint %}

### Claude Code

公式ドキュメント：[Claude Code MCP docs](https://code.claude.com/docs/en/mcp)

```bash
claude mcp add ptengine --transport http https://mcp.ptengine.com/open-api/v1/mcp
```

追加後、Claude Code 内で `/mcp` を実行し、ブラウザで Ptengine の認可を完了します（最初のツール呼び出し時にも認可ページが自動で開きます）。

### ChatGPT

公式ドキュメント：[ChatGPT Developer mode](https://developers.openai.com/api/docs/guides/developer-mode)

1. **Settings → Security and login** を開き、**Developer mode** を有効にします（トグルが表示されない場合は組織の管理者にご確認ください）
2. **Settings → Plugins**（または `chatgpt.com/plugins`）を開き、**+** から connector を新規作成します：Name に `Ptengine`、MCP Server URL に `https://mcp.ptengine.com/open-api/v1/mcp`、Authentication は **OAuth** を選択します
3. ブラウザで Ptengine の認可を完了します（任意：ワークスペースに公開すると、チームメンバーもそのまま追加できます）

### Codex

公式ドキュメント：[Codex MCP docs](https://developers.openai.com/codex/mcp)

**方法 A：画面から追加**

**Settings → MCP Servers → + Add Server** を開き、Name に `Ptengine`、種類は **Streamable HTTP**、URL に `https://mcp.ptengine.com/open-api/v1/mcp` を入力して **Save** をクリックします。

**方法 B：設定ファイルから追加**

`~/.codex/config.toml` を編集します：

```toml
[mcp_servers.ptengine]
url = "https://mcp.ptengine.com/open-api/v1/mcp"
```

保存後、次のコマンドを実行してブラウザで認可を完了します：

```bash
codex mcp login ptengine
```

### Cursor

公式ドキュメント：[Cursor MCP docs](https://cursor.com/docs/mcp)

`~/.cursor/mcp.json` を編集します（または Cursor Settings → **Tools & Integrations** から MCP Server を新規作成）：

```json
{
  "mcpServers": {
    "ptengine": {
      "url": "https://mcp.ptengine.com/open-api/v1/mcp",
      "transport": "http"
    }
  }
}
```

保存後に Cursor を再起動し、**Tools & Integrations** の一覧で Ptengine の **Login** をクリックすると（または最初のツール呼び出し時に）、ブラウザでの認可を経てすぐに利用できます。

## 認可の仕組み

Ptengine MCP は、主要な SaaS と同じ標準の **OAuth 2.0 + PKCE** を採用しています：

1. クライアントの初回呼び出し時に、認可エンドポイントの自動検出と登録が行われる（ユーザーの操作は不要）
2. ブラウザで Ptengine の認可ページが開く → 内容を確認して認可する
3. クライアントに戻り、アクセストークンが発行される
4. トークンは短期有効で、期限前に自動更新されるため、再認可は不要

## 質問の例

* **「<https://example.com/landing> の直近 1 週間のパフォーマンスを見せて」** → 対象ページの PV/UV・直帰率・コンバージョンなどの指標を返す
* **「流入元別に分解して」** → 同じページの指標を流入元ディメンションで分解して比較
* **「過去 30 日の PV 推移は？」** → 日別の時系列データを返す
* **「アカウント内の上位 5 ページ、直近 30 日の状況は？」** → まずトラフィック上位ページを取得し、順に照会して比較
* **「テスト X の結果はどう？」** → 対象の A/B テストを特定し、完全なレポートを返す

## よくあるご質問

* **接続も認可も成功したのに、データが返ってこない** — 対象プロファイルで MCP クエリ権限が有効になっているかご確認ください（現在段階的に提供中のため、[利用申請フォーム](https://ptmafia.notion.site/9e56643a981983aeb35c0100c860d3bd)からのお申し込みが必要です）。
* **認可後に読み込みが終わらない / リダイレクトに失敗する** — クライアントの認可キャッシュを削除して再試行してください。Claude Code は `rm -rf ~/.claude/mcp-auth/ptengine`、Cursor は終了後に `~/.cursor/mcp-auth/` を削除します。
* **呼び出しが 401 を返す** — トークンの期限切れと更新失敗が原因です。もう一度認可を行ってください。
* **呼び出しが 403 `insufficient_scope` を返す** — 認可時に権限のチェックを外したことが原因です。再認可し、権限にチェックを入れてください。
* **特定のプロファイルが見えない** — Ptengine アカウント自体にそのプロファイルへの権限があるかご確認ください。MCP が権限を拡大することはありません。
* **同僚も使えますか？** — 認可は 1 人ずつ行います。トークンは共有せず、各自のアカウントで OAuth 認可を行ってください。