# 只读 MCP 诊断

为支持 MCP 的助手配置应用范围令牌，查询发布、判定和健康度。

# 只读 MCP 诊断 {#mcp}

Pakta 在 `/api/mcp` 提供只读的 [Model Context Protocol](https://modelcontextprotocol.io/) 服务。它把发布目录、更新判定重放和结构化投放遥测提供给支持 Streamable HTTP 的助手。

## 接入

1. 在控制台打开 **设置 → MCP 接入**。
2. 创建凭据，填写客户端名称，并勾选一个或多个应用；默认有效期为 30 天。
3. 明文令牌展示时立即复制。服务端只保存摘要，之后不会再次显示完整值。
4. 在客户端配置地址 `https://<你的 Pakta 域名>/api/mcp`，并携带 `Authorization: Bearer <令牌>` 请求头。

凭据按应用授权。每次应用、渠道、包、投放和遥测查询都会重新检查范围。应用支持 ID 或精确名称；名称重名时会返回授权范围内的候选项，不会自行选择。

## 工具

服务端提供以下只读工具：

| 工具 | 用途 |
| --- | --- |
| `auth_status` | 查看凭据、过期时间和应用范围。 |
| `list_apps`、`get_app_detail` | 查看已授权应用和脱敏配置。 |
| `list_channels`、`list_native_versions` | 查看渠道与原生构建目录。 |
| `list_update_packages`、`list_deployments` | 查看不可变更新包和投放目标。 |
| `explain_update` | 按客户端参数重放当前更新判定；不消耗 SDK 查询配额，也不写入观测。 |
| `get_patch_info` | 查看精确构建补丁任务和 pdiff 关系。 |
| `get_request_observations` | 查看保留七天的隐私化真实检查观测。 |
| `get_rollout_health`、`get_adoption_trend` | 查看事件计数、时间桶和保守启发式建议。 |
| `diagnose_rollback` | 按 hash、版本和渠道聚合结构化回滚事件。 |

列表默认每页 50 条，最多 100 条。分析默认最近 24 小时，也支持 1 天或 7 天，并可按渠道、原生版本和更新 hash 筛选。健康规则会返回样本分母和阈值，只给出建议，不会暂停、回滚或发布投放。

## 排查

- **401**：必须携带 Bearer 请求头；确认完整复制令牌，并检查是否过期或已撤销。普通 API Key 和浏览器会话 JWT 不能用于 MCP 地址。
- **403**：检查请求 `Origin`，使用与服务地址相同的主机，或使用运营方配置的允许来源。令牌即使有效，也不能读取未勾选的应用。
- **未知工具或参数错误**：重新初始化 MCP 客户端以获取最新工具 schema，并提供 `application`、`packageVersion` 等必填字段。

运营方需要设置 `MCP_ENABLED=true` 才会启用服务，默认关闭。本版本只验证支持 Streamable HTTP 和自定义 Bearer 请求头的客户端，不提供 OAuth 授权服务。

## 数据边界

真实检查观测只包含应用、渠道、原生构建、SDK 版本、判定类别和时间，不包含 IP、设备标识、凭据或原始请求。观测异步写入并保留七天，功能启用前的数据明确不可用。采用趋势是事件计数，`mark_success` 表示启动确认，不是去重后的设备采用率。没有崩溃堆栈时，回滚诊断不能定位崩溃根因。