文档首页/ 智能体开发平台 AgentArts/ 用户指南/ 组件库/ MCP/ 故障排除
更新时间：2026-03-09 GMT+08:00
查看PDF
分享

故障排除

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

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

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

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

图1 MCP安装方式

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

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

NPX：基于Node.js生态的MCP服务。

UVX：基于Python生态的MCP服务。

Streamable HTTP/SSE（远程网络）

远程指的是用户自己搭建的MCP服务或者第三方提供的MCP服务。MCP服务代码并没有运行在AgentArts服务中，而是运行在别处（如通过本地电脑内网穿透暴露出来的地址、第三方MCP厂商提供的MCP API接口），平台仅作为客户端通过网络协议发起连接。

Streamable HTTP类型：基于标准HTTP协议的MCP连接方式，支持流式传输，是MCP协议推荐的远程连接方式，只需提供MCP服务的HTTP接口地址即可接入。

SSE类型：基于Server-Sent Events（服务器推送事件）协议的MCP连接方式，是较早期的远程连接方式，通过服务端主动向客户端推送数据实现实时通信，只需提供MCP服务的SSE接口地址即可接入。

接入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故障

表1 故障排查说明

故障现象

可能原因

排查方法

用户明确提出需求后智能体未调用MCP

MCP描述不够清晰，大模型无法关联。

优化MCP的名称和描述，使其更明确。

提示词中缺少MCP使用引导。

在提示词中明确说明MCP的使用场景和时机。

MCP未正确关联到智能体。

检查智能体配置中是否已添加对应的MCP。

智能体选错了MCP

多个MCP描述相似，大模型混淆。

差异化各MCP的描述，突出各自的使用场景。

挂载的MCP过多。

减少MCP数量，建议不超过5个。

提示词中未区分不同MCP的使用条件。

在提示词中为每个MCP写明具体的使用场景。

智能体对MCP返回结果的解读有误

返回数据字段含义不明确。

在提示词中说明如何解读MCP返回的数据。

MCP安装故障

当MCP安装失败时，平台会返回特定的错误码与错误信息。请按照思路进行初步诊断：

AgentArts内置了一套智能侦测机制。了解这个机制，能帮助您在面对复杂报错（如“超时”或“冲突”）时，快速判断问题是出在物理网络层还是应用配置层。

系统在连接您的MCP服务时，会依次执行两步探测：

  • 第一步 (Scout侦察)：使用TCP协议尝试与MCP服务建立连接。
  • 第二步 (SDK握手)：连接建立后，使用HTTP协议发送数据。

基于此机制，您可以根据报错详情进行精准定界：

表2 错误码说明

错误码

报错场景

典型报错信息

排查与解决思路

AgentArts.02401173

域名错误，无法解析目标主机地址

AgentStudioException: Unknown Host: mcp-unknown-host.local

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。

AgentArts.02401161

连接超时，网络物理隔离或防火墙丢包

Connect timed out (2s limit) 或TimeoutException... within 120000ms

物理网络直接断联

  • 现象：错误信息显示Connect timed out (2s limit)
  • 原因：系统连TCP握手都无法完成，报错连接超时。
  • 解决思路：
    • 连接第三方MCP时：对方可能封禁了云厂商的IP段（地理围栏）。建议更换相同功能的MCP。
    • 连接本地自建MCP时：MCP服务器是否因为安全组/系统防火墙原有没有放行端口，或者没有配置公网IP。

AgentArts.02401162

连接被拒绝，IP可达但端口不通

Connection Refused: Connection refused: no further information

连接被拒绝

  • 现象：错误信息显示Connection refused
  • 原因：系统成功触达了MCP服务，但MCP显式地反馈了拒绝信息。
  • 解决思路：
    • 连接本地自建MCP时：检查代码中是否固定监听地址，导致只接受服务器内部请求，拒绝外部AgentArts请求，需要将地址改为公网IP或内网穿透域名。
    • 创建MCP服务时：检查协议端口是否匹配，HTTP默认端口80，HTTPS默认端口443。请勿将HTTPS协议强行指定到非加密端口。

AgentArts.02401163

路径错误 (404) 服务通但路径不对

HTTP 404 Not Found: http://.../wrong-path

配置错误

  • 现象：错误信息显示HTTP 404 Not Found。
  • 原因：系统成功触达了MCP服务，但MCP显式地反馈了拒绝信息。
  • 解决思路：
    • 检查在AgentArts填写的MCP地址是否正确，URL是否存在拼写错误。检查URL的尾部。例MCP规范要求是/sse ，是否写成了/chat？尝试在浏览器直接访问该URL，确认是否能看到返回结果。
    • 检查创建MCP时是否漏填参数，或者参拼写错误。

AgentArts.02401164

代理/认证冲突，平台智能推断出配置错误

TimeoutException... (但错误码为1164) 或Conflict detected

应用层被拦截

  • 现象：错误信息显示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

安全协议与证书故障

  • 现象：报错信息显示PKIX path building failed或Handshake error。
  • 原因：AgentArts与MCP之前网络是通的，但双方在建立加密连接（SSL/TLS）时失败。
  • 解决思路：重点排查HTTPS证书的有效性。由于AgentArts默认不信任未经CA机构认证的自签名证书，无法信任非权威机构签发的证书。请根据您的场景采取以下对策：
    • 建议在测试阶段将协议由https:// 临时改为http://。此操作可绕过所有证书校验逻辑，但请确保您的服务端已开启非加密端口（通常为80或自定义端口）的监听。
    • 如果不确定证书状态，请在本地浏览器中直接访问该MCP的URL。如果地址栏弹出“您的连接不是私密连接”或“不安全”警告，即确认是证书问题。建议对自建MCP服务的证书进行更新，如更新为Let's Encrypt等正式的受信任证书。
父主题： MCP

相关文档