故障排除

当MCP安装失败时，平台会返回特定的错误码以及错误信息提示。针对服务创建过程中可能遇到的网络连通性、环境配置冲突及协议错误，本章节提供了典型错误码的诊断流程与解决方案。

前置检查：确认MCP安装方式

多数MCP服务安装失败源于MCP的安装方式选择错误。在您深入排查网络问题、配置问题前，请先确认MCP的安装方式是否选择正确。

平台支持Stdio（本地进程，含NPX、UVX）和Streamable HTTP/SSE（远程网络）两类连接模式。

图1 MCP安装方式

点击放大

Stdio（本地进程，含NPX、UVX）

这里的本地指的是AgentArts服务提供的运行环境，当选择NPX、UVX方式安装MCP时，平台会在内部自动从npm仓库/PyPI下载并启动MCP服务。

表1 NPX、UVX安装MCP差异
方式	适用生态	MCP来源
NPX	Node.js生态的MCP服务	npm仓库自动下载
UVX	Python生态的MCP服务	PyPI自动下载

Streamable HTTP/SSE（远程网络）

远程是指MCP服务未部署在AgentArts平台内，而是运行在外部环境（如您的本地服务器、第三方云服务）中，AgentArts平台通过网络协议远程连接这些服务，平台仅作为客户端通过网络协议发起连接，MCP服务需可通过公网访问。

表2 Streamable HTTP/SSE安装MCP
方式	说明	推荐程度
Streamable HTTP	基于标准HTTP协议，支持流式传输，是MCP协议官方推荐的远程连接方式。只需提供MCP服务的HTTP接口地址即可接入。	推荐（新建服务首选）
SSE	基于Server-Sent Events（服务器推送事件）协议，是较早期的远程连接方式，通过服务端主动向客户端推送数据实现实时通信。只需提供MCP服务的SSE接口地址即可接入。	仅兼容存量旧版MCP服务，新建服务不推荐

接入MCP服务时，MCP提供方基本均会标注出MCP的安装方式，如果未明确写出，也可以从MCP的配置脚本中判断出来使用哪种方式进行安装。请选择合适的MCP安装方式。

图2 各类MCP服务安装方式示例
点击放大

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描述相似，大模型混淆。	差异化各MCP的描述，突出各自的使用场景。
	挂载的MCP过多。	减少MCP数量，建议不超过5个。挂载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	代理策略拦截、证书问题

表6 MCP安装错误码说明
错误码	报错场景	报错信息	处置归属	排查与解决思路
AgentArts.02401173	域名错误，无法解析目标主机地址	AgentStudioException: Unknown Host: mcp-unknown-host.local	用户可修复 / 需更换MCP	DNS解析被拦截现象：错误信息显示Unknown Host。原因：系统在解析MCP的域名IP阶段就失败了，根本没发出网络包。解决思路：创建MCP服务时：检查在AgentArts填写的MCP地址是否正确，URL是否存在拼写错误。连接第三方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等正式的受信任证书。