11 — 平台 MCP / 工具 REST（Dify 等 Agent）

Dify 或其它 Agent 调用本平台知识库与待办时使用。身份绑定在 工具令牌，不是 HMAC，也不是门户登录 Token。

设计方案：doc/49-Dify接入与MCP开放.md、doc/51-通用单表GraphQL查询.md。
未开通 client_credentials。平台表白名单 GraphQL 只读见 POST /api/open/mcp/graphql（12 为 HMAC 通道）；第三方库 JDBC 视图仍见 09。

1. 鉴权

工具令牌由门户 AI 网关在用户已登录会话内签发（短期 opaque，存 Redis）。调用方请求：

Authorization: Bearer {toolToken}

服务端从令牌解析 username 与 scope。禁止用工具 Body 里的 username 做授权。

scope	能力
mcp:kb:read	知识检索 / 文档 / 文件（受文档 ACL）
mcp:matter:read	当前用户待办
mcp:data:query	平台表白名单 GraphQL 只读（叠加字段/行级权限）

时间窗：令牌 TTL 默认 1800 秒。过期须由网关重新签发。

2. 基路径

/api/open/mcp（不走门户 Session 拦截器）。

方法	路径	说明
POST	/kb/search	关键词检索当前用户可见文档
GET	/kb/documents?docCode=	文档详情
GET	/kb/files?fileCode=	文件下载（先过文档 ACL）
GET	/matters/unread-count	未读角标
GET	/matters/page?view=	事项分页（view 同门户）
GET	/matters?matterId=	事项详情（须为参与人或发起人）
POST	/graphql	平台表白名单 GraphQL（scope mcp:data:query）

响应：知识/待办接口仍为门户 ApiResult。/graphql 例外返回 GraphQL {data,errors}（见 12 §3.3）。其它接口鉴权失败 HTTP 200 + code=401/403（与开放 HMAC 习惯一致）或 401，以代码为准。

3. 知识可见范围

检索结果 = 已发布的 PLATFORM + SYSTEM + 本人 USER + 所在 TEAM 文档。他人 USER 文档不会出现。

4. 待办隔离

与门户 /api/portal/matters 相同：按 portal_matter_party.username / 发起人过滤。即使用户对模型说「查 B 的待办」，服务端仍只查令牌用户。

5. 与 HMAC / OAuth2 的边界

能力	鉴权
第三方 推送 事项/知识	HMAC（02、06）
任务中心用户委托	OAuth2（03）
Agent 读取 当前用户待办/知识	本文工具令牌
Agent 读取 平台表白名单（GraphQL）	本文工具令牌 + mcp:data:query
第三方系统批查平台表	HMAC 12（须先申请审核）
/api/portal/**、/api/system/**	门户会话，工具令牌不可用

6. Dify 配置提示

工作区级 MCP 凭证无法按终端用户隔离。推荐 Chatflow HTTP 请求工具，Header：

Authorization: Bearer {{tool_token}}

tool_token 来自网关写入的会话 inputs，不要让模型生成。