MCP 智能体接入
智能体（也叫 AI 助手）是能理解自然语言、自己决定下一步做什么的程序。光会聊天还不够，它要查数据、办事情，就得能调用别的系统提供的功能，这些功能叫工具。MCP（Model Context Protocol，模型上下文协议）是一种公开的标准，规定智能体怎样发现和调用工具。支持 MCP 的智能体客户端，配上地址和令牌就能接入，不需要为每个系统单独写对接代码。
栖梧可以作为 MCP 的服务端：智能体连上来以后，以某个用户的身份调用后台的工具，比如查自己的资料、按条件查用户、新建一本示例图书。它能做的事不会超过这个用户本人在后台能做的事。
默认关闭
智能体接入默认关闭，不需要的项目可以跳过这一页。模板只提供底座和四个示例工具，项目自己的工具按给模块加 MCP 工具添加。
打开开关
有两层开关：
| 开关 | 在哪里 | 作用 |
|---|---|---|
APP_MCP | 服务端环境变量，默认 false | 只在启动时读取，改完要重启全部服务端实例。关闭时整个模块不加载：/api/mcp、发现文档和所有管理接口都返回 404，侧栏和角色授权树里也看不到 MCP 工具、访问令牌 两页 |
mcp.paused | 系统管理 → 参数设置，默认 false，只有超级管理员（root）能改 | 运行中的急停。改成 true 后，所有工具调用立即被拒绝（工具列表照常能看，令牌也保留），改回 false 就恢复。不需要重启，所有实例同时生效 |
数据表（访问令牌、工具停用记录）不管开关如何都由数据库迁移创建，打开开关时不需要另外迁移。部署时的注意事项见部署 · 智能体接入，完整说明见仓库的启用。
端点
智能体只连一个地址：POST /api/mcp，比如 https://你的域名/api/mcp。
- 只提供工具这一种能力：初始化、列出工具（
tools/list）、调用工具（tools/call）。MCP 里的资源、提示词等其他能力都不提供； - 无状态：每个请求单独处理，服务端不保存会话，也不主动推送消息；
- 列出工具时，只列这个令牌此刻真正能用的工具：工具已启用、令牌允许、有写入许可（写入类工具），并且用户有对应的权限点。
协议细节见仓库的端点与协议。
两种接入方式
智能体每次调用都要带一个令牌，证明它代表的是哪个用户。令牌有两种来源。
个人访问令牌
最简单的方式，适合个人自己用的智能体。用户在个人中心的 访问令牌 页签里自己创建：
- 创建时要再输入一次当前密码；
- 令牌只在创建时显示一次，关掉弹窗就再也看不到了，请立即复制保存；系统里只存它的摘要和末 4 位，丢了只能吊销后重建；
- 有效期：页面上可以选 7 天、30 天、90 天或永不过期（接口允许 1 到 90 天，或不过期）；
- 允许的工具：可以只勾选部分工具；不选就是全部工具，以后新增的工具也自动包含；
- 允许写入类工具：会新增或修改数据的工具叫写入类工具，要单独打开这个开关才能用，否则只能用只读工具；
- 每人最多同时有 20 个有效令牌；
- 随时可以自己吊销，立即生效，不能恢复。
出现下面任一情况，这个用户的令牌永久失效（重新启用账号也不会恢复）：用户被停用或删除、修改或重置了密码、被管理员强制下线、密码多次输错被锁定；租户被停用，或租户的到期时间被提前到现在之前。换手机号、解绑微信不影响令牌。
见仓库的个人访问令牌。
OAuth2
适合第三方开发的智能体服务。它沿用单点登录（OAuth2）：管理员在 系统管理 → 客户端管理 里登记智能体的后端，勾选两个新的授权范围，用户在授权页同意后，智能体拿到代表这个用户的令牌。
| 授权范围 | 作用 |
|---|---|
mcp | 可以调用只读工具。只有带它的令牌才能访问 /api/mcp，也只能访问这里 |
mcp.write | 和 mcp 一起勾选：还可以调用写入类工具，代用户新增或修改数据 |
这两个范围默认不勾选，只在登记智能体客户端时由管理员明确授予。和单点登录一样，只支持有自己后端、能保管客户端密钥的机密客户端；不支持动态注册客户端，也不服务没有密钥的公开客户端。很多桌面智能体客户端依赖这两项完成 OAuth 登录，它们请改用个人访问令牌。
见仓库的 OAuth2。
以用户本人的身份运行
不管用哪种令牌，每次调用都按令牌所属用户本人的权限运行：
- 权限点和数据范围和这个用户在后台操作时完全一样，角色或菜单授权变了立即生效，见权限与数据范围；
- 开启多租户时，只在这个用户自己的租户里运行，身份和租户都只从令牌里来。平台人员“进入租户”的状态不能经 MCP 使用；
- 超级管理员（root）的令牌拥有 root 的全部权限，请谨慎签发；
- 每次调用（包括被拒绝的）都在 系统管理 → 日志管理 → 操作日志 里记一条，动作是“智能体调用”，标明是智能体代这个用户做的，并记下用的是哪个令牌；参数里像密码、密钥的字段显示为
***。工具改动的数据，创建人或修改人照常记为这个用户。
护栏
每次调用依次经过下面这些检查，任何一步不通过都不会执行：
| 检查 | 说明 |
|---|---|
| 限流 | 每个令牌每分钟最多 60 次调用（所有实例合计），每个来源 IP 每分钟最多 600 次请求 |
| 急停 | 参数 mcp.paused 为 true 时一律拒绝 |
| 参数大小 | 参数嵌套超过 32 层，或者超过 16 KiB，直接拒绝，不校验也不运行 |
| 工具开关 | 工具在 MCP 工具 页上被停用 |
| 令牌限制 | 令牌没有列出这个工具；或者是写入类工具，而令牌不允许写入 |
| 权限点 | 用户没有工具要求的权限点，或租户套餐不包含它 |
| 参数校验 | 参数不符合工具声明的格式时，返回出错的字段 |
| 超时 | 每个工具有运行时限（默认 30 秒，最长 120 秒） |
| 输出 | 结果里名称像密码、令牌、密钥的字段一律遮成 ***；结果超过 64 KiB 不返回 |
写入类工具超时时，智能体立即收到超时错误，但已经开始的写入可能随后完成。所以智能体收到超时后应该先查一下，再决定要不要重试。
见仓库的护栏与审计。
示例工具
模板自带四个示例工具：
| 工具 | 类型 | 需要的权限 | 做什么 |
|---|---|---|---|
iam.me.get | 只读 | 任何登录用户 | 返回令牌所属用户本人的资料：用户名、姓名、部门、角色、岗位、语言 |
iam.user.search | 只读 | 用户管理的浏览权限 | 按关键字、部门、状态查用户，每页最多 50 条；和用户列表是同一个查询，数据范围和手机号遮蔽都一样 |
cfg.dict.options | 只读 | 任何登录用户 | 一个已启用字典的选项，标签按请求的语言 |
demo.book.create | 写入 | 示例图书的新增权限 | 新建一本示例图书，和页面上的新增走同一套规则（部门数据范围、唯一性、创建人） |
见仓库的示例工具。
管理页面
打开开关后，系统管理 下多出两个页面：
- 系统管理 → MCP 工具：列出所有已注册的工具（工具名、标题、类型、所需权限、说明），页面上方显示 MCP 端点的地址。可以整体停用某个工具，对所有租户和令牌生效。开启多租户时这是平台专属页面，只有默认租户（平台）能用；
- 系统管理 → 访问令牌：查看本租户所有用户的访问令牌（可以按用户、名称、状态筛选），并且可以吊销。令牌本身不会显示，只显示末 4 位。
两个页面的按钮权限在 系统管理 → 角色管理 → 菜单权限 里授予：MCP 工具有浏览、修改，访问令牌有浏览、吊销。个人中心里的 访问令牌 页签每个登录用户都能用，不需要授权。
配置客户端
任何支持 MCP 的 Streamable HTTP 传输方式、并且能设置自定义请求头的客户端都可以接入。以个人访问令牌为例，大致步骤：
- 在个人中心的 访问令牌 页签里新建一个令牌，复制保存；
- 在客户端的 MCP 服务器配置里，填地址
https://你的域名/api/mcp，传输方式选 HTTP； - 添加请求头
Authorization，值是Bearer加上令牌； - 让智能体列出工具，确认能看到预期的工具。
具体的配置文件示例和检查命令见开发指南的给模块加 MCP 工具 · 配置客户端，以及仓库的客户端配置示例。
在演示站体验
在线演示没有打开智能体接入。演示站运行在演示模式下，写入操作一律被拒绝，所以也建不了访问令牌。要体验，请在自己的安装上打开 APP_MCP。另外，开了演示模式（APP_DEMO_MODE=true）的安装，即使打开了 APP_MCP，POST /api/mcp 也会和其他写接口一样被拒绝。
已知限制
- 只提供工具，不提供资源、提示词等其他 MCP 能力；服务端不主动推送，工具列表变了要由客户端重新获取；
- 超时只结束等待，已经开始的数据库操作无法中断；
- OAuth2 不支持动态注册客户端和公开客户端；
- 日志里按字段名遮蔽，名称里含
key、token、pass等词的字段（比如keyword）也会显示为***，这是有意的保守规则。
完整清单见仓库的已知上限。
相关功能：