For the complete documentation index, see llms.txt. This page is also available as Markdown.

Ptengine AI MCP 接入指南

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

AI 使用的工具均为只读,只能查询数据,不会修改 Ptengine 中的设置。


使用前须知

开放范围与费用

MCP 是新产品 Ptengine AI 先行提供的功能,目前免费使用。

每个站点都需要申请开通

账号

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

与 Ptengine 产品内数据的差异

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

数据类型
差异说明

PV、UV、CV 等基础指标

差异幅度约为 1%,仅供参考,并非固定值或保证上限。

热图相关数据

由于采集的数据更详细,浏览高度、停留时间等指标的计算分母和计算方式会发生变化。差异取决于实际用户行为,无法用固定比例预估。


接入方法

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

  1. 添加 — 在 AI 客户端中添加 Ptengine AI MCP。

  2. 授权 — 在浏览器中完成一次 Ptengine 数据访问授权,流程类似于通过 Google 或 GitHub 登录。

  3. 提问 — 用自然语言询问数据,AI 会自动选择所需工具。

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

MCP Server 地址

Claude

官方文档:Claude 自定义 connector 指南(网页版与桌面应用步骤相同)

  1. 打开 Settings → Connectors → Add custom connector。

  2. Name 填 Ptengine AI,URL 填上方的 MCP Server 地址。

  3. 点击 Connect,在浏览器中完成授权。

Team / Enterprise 账号需由组织 Owner 在 Organization settings → Connectors 中先行添加,成员再各自点击 Connect 授权。

Claude Code

官方文档:Claude Code MCP docs

添加后在 Claude Code 中运行 /mcp,按提示在浏览器中使用现有 Ptengine 账号为 Ptengine AI MCP 完成授权(首次调用工具时也会自动打开授权页)。

ChatGPT

官方文档:ChatGPT 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. 在浏览器中完成授权。

也可以将 connector 发布到工作区,供团队成员直接添加,此步骤可选。

Codex

官方文档:Codex MCP docs

方式 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 中追加以下内容:

保存后执行以下命令,在浏览器中完成授权:

Cursor

官方文档:Cursor MCP docs

编辑 ~/.cursor/mcp.json(或在 Cursor Settings → Tools & Integrations 中新建 MCP Server):

保存后重启 Cursor,在 Tools & Integrations 列表中找到 ptengine,点击 Login。在浏览器中完成授权后即可使用;首次调用工具时也会自动打开授权页。


试着提问

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

  • “帮我看看 https://example.com/landing 这个页面最近一周的表现” → 返回该页面的 PV/UV、跳出率、转化等指标

  • “按流量来源拆分一下” → 同一页面指标按来源维度拆分对比

  • “过去 30 天 PV 趋势” → 按天返回时间序列

  • “我账户里 Top 5 页面最近 30 天怎么样?” → 先列出流量 Top 页面,再逐一查询对比

  • “测试 X 表现怎么样?” → 找到对应的 A/B 测试,并汇总结果


工具参考

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

查询与分析

工具
用途

Run-Query

统一查询入口,按 queryType 路由到具体分析能力

List-Query-Types

列出支持的查询类型及概要

Get-Query-Schema

查询某个查询类型的参数说明

数据探索

工具
用途

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)

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 事件级完整旅程

“这个用户从头到尾都做了什么?”

旧工具迁移

旧工具
当前调用方式
状态

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)

已下线


权限与安全

  • 只读 — 只能查询,不能修改配置、新建测试或更改测试与互动的投放设置

  • 最小权限 — 当前所有工具仅需 query:read 一个权限范围(scope)

  • 数据范围 — AI 只能看到你的账号有权限的档案;MCP 不会扩大你的权限

  • 每用户独立授权 — 令牌按账号分别签发,请勿分享;请团队成员各自完成授权

授权原理(技术补充)

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

  1. 客户端首次调用 → 自动发现授权端点并注册(你无需操作)

  2. 浏览器打开 Ptengine 授权页 → 你确认授权

  3. 跳回客户端,换取访问令牌

  4. 令牌短期有效,会在到期前自动续期,无需重新授权。


故障排查

现象
原因
处理方法

连接成功,但查询不到数据

目标档案尚未开通查询权限

功能正在逐步开放,请提交开通申请

授权后一直加载,或无法返回客户端

客户端保留了旧的授权缓存

清除缓存后重试。Claude Code 执行 rm -rf ~/.claude/mcp-auth/ptengine;Cursor 退出后删除 ~/.cursor/mcp-auth/

返回 401

令牌已过期,且自动续期失败

重新授权

返回 403 insufficient_scope

授权时取消了权限勾选

重新授权,并勾选相应权限

看不到某个档案

Ptengine 账号本身没有该档案的权限

检查账号权限设置;MCP 不会扩大可访问的数据范围


常见问题

MCP 目前可以免费使用吗?

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

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

Ptengine AI 采集和处理数据的粒度更细,基础指标与热图指标的差异表现也不同。详见“与 Ptengine 产品内数据的差异”。

AI 会修改我的设置吗?

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

同事也可以使用吗?

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

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

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


最后更新于