AI 助理
备案控制台
官方文档
输入文档关键字查找
首页 智能编码助手通义灵码 操作指南 智能会话 MCP

MCP

更新时间：
我的收藏
重要

本文中含有需要您注意的重要提示信息，忽略该信息可能对您的业务造成影响，请务必仔细阅读。

本文介绍了如何使用 MCP（模型上下文协议）服务扩展通义灵码功能的综合指南，涵盖从服务配置到实际应用的场景示例。

前提条件

如需使用该功能 ，需要开发者将通义灵码 IDE 端插件更新：

  • JetBrains 插件：插件版本更新至 v2.5.0 及以上。

  • VS Code 插件：插件版本更新至 v2.5.0 及以上。

下载操作可前往下载安装。

模型上下文协议（Model Context Protocol）

MCP (Model Context Protocol)是一种开放标准协议，旨在为大语言模型（LLM）提供标准化的外部工具和上下文集成方式。借助 MCP 标准化接口的支持，通义灵码能够灵活扩展与不同数据源或外部系统的连接，使其智能体的能力和场景得到拓展，有效满足用户对于个性化扩展的诉求。

您可以选择连接现有的MCP服务或自行开发专属的 MCP 服务，例如魔搭社区 MCP 市场、Higress MCP 市场等热门市场，已经提供了丰富的 MCP 服务，您可以自行探索发现更多符合您需求的解决方案，加速项目开发与创新。

热门 MCP 市场

热门场景

  • 魔搭社区 MCP 市场：魔搭社区上架千余款热门的MCP服务，包括支付宝、MiniMax等全新 MCP服务，为AI开发者提供丰富的 MCP 服务及调试工具。

  • Higress MCP 市场：Higress MCP 市场目前已上架多款热门 MCP 服务。

  • 数据库：自动获取数据库中 schemas，生成DAO代码或完成数据查询等。

  • 在线文档：基于在线文档内容，完成代码生成、优化或智能问答。

  • 设计系统：根据设计系统中的设计稿，生成前端代码，还原前端交互设计。

通义灵码支持两种 MCP 服务器通信模式：

  • STDIO 模式：在此模式下，通信通过标准输入输出流进行，服务运行在本地。

  • SSE 模式：采用服务器发送事件（SSE）协议进行通信，服务可以运行在远端或本地。

MCP 服务配置与使用

重要

  • 支持在智能体模式下使用 MCP 服务，配合 qwen3 模型一起使用。

  • 允许同时连接最多 10 个 MCP 服务。

添加 MCP 服务

1.进入 MCP 服务页面

单击通义灵码欢迎语中的 MCP 工具链接，或在右上角头像处进入个人设置，单击条形框，进入 MCP 服务页面。

说明

MCP 添加后，可跨本地工程和 IDE 使用。

莫3@1x (46)

2.添加服务
方式一：通过 MCP 广场完成添加

  1. 单击MCP 广场 标签，可以看到推荐的 MCP 服务列表以及魔搭社区提供的全部 MCP 服务。

  2. 在 MCP 广场 中，浏览或搜索所需 MCP 服务，单击 安装 完成一键自动安装。

说明

部分 MCP Server 在运行使用时需要额外提供环境变量，例如 API_KEY 或 ACCESS_TOKEN。

  1. 安装完成后，返回我的服务页面，即可看到新安装的服务。图标显示为image，表示连接成功可正常使用。展开详情，可以看到 MCP 提供的工具列表。

说明

如果命令所依赖的环境缺失，会显示服务启动异常，请手动安装所需依赖。请参见常见问题。

莫3@1x (52)

方式二：通过手动方式完成添加

  1. 在 MCP 服务页面右上角单击“+”选择以下方式完成添加：

    • 手工添加：

      • STDIO 类型：填写名称、命令、参数和环境变量（选填）。

      • SSE 类型：填写名称和服务地址。

    • 配置文件添加：

      • 在 JSON 配置文件中增加服务对应的JSON配置信息。

  2. 添加完成后，即可看到新安装的服务。图标显示为image，表示连接成功可正常使用。展开详情，可以看到 MCP 提供的工具列表。

莫3

使用 MCP 工具

通义灵码会根据用户输入的提示词，结合 MCP 工具的名字及描述，自动判断所需调用的 MCP 工具，并将工具返回的结果输入下一步的处理流程中。

1. 输入提示词

在 IDE 的对话框中切换为智能体模式，并在对话框中输入如下提示词。

页面 10@1x (3)

2. 执行工具

当通义灵码需要调用 MCP 工具时，系统会出现提示，等您确认后将继续操作。

页面 10@1x (4)

3. 查看工具执行结果

工具执行完成后，通义灵码的交互窗口将显示执行结果。您可以展开查看 MCP 工具的详细输入与输出信息，便于进一步分析和操作。

页面 10@1x (5)

4. 代码审查与采纳

问答交互完成后，您可审查并采纳最终的代码生成。

页面 10@1x (13)

场景使用示例

通义灵码支持两种类型的 MCP 服务，您可以选择合适的 MCP 服务类型，来体验通义灵码 MCP 功能。

  1. SSE 类型（远端服务托管）：此类型的服务托管在远程服务器上，配置过程简单快捷，非常适合初次接触的新手用户快速上手体验。在本示例中，您可以通过魔搭社区的 MCP 市场选用fetch MCP服务，轻松实现从任意网页抓取内容的能力。

  2. STDIO 类型（本地服务运行）：此类型的服务在您的本地环境中运行，需要依赖您本地环境准备，适合于专业开发者。在本示例中，您将通过体验使用 weather MCP 查询城市天气的能力。

场景一： 使用远端 MCP 抓取网页内容

本场景演示如何通过 Fetch MCP 完成网页内容抓取。

1. 获取 MCP SSE 的服务地址

  • 进入魔搭 MCP 市场，登录后即可获取 MCP SSE 的服务地址。

  • 拷贝 SSE URL 字段。

莫3@1x (71)

2. MCP 服务添加

进入个人设置中的 MCP 服务，然后在 MCP 服务页面，完成 MCP 服务连接配置。

  • 名称：fetch

  • 类型：SSE

  • 服务地址：粘贴您复制的 URL

    例如：https://mcp-****.modelscope.cn/sse

莫3@1x (36)

3.完成配置

添加成功后，当图标显示image为连接成功。展开详情，可以看到 MCP 提供的工具列表。

image

4. 在通义灵码中使用 MCP

在通义灵码的 IDE 的对话框左下角切换为智能体模式，并在对话框中输入提示词。

  • 请输入以下提示词

帮我总结这篇文档的内容：https://help.aliyun.com/zh/lingma/developer-reference/listkbfiles-get-the-list-of-knowledge-base-files

页面 10@1x (14)

  • 请输入以下提示词

基于API文档生成调用示例代码：https://help.aliyun.com/zh/lingma/developer-reference/listkbfiles-get-the-list-of-knowledge-base-files

页面 10@1x (15)

场景二： 使用本地 MCP 查询城市天气

本场景演示如何通过 weather MCP 查询城市天气。

1. 前置环境检查

确保您的本地环境已经安装 node.js，您可以让通义灵码完成前置环境检查与准备。

  • 提示词：

请帮我检查我的本地环境，确保已经安装好node.js

页面 10@1x (8)

2. MCP 服务添加

进入个人设置中的 MCP 服务，然后在 MCP 服务页面，完成 MCP 服务连接配置。

服务配置参数如下：

  • 名称：weather

  • 类型：STDIO

  • 命令：npx

  • 参数：

-y @h1deya/mcp-server-weather

MCP 服务配置信息

  • 服务配置信息

    {
  "mcpServers": {
    "weather": {
      "command": "npx",
        "args": [
            "-y",
            "@h1deya/mcp-server-weather"
        ],
    }
  }
}

  • 源码地址：weather MCP 服务

页面 10@1x (9)

3. 完成配置

添加成功后，当图标显示image为连接成功。展开详情，可以看到 MCP 提供的工具列表。

页面 10@1x (10)

4. 在通义灵码中使用 MCP

在通义灵码的 IDE 对话框左下角切换为智能体模式，并在对话框中输入提示词。

提示词1：

帮我查询美国旧金山的天气

页面 10@1x (16)

提示词2：

明天美国有天气预警吗？

页面 10@1x (17)

MCP 使用常见问题

服务添加或安装异常

1. 缺少 npx 命令所需环境

  • 异常信息：failed to start command: exec: "npx": executable file not found in $PATH

  • 解决方案：下载并安装 Node.js。

警告

Node.js 版本须在 v18 及以上，npm 版本须在 v8 及以上。版本过低可能导致工具调用失败

  • 您可以访问 Node.js 官网，下载并安装 Node.js 18 或更高版本，也可以选择通过以下方式完成：

    安装验证步骤

    1.下载并安装

    Windows 系统

    使用 nvm-windows 管理多版本：

    nvm install 22.14.0  # 安装指定版本
nvm use 22.14.0

    Mac 系统

    使用 brew 安装（需先安装 brew）。

    # 2. 验证核心工具链
brew update
brew install node

# 2. 验证核心工具链
echo "Node.js版本: $(node -v)"
echo "npm版本: $(npm -v)"
echo "npx版本: $(npx -v)"

# 3. 配置环境变量（必要时）
echo 'export PATH="/usr/local/opt/node@16/bin:$PATH"' >> ~/.zshrc

    2.安装完成后，在终端中运行以下命令确认是否安装成功。 

    node -v
npx -v

    3.安装成功后，终端将显示已安装的 Node.js 版本号。

2. 缺少 uvx 命令所需环境

  • 异常信息：failed to start command: exec: "uvx": executable file not found in $PATH

  • 解决方案：安装 uv， uvx 是 uv 提供的命令行工具，用于快速运行 Python 脚本。

    • 您可以前往 Python 官网，下载并安装 Python 3.8 或更高版本，也可以选择通过以下方式完成：

      安装验证步骤

      1.下载并安装

      Windows 系统

      Windows 使用下面命令安装

      powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

      Mac 系统

      macOS 和 Linux 使用下面命令安装

      curl -LsSf https://astral.sh/uv/install.sh | sh

      2.安装完成后，在终端中运行以下命令确认是否安装成功。

      uv --version

      3.安装成功后，终端将显示已安装的 uv 版本号。

3. 无法初始化 MCP Client

  • 异常信息：failed to initialize MCP client: context deadline exceeded

  • 异常原因，包括但不限于以下原因：

    • 服务参数配置错误：MCP 服务的参数设置可能存在错误或其他情况，影响服务初始化。

    • 资源拉取失败：由于网络问题，无法成功拉取资源导致的安装失败。

    • 网络安全限制：由于公司内部安全组件的拦截，导致 MCP 服务初始化异常。

  • 排查步骤：

1. 单击复制完整命令，可以获取完整的命令。

莫3@1x (64)

2. 在终端中运行该命令，可以获取详细异常信息。

莫3@1x (67)

3.分析异常信息，进行对应修复。

常见问题 1：配置错误

在以上异常示例中，通过异常信息可以看出，是由于 Redis 连接URL 配置错误导致连接失败，据此应检查并通过编辑该MCP服务，修正错误的URL配置。

常见问题2：资源拉取失败

如果由于资源拉取问题导致命令运行失败，可以在命令行中执行以下命令，添加镜像源，再重启 lingma 进程后再试。

Windows 系统

npm config set registry https://registry.npmmirror.com

Mac 系统

export UV_INDEX_URL=https://mirrors.aliyun.com/pypi/simple/

常见问题3：Node.js 运行被安全组件拦截

根据安全组件的拦截提示，对Node.js进程或相关执行文件进行授权或加白操作。

工具使用相关问题

说明

如果您在使用 MCP 广场中的服务存在问题，请联系魔搭社区，获取技术支持。

ModelScope 开发者群（钉钉群号 44837352）

1. 环境变量或参数填写错误，导致工具执行失败

  • 排查步骤：

如果 MCP 工具调用出现异常或返回结果不符合预期，建议您首先展开工具调用详情，查看具体的错误信息，并据此进行分析与排查。

重要

部分 MCP 服务（如 Mastergo 和 Figma）的 API_KEY 或 TOKEN 等关键认证信息包含在“参数（args）”中。

因此，在通过 MCP 广场安装后，仍需手动配置这些参数。

莫3@1x (62)

  • 解决方案：

  1. 进入我的服务页面。

  2. 找到对应 MCP 服务，单击编辑。

  3. 在服务配置中，查看参数（args）部分。

  4. 替换其中需要更新或填写的变量内容，确保其准确无误，重新连接服务后再尝试调用。

莫3@1x (68)

2. 模型无法正常调用 MCP 工具

  • 确认当前在智能体模式。

    重要

    如果未打开相关工程目录，系统将仅进入智能问答模式，无法调用 MCP 工具。请先加载对应的工程目录，并切换到智能体模式。

  • 确认 MCP 服务处于已连接状态：

如果服务连接中断，在界面右侧单击image，系统会自动尝试重新启动 MCP 服务。

莫3@1x (66)

  • 使用建议：避免MCP服务及其工具使用相似命名（如 TextAnalyzer-Pro 和 TextAnalyzer-Plus 都包含名为 fetchText 的工具且功能类似），防止模型调用时产生歧义。

3. 个人设置、MCP 工具页无法打开，会话面板显示空白。

当页面显示空白并在 idea.log 中有如下报错信息：“WARN - #c.i.u.j.JBCefApp - JCefAppConfig.class is not from a JBR module”。

异常原因：Android Studio 默认设置不支持 JCEF，导致无法加载个人设置、MCP 等页面。

解决方案：

  1. 配置 JCEF：在 IDE 中选择Help > Find Action..，在弹出的输入框中输入 "Registry" 并打开。

    • 启用选项ide.browser.jcef.enabled

    • 关闭选项ide.browser.jcef.sandbox.enable

莫3@1x (70)

  1. 配置 IDE Runtime：再次选择Help > Find Action..，在输入框中输入 "Choose Boot Runtime for the IDE" 并打开，选择较新的 JCEF Runtime 版本，然后确定。

  2. 重启 IDE。

莫3@1x (72)

4. MCP 服务列表无法正常加载

服务列表持续显示加载中。

  • 重新启动 IDE。

  • 如果问题仍未解决，可尝试手动启动 Lingma 服务：

    Windows 系统

    进入目录：.lingma/bin/x.x.x/CPU架构_64_系统/

    执行命令： 

    Lingma.exe start

    Mac 系统

    单击电脑左上角苹果图标，选择“关于本机”查看处理器型号，然后根据处理器型号进入对应的目录。

    • m1 芯片：/.lingma/bin/x.x.x/aarch64_darwin/Lingma

    • intel 芯片：/.lingma/bin/x.x.x/x86_64_darwin/Lingma

    执行命令： 

    Lingma start

    等待启动成功后，重新单击登录按钮。

上一篇：工具下一篇：Lingma IDE