j9九游会登录/ 智果（agentarts）智能体平台/ 低代码开发/ / / 故障排除
更新时间：2026-07-15 gmt 08:00

故障排除-j9九游会登录

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

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

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

平台支持stdio（本地进程，含npx、uvx） 和http（远程网络，含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自动下载

http（远程网络，含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拦截等，用户无法干预对方服务策略。
  • 需联系服务j9九游会登录的技术支持解决：平台侦测机制异常、错误码无法匹配已知原因等平台侧问题。

不同场景需要重点关注的错误码不同，问题解决后重新创建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等正式的受信任证书。
父主题：

相关文档

网站地图