MCP 接入
鉴权与安全
一枚凭证能干什么、怎么收回、边界在哪。
能力是怎么算出来的
用户在工作区的角色 ∩ 凭证的 scope —— 写操作再 ∩ 签发时勾的发布落点。scope 只会收窄;一枚凭证永远不可能比它背后那个人能做的更多。
缺 scope 的工具不会出现在 tools/list 里 —— 不是报错,是根本不存在。所以「某个工具找不到」永远是 scope 的事,不是 bug。
每一次调用都会重新核对:授权人(A 类)或密钥创建者(B 类)是否仍是该工作区里 active 且未被封禁的成员。把他移出团队,这枚凭证下一次调用就失效 —— 不需要额外做撤销动作。
scope 清单
| scope | 允许什么 |
|---|---|
| workspace:read | 工作区信息、成员数与配额余量 |
| accounts:read | 已连接的社交账号与授权状态 |
| posts:read | 草稿、排期与发布记录 |
| posts:write | 创建和修改草稿、上传媒体 |
| approvals:write | 把草稿提交审批 |
| schedule:write | 安排定时发布 |
| publish:execute | 立即对外发布内容 |
| comments:read | 查看已发布内容收到的评论 |
| comments:write | 以工作区的社交账号回复评论 |
| analytics:read | 数据指标与趋势 |
| ideas:read | 查看选题库 |
| ideas:write | 往选题库写入选题 |
发布三档
| action | 需要 | 会发生什么 |
|---|---|---|
| draft | posts:write | 存成草稿。零对外副作用 —— 从这一档起步。 |
| schedule | schedule:write | 一次调用即进排期,没有二次确认 —— 到点由 popkit 真发出去。scheduledAt 必须带时区且至少晚 60 秒。既走套餐月配额,也吃每日上限(A 类与立即发布共用,B 类另有更宽的一本)。同账号间隔对排期不适用。 |
| publish | publish:execute | 立刻外发,不可撤回。A 类会先回 status: "draft" + confirm.token,必须再调 confirm_publish(一次性、10 分钟);签发为「免二次确认」的 B 类密钥一步到位。 |
publish_post 是第四条路径,一次调用、没有二次确认,但只认已经 approved(有人在站内点过审批 —— 没有审批工具)或 failed(重投已经发过一次的内容)的内容。
落点在签发时勾定,事后不能加宽 —— 要加就重签。get_workspace_context 的 credential.allowedActions 会告诉你现在有哪几档。发布会落到哪些账号见 调用规则(不传 targetAccountIds = 全部可用账号,上限 20 个)。
凭证生命周期
| A 类 · OAuth 令牌 | B 类 · 长期密钥 | |
|---|---|---|
| 谁签发 | 终端用户自己,在同意页上 | 工作区的管理员 / 所有者,在设置页 |
| 有效期 | access token 1 小时,refresh 30 天 | 不设到期即长期有效;也可签发时指定 1–365 天 |
| 存在哪 | 客户端自己持有 | 签发时只显示一次,我们只存哈希 |
| 怎么收回 | 「设置 → 接入外部系统」撤销。已签出的 access token 最长再活 1 小时 | 停用或吊销 —— 下一次调用即失效,没有过渡窗口 |
| 人离开了呢 | 下一次调用即失效 | 下一次调用即失效;密钥是停用不是删除,团队还能看到并接手 |
设了有效期的密钥,到期前 7 天与 1 天会提醒管理员;凭证开始大量失败时也会提醒 —— 无人值守的集成悄悄坏掉,才是最该被提前抓住的那种故障。
边界与实践
- 一枚凭证只看得见一个工作区 —— 工作区在签发那一刻钉死,任何参数都切不走。
popkit_it_…当密码对待:进密钥库,不进仓库、不进提示词。泄露就吊销重发 —— 明文找不回来。- 有对外副作用的写操作会进工作区审计,B 类调用标注「经外部系统 \<凭证名\>」。调用流水只记入参摘要与键名,不记你的正文。
- 没有
accounts:read的凭证读不到账号 handle —— 发布预检会把它脱敏,所以不能借预检去枚举工作区里有哪些账号。 - OAuth 元数据(A 类客户端 SDK 自动读取,人不用管;只有自己手写 OAuth 流程才需要):
https://popkit.loxily.com/.well-known/oauth-authorization-server与https://popkit.loxily.com/.well-known/oauth-protected-resource/api/mcp。
生产的发现文档只宣称
authorization_code 与 refresh_token:所以这里没有 client_credentials 这条路。无人值守的系统请用长期密钥。不注册也要标识客户端身份,用 CIMD —— client_id 就是一个 HTTPS URL,上面放客户端自己的元数据文档,popkit 在授权时去抓。