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

# Ptengine AI MCP 接入指南

通过 MCP（[Model Context Protocol](https://modelcontextprotocol.io/)），将 Ptengine AI 的数据接入 Claude、ChatGPT、Codex、Cursor 等 AI 客户端。无需编写代码，连接后即可在 AI 对话中用自然语言分析 PV/UV、漏斗、用户行为路径、A/B 测试等数据。

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/3a66643a981980669e93ed226d003eb6)或联系你的客户经理。
{% endhint %}

### 账号 <a href="#account" id="account"></a>

使用现有 Ptengine 账号即可，无需重新注册。请团队成员使用各自的账号连接，不要共享登录信息。

### 与 Ptengine 产品内数据的差异 <a href="#data-differences" id="data-differences"></a>

Ptengine AI 采集的数据粒度更细，处理范围也更加全面，因此通过 MCP 获取的数据可能与现有 Ptengine 产品内显示的数据存在差异。

| 数据类型           | 差异说明                                                          |
| -------------- | ------------------------------------------------------------- |
| PV、UV、CV 等基础指标 | 差异幅度约为 1%，仅供参考，并非固定值或保证上限。                                    |
| 热图相关数据         | 由于采集的数据更详细，浏览高度、停留时间等指标的计算分母和计算方式会发生变化。差异取决于实际用户行为，无法用固定比例预估。 |

***

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

各 AI 客户端的基本流程相同：

1. **添加** — 在 AI 客户端中添加 Ptengine AI MCP。
2. **授权** — 在浏览器中完成一次 Ptengine 数据访问授权，流程类似于通过 Google 或 GitHub 登录。
3. **提问** — 用自然语言询问数据，AI 会自动选择所需工具。

完成一次授权后，授权信息会自动保存和续期。从第二次使用起，无需额外操作即可直接使用。

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

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

### Claude <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 地址。
3. 点击 **Connect**，在浏览器中完成授权。

{% hint style="info" %}
Team / Enterprise 账号需由组织 Owner 在 **Organization settings → Connectors** 中先行添加，成员再各自点击 **Connect** 授权。
{% endhint %}

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

官方文档：[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 账号为 Ptengine AI MCP 完成授权（首次调用工具时也会自动打开授权页）。

### 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**（或访问 `chatgpt.com/plugins`），点击 **+** 新建 connector：
   * **Name**：`Ptengine AI`
   * **MCP Server URL**：上方的 MCP Server 地址
   * **Authentication**：`OAuth`
3. 在浏览器中完成授权。

{% hint style="info" %}
也可以将 connector 发布到工作区，供团队成员直接添加，此步骤可选。
{% endhint %}

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

官方文档：[Codex MCP docs](https://developers.openai.com/codex/mcp)

**方式 A：界面添加**

进入 **Settings → MCP Servers → + Add Server**，Name 填 `Ptengine AI`，类型选 **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 <a href="#cursor" id="cursor"></a>

官方文档：[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**。在浏览器中完成授权后即可使用；首次调用工具时也会自动打开授权页。

***

## 试着提问 <a href="#try-asking" id="try-asking"></a>

连接完成后，可以参考下面的方式提问。AI 会自动选择所需工具，也会组合多个工具的结果来回答。

* **“帮我看看 <https://example.com/landing> 这个页面最近一周的表现”** → 返回该页面的 PV/UV、跳出率、转化等指标
* **“按流量来源拆分一下”** → 同一页面指标按来源维度拆分对比
* **“过去 30 天 PV 趋势”** → 按天返回时间序列
* **“我账户里 Top 5 页面最近 30 天怎么样？”** → 先列出流量 Top 页面，再逐一查询对比
* **“测试 X 表现怎么样？”** → 找到对应的 A/B 测试，并汇总结果

***

## 工具参考 <a href="#tool-reference" id="tool-reference"></a>

日常使用时，无需自行选择工具。想了解能查询哪些数据时，可以参考以下列表。

### 查询与分析 <a href="#query-and-analysis" id="query-and-analysis"></a>

| 工具                 | 用途                             |
| ------------------ | ------------------------------ |
| `Run-Query`        | 统一查询入口，按 `queryType` 路由到具体分析能力 |
| `List-Query-Types` | 列出支持的查询类型及概要                   |
| `Get-Query-Schema` | 查询某个查询类型的参数说明                  |

### 数据探索 <a href="#data-discovery" id="data-discovery"></a>

| 工具                    | 用途                                      |
| --------------------- | --------------------------------------- |
| `List-Profiles`       | 列出你可访问的档案（站点）                           |
| `List-Catalog`        | 档案级目录的统一入口，按 `kind` 查询页面、事件、属性、测试、目标等目录 |
| `Get-Current-Account` | 查看当前连接的账号：账号 id、邮箱、连接方式、权限              |

`List-Catalog` 支持的 `kind`：

| kind               | 返回内容                            |
| ------------------ | ------------------------------- |
| `pages`            | 档案下访问量较高的页面（可按 URL 关键字过滤）       |
| `events`           | 事件目录（含业务术语别名）                   |
| `event_properties` | 事件属性（用于按属性分组 / 筛选）              |
| `user_properties`  | 用户属性（内置 + CRM / 数据连接器同步）        |
| `experiences`      | A/B 测试与互动的列表（含目标和版本）            |
| `goals`            | 目标与转化的合并目录                      |
| `page_groups`      | 页面组目录（页面组类型转化引用的 group id → 名称） |

### 支持的查询类型（`Run-Query`） <a href="#supported-query-types-run-query" id="supported-query-types-run-query"></a>

| queryType                      | 用途                                               | 典型问法                          |
| ------------------------------ | ------------------------------------------------ | ----------------------------- |
| `page_insight`                 | 单页指标按单一维度拆分（设备/来源/访问类型/UTM/按天/按周）                | “按设备、流量来源和日期拆分一下”             |
| `page_block_metrics`           | 单页区块级热图指标（曝光/流失/停留），可按设备查看                       | “首屏各区块的曝光和流失情况如何？”            |
| `page_element_metrics`         | 单页元素级 曝光/点击/点击率 + goal 转化                        | “页面内各元素的点击率和转化情况如何？”          |
| `traffic_insight`              | 全站基础表现：12 项指标（访问/新访问率/跳出/停留/PV/点击/流失等），可选按单一维度拆分 | “最近 30 天全站的整体表现怎么样？”          |
| `event_insight`                | 事件级行为：某事件的触发次数、触发人数、转化率，可聚合事件属性（求和/均值等），可按单一维度拆分 | “加购事件最近 7 天触发了多少次、涉及多少人？”     |
| `funnel_insight`               | 有序事件漏斗：多步转化率与流失、各步平均耗时                           | “浏览 → 加购 → 购买的漏斗中，用户在哪一步流失？”  |
| `path_insight`                 | 以某个页面或事件为起点，查看会话内的行为路径（之后去了哪里 / 之前从哪里来）          | “看完这个页面后，用户去了哪里？”             |
| `page_transitions`             | 不指定起点，查看站内页面之间的直接跳转关系                            | “查看站内页面之间的跳转关系”               |
| `experience_abtest_report`     | 单个 A/B 测试的 版本 × goal + 提升幅度，可按维度拆分               | “测试 X 让转化提升了百分之多少？”           |
| `experience_report`            | 单个测试的整体合计报告（不拆版本、无提升幅度），可按单一维度拆分                 | “测试 X 的整体结果怎么样？”              |
| `experiment_attributed_funnel` | 一组测试对事件漏斗的归因影响（first/last/all）                   | “测试 A、B、C 对登录 → 购买漏斗带来了多少提升？” |
| `experience_search`            | 搜索测试目录（按名称关键字 / 状态 / 创建时间），返回 name + id + status | “有哪些测试正在运行？”                  |
| `user_list`                    | 用户列表检索（按姓名 / 邮箱 / userId 搜索，分页排序）                | “查找邮箱为 xxx 的用户”               |
| `user_overview`                | 单个用户的画像概览                                        | “这个用户的概况如何？”                  |
| `user_timeline`                | 单个用户最近的行为时间线（最近 20 个 session 摘要）                 | “这个用户最近做了什么？”                 |
| `user_session_detail`          | 单个用户在指定 session 内的事件序列                           | “这个用户在那次访问中具体做了什么？”           |
| `user_journey`                 | 单个用户的跨 session 事件级完整旅程                           | “这个用户从头到尾都做了什么？”              |

### 旧工具迁移 <a href="#migrating-from-older-tools" id="migrating-from-older-tools"></a>

| 旧工具                                                                                                                 | 当前调用方式                                   | 状态              |
| ------------------------------------------------------------------------------------------------------------------- | ---------------------------------------- | --------------- |
| `List-Pages` / `List-Events` / `List-Event-Properties` / `List-User-Properties` / `List-Experiences` / `List-Goals` | `List-Catalog(kind=…)`                   | 已弃用，暂时保留以兼容已有配置 |
| `List-Page-Groups`                                                                                                  | `List-Catalog(kind=page_groups)`         | 已下线             |
| `Get-User-Journey`                                                                                                  | `Run-Query(queryType=user_journey)`      | 已下线             |
| `Get-Experience-Report`                                                                                             | `Run-Query(queryType=experience_report)` | 已下线             |

***

## 权限与安全 <a href="#permissions-and-security" id="permissions-and-security"></a>

* **只读** — 只能查询，不能修改配置、新建测试或更改测试与互动的投放设置
* **最小权限** — 当前所有工具仅需 `query:read` 一个权限范围（scope）
* **数据范围** — AI 只能看到**你的账号有权限的档案**；MCP 不会扩大你的权限
* **每用户独立授权** — 令牌按账号分别签发，请勿分享；请团队成员各自完成授权

### 授权原理（技术补充） <a href="#how-authorization-works-technical-details" id="how-authorization-works-technical-details"></a>

Ptengine AI MCP 使用标准 **OAuth 2.0 + PKCE** 授权，与主流 SaaS 产品一致：

1. 客户端首次调用 → 自动发现授权端点并注册（你无需操作）
2. 浏览器打开 Ptengine 授权页 → 你确认授权
3. 跳回客户端，换取访问令牌
4. 令牌短期有效，会在到期前自动续期，无需重新授权。

***

## 故障排查 <a href="#troubleshooting" id="troubleshooting"></a>

| 现象                          | 原因                    | 处理方法                                                                                           |
| --------------------------- | --------------------- | ---------------------------------------------------------------------------------------------- |
| 连接成功，但查询不到数据                | 目标档案尚未开通查询权限          | 功能正在逐步开放，请[提交开通申请](https://ptmafia.notion.site/3a66643a981980669e93ed226d003eb6)               |
| 授权后一直加载，或无法返回客户端            | 客户端保留了旧的授权缓存          | 清除缓存后重试。Claude Code 执行 `rm -rf ~/.claude/mcp-auth/ptengine`；Cursor 退出后删除 `~/.cursor/mcp-auth/` |
| 返回 `401`                    | 令牌已过期，且自动续期失败         | 重新授权                                                                                           |
| 返回 `403 insufficient_scope` | 授权时取消了权限勾选            | 重新授权，并勾选相应权限                                                                                   |
| 看不到某个档案                     | Ptengine 账号本身没有该档案的权限 | 检查账号权限设置；MCP 不会扩大可访问的数据范围                                                                      |

***

## 常见问题 <a href="#frequently-asked-questions" id="frequently-asked-questions"></a>

**MCP 目前可以免费使用吗？**

可以。MCP 作为新产品 Ptengine AI 先行提供的功能，现阶段免费使用。使用前需为每个档案申请开通。

**为什么查询结果与 Ptengine 产品内的数据不同？**

Ptengine AI 采集和处理数据的粒度更细，基础指标与热图指标的差异表现也不同。详见“[与 Ptengine 产品内数据的差异](#data-differences)”。

**AI 会修改我的设置吗？**

不会。AI 可调用的工具均为只读，只能查询数据，无法进行修改。

**同事也可以使用吗？**

可以，但每个人都需要使用自己的账号完成授权，请勿共享登录信息。

**可以使用本文未列出的客户端吗？**

支持 MCP、远程 HTTP 服务器和 OAuth 授权的客户端也可以连接，具体设置方法请参考对应客户端的文档。

***

## 相关页面 <a href="#related-pages" id="related-pages"></a>

* [Open API](https://helps.ptengine.com/cn/developer/open-api.md) — 不用 MCP，直接调接口取数
* [数据中心](https://helps.ptengine.com/cn/insight/data-center.md) — MCP 能问到的数据，在产品里对应哪些报告
* [Insight术语表](https://helps.ptengine.com/cn/insight/glossary.md) — 指标口径
