Ptengine MCP 接入指南
让 Claude、ChatGPT、Codex、Cursor 等 AI 助手通过 MCP 协议直接查询你的 Ptengine 数据。无需编写代码——只需授权一次，即可在对话中用自然语言分析 PV/UV、漏斗、用户路径、A/B 测试等数据。
Ptengine MCP 目前为逐步开放阶段，查询权限需按档案开通。若档案尚未开通该权限，即使 MCP 连接和授权成功，查询也不会返回数据。如需开通，请提交开通申请或联系你的客户经理。
概览
Ptengine MCP Server 是基于 Model Context Protocol 的远程工具服务。AI 客户端连接后，即可调用一组只读分析工具，把你 Ptengine 账户中的数据接入 AI 对话。
四步开始使用：
接入 — 在 AI 客户端中添加 Ptengine MCP Server
授权 — 在浏览器中完成一次性 OAuth 授权（与登录 Google / GitHub 的体验相同）
提问 — 用自然语言询问数据，AI 会自动选择合适的工具
复用 — 授权自动缓存与续期，下次直接使用
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：
pages
档案下流量 Top N 的页面（可按 URL 关键字过滤）
events
事件目录（含业务术语别名）
event_properties
事件属性（用于按属性分组 / 筛选）
user_properties
用户属性（内置 + CRM / 数据连接器同步）
experiences
A/B 测试 / engagement 目录（含 goals、versions）
goals
目标与转化的合并目录
page_groups
页面组目录（页面组类型转化引用的 group id → 名称）
工具变更说明：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 查询类型（见下表）。
支持的查询类型（Run-Query）
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 指南（网页版与桌面应用步骤相同）
进入 Settings → Connectors → Add custom connector，Name 填 Ptengine、URL 填 https://mcp.ptengine.com/open-api/v1/mcp，点击 Connect 在浏览器中完成授权。
Team / Enterprise 账号需由组织 Owner 在 Organization settings → Connectors 中先行添加，成员再各自点击 Connect 授权。
Claude Code
官方文档：Claude Code MCP docs
添加后在 Claude Code 中运行 /mcp，按提示在浏览器中完成 Ptengine 授权（首次调用工具时也会自动打开授权页）。
ChatGPT
进入 Settings → Security and login，打开 Developer mode（开关不可用时请联系组织管理员放行）
进入 Settings → Plugins（或访问
chatgpt.com/plugins），点击 + 新建 connector：Name 填Ptengine，MCP Server URL 填https://mcp.ptengine.com/open-api/v1/mcp，Authentication 选 OAuth在浏览器中完成 Ptengine 授权（可选：发布到 workspace，供团队成员直接添加）
Codex
官方文档：Codex MCP docs
方式 A：界面添加
进入 Settings → MCP Servers → + Add Server，Name 填 Ptengine，类型选 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（或首次调用工具时），完成浏览器授权即可使用。
授权说明
Ptengine MCP 使用标准 OAuth 2.0 + PKCE 授权，与主流 SaaS 产品一致：
客户端首次调用 → 自动发现授权端点并注册（你无需操作）
浏览器打开 Ptengine 授权页 → 你确认授权
跳回客户端，换取访问令牌
令牌短期有效，到期前自动续期，无需重复授权
示例提问
"帮我看看 https://example.com/landing 这个页面最近一周的表现" → 返回该页面的 PV/UV、跳出率、转化等指标
"按流量来源拆分一下" → 同一页面指标按来源维度拆分对比
"过去 30 天 PV 趋势" → 按天返回时间序列
"我账户里 Top 5 页面最近 30 天怎么样？" → 先列出流量 Top 页面，再逐一查询对比
"测试 X 表现怎么样？" → 先找到对应的 A/B 测试，再返回完整测试报告
常见问题
连接和授权都成功，但查询不到数据 — 请确认该档案已开通 MCP 查询权限（目前为逐步开放阶段，需提交开通申请或联系客户经理开通）。
授权后一直转圈 / 跳转失败 — 清除客户端授权缓存后重试：Claude Code 执行
rm -rf ~/.claude/mcp-auth/ptengine；Cursor 退出后删除~/.cursor/mcp-auth/。调用返回 401 — 令牌过期且续期失败，重新触发一次授权即可。
调用返回 403
insufficient_scope— 授权时取消了权限勾选，重新授权并勾选权限。看不到某个档案 — 请确认你的 Ptengine 账号本身有该档案的权限；MCP 不会扩大权限。
能给同事用吗？ — 每人独立授权，请勿分享令牌，请对方使用自己的账号完成 OAuth 授权。
最后更新于