如何在通义灵码里使用 MCP 能力？

通义灵码编程智能体支持 MCP 工具使用，根据用户需求描述，通过模型自主规划，实现 MCP 工具调用，并深度集成国内最大的 MCP 中文社区——魔搭 MCP 广场，涵盖开发者工具、文件系统、搜索、地图等十大热门领域 2400+ MCP 服务，全面拓宽 AI 编码助手能力边界，更加贴合开发者工作流程。

重要

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

本文介绍了如何使用 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 服务器通信模式：

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

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

MCP 服务配置与使用

重要

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

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

添加 MCP 服务

1. 进入 MCP 服务页面

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

说明

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

2. 添加服务

方式一：通过 MCP 广场完成添加

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

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

说明

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

3. 安装完成后，返回我的服务页面，即可看到新安装的服务。图标显示为

4. 

5. ，表示连接成功可正常使用。展开详情，可以看到 MCP 提供的工具列表。

说明

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

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

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

• 手工添加：

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

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

• 配置文件添加：

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

2. 添加完成后，即可看到新安装的服务。图标显示为

3. 

4. ，表示连接成功可正常使用。展开详情，可以看到 MCP 提供的工具列表。

使用 MCP 工具

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

1. 输入提示词

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

2. 执行工具

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

3. 查看工具执行结果

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

4. 代码审查与采纳

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

场景使用示例

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

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

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

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

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

1. 获取 MCP SSE 的服务地址

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

• 拷贝 SSE URL 字段。

2. MCP 服务添加

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

• 名称： fetch
  

• 类型： SSE
  

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

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

3. 完成配置

添加成功后，当图标显示

为连接成功。展开详情，可以看到 MCP 提供的工具列表。

4. 在通义灵码中使用 MCP

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

• 请输入以下提示词

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

• 请输入以下提示词

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

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

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

1. 前置环境检查

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

• 提示词：

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

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 服务
  

3. 完成配置

添加成功后，当图标显示

为连接成功。展开详情，可以看到 MCP 提供的工具列表。

4. 在通义灵码中使用 MCP

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

提示词 1：

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

提示词 2：

明天美国有天气预警吗？

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

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

node -vnpx -v

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

Mac 系统

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

# 2. 验证核心工具链brew updatebrew 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 -vnpx -v

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

2. 缺少 uvx 命令所需环境

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

• 解决方案： 安装 uvx （Python 3.8 及以上版本）。

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

安装验证步骤

1.下载并安装

Windows 系统

通过 Chocolatey 安装（需先安装Chocolatey）：

choco install uvx

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

uvx --version

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

Mac 系统

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

# 1. 添加uvx官方仓库brew tap uvx/tools
# 2. 执行一键安装brew install uvx
# 3. 验证安装结果uvx doctor --environment
# 4. 配置自动更新（可选）brew upgrade --cask uvx-updater

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

uvx --version

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

3. 无法初始化 MCP Client

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

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

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

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

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

• 排查步骤：

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

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

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 广场安装后，仍需手动配置这些参数。

• 解决方案：

1. 进入我的服务页面。

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

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

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

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

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

重要

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

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

如果服务连接中断，在界面右侧单击

，系统会自动尝试重新启动 MCP 服务。

• 使用建议： 建议避免 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" 并打开。

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

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

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

3. 重启 IDE。

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

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

了解更多：https://help.aliyun.com/zh/lingma/user-guide/guide-for-using-mcp?spm=a2c4g.11186623.help-menu-2804669.d_2_2_7.4d717a3bnecIeq