通过 MCP 在 AI 工具中查询 Ptengine 数据
使用自己的账号授权，在外部 AI 客户端中读取已开放档案的数据。
MCP 能做什么
Ptengine AI MCP 让支持该协议的 AI 工具读取有权限的数据，用自然语言查询流量、页面、漏斗、路径和已有实验结果。当前数据工具是只读的，不负责修改设置、创建实验或发布页面。连接成功和档案已开通是两件事，查询权限按站点确认。
连接前确认账号与档案开通
可以使用现有 Ptengine 账号。先登录 Ptengine，确认该账号本身能进入目标档案。客户端授权与 MCP 档案开通是两件事：数据查询需要按档案启用，一个站点已申请不代表其他站点同时开通。
- 确定使用的账号和目标档案。
- 尚未开通时，通过MCP 使用申请表或负责同事申请。
- 使用企业管理的 AI 工具时，先确认管理员允许外部连接，也确认这些数据可以交给该 AI 客户端处理。
提交申请不等于已启用。连接后还需要按下方步骤确认目标档案能够被读取。
在 Claude 中完成连接
服务地址为 https://mcp.ptengine.com/open-api/v1/mcp。个人 Pro / Max 账号可按以下步骤添加。
- 打开 Claude 的 Customize → Connectors，选择添加自定义连接器。
- 名称填写“Ptengine AI”，服务地址填写上方 URL，并核对客户端识别的认证设置。
- 添加后连接，在浏览器中用自己的 Ptengine 账号登录并授权；使用时也要在当前对话中启用该连接器。
Team / Enterprise 需要有权限的组织管理员先添加连接器，成员再分别连接自己的账号。若界面不同，请按 Claude 官方连接说明操作。无需把密码或授权后的令牌粘贴进对话。
验证连接与数据读取分别成功
- 确认客户端中出现 Ptengine 工具，且没有连接或认证错误。
- 向 AI 提问“列出我能访问的 Ptengine 档案”。检查是否实际返回
List-Profiles结果，以及其中是否包含目标档案。 - 指定该档案和确定有数据的日期，先请求站点总体等简单查询，检查返回的时间范围、数量和指标。
- 找不到档案或结果为空时，分别检查账号权限、MCP 开通状态与日期条件。
不要只根据 AI 回复“已连接”判断成功，要看实际工具返回。需要访问更多档案时，请调整本人应有的权限，不借用管理员账号查询。
第一次提问写清范围
先确认当前可访问档案，再给出页面 URL、日期、时区、设备或流量来源等必要条件。例如：“查看这个页面上周移动端的表现，列出所用指标、时间范围和仍需确认的问题。”同一问题先看总体，再拆一个维度，避免一开始要求无法比较的大量交叉数据。
核对结果而不是只看总结
请 AI 说明数据来源、目标档案、统计口径、筛选条件和缺失项。外部 AI 的总结可能有误解，关键数字应和实际查询结果核对。不同产品的数据采集粒度与口径可能不同，不设定固定误差保证；遇到差异先比较范围与分母，再判断是否是计测异常。
常见连接问题
| 现象 | 检查与处理 |
|---|---|
| 连接成功但无法取得数据 | 确认目标档案已开通 MCP。未申请时使用上方表单或联系负责同事；反复重新授权不会代替档案开通。 |
| 档案列表中找不到目标 | 用同一账号登录 Ptengine，确认能否打开该档案。账号本身没有访问权时，请管理员处理。 |
| 401 | 可能是认证过期等问题。在客户端重新连接 Ptengine，并用本人账号重新授权。 |
| 403 insufficient_scope | 检查是否授予所需只读权限。重新授权时确认 query:read；其他 403 则结合具体错误和目标权限判断。 |
| 能列出档案，但查询为空 | 检查日期、URL、筛选项和实际数据是否存在，不把空结果当成零访问。 |
仍未解决时，提供客户端名称、发生时间、错误文本和脱敏后的查询条件，不发送令牌、密码或验证码。
使用其他客户端
服务地址相同，但添加和授权入口因客户端而异。使用 Codex 或 Cursor 时，请分别查看 Codex 官方 MCP 指南、Cursor 官方 MCP 指南中的远程 HTTP 服务和 OAuth 配置；完成后继续执行本文的数据读取验证。
手工编辑配置文件时，应在保留已有服务的前提下添加 Ptengine，不要整份覆盖。需要组织批准或特定套餐的客户端，先与管理员确认。更换客户端不会扩大 Ptengine 账号本身的访问权限。