01 接入方案与身份选择
本文采用飞书官方“开发者调用远程 MCP 服务”，面向 DF AI Web 后端集成，无需部署本地 MCP 服务。当前官方远程工具主要面向云文档，支持搜索、读取、创建、更新文档等；不能据此认为它覆盖全部飞书 API。
| 身份 | 令牌与 MCP 请求头 | 适用场景 |
|---|---|---|
| 用户身份 | user_access_token（UAT） X-Lark-MCP-UAT | 用户授权后搜索、读取或编辑本人有权限的文档；适合按用户使用的知识问答 |
| 应用身份 | tenant_access_token（TAT） X-Lark-MCP-TAT | 应用读取或更新明确授权给应用的文档；适合固定资料库、后台自动化 |
两个身份请求头任选其一。飞书 MCP 不需要腾讯广告的 MCP KEY，也不使用巨量引擎的 Access-Token 请求头；App Secret 不能直接当作 MCP 访问令牌。
DF AI 若要求每位用户只能访问自己的飞书资源，建议使用 UAT 并绑定当前 DF AI 用户；后台统一交付到授权文档可评估 TAT。具体选择取决于工具支持的身份及资源权限。
02 获取 MCP 服务 URL
官方开发者文档“认证与请求 → 请求路径”提供固定服务地址：
https://mcp.feishu.cn/mcp
连接方式为 Streamable HTTP，官方请求方法为 POST。飞书开放平台网页、文档链接和普通 OpenAPI 地址均不能当作 MCP 服务 URL。
凭据与允许调用的工具通过请求头配置，不拼接到上述 URL 中。
来源：飞书 MCP 认证与请求说明。
03 获取 App ID 与 App Secret
- 登录 飞书开放平台开发者后台，创建企业自建应用。本文先按企业内部自建应用说明。
- 进入应用的 基础信息 → 凭证与基础信息，获取 App ID、App Secret。
- 在权限管理中，根据工具清单申请对应身份的 API 权限，并按平台流程完成版本发布或管理员审批。
- 需要用户身份时，在 开发配置 → 安全设置登记 OAuth 重定向 URL。该地址由 DF AI 后端提供，用于接收授权码。
- 应用身份访问文档时，还需将应用加入相应文档或知识库的访问范围；仅开通 API 权限不足以读取所有企业文档。
04 获取 MCP 访问令牌
方案 A：用户身份 UAT
创建应用 → 配置回调 → 用户登录授权 → 后端收到 code → 换取 UAT → 按官方机制刷新
- 后端按 获取授权登录授权码文档生成用户授权链接，校验回调与 state，将授权结果绑定到当前 DF AI 用户。
- 用户登录飞书并授权所需权限，平台回调登记地址，后端接收授权码。
- 后端调用 获取 user_access_token接口，按官方参数换取令牌，保存返回的有效期及刷新凭据。
- 请求 MCP 时配置
X-Lark-MCP-UAT: <user_access_token>，不加 Bearer 前缀。 - 到期前通过 刷新 user_access_token更新令牌；用户撤销授权或刷新失败时，引导重新授权。
有效期以接口返回为准，不通过令牌字符串前缀推断类型；新版本 UAT 格式可能与旧版不同。
方案 B：应用身份 TAT
- 后端使用自建应用 App ID 和 App Secret，调用 自建应用获取 tenant_access_token接口。
- 保存返回的 tenant_access_token 和剩余有效期，按官方规则更新。
- 请求 MCP 时配置
X-Lark-MCP-TAT: <tenant_access_token>，不加 Bearer 前缀。 - 确保应用的 API 权限及目标文档、知识库访问权限已开通。
用户授权、应用 API 权限和具体资源访问权限是不同环节。获取令牌成功不代表可以访问所有文档。
来源：访问凭证获取指南、MCP 身份请求头说明。
05 DF AI 配置示例
按用户查询飞书文档（UAT）
{
"mcpServers": {
"飞书云文档查询": {
"transportType": "streamable-http",
"url": "https://mcp.feishu.cn/mcp",
"headers": {
"X-Lark-MCP-UAT": "<当前用户的user_access_token>",
"Content-Type": "application/json",
"X-Lark-MCP-Allowed-Tools": "search-doc,fetch-doc,list-docs"
}
}
}
}应用身份时，将 X-Lark-MCP-UAT 替换为 X-Lark-MCP-TAT，并使用 TAT。search-doc 仅支持 UAT，TAT 示例允许工具应改为 fetch-doc,list-docs；不要同时填写两个身份请求头。
工具清单为逗号分隔的名称。官方说明：如果未配置 X-Lark-MCP-Allowed-Tools，AI 无法发现和调用工具，因此本方案必须显式配置。令牌由后端按用户或应用动态注入，不在浏览器公开保存。
| 示例工具 | 身份 | 权限说明 |
|---|---|---|
| search-doc | 仅 UAT | search:docs:read、wiki:wiki:readonly |
| fetch-doc | UAT / TAT | docx:document:readonly、task:task:read、im:chat:read；按官方清单申请 |
| list-docs | UAT / TAT | wiki:wiki:readonly |
fetch-doc 暂不支持读取多维表格、电子表格等内容。文档写入、评论等能力需另加工具及相应权限；不要把群聊推送配置视为本远程 MCP 已支持的工具。
来源：官方工具支持身份、权限及功能限制。
06 DF AI 开发与验证建议
- 统一由后端连接：建立 MCP 会话，按官方流程执行 initialize、tools/list、tools/call；优先使用合适的 MCP SDK处理协议及会话。
- 按用户绑定授权：UAT 按 DF AI 用户与飞书用户身份关联，避免多人共用某个管理员的令牌。TAT 仅访问已授权给应用且 DF AI 用户也有权使用的资料。
- 维护令牌：服务端保管 App Secret、令牌及刷新凭据；刷新失败或撤权时停止调用并要求重新授权。
- 先测只读：初始化、获取工具列表，再搜索或读取一篇有权限的文档，并检查越权文档应被拒绝。
- 分辨错误：检查身份请求头、工具允许列表、API 权限及文档权限；HTTP 200 时仍要检查工具结果中的 isError，不能只看状态码。
- 确认接入边界：本方案采用官方开发者远程 MCP。个人托管链接和历史远程配置已被官方标记不推荐，避免用个人链接作为企业公共凭据。
本说明用于原型评审与开发参考。本次未创建飞书应用、获取真实令牌或执行真实文档操作；DF AI 仍需实现后端授权、刷新与身份隔离。