MCP管理
MCP（Model Context Protocol，模型上下文协议）是 AI 助手调用外部工具的通用协议。开通后，Cursor、Claude Code、Codex、企业微信大圆、千问办公、WorkBuddy 等支持 MCP 的 AI 工具，可以用你企业的 API Key 直接调用立刻智能体的知识库、智能体与业务工具；Claude 网页版 / 桌面版、ChatGPT 则由员工用自己的控制台账号 OAuth 授权接入。不需要再逐个对接接口。
本篇面向控制台使用者，说明怎么开通、怎么管工具、出了问题怎么查。开发者与合作方平台需要的接口参数、返回结构与错误码，请看技术文档 MCP 文档。
能做什么
| 工具 | 作用 | 类型 | 需要的能力授权 | 适用套餐 |
|---|---|---|---|---|
| 知识检索 | 按问题检索企业知识库，返回命中的问答原文 | 只读 | AI 会话 | 专业版 / 旗舰版 |
| 智能体问答 | 向企业智能体提问，得到与开放 API 一致的回答 | 只读 | AI 会话 | 专业版 / 旗舰版 |
| 新增知识 | 向知识库新增一条问答 | 写入 | 知识库写入 | 专业版 / 旗舰版 |
| HS 编码查询 | 按商品名称搜索编码，或查询编码详情 | 只读 | 无 | 专业版 / 旗舰版 |
| 汇率查询 | 查询汇率并换算金额 | 只读 | 无 | 专业版 / 旗舰版 |
| 舱单查询 | 按提运单号查询舱单状态 | 只读 | 无 | 仅旗舰版 |
| 立刻云单号查询 | 按单号和客户群查询立刻云单票信息，默认关闭，详见下文「立刻云两个工具」 | 只读 | 无（经 OAuth 调用时另需员工权限） | 仅旗舰版 |
| 立刻云单证获取 | 按单号、单证类型和客户群获取单证文件下载链接，默认关闭 | 只读 | 无（经 OAuth 调用时另需员工权限） | 仅旗舰版 |
| 可推送群列表 | 列出可推送通知的群 | 只读 | 推送通知 | 专业版 / 旗舰版 |
| 推送通知 | 向指定群推送通知，发出后不能撤回 | 对外发送 | 推送通知 | 专业版 / 旗舰版 |
- 套餐：基础版不支持；专业版可用其余全部工具（不含舱单查询与立刻云两个工具）；旗舰版可用全部工具。
- 计费：与在控制台或开放 API 中使用同一能力的计费一致。智能体问答按实际消耗扣套餐 Token；知识检索、新增知识只计向量化的 Token；HS 编码、舱单查询成功出站扣技能点（技术失败自动冲正）；汇率查询与可推送群列表免费；立刻云单号查询、单证获取免费（不经大模型、不扣技能点）；推送通知占用推送通知额度。工具清单的「计费」一栏以页面显示为准。HS 编码、汇率、舱单查询经 MCP 直接调用时不经过智能体，技能点用量明细里「智能体」显示为「未调用智能体」、「渠道」显示为「MCP」；经智能体问答间接调用的技能仍显示对应智能体。
- 调用频率：MCP 与开放 API 共用同一 Key 的每分钟调用上限（见开放 API），AI 工具的每一次请求（含建立连接、列出工具）都计一次。
入口与权限
- 入口：控制台 外部拓展 → MCP管理（位于「API设置」下方）。页面有三个 Tab：「对外开放」「个人授权」「调用记录」。
- 权限：需要 MCP管理（
mcp-server）功能权限，企业管理员始终拥有；员工需由企业管理员在成员与权限中授予。「全部标准功能」授权模式不包含此项，须单独勾选（在角色或个人加授中）。该权限依赖「API 设置」，属于敏感权限——持有者可以为 Key 开启会对外发送的工具。 - 套餐：专业版 / 旗舰版。基础版菜单置灰并带 Pro 角标，点开显示升级提示。
- 「开放 API 权限」（为 Key 开通 MCP 接入）仍只有企业管理员可以修改。
开通步骤
- 准备 API Key：在 外部拓展 → API设置 新建一个 Key（如「Cursor 接入」），把完整 Key 保存好。完整 Key 只在新建时显示一次，之后只能看到前缀。
- 为 Key 开通 MCP 接入（企业管理员）：进入 系统设置 → 开放 API 权限，启用「MCP 接入」并勾选上一步的 Key，点击保存。详见系统设置。若要使用知识检索、智能体问答、新增知识、推送通知等工具，还需在同一页为该 Key 勾选对应能力类（AI 会话 / 知识库写入 / 推送通知）。
- 在 MCP管理开关工具：打开 外部拓展 → MCP管理 → 对外开放，在「可用 Key」中点选该 Key，在「工具清单」中按需开关工具。
- 复制配置：在「接入配置」中切换到你的平台（Claude 网页版 / 桌面版 / ChatGPT / 千问办公 / WorkBuddy / 企业微信大圆 / Cursor / Claude Code / Codex / 通用（JSON）），点「复制配置」，粘贴到对应 AI 工具中，并把占位符
<请填入你的 sk-Key>替换成第 1 步保存的完整 Key（Claude 网页版 / 桌面版、ChatGPT 不用 Key，见下文「OAuth 授权接入」）。 - 检查开通状态：回到 MCP管理，选中该 Key 点「检查开通状态」，确认可用；再在 AI 工具中调用一次工具，到「调用记录」Tab 确认出现记录。
服务地址有两个：用 Key 接入的形如
https://agent.likelic.com/mcp?customer_code=你的企业代码（页面上已自动带上本企业代码，可直接复制）；用 OAuth 接入的是不带企业代码的https://agent.likelic.com/mcp。千问办公、WorkBuddy 用 Key 接入，各有独立说明：千问办公接入 MCP、WorkBuddy 接入 MCP。
OAuth 授权接入（Claude 网页版 / 桌面版、ChatGPT、Gemini 网页版）
Claude 网页版 / 桌面版和 ChatGPT 的自定义连接器只支持 OAuth 授权，不能填 Key。企业管理员开启后，员工在 AI 助手里只填一个地址，跳转到立刻智能体的授权页，用自己的控制台账号登录并同意，就可以以企业名义调用 MCP 工具。
所需权限与套餐
- 套餐：专业版 / 旗舰版。
- 管理员侧（开启与管理授权）：需要 MCP管理（
mcp-server）功能权限，企业管理员始终拥有。 - 员工侧（授权并使用）：需要 MCP 个人授权（
mcp-oauth）功能权限，依赖「个人设置」。企业管理员始终拥有；员工须由管理员单独授予，「全部标准功能」授权模式不包含此项，见成员与权限。
管理员：开启 OAuth 授权接入
- 先按上文「开通步骤」准备一个已在 系统设置 → 开放 API 权限 开通「MCP 接入」的 Key，并在 MCP管理 里开好需要的工具（建议单独建一个 Key，如「OAuth 接入」）。
- 进入 外部拓展 → MCP管理 → 对外开放，在「OAuth 授权接入」区的「OAuth 接入 Key」下拉里选择这个 Key。下拉只列出已启用、未过期且已开通「MCP 接入」的 Key。
- 打开「OAuth 授权接入」开关。没选 Key 时不能开启；已开启时不能把 Key 清空。
- 在「接入配置」里把平台切到「Claude 网页版 / 桌面版」或「ChatGPT」，复制不带企业代码的服务地址，发给员工。
要点：
- 全部员工共用这一个 Key：OAuth 调用能用哪些工具、拥有哪些能力、每分钟能调多少次，都由这个 Key 的工具开关、能力授权和调用频率决定；计费计入企业。
- 更换 Key：已开启时更换 Key 会二次确认。已有授权不会失效，之后改按新 Key 判定，员工授权时看到的工具列表可能随之变化。
- 关闭开关：会二次确认，页面提示将暂停的有效授权数。关闭期间所有员工的授权暂停，重新开启后，30 天内用过的授权自动恢复。关闭时会保留已选的 OAuth 接入 Key，重新开启时默认选中它；如果这把 Key 在关闭期间被删除、停用或移出「MCP 接入」，选择会被清空，开启前须重新选 Key。
- 所选 Key 被停用、删除或在「开放 API 权限」中移出「MCP 接入」时，OAuth 授权接入会自动关闭并清空所选 Key，区内提示原因，需重新选择并开启；所选 Key 过期时，区内提示「OAuth 接入 Key 已过期」，期间员工授权暂停，续期或换 Key 后恢复。
员工：添加连接器并授权
Claude 网页版 / 桌面版
- 在 Claude 中打开「设置 → 连接器 → 添加自定义连接器」。
- 名称填「立刻智能体」，地址填管理员给你的服务地址，不需要填 Key。
- 首次使用时 Claude 会跳转到立刻智能体授权页，用控制台账号登录并点「同意」。
ChatGPT
- 在 ChatGPT 中打开「设置 → 连接器 → 创建」。
- MCP 服务器地址填管理员给你的地址，认证方式选 OAuth。
- 保存后按提示跳转授权页，用控制台账号登录并同意。
Gemini 网页版
- 在 Gemini 的自定义 MCP 连接里，MCP 服务器地址填管理员给你的服务地址。
- 客户端 ID、客户端密钥都不用填（留空），Gemini 会自动注册。
- 保存后按提示跳转授权页，用控制台账号登录并同意。
注意：目前在 Gemini 里，自定义应用只能在「任务」中被调用，在普通对话里 Gemini 不会使用它（这是 Gemini 产品的限制，可能随 Google 调整，请以 Google 官方说明为准）。
授权页说明：
- 登录需要企业代码、用户名和密码；地址里带企业代码时会自动预填。登录失败统一提示「企业代码、用户名或密码错误」；连续输错会被锁定，规则与控制台登录相同。在授权页登录不会同时登录控制台。
- 登录后的确认页显示「某客户端申请访问某企业的立刻智能体」、客户端回调域名，以及本次可用的工具。该客户端未经立刻智能体验证，请确认是你本人在操作后再同意；点「拒绝」或登录步骤的「取消」都会回到 AI 助手并提示已取消。
- 无法授权时，页面会说明原因：套餐暂不支持 MCP 接入；企业尚未开启 OAuth 授权接入（含 OAuth 接入 Key 不可用）；你还没有「MCP 个人授权」权限。按提示联系企业管理员。
- 当前没有可用工具时仍可授权，页面会提示联系管理员开启工具。
授权链接要在同一个浏览器里完成
- 授权链接要在发起授权的同一个浏览器里打开并完成。
- 在另一个浏览器或设备上打开，或先在 AI 助手的内置窗口里打开过链接，会看到「授权请求已被处理」：该授权请求已在另一个浏览器中处理。请回到发起授权的浏览器继续；若你刚在 AI 助手的内置窗口里打开过，请在 AI 助手中重新发起授权。
- 看到「授权请求无效」：该授权链接已失效或来源不受信任，请回到 AI 助手重新添加连接器。
- 反复显示「授权请求已被处理」或「授权请求无效」时，请确认浏览器没有禁用 Cookie，并在系统浏览器中打开授权链接。
部分工具需要员工本人权限
OAuth 调用在 Key 的工具开关之外，对部分工具另核员工本人的功能权限。不满足时 AI 助手看不到该工具，直接调用会提示「你没有使用该工具所需的权限」：
| 工具 | 员工需具备（任一即可） |
|---|---|
| 新增知识 | 知识库 |
| 推送通知、可推送群列表 | 合作管理 或 API设置 |
| 立刻云单号查询、立刻云单证获取 | 合作管理、企微机器人、QQ机器人 任一 |
新增知识还受员工的「知识分类」授权约束：只能写入你被授权的分类；分类范围被限定的员工写入其他分类时，会提示「分类「X」不存在，或你没有该分类的写入权限」，并只列出你有权限的分类。
其余工具只看 Key 的工具开关。Key 接入不受这条限制。
授权的有效期、暂停与失效
- 访问令牌有效 1 小时，AI 助手会用刷新令牌自动续期；刷新令牌 30 天有效，每次使用都会续期并轮换。超过 30 天没有使用，授权失效，需重新授权。
- 永久失效（须重新授权）：管理员或员工本人撤销；员工被停用或删除；员工被收回「MCP 个人授权」权限（之后再授予也不恢复旧授权）；员工修改或重置密码；检测到令牌被重放使用。
- 暂停（恢复后自动可用，刷新令牌未过期即可）：企业被平台禁用；企业关闭了 OAuth 授权接入；套餐降为不含 MCP；OAuth 接入 Key 被停用、删除、过期或移出「MCP 接入」。暂停期间 AI 助手调用会提示授权已失效或暂停，请在 AI 助手中重新连接。
查看与撤销授权
- 管理员：MCP管理 → 个人授权 Tab 列出全部员工授权（员工、客户端名、授权时间、最近使用时间、状态：有效 / 已暂停 / 已失效），可按关键词和状态筛选。有效或已暂停的授权可点「撤销」（二次确认），撤销后立即失效且不可恢复，员工需重新授权；已失效的授权保留显示 90 天。
- 员工：系统管理 → 个人设置 → 已授权的 AI 助手，见个人设置，可查看并撤销自己的授权。
- 调用记录 Tab 可按「来源」（Key / OAuth）筛选；OAuth 调用的 Key 列为 OAuth 接入 Key，调用人显示为「员工姓名 · 客户端名」。
立刻云两个工具（仅旗舰版）
适合货代企业在 AI 助手里按单号查询某个客户群可见的单票信息和单证文件，数据范围与群内 @ 机器人查单号一致。
- 套餐：仅旗舰版；专业版在工具清单显示「套餐不支持」。
- 默认关闭：到 MCP管理 的「工具清单」按 Key 手动开启；它们是只读工具，开启时没有写入类的二次确认。
- 前提：企业已在 系统设置 → 单号查询 配置立刻云服务地址，否则提示「尚未配置立刻云服务」。不要求群内机器人的「单号查询」开关开启。
- 计费与频率：免费，不经大模型、不扣技能点；与群内单号查询共用立刻云每企业每分钟的查询频率限制，AI 助手连续查询会占用群内额度；同时计入 MCP 调用频率。
- 经 OAuth 调用需员工具备「合作管理」「企微机器人」「QQ机器人」任一权限（见上文）。
立刻云单号查询
| 参数 | 必填 | 说明 |
|---|---|---|
单号 order_no |
是 | 1～64 位字母、数字或 - / _ |
群渠道 channel |
是 | wework（企微）或 qq |
群标识 room_id |
是 | 企微填群 ID（可带 R: 前缀，也可不带），QQ 填群的 group_openid |
怎么拿到群标识：在目标群里发「群ID」，机器人会回复；或者在 Key 具备推送通知能力时，让 AI 助手调用「可推送群列表」查询。该群须被本企业任一未删除的机器人收录过（不要求机器人在线或仍在群内）。
返回：命中的全部票，最多 10 票，每票含工作号、客户代码、业务类型、主单号、分单号、参考号、件数、毛重、订单详情链接；超出 10 票时注明「还有 N 票未返回，请登录系统查看」。未命中时返回「未查到单号 X」。
立刻云单证获取
| 参数 | 必填 | 说明 |
|---|---|---|
单号 order_no |
是 | 同上 |
单证类型 doc_type |
是 | 须属于企业在 系统设置 → 单号查询 配置的单证类型清单 |
群渠道 channel、群标识 room_id |
是 | 同上 |
返回：每份文件的文件名与下载链接，最多 5 份，链接与群内发送的文件同一转存方式。
- 文件超过 5 份时注明「还有 N 份未返回，请登录系统查看」。
- 立刻云原始链接转存失败时，改给临时链接并注明「临时链接，可能过期」。
- 超过 50MB 的文件不转存，只列文件名并注明「文件过大，请登录系统查看」。
- 解不出内容、0 字节或无法访问的文件不返回，注明「N 份文件无法获取」。
- 整体 50 秒内未取完时，返回已取得的部分并注明「其余 N 份未在时限内取到，请重试」；既没有取到任何文件、也没有超大文件时，才提示「未在时限内取到任何文件，请重试」；有超大文件的情形按成功返回并注明「文件过大，请登录系统查看」。
常见错误
| 提示 | 原因 | 处理 |
|---|---|---|
| 单号格式不正确 | 单号含不允许的字符或超过 64 位 | 核对单号 |
| 群不存在或不可用 | 群标识写错，或该群未被本企业的机器人收录 | 在群内发「群ID」重新获取 |
| 尚未配置立刻云服务 | 企业未配置立刻云服务地址 | 到 系统设置 → 单号查询 配置 |
| 单证类型不在清单中，可用类型：… | 单证类型不在企业清单内 | 按提示的可用类型重试 |
| 企业未配置单证类型清单 | 未配置单证类型 | 到 系统设置 → 单号查询 配置 |
| 立刻云查询繁忙，请稍后重试 | 触发立刻云每分钟频率限制 | 稍后重试 |
| 立刻云查询失败，请稍后重试 | 立刻云接口报错或超时 | 稍后重试，持续失败请联系技术支持 |
工具开关与写入风险
- 工具开关按 Key 分别设置：同一工具可以只对某个 Key 开放。
- 只读工具默认开启，写入类工具默认关闭（立刻云两个只读工具是例外，同样默认关闭）。「新增知识」会写入你的知识库，「推送通知」会对外发送且发出后不能撤回，开启时页面会二次确认。只给确实需要的 Key 开启写入类工具。
- 开关置灰时，悬停可看到原因：「套餐不支持」「Key 缺少能力授权」（需先在系统设置为该 Key 勾选对应能力类）或「暂不可用」（对应技能已下线）。
- 关闭某个工具后，该 Key 经 MCP 调用智能体问答时，智能体也不会调用该工具对应的技能（如关闭舱单查询后，智能体问答不会再查舱单）；控制台与其它渠道的对话不受影响。
- Key 被移出「MCP 接入」「知识库写入」或「推送通知」授权、或 Key 被停用时，它已开启的写入类工具会自动关闭，之后重新授权或重新启用不会自动恢复，需要回到这里重新开启。删除 Key 时，它的工具开关与各能力类授权会一并清除。
检查开通状态与调用记录
检查开通状态：在「对外开放」中选中 Key 后点击，平台会依次检查 Key 是否启用且未过期、套餐是否支持、Key 是否已开通 MCP 接入，并给出当前可用的工具数。检查不经过 MCP 服务，不计费、不占调用次数、不产生调用记录。
调用记录：在「调用记录」Tab 查看每一次工具调用，包括时间、Key、工具、调用人、参数摘要、结果、失败原因、耗时与消耗。
- 可按关键词（匹配参数摘要、调用人、失败原因、Key 名称或前缀）、日期范围、Key、工具、结果筛选，填好条件后点「查询」。
- 只保存参数摘要，摘要以外的参数内容搜不到。
- 已删除 Key 的历史记录仍会保留并标注「已删除」。
- 保存期限：专业版 90 天，旗舰版 365 天，超期自动清理。
- 鉴权失败、套餐不支持、未开通、超出频率、参数格式错误等在进入工具之前就被拒绝的请求，不会产生调用记录。
常见错误与处理
| 现象 | 原因 | 处理 |
|---|---|---|
401 unauthorized「API Key 或企业代码无效」 |
Key 填错、已停用或过期；企业代码缺失或与 Key 不符；服务地址与请求头中的企业代码不一致；把 Key 放在了 URL 里 | 核对完整 Key 与企业代码；Key 只能放在请求头中；遗失完整 Key 时到 API设置 新建 |
403 plan_required |
当前为基础版 | 升级到专业版或旗舰版 |
403 mcp_disabled |
企业未开通「MCP 接入」，或该 Key 未被勾选 | 由企业管理员到 系统设置 → 开放 API 权限 开通并勾选该 Key |
| 授权页提示「授权请求无效」 | 授权链接已超过 10 分钟、已被使用，或来源校验未通过（回调地址与 AI 助手注册的不一致）。画面说明：该授权链接已失效或来源不受信任，请回到 AI 助手重新添加连接器。 | 回到 AI 助手重新添加或重新连接，不要收藏授权页链接（同一个浏览器里刷新页面可以继续授权）；反复出现时请确认浏览器没有禁用 Cookie，并在系统浏览器中打开授权链接，仍无法解决再联系平台方排查 |
| Gemini 里已连接，但在普通对话里无法使用，Gemini 回答没有挂载该应用 | 目前在 Gemini 里，自定义应用只能在「任务」中被调用，在普通对话里 Gemini 不会使用它（这是 Gemini 产品的限制，可能随 Google 调整，请以 Google 官方说明为准） | 在 Gemini 里新建「任务」，在任务中启用并使用该应用 |
| 授权页提示「授权请求已被处理」 | 该授权请求已在另一个浏览器中处理：在另一个浏览器或设备上打开了链接，或先在 AI 助手的内置窗口里打开过 | 请回到发起授权的浏览器继续；若你刚在 AI 助手的内置窗口里打开过，请在 AI 助手中重新发起授权。若反复出现，请确认浏览器没有禁用 Cookie，并在系统浏览器中打开授权链接。 |
| 401「授权已失效或暂停，请在 AI 助手中重新连接」 | OAuth 授权被撤销、失效或暂停（见「授权的有效期、暂停与失效」） | 在 AI 助手中重新连接并授权；暂停类需先让管理员恢复 OAuth 授权接入或 OAuth 接入 Key |
429 rate_limited |
超出该 Key 的每分钟调用上限（与开放 API 合计） | 按响应中的等待秒数稍后重试，或在 API设置 调高该 Key 的速率 |
| 工具列表里找不到某个工具 | 套餐不支持、Key 缺少能力授权、工具被关闭或暂不可用 | 在 MCP管理 选中该 Key 查看工具状态与原因 |
| 「处理超时，请稍后重试」 | 只读工具 60 秒内未完成 | 稍后重试 |
| 「处理超时，结果未确认」（新增知识） | 写入可能已成功 | 不要直接重试，先用知识检索核实是否已新增 |
| 「处理超时，结果未确认」（推送通知） | 发送可能已受理 | 如需重试，使用相同的 biz_msg_id，不会重复发送 |
更多错误码与重试规则见 MCP 文档。
限制
- MCP 服务只接受 POST JSON 请求，不提供 SSE 流式连接，也不保持会话。
- 推送通知的附件只支持图片 / 文件的 url 形式与链接，不支持 base64。
- 推送通知用同一 biz_msg_id 重复提交时不会重复发送，返回中的 summary 是首次受理时的快照（排队数不会随发送进展变化）；要看是否已发出，以返回中各群的 status 或开放 API 回执查询为准。经 MCP 发出的通知，在「合作管理 → 投递记录」（见合作管理）里来源显示为「MCP」。
- 智能体问答不会转人工，也不触发销售线索通知。
- 来自浏览器网页（带 Origin 请求头）的调用默认被拒绝，请在桌面客户端、命令行或服务端平台中使用。