MCP 作用域和令牌
签发带作用域的 MCP 令牌，并安全地轮换或撤销。
Showly MCP 令牌用于验证智能体身份。本页说明如何签发令牌、严格限制 作用域，以及在需要时轮换或撤销。
签发令牌
工作区设置 → MCP 客户端 → 新客户端。
您将设置五个字段：
- 客户端名称 — 显示在审计日志中。使用描述性名称，例如
Claude Code (alice@acme) 比 token-3 更清楚。
- 项目限制 — 可选。设置后，令牌只能查看和修改该项目中的站点与部署。
- 作用域 — 只选择所需的最小集合。默认值为
project:read、
site:read、preview:read。
- TTL — 令牌的有效时间。默认 90 天，最长 365 天。
- 备注 — 自由文本，用于记录令牌用途。
令牌在创建时显示一次。复制它；我们不存储明文。
作用域参考
作用域是扁平字符串，不存在嵌套层级。令牌包含显式列表，API 只识别下表中的准确名称。
| 作用域 | 类型 | 允许 |
|---|---|---|
project:read | 读 | list_projects — 列出并检查该令牌可以访问的项目 |
site:read | 阅读 | list_sites、get_site_context、create_change_plan、list_site_versions、get_site_files — 读取站点状态 |
site:write | 写 | apply_site_patch、create_site_from_template — 暂存修改，不直接部署 |
site:delete | 写 | delete_site — 通过两步确认级联软删除站点 |
preview:read | 阅读 | get_preview_status — 读取部署状态 |
preview:create | 写 | create_preview、create_github_preview、delete_preview — 创建或软删除私有预览 |
checks:run | 写 | run_checks — 读取 lint/typecheck/build/audit 状态 |
publish:request | 写 | request_publish — 为生产发布创建审批请求 |
publish:confirm | 写 | publish_site — 对话内两步确认并发布到生产 |
rollback:confirm | 写 | rollback_to_version — 两步确认后回滚到先前版本 |
logs:read | 读 | get_deployment_logs — 读取受限长度的构建日志；diagnose_deployment 还提供受限的客户端/智能体诊断 |
template:read | 阅读 | list_templates — 列出可用的网站模板 |
template:create | 写 | create_site_from_template — 从模板具体化一个新站点 |
不存在隐式权限继承。 授予 publish:request 不会同时授予 preview:create；请准确选择客户端需要的作用域。Web UI 的“MCP 令牌” 面板以复选框展示同一清单，自定义 RBAC 角色构建器也使用这组常量。
无论授予什么作用域，旧版rollback_deployment都不会通过 MCP 公开。publish_site只有在具备publish:confirm且完成对话内两步 确认后才能调用。原因见 工具参考。
最小权限示例
对于永远不应该接触基础设施的_仅内容_代理：
- 允许列表：仅限
marketing-site站点。 - 作用域：
site:read、site:write。智能体可以暂存补丁，但不能创建预览或发布。 - TTL：30 天。
对于 CI 中的_deploy-bot_：
- 允许列表：仅限其正在部署的生产站点。
- 作用域：
preview:read、preview:create、checks:run、
publish:request。不授予 site:write，因为补丁来自 CI 中已提交的工作流。
- TTL：14 天，由 CI 轮换。
对于_模板驱动的入门机器人_：
- 允许列表：邀请机器人参与的任何项目。
- 作用域：
project:read、template:read、template:create、
site:write、preview:read、preview:create。它可以选择模板、创建 站点并等待第一个预览完成。
- TTL：7 天。
轮换
两条路：
- 手动 — 点击客户端上的轮换。旧令牌会立即撤销；复制新令牌并
更新 shell 配置。
- 定期 — 在工作区设置 → 令牌策略中设置轮换周期。Showly 会在
到期前向工作区所有者发送邮件。
撤销
点击撤销会立即停用令牌。继续使用该令牌的工具调用会收到 401。 客户端名称仍保留在审计日志中，并带有 revoked 标记，因此历史记录 仍可追溯。
如果怀疑令牌泄露，先撤销，再调查。即使泄露的令牌拥有 publish:request，也只能创建发布审批，不能绕过人工审批或与部署绑定 的发布确认。
审计可见性
每次工具调用都会写入包含客户端 ID（不包含令牌）的审计记录。你可以：
- 查询某个客户端的全部调用：
client_id eq <id>。 - 查询某类写操作：
action eq mcp.request_publish。 - 在已启用审计功能的工作区中查看和导出记录。
令牌不能做什么
- 跨租户读取。该令牌绑定到一个工作区。
- 绕过审批。
publish:request只允许_创建_审批请求，现有审批规则仍然适用。 - 修改计费或 RBAC。这些操作需要人类用户、管理员角色和浏览器会话。
- 调用旧版
rollback_deployment，因为它没有在 MCP 服务器注册。
publish_site 需要 publish:confirm 作用域和明确的两步确认。
直接发布也使用 publish:confirm。推荐的发布智能体授权会包含该作用域， 但仍需第二次调用提交短时确认令牌。删除与回滚等破坏性作用域始终需要 显式选择。