通义灵码编程智能体支持 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 广场完成添加
- 单击MCP 广场 标签，可以看到推荐的 MCP 服务列表以及魔搭社区提供的全部 MCP 服务。
- 在 MCP 广场 中，浏览或搜索所需 MCP 服务，单击 安装 完成一键自动安装。
说明
部分 MCP Server 在运行使用时需要额外提供环境变量，例如 API_KEY 或 ACCESS_TOKEN。
- 安装完成后，返回我的服务页面，即可看到新安装的服务。图标显示为
，表示连接成功可正常使用。展开详情，可以看到 MCP 提供的工具列表。
说明
如果命令所依赖的环境缺失，会显示服务启动异常，请手动安装所需依赖。请参见常见问题。
方式二：通过手动方式完成添加
- 在 MCP 服务页面右上角单击“ + ”选择以下方式完成添加：
手工添加：
- STDIO 类型：填写名称、命令、参数和环境变量（选填）。
- SSE 类型： 填写名称和服务地址。
配置文件添加：
- 在 JSON 配置文件中增加服务对应的JSON配置信息。
- 添加完成后，即可看到新安装的服务。图标显示为
，表示连接成功可正常使用。展开详情，可以看到 MCP 提供的工具列表。
使用 MCP 工具
通义灵码会根据用户输入的提示词，结合 MCP 工具的名字及描述，自动判断所需调用的 MCP 工具，并将工具返回的结果输入下一步的处理流程中。
1. 输入提示词
在 IDE 的对话框中切换为智能体模式，并在对话框中输入如下提示词。
2. 执行工具
当通义灵码需要调用 MCP 工具时，系统会出现提示，等您确认后将继续操作。
3. 查看工具执行结果
工具执行完成后，通义灵码的交互窗口将显示执行结果。您可以展开查看 MCP 工具的详细输入与输出信息，便于进一步分析和操作。
4. 代码审查与采纳
问答交互完成后，您可审查并采纳最终的代码生成。
场景使用示例
通义灵码支持两种类型的 MCP 服务，您可以选择合适的 MCP 服务类型，来体验通义灵码 MCP 功能。
- SSE 类型（远端服务托管） ：此类型的服务托管在远程服务器上，配置过程简单快捷，非常适合初次接触的新手用户快速上手体验。在本示例中，您可以通过魔搭社区的 MCP 市场选用fetch MCP服务，轻松实现从任意网页抓取内容的能力。
- 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. 完成配置
添加成功后，当图标显示
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-weatherMCP 服务配置信息
- 服务配置信息
{
"mcpServers": {
"weather": {
"command": "npx",
"args": [
"-y",
"@h1deya/mcp-server-weather"
],
}
}
}- 源码地址：weather MCP 服务
3. 完成配置
添加成功后，当图标显示
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.02.安装完成后，在终端中运行以下命令确认是否安装成功。
node -v
npx -v3.安装成功后，终端将显示已安装的 Node.js 版本号。
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"' >> ~/.zshrc2.安装完成后，在终端中运行以下命令确认是否安装成功。
node -v
npx -v3.安装成功后，终端将显示已安装的 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 uvx2.安装完成后，在终端中运行以下命令确认是否安装成功。
uvx --version3.安装成功后，终端将显示已安装的 uvx 版本号。
Mac 系统
使用 brew 安装（需先安装 brew）。
# 1. 添加uvx官方仓库
brew tap uvx/tools
# 2. 执行一键安装
brew install uvx
# 3. 验证安装结果
uvx doctor --environment
# 4. 配置自动更新（可选）
brew upgrade --cask uvx-updater2.安装完成后，在终端中运行以下命令确认是否安装成功。
uvx --version3.安装成功后，终端将显示已安装的 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.comMac 系统
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 广场安装后，仍需手动配置这些参数。
- 解决方案：
- 进入我的服务页面。
- 找到对应 MCP 服务，单击编辑。
- 在服务配置中，查看参数（args） 部分。
- 替换其中需要更新或填写的变量内容，确保其准确无误，重新连接服务后再尝试调用。
2. 模型无法正常调用 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 等页面。
解决方案：
配置 JCEF：在 IDE 中选择*Help > Find Action.. *，在弹出的输入框中输入 "Registry" 并打开。
- 启用选项
ide.browser.jcef.enabled - 关闭选项
ide.browser.jcef.sandbox.enable
- 启用选项
- 配置 IDE Runtime：再次选择*Help > Find Action.. *，在输入框中输入 "Choose Boot Runtime for the IDE" 并打开，选择较新的 JCEF Runtime 版本，然后确定。
- 重启 IDE。
4. MCP 服务列表无法正常加载
服务列表持续显示加载中。
- 重新启动 IDE。
- 如果问题仍未解决，可尝试手动启动 Lingma 服务：
Windows 系统
进入目录：.lingma/bin/x.x.x/CPU架构_64_系统/
执行命令：
Lingma.exe startMac 系统
单击电脑左上角苹果图标，选择“关于本机”查看处理器型号，然后根据处理器型号进入对应的目录。
- 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-...
**粗体** _斜体_ [链接](http://example.com) `代码` - 列表 > 引用。你还可以使用@来通知其他用户。