一、【业务场景】

1.1 适用对象

• 需要在 Codex、Claude Code、WorkBuddy 等 MCP 客户端中调用乐檬 AGI Ability 的客户IT、产品和实施人员。

• 需要通过统一协议检索、阅读、验证并调用已发布 Ability 的团队成员。

1.2 核心场景

二、【功能介绍】

2.1 功能概述

本次更新提供 lemon-agi MCP 接入说明，明确乐檬 AGI Ability 如何通过 MCP 协议对外暴露。接入后，客户端可以在同一套 MCP 工具下完成 Ability 搜索、接口文档读取、身份验证和 Ability 调用。

服务统一采用 Streamable HTTP 传输方式，连接地址为：

https://cloud.nhsoft.cn/agi/mcp

2.2 核心能力

• Ability 搜索：通过 search_agi_abilities 按关键词、应用、请求方法或标签查找已发布的 Ability。

• 文档读取：通过 get_agi_ability_document 获取指定 Ability 的完整 OpenAPI 文档。

• Ability 调用：通过 call_agi_ability 按文档要求发起 GET 或 POST 调用。

• 身份验证：通过 whoami 校验当前个人访问令牌对应的用户身份。

• 分级可用：未配置令牌时可进行只读检索；配置有效令牌后才允许验证身份和调用 Ability。

• 多客户端接入：支持 Codex、Claude Code、WorkBuddy 等支持 Streamable HTTP 的 MCP 客户端。

2.3 适用场景

• 在 AI 编码工具中直接调用乐檬 AGI 平台能力。

• 调试某个 Ability 的请求参数、响应结构和版本信息。

• 搭建基于 MCP 的内部自动化工具或智能体能力编排流程。

三、【使用说明】

3.1 入口方式

• 接入说明文档：https://agi.lemengcloud.com/integration/lemon-agi-server

• AGI 说明文档：https://agi.lemengcloud.com

• MCP 服务地址：https://cloud.nhsoft.cn/agi/mcp

• 乐檬 AGI 个人访问令牌入口：乐檬零售后台 → 档案 → 用户中心 → 用户 → 用户令牌管理

3.2 接入前准备

使用前请确认已具备以下条件：

1. 当前网络可以访问 https://cloud.nhsoft.cn/agi/mcp。

1. 已获取乐檬 AGI 个人访问令牌。

1. MCP 客户端支持 Streamable HTTP 传输方式。

1. 客户端请求头支持配置 Authorization: Bearer <个人访问令牌>。

1. 客户端可以声明响应类型 Accept: application/json, text/event-stream。

3.3 WorkBuddy 配置示例

推荐使用用户级配置文件：~/.workbuddy/mcp.json。

{
  "mcpServers": {
    "lemon-agi": {
      "type": "http",
      "url": "https://cloud.nhsoft.cn/agi/mcp",
      "headers": {
        "Authorization": "Bearer <个人访问令牌>"
      },
      "disabled": false
    }
  }
}

也可以在 WorkBuddy 侧边栏进入“插件 → MCP 服务器 → 配置 MCP”填写上述配置。保存后需要确认信任该服务，并检查连接状态是否可用。

3.4 Codex 配置示例

先在启动 Codex 的终端中设置令牌：

export LEMON_AGI_PERSONAL_TOKEN='<个人访问令牌>'

在 ~/.codex/config.toml 中增加：

[mcp_servers.lemon-agi]
url = "https://cloud.nhsoft.cn/agi/mcp"
bearer_token_env_var = "LEMON_AGI_PERSONAL_TOKEN"
default_tools_approval_mode = "prompt"

重新启动 Codex 后，可在 /mcp 中查看连接状态。

3.5 Claude Code 配置示例

先在启动 Claude Code 的终端中设置令牌：

export LEMON_AGI_PERSONAL_TOKEN='<个人访问令牌>'

在项目根目录 .mcp.json 中增加：

{
  "mcpServers": {
    "lemon-agi": {
      "type": "http",
      "url": "https://cloud.nhsoft.cn/agi/mcp",
      "headers": {
        "Authorization": "Bearer ${LEMON_AGI_PERSONAL_TOKEN}"
      }
    }
  }
}

重新启动 Claude Code 后，可通过 /mcp 查看连接状态。项目级 MCP 首次启用时，需要确认信任该服务。

3.6 推荐调用流程

1. 使用 search_agi_abilities 查找目标 Ability，并取得准确的 ability_code。

1. 使用 get_agi_ability_document 读取该 Ability 的参数、响应结构和版本信息。

1. 根据接口文档准备 query 或 body 参数。

1. 使用 call_agi_ability 发起调用。

1. 如需验证令牌身份，调用 whoami 查看当前令牌对应用户。

call_agi_ability 当前仅支持 GET 和 POST。GET 参数放在 query 中，POST 数据放在 body 中。

四、【注意事项】

• 个人访问令牌只应保存在本机环境变量或客户端安全凭据存储中，不要写入项目文件、提交记录或截图。

• 未提供有效令牌时，工具列表只会显示 search_agi_abilities 和 get_agi_ability_document，只能进行 Ability 搜索和文档读取。

• 调用 whoami 和 call_agi_ability 必须配置有效的 Authorization: Bearer <个人访问令牌> 请求头。

• Bearer 与令牌之间必须保留一个空格，不能使用其他鉴权 scheme。

• MCP 地址必须使用完整路径 https://cloud.nhsoft.cn/agi/mcp，遗漏 /agi/mcp 可能导致 404。

• 客户端必须支持 Streamable HTTP；该服务不提供 stdio 传输方式。

• 客户端需要同时接受 application/json 和 text/event-stream，否则可能出现响应解析失败。

• WorkBuddy 用户级 MCP 配置推荐放在 ~/.workbuddy/mcp.json；项目级配置必须排除版本控制，避免令牌泄露。

• 如果只能看到两个工具，优先检查令牌是否配置、请求头是否正确，并重新连接 MCP 服务刷新工具列表。