---
url: https://qiwuadmin.com/features/mcp.md
description: >-
  让智能体（AI 助手）以某个用户的身份调用后台功能：APP_MCP 开关与急停参数、POST /api/mcp 端点、个人访问令牌和 OAuth2
  两种接入方式、权限与操作日志、护栏、示例工具、MCP 工具页和访问令牌页，默认关闭。
---

# MCP 智能体接入

**智能体**（也叫 AI 助手）是能理解自然语言、自己决定下一步做什么的程序。光会聊天还不够，它要查数据、办事情，就得能调用别的系统提供的功能，这些功能叫**工具**。**MCP**（Model Context Protocol，模型上下文协议）是一种公开的标准，规定智能体怎样发现和调用工具。支持 MCP 的智能体客户端，配上地址和令牌就能接入，不需要为每个系统单独写对接代码。

栖梧可以作为 MCP 的**服务端**：智能体连上来以后，以**某个用户的身份**调用后台的工具，比如查自己的资料、按条件查用户、新建一本示例图书。它能做的事不会超过这个用户本人在后台能做的事。

::: tip 默认关闭
智能体接入默认关闭，不需要的项目可以跳过这一页。模板只提供底座和四个示例工具，项目自己的工具按[给模块加 MCP 工具](/core/mcp)添加。
:::

## 打开开关

有两层开关：

| 开关 | 在哪里 | 作用 |
| --- | --- | --- |
| `APP_MCP` | 服务端环境变量，默认 `false` | 只在启动时读取，改完要重启**全部**服务端实例。关闭时整个模块不加载：`/api/mcp`、发现文档和所有管理接口都返回 404，侧栏和角色授权树里也看不到 **MCP 工具**、**访问令牌** 两页 |
| `mcp.paused` | **系统管理 → 参数设置**，默认 `false`，**只有超级管理员（root）能改** | 运行中的急停。改成 `true` 后，所有工具调用立即被拒绝（工具列表照常能看，令牌也保留），改回 `false` 就恢复。不需要重启，所有实例同时生效 |

数据表（访问令牌、工具停用记录）不管开关如何都由数据库迁移创建，打开开关时不需要另外迁移。部署时的注意事项见[部署 · 智能体接入](/guide/deploy#智能体接入-mcp)，完整说明见仓库的[启用](https://github.com/732124645/qiwu-vue-admin/blob/main/docs/mcp.md#启用)。

## 端点

智能体只连一个地址：`POST /api/mcp`，比如 `https://你的域名/api/mcp`。

* 只提供**工具**这一种能力：初始化、列出工具（`tools/list`）、调用工具（`tools/call`）。MCP 里的资源、提示词等其他能力都不提供；
* **无状态**：每个请求单独处理，服务端不保存会话，也不主动推送消息；
* 列出工具时，只列这个令牌此刻**真正能用**的工具：工具已启用、令牌允许、有写入许可（写入类工具），并且用户有对应的权限点。

协议细节见仓库的[端点与协议](https://github.com/732124645/qiwu-vue-admin/blob/main/docs/mcp.md#端点与协议)。

## 两种接入方式

智能体每次调用都要带一个**令牌**，证明它代表的是哪个用户。令牌有两种来源。

### 个人访问令牌

最简单的方式，适合个人自己用的智能体。用户在**个人中心**的 **访问令牌** 页签里自己创建：

* 创建时要再输入一次**当前密码**；
* 令牌**只在创建时显示一次**，关掉弹窗就再也看不到了，请立即复制保存；系统里只存它的摘要和末 4 位，丢了只能吊销后重建；
* **有效期**：页面上可以选 7 天、30 天、90 天或永不过期（接口允许 1 到 90 天，或不过期）；
* **允许的工具**：可以只勾选部分工具；不选就是全部工具，以后新增的工具也自动包含；
* **允许写入类工具**：会新增或修改数据的工具叫**写入类工具**，要单独打开这个开关才能用，否则只能用只读工具；
* 每人最多同时有 20 个有效令牌；
* 随时可以自己**吊销**，立即生效，不能恢复。

出现下面任一情况，这个用户的令牌**永久失效**（重新启用账号也不会恢复）：用户被停用或删除、修改或重置了密码、被管理员强制下线、密码多次输错被锁定；租户被停用，或租户的到期时间被提前到现在之前。换手机号、解绑微信不影响令牌。

见仓库的[个人访问令牌](https://github.com/732124645/qiwu-vue-admin/blob/main/docs/mcp.md#个人访问令牌)。

### OAuth2

适合第三方开发的智能体服务。它沿用[单点登录（OAuth2）](/features/oauth)：管理员在 **系统管理 → 客户端管理** 里登记智能体的后端，勾选两个新的授权范围，用户在授权页同意后，智能体拿到代表这个用户的令牌。

| 授权范围 | 作用 |
| --- | --- |
| `mcp` | 可以调用只读工具。只有带它的令牌才能访问 `/api/mcp`，也只能访问这里 |
| `mcp.write` | 和 `mcp` 一起勾选：还可以调用写入类工具，代用户新增或修改数据 |

这两个范围默认不勾选，只在登记智能体客户端时由管理员明确授予。和单点登录一样，只支持有自己后端、能保管客户端密钥的**机密客户端**；不支持动态注册客户端，也不服务没有密钥的公开客户端。很多桌面智能体客户端依赖这两项完成 OAuth 登录，它们请改用个人访问令牌。

见仓库的 [OAuth2](https://github.com/732124645/qiwu-vue-admin/blob/main/docs/mcp.md#oauth2)。

## 以用户本人的身份运行

不管用哪种令牌，每次调用都按**令牌所属用户本人**的权限运行：

* **权限点**和**数据范围**和这个用户在后台操作时完全一样，角色或菜单授权变了立即生效，见[权限与数据范围](/features/permission)；
* 开启[多租户](/features/multi-tenancy)时，只在这个用户自己的租户里运行，身份和租户都只从令牌里来。平台人员“进入租户”的状态不能经 MCP 使用；
* 超级管理员（root）的令牌拥有 root 的全部权限，请谨慎签发；
* 每次调用（包括被拒绝的）都在 **系统管理 → 日志管理 → 操作日志** 里记一条，动作是“智能体调用”，标明是智能体代这个用户做的，并记下用的是哪个令牌；参数里像密码、密钥的字段显示为 `***`。工具改动的数据，创建人或修改人照常记为这个用户。

## 护栏

每次调用依次经过下面这些检查，任何一步不通过都不会执行：

| 检查 | 说明 |
| --- | --- |
| 限流 | 每个令牌每分钟最多 60 次调用（所有实例合计），每个来源 IP 每分钟最多 600 次请求 |
| 急停 | 参数 `mcp.paused` 为 `true` 时一律拒绝 |
| 参数大小 | 参数嵌套超过 32 层，或者超过 16 KiB，直接拒绝，不校验也不运行 |
| 工具开关 | 工具在 **MCP 工具** 页上被停用 |
| 令牌限制 | 令牌没有列出这个工具；或者是写入类工具，而令牌不允许写入 |
| 权限点 | 用户没有工具要求的权限点，或租户套餐不包含它 |
| 参数校验 | 参数不符合工具声明的格式时，返回出错的字段 |
| 超时 | 每个工具有运行时限（默认 30 秒，最长 120 秒） |
| 输出 | 结果里名称像密码、令牌、密钥的字段一律遮成 `***`；结果超过 64 KiB 不返回 |

写入类工具超时时，智能体立即收到超时错误，但已经开始的写入可能随后完成。所以智能体收到超时后应该先查一下，再决定要不要重试。

见仓库的[护栏与审计](https://github.com/732124645/qiwu-vue-admin/blob/main/docs/mcp.md#护栏与审计)。

## 示例工具

模板自带四个示例工具：

| 工具 | 类型 | 需要的权限 | 做什么 |
| --- | --- | --- | --- |
| `iam.me.get` | 只读 | 任何登录用户 | 返回令牌所属用户本人的资料：用户名、姓名、部门、角色、岗位、语言 |
| `iam.user.search` | 只读 | 用户管理的浏览权限 | 按关键字、部门、状态查用户，每页最多 50 条；和用户列表是同一个查询，数据范围和手机号遮蔽都一样 |
| `cfg.dict.options` | 只读 | 任何登录用户 | 一个已启用字典的选项，标签按请求的语言 |
| `demo.book.create` | 写入 | 示例图书的新增权限 | 新建一本示例图书，和页面上的新增走同一套规则（部门数据范围、唯一性、创建人） |

见仓库的[示例工具](https://github.com/732124645/qiwu-vue-admin/blob/main/docs/mcp.md#示例工具)。

## 管理页面

打开开关后，**系统管理** 下多出两个页面：

* **系统管理 → MCP 工具**：列出所有已注册的工具（工具名、标题、类型、所需权限、说明），页面上方显示 MCP 端点的地址。可以整体**停用**某个工具，对所有租户和令牌生效。开启多租户时这是**平台专属页面**，只有默认租户（平台）能用；
* **系统管理 → 访问令牌**：查看本租户所有用户的访问令牌（可以按用户、名称、状态筛选），并且可以吊销。令牌本身不会显示，只显示末 4 位。

两个页面的按钮权限在 **系统管理 → 角色管理 → 菜单权限** 里授予：MCP 工具有浏览、修改，访问令牌有浏览、吊销。个人中心里的 **访问令牌** 页签每个登录用户都能用，不需要授权。

## 配置客户端

任何支持 MCP 的 **Streamable HTTP** 传输方式、并且能设置自定义请求头的客户端都可以接入。以个人访问令牌为例，大致步骤：

1. 在个人中心的 **访问令牌** 页签里新建一个令牌，复制保存；
2. 在客户端的 MCP 服务器配置里，填地址 `https://你的域名/api/mcp`，传输方式选 HTTP；
3. 添加请求头 `Authorization`，值是 `Bearer ` 加上令牌；
4. 让智能体列出工具，确认能看到预期的工具。

具体的配置文件示例和检查命令见开发指南的[给模块加 MCP 工具 · 配置客户端](/core/mcp#配置客户端)，以及仓库的[客户端配置示例](https://github.com/732124645/qiwu-vue-admin/blob/main/docs/mcp.md#客户端配置示例)。

## 在演示站体验

[在线演示](/guide/introduction#在线演示)**没有打开**智能体接入。演示站运行在演示模式下，写入操作一律被拒绝，所以也建不了访问令牌。要体验，请在自己的安装上打开 `APP_MCP`。另外，开了演示模式（`APP_DEMO_MODE=true`）的安装，即使打开了 `APP_MCP`，`POST /api/mcp` 也会和其他写接口一样被拒绝。

## 已知限制

* 只提供工具，不提供资源、提示词等其他 MCP 能力；服务端不主动推送，工具列表变了要由客户端重新获取；
* 超时只结束等待，已经开始的数据库操作无法中断；
* OAuth2 不支持动态注册客户端和公开客户端；
* 日志里按字段名遮蔽，名称里含 `key`、`token`、`pass` 等词的字段（比如 `keyword`）也会显示为 `***`，这是有意的保守规则。

完整清单见仓库的[已知上限](https://github.com/732124645/qiwu-vue-admin/blob/main/docs/mcp.md#已知上限)。

相关功能：

* [单点登录（OAuth2）](/features/oauth)
* [权限与数据范围](/features/permission)
* [系统管理 · 个人中心](/features/system#个人中心)
* [给模块加 MCP 工具](/core/mcp)（开发指南）