# 故障排除 当MCP安装失败时，平台会返回特定的错误码以及错误信息提示。针对服务创建过程中可能遇到的网络连通性、环境配置冲突及协议错误，本章节提供了典型错误码的诊断流程与解决方案。 #### 前置检查：确认MCP安装方式 多数MCP服务安装失败源于MCP的安装方式选择错误。在您深入排查网络问题、配置问题前，请先确认MCP的安装方式是否选择正确。 平台支持Stdio（本地进程，含NPX、UVX） 和HTTP（远程网络，含Streamable HTTP、SSE) 两类连接模式。 图1MCP安装方式 ![](https://support.huaweicloud.com/lowcode-agentarts/zh-cn_image_0000002717389469.png "点击放大") **Stdio（本地进程，含NPX、UVX）** 这里的本地指的是AgentArts服务提供的运行环境，当选择NPX、UVX方式安装MCP时，平台会在内部自动从npm仓库/PyPI下载并启动MCP服务。 表1NPX、UVX安装MCP差异 | 方式 | 适用生态 | MCP来源 | |:---|:---|:---| | NPX | Node.js生态的MCP服务 | npm仓库自动下载 | | UVX | Python生态的MCP服务 | PyPI自动下载 | **HTTP（远程网络，含Streamable HTTP、SSE** **）** **远程** 是指MCP服务未部署在AgentArts平台内，而是运行在外部环境（如您的本地服务器、第三方云服务）中，AgentArts平台通过网络协议远程连接这些服务，平台仅作为客户端通过网络协议发起连接，MCP服务需可通过公网访问。 表2Streamable HTTP、SSE安装MCP | 方式 | 说明 | 推荐程度 | |:---|:---|:---| | Streamable HTTP | 基于标准HTTP协议，支持流式传输，是MCP协议官方推荐的远程连接方式。只需提供MCP服务的HTTP接口地址即可接入。 | 推荐（新建服务首选） | | SSE | 基于Server-Sent Events（服务器推送事件）协议，是较早期的远程连接方式，通过服务端主动向客户端推送数据实现实时通信。只需提供MCP服务的SSE接口地址即可接入。 | 仅兼容存量旧版MCP服务，新建服务不推荐 | 接入MCP服务时，MCP提供方通常均会标注出MCP的安装方式，如果未明确写出，也可以从MCP的配置脚本中判断出来使用哪种方式进行安装。请选择合适的MCP安装方式。 图2各类MCP服务安装方式示例 ![](https://support.huaweicloud.com/lowcode-agentarts/zh-cn_image_0000002687789852.png "点击放大") #### MCP调试故障 调试MCP工具时，请严格按照参数的格式要求填写输入值。参数格式不正确是调试中最常见的报错原因。建议在调试前先查看每个参数的类型、格式说明及示例，确保输入值符合要求。 以下是几类常见的参数格式错误及正确写法： **示例一：日期/时间参数** 部分MCP工具要求传入日期或时间参数，通常需要遵循特定格式： ``` 错误写法： date: 2025年1月15日 date: 01-15-2025 date: 2025/01/15 正确写法（需要根据MCP的实际要求填写）： date: 2025-01-15 （日期格式：YYYY-MM-DD） datetime: 2025-01-15T10:30:00Z （日期时间格式：ISO 8601） ``` **示例二：数组/列表参数** 部分工具的参数需要传入多个值（数组格式）： ``` 错误写法： tags: 科技,金融,医疗 tags: 科技、金融、医疗 tags: "科技" "金融" "医疗" 正确写法： tags: ["科技", "金融", "医疗"] ``` 常见报错：Expected array、got string或参数类型不匹配。 原因：数组参数需要使用JSON数组格式 \["值1", "值2"\]，而非逗号分隔的普通文本。 **示例三：JSON对象参数** 部分工具需要传入结构化的JSON对象： ``` 错误写法： filter: name=张三, age=25 filter: {name: 张三, age: 25} 正确写法： filter: {"name": "张三", "age": 25} ``` 常见报错：JSON parse error或Invalid JSON format。 原因：JSON格式要求键名必须用英文双引号包裹，字符串值也需要双引号，不能使用单引号或省略引号。 **示例四：枚举/固定可选值参数** 部分参数只接受预定义的几个固定值： ``` 参数说明：language（语言），可选值：zh / en / ja 错误写法： language: 中文 language: chinese language: ZH 正确写法： language: zh ``` 常见报错：Invalid enum value或参数值不在允许范围内。 原因：枚举参数必须严格使用规定的可选值，注意大小写通常也需要完全匹配。 **快速排查清单：** ``` 参数值的类型是否正确（字符串/数字/布尔值/数组/对象）？ 字符串值是否需要加引号？ 日期格式是否符合 ISO 8601 标准（YYYY-MM-DD）？ 数组参数是否使用了 JSON 数组格式 ["值1", "值2"]？ JSON 对象的键名是否用了英文双引号？ 枚举参数的值是否与可选项完全一致（含大小写）？ 必填参数是否全部填写？ 参数值中是否包含多余的空格或特殊字符？ ``` #### 智能体中使用MCP故障 以下故障通常由智能体配置不当引起，用户可通过调整提示词、MCP描述解决。 表3故障排查说明 | 故障现象 | 可能原因 | 排查方法 | |:---|:---|:---| | 用户明确提出需求后智能体未调用MCP | MCP描述不够清晰，大模型无法关联。 | 优化MCP的名称和描述，使其更明确。例如填写：获取天气信息，根据城市名称查询当前天气信息，包括温度、湿度、风力等。 | | 用户明确提出需求后智能体未调用MCP | 提示词中缺少MCP使用引导。 | 在提示词中明确说明MCP的使用场景和时机。例如添加：当用户询问天气信息时，请使用获取天气信息MCP查询。 | | 用户明确提出需求后智能体未调用MCP | MCP未正确关联到智能体。 | 检查智能体配置中是否已添加对应的MCP。如果已添加优先检查提示词中是否指明了MCP的应用场景。如果仍然无法触发，检查MCP本身是否可以正常使用，详见[调试MCP](https://support.huaweicloud.com/lowcode-agentarts/agentarts_05_0322.html)。 | | 智能体选错了MCP | 多个MCP描述相似，大模型混淆。 | 差异化各MCP的描述，突出各自的使用场景。 | | 智能体选错了MCP | 挂载的MCP过多。 | 减少MCP数量，建议不超过5个。挂载MCP过多会导致大模型在工具选择时产生混淆，降低调用准确率。如需使用更多工具，建议合并功能相近的MCP服务。 | | 智能体选错了MCP | 提示词中未区分不同MCP的使用条件。 | 在提示词中为每个MCP写明具体的使用场景。 | | 智能体对MCP返回结果的解读有误 | 返回数据字段含义不明确。 | 在提示词中说明如何解读MCP返回的数据。例如：MCP返回的JSON中，temp字段表示摄氏温度，humidity字段表示湿度百分比。 | #### MCP安装故障 当MCP安装失败时，平台会返回特定的错误码与错误信息。请按照思路进行初步诊断： AgentArts内置了一套智能侦测机制。了解这个机制，能帮助您在面对复杂报错（如"超时"或"冲突"）时，快速判断问题是出在物理网络层还是应用配置层。 系统在连接您的MCP服务时，会依次执行两步探测： - 第一步 (Scout侦察)：使用TCP协议尝试与MCP服务建立连接。 - 第二步 (SDK握手)：连接建立后，使用HTTP协议发送数据。 基于此机制，各错误码对应的失败阶段如下： 表4失败阶段说明 | 失败阶段 | 对应错误码 | 错误特征 | |:---|:---|:---| | 第一步（TCP侦察）失败 | 1173、1161、1162 | 连接尚未建立即报错，问题在网络层 | | 第二步（HTTP/SDK握手）失败 | 1164、1150、1163 | TCP通但HTTP层被拦截或证书异常，问题在应用层 | 在排查安装故障前，请先了解报错的处置归属： - 用户可自行修复：配置填写错误、URL路径错误这类配置类问题。 - 需更换MCP服务：第三方MCP封禁了华为云IP段、WAF拦截等，用户无法干预对方服务策略。 - 需联系服务技术支持解决：平台侦测机制异常、错误码无法匹配已知原因等平台侧问题。 不同场景需要重点关注的错误码不同，问题解决后重新创建MCP，如果MCP显示"部署成功"则表示问题已解决： 表5错误排查指引 | 场景 | 重点关注的错误码 | 首要排查方向 | |:---|:---|:---| | 使用第三方MCP厂商服务 | 1161、1164 | 网络连通性、WAF/CDN拦截 | | 本地自建MCP通过内网穿透暴露 | 1173、1161、1162 | 域名解析、公网可达性、端口监听 | | 公司内网部署MCP | 1164、1150 | 代理策略拦截、证书问题 | 表6MCP安装错误码说明 | 错误码 | 报错场景 | 报错信息 | 处置归属 | 排查与解决思路 | |:---|:---|:---|:---|:---| | AgentArts.02401173 | 域名错误，无法解析目标主机地址 | AgentStudioException: Unknown Host: mcp-unknown-host.local | 用户可修复 / 需更换MCP | **DNS解析被拦截** - **现象：**错误信息显示Unknown Host。 - **原因：**系统在解析MCP的域名IP阶段就失败了，根本没发出网络包。 - **解决思路：** - 创建MCP服务时：检查在AgentArts填写的MCP地址是否正确，URL是否存在拼写错误。 ![](https://support.huaweicloud.com/lowcode-agentarts/zh-cn_image_0000002717549345.png "点击放大") - 连接第三方MCP时：对方可能封禁了云厂商的IP段（地理围栏）。建议更换相同功能的MCP。 - 连接本地自建MCP时：自建MCP服务必须绑定公网IP (EIP) 或使用内网穿透域名。本地MCP服务器的安全组/系统防火墙没有放行端口，或者您没有配置公网IP，或者是否填写了.local或k8s-svc等内部域名？注意，AgentArts使用公网DNS，无法解析私有域名，导致AgentArts无法连通MCP，请勿在MCP地址中填写仅内网可用的域名。 | | AgentArts.02401161 | 连接超时，网络物理隔离或防火墙丢包 | Connect timed out (2s limit) 或TimeoutException... within 120000ms | 用户可修复 / 需更换MCP | **物理网络直接断连** - **现象：**错误信息显示Connect timed out (2s limit) - **原因：**系统连TCP握手都无法完成，报错连接超时。 - **解决思路：** - 连接第三方MCP时：对方可能封禁了云厂商的IP段（地理围栏）。建议更换相同功能的MCP。 - 连接本地自建MCP时：MCP服务器是否因为安全组/系统防火墙原未放行端口，或者没有配置公网IP。 | | AgentArts.02401162 | 连接被拒绝，IP可达但端口不通 | Connection Refused: Connection refused: no further information | 自建MCP问题，需联系供应方 | **连接被拒绝** - **现象：**错误信息显示Connection refused - **原因：**系统成功触达了MCP服务，但请求的URL路径在服务端不存在。 - **解决思路：** - 连接本地自建MCP时：检查代码中是否固定监听地址，导致只接受服务器内部请求，拒绝外部AgentArts请求，需要将地址改为公网IP或内网穿透域名。 - 创建MCP服务时：检查协议端口是否匹配，HTTP默认端口80，HTTPS默认端口443。请勿将HTTPS协议强行指定到非加密端口。 | | AgentArts.02401163 | 路径错误 (404) 服务通但路径不对 | HTTP 404 Not Found: http://.../wrong-path | 自建MCP问题，需联系供应方 | **配置错误** - **现象：**错误信息显示HTTP 404 Not Found。 - **原因：**系统成功触达了MCP服务，但MCP显式地反馈了拒绝信息。 - **解决思路：** - 检查在AgentArts填写的MCP地址是否正确，URL是否存在拼写错误。检查URL的尾部。例MCP规范要求是/sse ，是否写成了/chat？尝试在浏览器直接访问该URL，确认是否能看到返回结果。 - 检查创建MCP时是否漏填参数，或者参数拼写错误。 | | AgentArts.02401164 | 代理/认证冲突，平台智能推断出配置错误 | TimeoutException... (但错误码为1164) 或Conflict detected | 自建MCP问题，需联系供应方 | **应用层被拦截** - **现象：**错误信息显示TimeoutException且时间较长（如60s/120s），但错误码判定为1164。 - **原因：**系统发现TCP连接成功了（说明IP、端口、防火墙都是通的），但在发送HTTP请求时被阻塞或超时。 - **解决思路：** - 连接第三方MCP时：极大概率是对方的WAF (Web防火墙) 或CDN将AgentArts的请求视为爬虫/攻击流量进行了拦截（TCP握手放行，HTTP内容拦截）。建议更换相同功能的MCP。 - 连接公司内网搭建的MCP时：公司边缘网关的Proxy (代理) 策略拦截了该请求，但未返回标准的拒绝状态码。检查代理配置，确保目标地址已加入NO_PROXY列表，或允许来自AgentArts的HTTP持久连接。 | | AgentArts.02401150 | SSL/证书错误或其他通用网络错误 | Probe Error: PKIX path building failed | 自建MCP问题，需联系供应方 | **安全协议与证书故障** - **现象：**报错信息显示PKIX path building failed或Handshake error。 - **原因：**AgentArts与MCP之间网络是通的，但双方在建立加密连接（SSL/TLS）时失败。 - **解决思路：** 重点排查HTTPS证书的有效性。由于AgentArts默认不信任未经CA机构认证的自签名证书，无法信任非权威机构签发的证书。请根据您的场景采取以下对策： - 建议在测试阶段将协议由https:// 临时改为http://。此操作可绕过证书校验逻辑。此方法仅限本地测试环境，用于临时验证网络连通性，严禁在生产环境中使用。测试完成后请立即恢复为https://并修复证书问题。如需临时使用http，请确认服务端已开启非加密端口（通常为80或自定义端口）的监听。 - 如果不确定证书状态，请在本地浏览器中直接访问该MCP的URL。如果地址栏弹出"您的连接不是私密连接"或"不安全"警告，则确认是证书问题。建议对自建MCP服务的证书进行更新，如更新为Let's Encrypt等正式的受信任证书。 |