> 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 MCP 接入指南

让 Claude、ChatGPT、Codex、Cursor 等 AI 助手通过 MCP 协议直接查询你的 Ptengine 数据。无需编写代码——只需授权一次，即可在对话中用自然语言分析 PV/UV、漏斗、用户路径、A/B 测试等数据。

{% hint style="warning" %}
Ptengine MCP 目前为逐步开放阶段，查询权限需**按档案开通**。若档案尚未开通该权限，即使 MCP 连接和授权成功，查询也不会返回数据。如需开通，请[提交开通申请](https://ptmafia.notion.site/3a66643a981980669e93ed226d003eb6)或联系你的客户经理。
{% endhint %}

## 概览

Ptengine MCP Server 是基于 [Model Context Protocol](https://modelcontextprotocol.io/) 的远程工具服务。AI 客户端连接后，即可调用一组**只读**分析工具，把你 Ptengine 账户中的数据接入 AI 对话。

四步开始使用：

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`            | 档案下流量 Top N 的页面（可按 URL 关键字过滤）            |
| `events`           | 事件目录（含业务术语别名）                            |
| `event_properties` | 事件属性（用于按属性分组 / 筛选）                       |
| `user_properties`  | 用户属性（内置 + CRM / 数据连接器同步）                 |
| `experiences`      | A/B 测试 / engagement 目录（含 goals、versions） |
| `goals`            | 目标与转化的合并目录                               |
| `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` 两个独立工具也已下线，对应能力并入 `Run-Query` 的 `user_journey`、`experience_report` 查询类型（见下表）。
{% endhint %}

### 支持的查询类型（`Run-Query`）

| queryType                      | 用途                                                  | 典型问法                          |
| ------------------------------ | --------------------------------------------------- | ----------------------------- |
| `page_insight`                 | 单页指标按单一维度拆分（设备/来源/访问类型/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 个 session 摘要）                    | "这个用户最近都在做什么"                 |
| `user_session_detail`          | 单个用户在指定 session 内的事件序列                              | "这个用户在某次访问里具体做了什么"            |
| `user_journey`                 | 单个用户的跨 session 事件级完整旅程                              | "这个用户从头到尾都做了什么"               |
| `user_list`                    | 用户列表检索（按姓名 / 邮箱 / userId 搜索，分页排序）                   | "帮我找邮箱是 xxx 的用户 / 最近活跃的用户有哪些" |

## 权限与安全

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

## 接入方式

### Claude

官方文档：[Claude 自定义 connector 指南](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp)（网页版与桌面应用步骤相同）

进入 **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 授权（可选：发布到 workspace，供团队成员直接添加）

### 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 使用标准 **OAuth 2.0 + PKCE** 授权，与主流 SaaS 产品一致：

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

## 示例提问

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

## 常见问题

* **连接和授权都成功，但查询不到数据** — 请确认该档案已开通 MCP 查询权限（目前为逐步开放阶段，需[提交开通申请](https://ptmafia.notion.site/3a66643a981980669e93ed226d003eb6)或联系客户经理开通）。
* **授权后一直转圈 / 跳转失败** — 清除客户端授权缓存后重试：Claude Code 执行 `rm -rf ~/.claude/mcp-auth/ptengine`；Cursor 退出后删除 `~/.cursor/mcp-auth/`。
* **调用返回 401** — 令牌过期且续期失败，重新触发一次授权即可。
* **调用返回 403 `insufficient_scope`** — 授权时取消了权限勾选，重新授权并勾选权限。
* **看不到某个档案** — 请确认你的 Ptengine 账号本身有该档案的权限；MCP 不会扩大权限。
* **能给同事用吗？** — 每人独立授权，请勿分享令牌，请对方使用自己的账号完成 OAuth 授权。