立刻智能体平台 · MCP 文档

概述

立刻智能体提供 MCP（Model Context Protocol）服务。支持 MCP 的 AI 工具与智能体平台（Cursor、Claude Code、Codex、企业微信大圆、千问办公、WorkBuddy 等）可以用企业的 API Key 直接调用知识检索、智能体问答、HS 编码、汇率、舱单、推送通知、立刻云单号与单证查询等工具，无需逐个对接 REST 接口；Claude 网页版 / 桌面版、ChatGPT 等只认 OAuth 的 AI 助手，由员工经 OAuth 授权接入（见「OAuth 授权接入」）。

开通前提

套餐

服务地址与传输方式

POSThttps://agent.likelic.com/mcp?customer_code={企业代码}

• 企业代码：控制台 MCP管理 页面给出的服务地址已自动带上本企业代码。也可以改用请求头 X-Customer-Code 传递；两处都给时必须一致，否则返回 401。
• 传输方式：MCP Streamable HTTP 的无状态 JSON 模式。每个请求是一条 JSON-RPC 2.0 消息，响应为 Content-Type: application/json，不开 SSE、不建会话，响应头不返回 Mcp-Session-Id。
• 支持的方法：initialize、notifications/initialized、tools/list、tools/call、ping。通知类消息返回 HTTP 202、无响应体。
• 只接受 POST：GET / DELETE /mcp 返回 405（Allow: POST）；/mcp/ 下的任何子路径返回 404 not_found。
• 单条消息：不支持 JSON-RPC 批量数组；请求体上限 2MB。
• Accept：可不传，服务端会补齐，不会返回 406。

curl -X POST "https://agent.likelic.com/mcp?customer_code={企业代码}" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <请填入你的 sk-Key>" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

鉴权与调用频率

调用频率

• 按 Key：与开放 API（/api/v1）共用同一 Key 的每分钟上限与计数（Key 自身设置的速率，不超过套餐上限：专业版 200 次/分钟，旗舰版 1000 次/分钟）。打到 /mcp 的每个 HTTP 请求都计一次，包括 initialize 与 tools/list。超限返回 429 rate_limited，带 retry_after_seconds 与 Retry-After 头。
• 按来源 IP：同一来源 IP 对 /api/v1 与 /mcp 合计每分钟 200 次，超限返回 429 { "success": false, "message": "请求过于频繁，请稍后再试" }，带标准 RateLimit-* 头。

浏览器来源

带 Origin 请求头的请求（来自浏览器网页）须在服务端白名单内，否则返回 403 origin_not_allowed；默认白名单为空。桌面客户端、命令行与服务端平台不带 Origin，不受影响。

判定顺序

IP 频率 → 来源 → 请求体解析 → Key 与企业代码 → 套餐 → MCP 接入授权 → Key 频率 → 工具可见性。进入工具之前被拒绝的请求不写调用记录。

OAuth 授权接入

Claude 网页版 / 桌面版、ChatGPT 等只认 OAuth 的 AI 助手，不能填 API Key，而是由员工经 OAuth 2.1 授权接入：授权码 + PKCE，访问令牌作为 Authorization: Bearer 调用 /mcp。需企业管理员先在控制台 MCP管理 开启「OAuth 授权接入」并指定一个 OAuth 接入 Key，员工需具备「MCP 个人授权」权限；开启与授权步骤见帮助中心 MCP管理。

发现文档（元数据）

不带凭据请求 /mcp 时返回 401，并带 WWW-Authenticate: Bearer resource_metadata="https://agent.likelic.com/.well-known/oauth-protected-resource"，客户端据此发现授权服务器。

端点

授权码 + PKCE 流程

1. 客户端经 /oauth/register 注册，得到 client_id。
2. 客户端生成 code_verifier 与其 S256 摘要 code_challenge，打开 /oauth/authorize。PKCE 必填且只接受 S256，缺失或 plain 一律拒绝。
3. 用户在授权页用企业代码、用户名、密码登录，确认页列出本次可用工具；同意后带 code 与 state 回到 redirect_uri，拒绝或取消则带 error=access_denied。
4. 客户端 POST /oauth/token，grant_type=authorization_code，带 code、code_verifier、redirect_uri、client_id，得到 access_token、refresh_token。
5. 客户端带 Authorization: Bearer <access_token> 调用 /mcp。

• 回调地址：须与注册值精确一致，且只允许 https 或本机回环地址（回环地址按 RFC 8252 允许端口不同）；回调不符时不会向该地址跳转，而是显示授权请求无效。
• 授权码：一次性，10 分钟内有效；重放即拒绝，并作废以该码签发的令牌与授权。
• 资源绑定：访问令牌只对本服务 /mcp 有效；resource 缺省为 https://agent.likelic.com/mcp，指向其它地址返回 invalid_target。

授权链接要在同一个浏览器里完成

• 授权链接要在发起授权的同一个浏览器里打开并完成。
• 在另一个浏览器或设备上打开，或先在 AI 助手的内置窗口里打开过链接，会看到「授权请求已被处理」：该授权请求已在另一个浏览器中处理。请回到发起授权的浏览器继续；若你刚在 AI 助手的内置窗口里打开过，请在 AI 助手中重新发起授权。
• 看到「授权请求无效」：该授权链接已失效或来源不受信任，请回到 AI 助手重新添加连接器。
• 反复显示「授权请求已被处理」或「授权请求无效」时，请确认浏览器没有禁用 Cookie，并在系统浏览器中打开授权链接。

令牌有效期与轮换

两种令牌格式与 sk- Key 不重叠：Authorization: Bearer 中以 sk- 开头的按 Key 判定，符合访问令牌格式的按 OAuth 令牌判定，其余格式直接返回 401。刷新使用 grant_type=refresh_token 与 refresh_token、client_id。已轮换的旧刷新令牌再被使用，该授权整体作废，须重新授权。令牌只存哈希，明文仅在签发响应中出现一次。响应形如：

{ "access_token": "lka_…", "token_type": "Bearer", "expires_in": 3600, "refresh_token": "lkr_…", "scope": "mcp" }

暂停与失效时的错误

每次 /mcp 请求（访问令牌未过期时同样）都会复核员工与企业状态。OAuth 凭据下，授权失效与暂停一律返回 401（Key 接入仍沿用上文的 401 / 403 区分），便于客户端提示重新授权：

401 响应体为 { "code": "unauthorized", "message": "授权已失效或暂停，请在 AI 助手中重新连接" }，并带 WWW-Authenticate 头。更换 OAuth 接入 Key 不影响已有授权，之后按新 Key 判定。

员工权限与可见工具

OAuth 下工具可见集合 = OAuth 接入 Key 的可见集合 与 员工权限的交集。create_knowledge_entry 另需员工具备「知识库」权限，send_notification 与 list_notify_rooms 另需「合作管理」或「API设置」，query_likeyun_order 与 get_likeyun_documents 另需「合作管理」「企微机器人」「QQ机器人」任一；不满足时 tools/list 不列出该工具，直接调用返回工具错误「你没有使用该工具所需的权限」。新增知识还受员工的「知识分类」授权约束：只能写入你被授权的分类；分类范围被限定的员工写入其他分类时，会提示「分类「X」不存在，或你没有该分类的写入权限」，并只列出你有权限的分类。其余工具只看 Key 开关。

调用频率与记录

OAuth 调用与该 OAuth 接入 Key 共用每分钟调用上限与计数。授权端点按来源 IP 限频：/oauth/authorize 与 /oauth/revoke 每 IP 每 15 分钟 300 次，/oauth/token 按 client_id + IP 每 15 分钟 600 次，并另有每 IP 每 15 分钟 3000 次的外层额度，客户端注册（/oauth/register）每 IP 每小时 20 次，超限返回 429。调用记录的来源为 OAuth，Key 列为 OAuth 接入 Key，调用人为「员工姓名 · 客户端名」。

工具一览

tools/list 只返回当前 Key 可用的工具：工具开放套餐 → Key 具备工具所需的能力类 → 该 Key 的工具开关为开 → 工具依赖的技能在线，四项全部满足才列出。只读工具默认开启，写入 / 对外发送类工具默认关闭（立刻云两个工具虽为只读，同样默认关闭），需在控制台 MCP管理 中按 Key 开启。

「只读」指不改变企业业务数据（ask_agent 产生的会话记录与计费不视为写入），注解为 readOnlyHint: true；写入与对外发送类为 readOnlyHint: false，send_notification 另带 destructiveHint: true、openWorldHint: true。

调用结果的形态

• 成功：{ "content": [{ "type": "text", "text": "…" }], "structuredContent": {…}, "isError": false }。
• 业务失败（工具错误）：{ "content": [{ "type": "text", "text": "中文原因" }], "isError": true }，见「错误码」。

工具参数与返回

search_knowledge 知识检索

按问题检索企业知识库，返回命中的问答原文（与智能体对话时的知识检索同范围、同顺序），不调用大模型生成回答。

返回：structuredContent: { items: [{ question, answer, category, score }], degraded }。score 为 0～1 的相似度，缺失时为 null；查询向量化不可用或 Token 用尽时降级为关键词检索（最多 3 条，score: null，degraded: true）。text 为逐条「问：… / 答：…」，无命中时为「未找到相关知识」且 items: []。

工具错误：「智能体不存在或已停用」。

ask_agent 智能体问答

向企业智能体提问，回答与开放 API AI 会话一致；传入 session_id 可延续多轮对话。不转人工，也不触发销售线索通知；回答时只会调用本 Key 已开启的 HS 编码 / 汇率 / 舱单工具对应的技能。

返回：text 为回答内容，structuredContent: { session_id }。套餐 Token 用尽等情况与开放 API 一致，以普通回答返回提示文案（isError: false）。

工具错误：「智能体不存在或已停用」「企业尚未启用任何智能体」。

create_knowledge_entry 新增知识

向企业知识库新增一条问答。写入类工具，默认关闭。

返回：structuredContent: { id, category }，text 为「已新增知识：{问题前 50 字}」。

工具错误：知识条数达套餐上限、分类不存在（只能选已有分类）、超时「处理超时，结果未确认；请先用 search_knowledge 核实是否已新增，不要直接重试」。

query_hs_code HS 编码查询

返回：技能结果文本，编码展示为 XXXXXXXX.XX。工具错误：技能点余额不足、该功能暂不可用（所需技能下线）。

query_exchange_rate 汇率查询

返回：技能结果文本。免费。工具错误：参数不合法、技能暂不可用。

query_manifest 舱单查询（仅旗舰版）

返回：技能结果文本。工具错误：「当前套餐不支持该工具」（专业版，不扣点）、技能点余额不足。

list_notify_rooms 可推送群列表

列出本企业可作为通知目标的企微群与 QQ 群，与开放 API GET /api/v1/rooms 同名同义。

返回：与开放 API 群清单一致（每项含 channel、instance_id、room_id、room_name、company_code、push_state 等），字段说明见 开放 API 文档 · 查询群清单。免费。

send_notification 推送通知

会对外发送，发出后不能撤回。对外发送类工具，默认关闭。请求字段与开放 API POST /api/v1/notifications 相同，受理校验、幂等与额度共用。

返回：受理结果，与开放 API 一致，含 biz_msg_id、duplicate、summary 等。同一 biz_msg_id 再次提交返回 duplicate: true，不会新建投递；此时 summary 为首次受理时的快照，实时状态以 deliveries[].status 或开放 API 回执查询 GET /api/v1/notifications/{biz_msg_id} 为准。经本工具受理的投递单，回执与控制台投递记录中来源记为 mcp。字段与目标形态详见 开放 API 文档「推送通知」。

工具错误：「MCP 不支持 base64 附件，请改用 url」、受理校验错误（同开放 API 文案）、超时「处理超时，结果未确认；如需重试请使用相同 biz_msg_id，不会重复发送」。

query_likeyun_order 立刻云单号查询（仅旗舰版）

按单号和客户群查询立刻云单票信息，与群内 @ 机器人查单号同源同口径。只读，默认关闭；免费，不经大模型、不扣技能点；与群内单号查询共用立刻云每企业每分钟频控，并计入 MCP 调用频率。企业须已在控制台「系统设置 → 单号查询」配置立刻云服务地址。不要求群内机器人的「单号查询」开关开启。经 OAuth 调用另需员工具备「合作管理」「企微机器人」「QQ机器人」任一权限。

返回：命中的全部票，最多 10 票；structuredContent: { order_no, items, truncated }，每票含工作号、客户代码、业务类型、主单号、分单号、参考号、件数、毛重、订单详情链接，text 为中文摘要；超出 10 票时 truncated 为超出数，摘要注明「还有 N 票未返回，请登录系统查看」。未命中时 text 为「未查到单号 X」、items: []，按成功记录。

工具错误：「单号格式不正确」「群不存在或不可用」「尚未配置立刻云服务」「立刻云查询繁忙，请稍后重试」（触发立刻云频控，记业务错误）「立刻云查询失败，请稍后重试」（立刻云接口报错或超时，记系统错误）。

get_likeyun_documents 立刻云单证获取（仅旗舰版）

按单号、单证类型和客户群获取立刻云单证文件的下载链接，转存方式与群内发送的单证文件一致。共同口径（套餐、默认关闭、免费、频控、OAuth 员工权限）同 query_likeyun_order。

返回：structuredContent: { order_no, doc_type, files, unavailable, oversize, truncated }，files 每项含 file_name、url、temporary；每次最多返回 5 份。

• 超出 5 份时 truncated 为超出数，摘要注明「还有 N 份未返回，请登录系统查看」。
• 立刻云原始链接转存失败时降级返回原始临时链接，temporary 为 true，摘要注明「临时链接，可能过期」。
• 超过 50MB 的文件不转存，文件名列在 oversize，摘要注明「文件过大，请登录系统查看」。
• 解不出内容、0 字节或探测不可达的文件不返回，计入 unavailable，摘要注明「N 份文件无法获取」。
• 50 秒截止（早于 MCP 的 60 秒超时）：截止时已取得部分文件，则返回这些文件并注明「其余 N 份未在时限内取到，请重试」，按成功记录；截止时既没有取到任何文件、也没有超大文件时，才为工具错误「未在时限内取到任何文件，请重试」，记业务错误；有超大文件的情形按成功返回并注明「文件过大，请登录系统查看」，不会整体报超时。
• 未查到时 text 为「未查到单号 X 的」后接实际请求的单证类型值（如请求「提单」则为「未查到单号 X 的提单」）、files: []，按成功记录。

工具错误：「单号格式不正确」「群不存在或不可用」「尚未配置立刻云服务」「企业未配置单证类型清单」「单证类型不在清单中，可用类型：…」「立刻云查询繁忙，请稍后重试」「立刻云查询失败，请稍后重试」「未在时限内取到任何文件，请重试」。

错误码

HTTP 层（未进入工具，不写调用记录）

JSON-RPC 协议错误（以 JSON-RPC error 返回，不写调用记录）

工具错误（isError: true，写调用记录）

参数格式正确、但依赖数据或状态的问题在工具内判定，content[0].text 为中文原因，例如：

• 「当前套餐不支持该工具」「该 Key 未授权此能力」「该工具已关闭」「该工具暂不可用」
• OAuth 下员工权限不足：「你没有使用该工具所需的权限」
• 立刻云两个工具：「单号格式不正确」「群不存在或不可用」「尚未配置立刻云服务」「企业未配置单证类型清单」「立刻云查询繁忙，请稍后重试」「立刻云查询失败，请稍后重试」「未在时限内取到任何文件，请重试」
• 技能点余额不足、知识条数达上限、分类不存在、智能体不存在或已停用
• 「MCP 不支持 base64 附件，请改用 url」及推送通知的受理校验错误
• 工具内部意外异常：「服务暂时异常，请稍后重试」

超时与重试

每次 tools/call 以 60 秒为限。超时后服务端不会中止已开始的处理，因此写入类工具的结果「未确认」：

遇到 429 时请按 Retry-After 等待；遇到 401 / 403 时重试无效，需先处理授权或套餐。

平台接入

以下配置与控制台 MCP管理「接入配置」给出的内容一致。控制台里服务地址与企业代码已自动填好；本页用 {企业代码} 表示，请替换为你的企业代码，并把 <请填入你的 sk-Key> 替换为完整 Key。

Claude 网页版 / 桌面版

通过 OAuth 授权接入，只填不带企业代码的服务地址，不需要 Key。需企业管理员先在控制台开启 OAuth 授权接入：

名称：立刻智能体
服务地址：https://agent.likelic.com/mcp
认证方式：OAuth（无需填写 Key）

ChatGPT

通过 OAuth 授权接入，MCP 服务器地址填不带企业代码的地址，认证方式选 OAuth，不需要 Key：

名称：立刻智能体
MCP 服务器地址：https://agent.likelic.com/mcp
认证方式：OAuth

Gemini 网页版

通过 OAuth 授权接入，不需要 Key：

1. 在 Gemini 的自定义 MCP 连接里，MCP 服务器地址填管理员给你的服务地址。
2. 客户端 ID、客户端密钥都不用填（留空），Gemini 会自动注册。
3. 保存后按提示跳转授权页，用控制台账号登录并同意。

注意：目前在 Gemini 里，自定义应用只能在「任务」中被调用，在普通对话里 Gemini 不会使用它（这是 Gemini 产品的限制，可能随 Google 调整，请以 Google 官方说明为准）。

千问办公

在「扩展 → 连接器」点「+」添加，粘贴以下 JSON；也可手动选择 Streamable HTTP，填写地址并添加 Header：

{
  "mcpServers": {
    "likelic": {
      "type": "streamableHttp",
      "url": "https://agent.likelic.com/mcp?customer_code={企业代码}",
      "headers": {
        "Authorization": "Bearer <请填入你的 sk-Key>"
      }
    }
  }
}

WorkBuddy

在「连接器 → 自定义连接器 → 配置 MCP」粘贴以下 JSON，保存后点「信任」并启用：

{
  "mcpServers": {
    "likelic": {
      "type": "streamableHttp",
      "url": "https://agent.likelic.com/mcp?customer_code={企业代码}",
      "headers": {
        "Authorization": "Bearer <请填入你的 sk-Key>"
      }
    }
  }
}

企业微信大圆

在大圆后台「插件 → MCP 插件」中新建，按下表填写（鉴权位置选 Header）：

服务地址：https://agent.likelic.com/mcp?customer_code={企业代码}
传输方式：Streamable HTTP
鉴权位置：Header
Header 名称：Authorization
Header 值：Bearer <请填入你的 sk-Key>
企业代码：已在服务地址中（customer_code={企业代码}）

Cursor

粘贴到 ~/.cursor/mcp.json（或项目内 .cursor/mcp.json）后重启 Cursor：

{
  "mcpServers": {
    "likelic": {
      "url": "https://agent.likelic.com/mcp?customer_code={企业代码}",
      "headers": {
        "Authorization": "Bearer <请填入你的 sk-Key>",
        "X-Customer-Code": "{企业代码}"
      }
    }
  }
}

Claude Code

在终端执行：

claude mcp add --transport http likelic "https://agent.likelic.com/mcp?customer_code={企业代码}" \
  --header "Authorization: Bearer <请填入你的 sk-Key>" \
  --header "X-Customer-Code: {企业代码}"

Codex

追加到 ~/.codex/config.toml：

[mcp_servers.likelic]
url = "https://agent.likelic.com/mcp?customer_code={企业代码}"
http_headers = { "Authorization" = "Bearer <请填入你的 sk-Key>", "X-Customer-Code" = "{企业代码}" }

通用（JSON）

其它支持粘贴 JSON 的平台按此配置接入：在其 MCP 配置处粘贴以下 JSON，字段名以对方平台文档为准（传输方式选 Streamable HTTP / HTTP，鉴权放在请求头）。

{
  "name": "立刻智能体",
  "type": "streamable-http",
  "url": "https://agent.likelic.com/mcp?customer_code={企业代码}",
  "headers": {
    "Authorization": "Bearer <请填入你的 sk-Key>",
    "X-Customer-Code": "{企业代码}"
  }
}

不支持的客户端

• 只支持 SSE 传输或要求服务端会话的旧版客户端：本服务不开 SSE、不建会话。

接入后自检

1. 在控制台 MCP管理 选中该 Key，点「检查开通状态」，确认可用工具数大于 0。
2. 在 AI 工具中列出工具，并调用一次只读工具（如 query_exchange_rate）。
3. 到 MCP管理「调用记录」确认出现该次调用。