跳到主要内容

MCP 智能体

「MCP 智能体」用于登记外部 AI 平台，并控制它能通过管理端 MCP 使用哪些 ApiGo 工具。它与 AI 助手页面中的对话智能助理是两套独立系统：

系统位置用途
对话智能助理AI 助手页面平台内置的对话式操作入口

智能体列表​

入口：账户中心 → MCP。

列说明
编码智能体编码，即 MCP 地址中的 {agentCode}
名称智能体展示名称
类型WorkBuddy、千问办公、豆包或自定义
项目智能体所属项目
状态启用 / 禁用
最后修改最近更新时间
操作工具、MCP 配置、重置 Key、删除

列表支持按关键词和类型筛选。启用状态可以直接通过开关切换，禁用后该智能体的所有 MCP 请求被拒绝。

创建智能体​

创建分两步：

1. 选择类型​

类型说明默认工具
WorkBuddy通用办公智能体数据源查询、接口查询、日志查询、接口保存/上下线等 9 个工具
千问办公千问办公智能体数据源与接口查询 4 个工具
豆包豆包智能体接口查询 2 个工具
自定义通用 MCP 客户端不预置工具

模板只决定初始工具集，创建后可以在「工具」中自由调整。

2. 填写信息​

字段必填说明
智能体类型是上一步选择的类型，创建后可重新选择
项目—只读，取当前项目
编码是^[a-z0-9_-]{3,64}$，创建后不可修改，同时作为 MCP 路径参数
名称是智能体展示名称
图标否当前界面未开放
描述否用途说明

编码建议体现调用方和用途，例如 workbuddy-dev、ops-assistant。

Agent Key​

创建成功后弹出 Agent Key：

  • 格式为 ak_ 加随机串；
  • 服务端只保存 SHA-256 哈希和 8 位前缀，明文只展示一次；
  • 弹窗同时给出对应平台的 MCP 配置片段；
  • 忘记或泄露后可在列表点击「重置 Key」，旧 Key 立即失效。

配置片段的核心结构：

{
  "mcpServers": {
    "ApiGo-Admin": {
      "type": "http",
      "url": "https://{your-gateway}/api/box/mcp/{agentCode}",
      "headers": {
        "X-Agent-Key": "{AgentKey}"
      }
    }
  }
}

管理端 MCP 端点、协议和错误码见 MCP 接入。

工具授权​

点击列表中的「工具」打开工具抽屉：

  • 工具按数据源、接口开发、日志、分组、其他分类展示；
  • 每个工具标注是否为写操作；
  • 支持按名称/描述搜索、只看已选、按分类全选；
  • 底部显示已选数量和写工具数量；
  • 保存后立即影响 tools/list 的返回结果。

工具目录共 32 个：18 个只读、14 个写。写工具在智能助理中会触发二次确认；api_debug_invoke 因可能产生业务副作用也按写操作处理。

智能体实际可用的工具还受创建者的管理端权限约束。即使绑定了某个工具，创建者没有对应权限时也不会出现在 tools/list 中。

权限与隔离​

管理端 MCP 的权限模型：

  1. 智能体维度：只暴露绑定的工具；
  2. 创建者维度：创建者必须仍是有效用户，且拥有智能体所属项目的访问权限；
  3. 项目维度：所有工具调用在智能体所属项目的上下文中执行，不能跨项目访问资源；
  4. 状态维度：智能体禁用、Key 重置或创建者失效都会导致调用失败。

因此智能体不是超级账号，它继承创建者在所属项目内的权限，并进一步收窄到绑定的工具集合。

调用与管理​

  • 外部客户端使用 POST /api/box/mcp/{agentCode}，请求头携带 X-Agent-Key；
  • 支持 initialize、tools/list、tools/call；
  • 每次成功鉴权会刷新最后活跃时间；
  • 调用记录写入智能体调用日志，包含工具、参数摘要、结果和执行时间；
  • 删除智能体会同时删除其工具绑定和 Key，操作不可恢复。

常见问题​

现象原因处理
客户端提示缺少 API Key未携带 X-Agent-Key在请求头中补充 Agent Key
提示智能体不存在agentCode 写错或智能体已删除核对列表中的编码
提示智能体已禁用状态开关关闭在列表中启用
提示 Key 无效Key 被重置或复制不完整使用最新 Key
工具列表为空未绑定工具，或创建者无对应权限在工具抽屉中绑定并检查创建者权限
工具调用提示无权限创建者失去项目访问权限恢复项目权限或重建智能体

相关文档​