> 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/aitsru/mcp.md).

# Ptengine AI MCP 接続・活用ガイド

MCP（[Model Context Protocol](https://modelcontextprotocol.io/)）を使うと、Ptengine のデータを Claude・ChatGPT・Claude Code・Cursor などの AI クライアントにつなげられます。コーディングは不要です。連携後は、PV / UU・ファネル・ユーザー行動パス・A/B テストなどのデータを、AI との会話の中で自然言語のまま分析できます。

役割は次のように分かれています。

* **データの取得は Ptengine が担当します。** ご質問の内容に応じて、対象サイトの数値を正確に AI へ渡します。
* **データの解釈は AI が担当します。** 結論・示唆・レポートの文面は、お使いの AI が組み立てます。

そのため、まとめ方や示唆の質はご利用の AI やモデルによって変わります。データそのものは、どの AI から呼び出しても、同じ条件であれば Ptengine から同じ値が返ります。また、AI が利用できるツールはすべて読み取り専用です。データを参照するだけで、Ptengine 側の設定が変更されることはありません。

***

## ご利用の前に <a href="#before-you-start" id="before-you-start"></a>

### 提供状況と料金 <a href="#availability-and-pricing" id="availability-and-pricing"></a>

MCP は新製品 **Ptengine AI** の先行提供機能です。現在は無料でご利用いただけます。

### サイトごとに利用申請が必要です <a href="#request-access-for-each-site" id="request-access-for-each-site"></a>

{% hint style="warning" %}
この機能は順次提供しています。データを参照する権限はプロジェクト（Ptengine で計測している各サイト）ごとに有効化する必要があり、権限が有効になっていないプロジェクトでは、**連携に成功してもデータが返ってきません**。

ご利用を希望される場合は、[利用申請フォーム](https://ptmafia.notion.site/9e56643a981983aeb35c0100c860d3bd)からお申し込みいただくか、担当者までお問い合わせください。
{% endhint %}

### アカウント <a href="#account" id="account"></a>

お使いの Ptengine アカウントをそのままご利用いただけます。新しくアカウントを作成する必要はありません。連携はメンバーひとりずつ行ってください（ログイン情報を共有して使うことはできません）。

### Ptengine の画面に表示される数値との差 <a href="#data-differences" id="data-differences"></a>

Ptengine AI では、これまでより細かい粒度でデータを収集し、より広い範囲を対象に処理しています。そのため、MCP で取得した数値が、現在の Ptengine の画面の数値と一致しない場合があります。

PV・UU・CV などの基本指標では、差はおおむね 1% 前後です。ただし、この範囲に収まることを保証するものではありません。

***

## 接続方法 <a href="#connecting" id="connecting"></a>

どの AI クライアントでも、進め方は共通です。

1. **追加** — AI クライアントに Ptengine AI MCP を追加します
2. **許可** — ブラウザで Ptengine の認可画面が開くので、一度だけアクセスを許可します（Google アカウントで他のサービスにログインするときと同じ流れです）
3. **質問** — ご自身の言葉で質問すると、AI が必要なツールを自動で選びます

一度許可すると、その状態は自動的に保存・更新されます。2 回目以降は、追加の操作なしでそのままお使いいただけます。

### MCP Server URL <a href="#mcp-server-url" id="mcp-server-url"></a>

```
https://mcp.ptengine.com/open-api/v1/mcp
```

### Claude（Web 版・デスクトップアプリ共通） <a href="#claude" id="claude"></a>

参考：[Claude カスタム connector ガイド](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp)

1. **Settings → Connectors → Add custom connector** を開きます
2. **Name** に `Ptengine AI`、**URL** に上記の MCP Server URL を入力します
3. **Connect** をクリックし、ブラウザで表示される画面でアクセスを許可します

{% hint style="info" %}
**Team / Enterprise プランをご利用の場合**：先に組織の Owner が **Organization settings → Connectors** から追加する必要があります。そのうえで、メンバーが各自 **Connect** から許可します。
{% endhint %}

### ChatGPT <a href="#chatgpt" id="chatgpt"></a>

参考：[ChatGPT Developer mode](https://developers.openai.com/api/docs/guides/developer-mode)

1. **Settings → Security and login** を開き、**Developer mode** を有効にします（切り替えスイッチが表示されない場合は、組織の管理者にご確認ください）
2. **Settings → Plugins** を開き、**+** から connector を新規作成します
   * **Name**：`Ptengine AI`
   * **MCP Server URL**：上記の MCP Server URL
   * **Authentication**：`OAuth`
3. ブラウザでアクセスを許可します

{% hint style="info" %}
ワークスペースに公開すると、チームのメンバーも同じ connector をそのまま追加できます（任意）。
{% endhint %}

### Claude Code <a href="#claude-code" id="claude-code"></a>

参考：[Claude Code MCP ドキュメント](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` を実行し、ブラウザでアクセスを許可します（最初にツールが呼び出されたタイミングでも、許可の画面が自動的に開きます）。

### Codex <a href="#codex" id="codex"></a>

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

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

**Settings → MCP Servers → + Add Server** を開き、**Name** に `Ptengine AI`、種類に **Streamable HTTP**、**URL** に上記の MCP Server URL を入力して保存します。

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

`~/.codex/config.toml` に次の内容を追記します。

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

保存後、次のコマンドを実行し、ブラウザでアクセスを許可します。

```bash
codex mcp login ptengine
```

### Cursor <a href="#cursor" id="cursor"></a>

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

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

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

保存後に Cursor を再起動し、**Tools & Integrations** の一覧から `ptengine` を選んで **Login** をクリックします。

### そのほかのクライアント <a href="#other-clients" id="other-clients"></a>

MCP に対応し、リモートの HTTP サーバーと OAuth に対応しているクライアントであればご利用いただけます。設定方法は各クライアントのドキュメントをご確認ください。

***

## AI に聞けること <a href="#what-you-can-ask-ai" id="what-you-can-ask-ai"></a>

連携後は、次のように自然言語のまま質問できます。AI が必要なツールを自動で選び、複数のツールを組み合わせて回答します。

| 聞きたいこと        | 質問の例                                                          | 返ってくるもの                                         |
| ------------- | ------------------------------------------------------------- | ----------------------------------------------- |
| ページの状況        | 「`https://example.com/lp` の先週の訪問数・直帰率・平均滞在時間・コンバージョンを知りたい」    | そのページの直近 7 日間の指標表                               |
| 流入元別の内訳       | （続けて）「流入元ごとに分けて」「前の週と比べて」                                     | 同じページの数値が流入元別、または 2 期間の並びに分かれます                 |
| 離脱箇所の特定       | 「商品閲覧 → カート追加 → 購入完了の、各ステップの人数と遷移率を知りたい」                      | 各ステップの到達人数・遷移率・全体のコンバージョン率・平均所要時間               |
| A/B テストの勝敗    | 「テスト X の各パターンのゴール率・成績・勝率を知りたい」                                | パターン × ゴールごとの結果（サンプル数が不足する場合は注意書きが付きます）         |
| 実行中のテスト一覧     | 「いま実行中のテストは？」                                                 | テスト名・ステータス・開始日時の一覧                              |
| 個別ユーザーの行動     | 「メールアドレスが `xxx@example.com` のユーザーの、直近の訪問内容を知りたい」              | 直近 20 セッション程度の概要                                |
| ユーザーグループ限定の集計 | 「Ptengine に保存している『VIP 会員』ユーザーグループの、今月のサイト全体の指標とコンバージョン率を知りたい」 | 通常の全体指標と同じ形式で、そのユーザーグループのみを集計（定義は製品内の設定をそのまま使用） |
| 導線の検証         | 「このページを見たあと、ユーザーがよく移動するページを知りたい」                              | 次の遷移先ページとその割合                                   |

上記のどの質問にも「〇〇ユーザーグループに限定して」と付け加えられます。また、取得した結果に対して「週次レポートの形式で 1 段落にまとめて。変化率が 10% を超えた項目は目立たせて」のように、整形や解釈を続けて依頼することもできます。

## 正確な回答を得るための質問のコツ <a href="#tips-for-accurate-answers" id="tips-for-accurate-answers"></a>

聞き方を少し変えるだけで、回答の正確さは大きく変わります。

**1. 期間を明示する**

「直近 7 日」「2026-05-01 から 05-31」のように、いつのデータかを必ず入れてください。複数の指標を 1 つの質問でまとめて聞くことも可能です。結果が想定と違う場合は、指標ごとに分けて聞き直すと原因を切り分けやすくなります。

**2. Ptengine の画面にある名称を、そのまま使う**

イベント名・ゴール名・ユーザーグループ名は、製品内で使っている呼び名のまま伝えてください。AI が気を利かせて `purchase_v2` のような技術的な名称に言い換えてしまうと、エラーにはならず「該当データ 0 件」という結果だけが返ります。データがあるはずなのに取得できない原因として、最も多いパターンです。

**3. 絞り込んだはずの数字が、全体と同じになっていないか確かめる**

「〇〇ユーザーグループに限定して」と伝えたのに、サイト全体と変わらない数字が返ってくることがあります。条件が正しく解釈されなかった場合、エラーにならないまま全体の数値が返るためです。件数が全体より小さくなっているかをご確認ください。

**4. 分けて出した数字を、足して合計にしない**

流入元別に出した各行の UU を合計すると、サイト全体の UU を上回ります。1 人のユーザーが複数の流入元に登場するためです。合計が必要なときは、分割せずにもう一度質問してください。

**5. AI が「どれを指していますか」と聞き返すのは正常な動作**

サイト名や体験名が複数一致した場合、AI は候補を提示して確認します。ここで AI に選ばせず、ご自身で指定してください。

AI に毎回同じ前提を伝える手間を省きたい場合は、[技術リファレンス](https://helps.ptengine.com/aitsru/mcp/reference.md)の「AI に設定するルール」に、プロジェクト指示やカスタム指示へそのまま貼り付けられるルール文を掲載しています。

***

## 認証と権限 <a href="#permissions-and-security" id="permissions-and-security"></a>

* 標準の **OAuth 2.0 + PKCE** を採用しています。クライアントが最初に呼び出したタイミングで、認可エンドポイントの検出と登録が自動的に行われるため、手動での設定は不要です
* スコープは `query:read` の 1 つのみです。すべてのツールが読み取り専用で、設定の変更、体験（A/B テスト・Web 接客）の作成や配信設定の変更はできません
* アクセストークンの有効期限は短く、期限切れ前に自動更新されるため、許可のやり直しは不要です
* トークンはアカウントごとに発行されます。AI が参照できるプロジェクトの範囲は、アカウント自身の権限と同じです。MCP を使うことで、参照できる範囲が広がることはありません

## うまくいかないとき <a href="#troubleshooting" id="troubleshooting"></a>

### 接続・認証 <a href="#connection-and-authentication" id="connection-and-authentication"></a>

| 症状                              | 原因                               | 対処                                                                                                         |
| ------------------------------- | -------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| 連携は成功するが、データが返ってこない             | 対象プロジェクトの利用申請が未完了                | [利用申請フォーム](https://ptmafia.notion.site/9e56643a981983aeb35c0100c860d3bd)からお申し込みください                        |
| 許可したあと、読み込みが終わらない／画面が戻ってこない     | クライアント側に古い許可情報が残っている             | Claude Code は `rm -rf ~/.claude/mcp-auth/ptengine`、Cursor はアプリを終了してから `~/.cursor/mcp-auth/` を削除し、再度お試しください |
| `401` エラーが返る                    | トークンの期限切れと、自動更新の失敗               | もう一度、許可をやり直してください                                                                                          |
| `403 insufficient_scope` エラーが返る | 許可の画面で権限のチェックを外している              | もう一度許可をやり直し、権限にチェックを入れてください                                                                                |
| 特定のプロジェクトが表示されない                | Ptengine アカウント自体に、そのプロジェクトの権限がない | アカウントの権限設定をご確認ください。MCP で参照範囲が広がることはありません                                                                   |

データが取得できない、数字が想定と違うといった症状は、[技術リファレンス](https://helps.ptengine.com/aitsru/mcp/reference.md)の「データ・回答の精度」をご覧ください。

***

## さらに詳しく：技術リファレンス <a href="#technical-reference" id="technical-reference"></a>

プロンプトやルールを自分で調整したい場合、取得したデータが想定と違う原因を切り分けたい場合は、子ページの[技術リファレンス](https://helps.ptengine.com/aitsru/mcp/reference.md)をご覧ください。次の内容を掲載しています。

* **Ptengine の画面の用語との対応** — 画面の呼び方と、MCP のパラメータ名の対応表
* **AI に設定するルール** — プロジェクト指示やカスタム指示に貼り付けられるルール文
* **ツールリファレンス** — AI が呼び出す 7 つのツールと、`List-Catalog` で取得できる一覧
* **`queryType` リファレンス** — 18 種類のクエリの用途・適した質問・主要パラメータ
* **横断的な概念** — 期間指定、対象ユーザーの定義、ゴールと金額の列、軸による分割の注意点
* **データ・回答の精度** — 「0 件が返る」「絞り込みが効かない」などの症状別の切り分け

***

## よくあるご質問 <a href="#frequently-asked-questions" id="frequently-asked-questions"></a>

**料金はかかりますか？**

現時点では無料です。新製品 Ptengine AI の先行提供機能として提供しています。ご利用にはプロジェクトごとの利用申請が必要です。

**Ptengine の画面と数値が違うのはなぜですか？**

Ptengine AI では、これまでより細かい粒度でデータを収集・処理しているためです。詳しくは「[Ptengine の画面に表示される数値との差](#data-differences)」をご覧ください。

**AI に設定を変更されてしまうことはありませんか？**

ありません。AI が利用できるツールはすべて読み取り専用です。

**同僚も使えますか？**

はい。許可はひとりずつ行います。ログイン情報を共有せず、各自のアカウントで許可してください。

**回答が正確でない／データがないと言われる場合は？**

まず、対象サイト（プロジェクト）で利用申請が完了しているかをご確認ください。そのうえで、「[正確な回答を得るための質問のコツ](#rules)」をご覧ください。症状別の切り分けは[技術リファレンス](https://helps.ptengine.com/aitsru/mcp/reference.md)の「データ・回答の精度」に一覧があります。

**AI は 1 回の質問で何をしているのですか？**

AI は 1 つの質問に対して、内部で複数のツールを順番に呼び出しています。

1. どのプロジェクト（サイト）を指しているかを確定します。複数一致した場合は、AI がどれを指しているか聞き返します
2. 必要に応じて、イベント・ゴール・体験の実際の名称や id を確認します
3. パラメータが不確実な場合は、そのクエリの正確な仕様を取得します
4. クエリを実行して結果を受け取り、回答を組み立てます

1 つの質問は、通常 3〜4 回のツール呼び出しで完了します。それぞれのツールの役割は[技術リファレンス](https://helps.ptengine.com/aitsru/mcp/reference.md)をご覧ください。

**ツールの呼び出しが十数回続いて終わりません**

本来 1 回の集計で済む問いを、対象を 1 件ずつ調べる形で進めている可能性があります。いったん中断し、「〇〇別に上位 20 件」のようにグループ化を明示して聞き直してください。

**AI クライアント側でのデータの取り扱いはどうなりますか？**

各 AI クライアントでのデータの取り扱いは、それぞれの提供事業者の利用規約・プライバシーポリシーに従います。これらの内容について当社では保証いたしかねますので、ご利用前にご確認ください。

**個人情報はマスキングされますか？**

個人を特定し得る項目（メールアドレス、氏名、電話番号等）は既定でマスキングして返却します。ただし、お客様が任意の項目として送信されたデータについては、当社において個人情報該当性を判断することができないため、マスキングの完全性を保証するものではありません。

**エンドユーザーに公表している利用目的との関係は？**

MCP 経由での取得・分析が、お客様がエンドユーザーに対して公表している利用目的の範囲内であることの確認は、お客様の責任において行っていただきます。
