文档中心

AgentKit

故障处理

MCP 故障处理

本文介绍 AgentKit 中 MCP（Model Context Protocol，模型上下文协议）服务和 MCP 工具集的常见故障现象、可能原因与处理方法，适用于创建、连接、调用、私网访问、配额、计费和协议兼容性等场景，您可参考本文对应故障场景自行排障。

MCP 服务或 MCP 工具集创建失败

MCP 服务长时间处于“创建中”状态

现象描述

创建 MCP 服务后，状态长时间停留在创建中。正常情况下创建可能需要约 7～8 分钟，若超过 30 分钟仍未完成，可视为异常。

可能原因

底层资源仍在创建，还未完成初始化。

MCP 服务部署过程发生异常。

处理步骤

MCP 服务创建后等待 7～8 分钟，刷新页面以更新 MCP 服务列表，刷新后重新查看 MCP 服务的状态，是否已更新为运行中。

刷新后如果状态更新为不可用，可查看失败日志，该方式仅适用于通过“部署 MCP 服务”方式创建的 MCP 服务。

页面刷新后如果 MCP 服务状态变为不可用，将鼠标悬停在状态上，单击“查看日志”按钮。

在日志中搜索关键字“error”定位问题。

根据日志报错信息处理相关问题后重试，如果无法自行处理请记录服务名称、创建时间和当前状态，联系火山引擎技术支持人员处理。

通过 OpenAPI 查询失败日志。

调用 GetMCPService 查询 MCP 服务状态，部分部署失败场景会在 FailedLogFileUrl 字段中返回失败日志地址。

如果服务超过 30 分钟仍处于创建中，且上述操作均无法修复，请记录服务名称、创建时间和当前状态，联系火山引擎技术支持人员处理。

MCP 服务创建后状态显示“不可用”

现象描述

在控制台创建 MCP 服务失败，服务状态显示为不可用。

可能原因

MCP 部署过程中需要从公网拉取 GitHub 相关依赖包，可能因网络问题拉取时间超过 2 分钟时会导致 MCP 创建失败。

处理步骤

重新创建 MCP 服务。此操作针对概率性失败问题，重试后可能恢复。

如果多次重试仍失败，请记录服务名称、创建时间和日志信息，联系火山引擎技术支持人员处理。

MCP 工具接口文件解析成功，但确认后提示“内部异常”

现象描述

创建 MCP 工具时，接口文件已解析成功，但确认创建后提示“内部异常”。

可能原因

上传的接口文件不规范或格式存在问题。

处理步骤

确认创建 MCP 时上传的接口文件为规范化的 Swagger 2.0 或 OpenAPI 3.0 文件，详细要求请参见 MCP 服务 API 文件规范与示例。

确认创建 MCP 时上传的文件格式为.json、.yaml或.yml，且文件大小不超过 5 MiB。

注意

请不要上传 Word、PDF、网页说明或普通 Markdown 文档。

若上传的文件均满足上述要求但仍提示“内部异常”，请记录操作时间、文件格式、文件大小和错误提示，联系火山引擎技术支持人员处理。

连接外部 MCP Server 失败

使用第三方地址创建 MCP 服务后连接失败

现象描述

使用第三方服务地址创建 MCP 服务时，连接失败、服务不可用，或网络已连通但无法完成 MCP 调用。

可能原因

填写的是第三方普通 REST API 地址，而不是标准 MCP Server 地址。

配置的协议、域名、端口或路径与服务端实际信息不一致。

MCP 传输协议与服务端支持的协议不一致。

公网后端存在 DNS 解析、TLS 证书或网络访问异常。

后端要求 API Key、Token 或自定义 Header，但未正确配置出站凭据。

控制台连接测试受浏览器跨域资源共享（CORS）策略限制。

服务发生短暂异常后自行恢复。

处理步骤

登录AgentKit控制台。在 MCP 服务列表中查看服务状态，如果通过“部署 MCP 服务”方式创建的 MCP 服务，将鼠标悬停在状态上，单击“查看日志”按钮，查看日志确认问题原因。

确认 MCP 服务的后端地址是第三方提供的完整 MCP Server 地址，而不是普通 REST API 地址。

逐项核对后端地址中的协议、域名、端口和路径，确认配置无误，如果发现配置有误请在详情页面修改后端服务配置。

确认 MCP 服务中选择的传输协议与后端实际支持的协议是否一致，不一致可能导致 MCP 服务不可用，如果发现配置有误请在详情页面修改后端服务配置。

如果后端为公网地址，检查以下项目：

DNS 是否可以正常解析。

TLS 证书是否有效，证书域名是否与访问域名匹配。

后端是否允许公网访问。

如果后端要求鉴权，必须在 MCP 服务的后端出站凭据中配置对应的凭据。

如果返回 HTTP 401 或 403，请检查出站凭据是否缺失、填写错误或已经过期，并确认 Header 名称及认证前缀与后端要求一致。

再次发起调用，确认后端返回的是 MCP 协议响应而不是普通 REST API 响应，更多配置说明，请参见 MCP 服务相关文档。

如果仍无法解决，请记录操作时间、文件格式、文件大小和错误提示，联系火山引擎技术支持人员处理。

排查私网访问问题

私网 MCP 服务无法访问目标云服务器

现象描述

MCP 服务网络配置为 VPC 私网访问，但无法访问同一 VPC 中的云服务器，或误以为启用私网访问后会自动放通 VPC 内所有云服务器和端口。

说明

如果 MCP 服务所属网关为“专属网关”，MCP 网络配置跟随所属专属网关。

可能原因

启用私网访问只建立访问 VPC 内资源的网络条件，不会自动放通所有云服务器和端口。实际连通性还取决于安全组、网络 ACL、系统防火墙、服务监听地址及端口配置。

处理步骤

确认 MCP 服务与目标云服务器位于同一 VPC，或二者之间已有可用的网络连接。

检查目标云服务器的安全组入方向规则，按需放行 MCP 服务访问所需的协议和端口。

检查子网网络 ACL，确认未拦截对应的入站或出站流量。

检查目标云服务器的系统防火墙，确认目标端口已放行。

检查后端服务是否已启动，并监听可被 VPC 内其他资源访问的地址和端口。

根据 MCP 服务的创建方式核对后端配置：

部署 MCP 服务：部署后的代码可以访问 VPC 内网络可达且已放行的资源。

导入 MCP 服务或 HTTP 转 MCP：需要明确选择函数、容器、云服务器及端口，或配置固定域名作为后端。

仅开放业务所需的目标云服务器和端口，验证连接是否恢复。

如果上述操作均无法解决，请记录错误提示、网络配置等信息，联系火山引擎技术支持人员处理。

私网域名无法解析

现象描述

MCP 服务无法解析或访问内网域名。

可能原因

内网域名解析仅对火山引擎 VPC 内部资源有效。当前访问端可能不在对应 VPC 内，或域名解析链路未生效。

处理步骤

确认访问端位于对应的火山云 VPC 内，或已通过可用的网络连接接入该 VPC。

先使用目标 IP 和端口验证网络是否连通。

如果网络已连通但域名仍无法解析，可临时在访问端的 hosts 文件中配置域名与目标 IP 的映射。

重新发起连接并验证服务是否可用。

注意

手动修改 hosts 仅适合临时验证，生产环境中的域名解析方案及维护方式需结合实际网络架构确认。

如果上述操作均无法解决，请联系火山引擎技术支持人员处理。

排查 MCP 工具未加载或无响应

Harness Runtime 中显示 tools: []

现象描述

已创建 MCP Service 和 Toolset，并通过--mcp-toolset-id将 MCP 工具集关联到 Harness Runtime，但运行日志中的 ADK Agent 显示 tools: []，且未加载 MCP 工具。

可能原因

当前公测版本的 Harness 尚未适配 MCP 工具。agentkit runtime update --mcp-toolset-id只在 Runtime 层建立关联，不会自动把 MCP 工具注入 Harness 内部创建的 Agent。

处理步骤

检查当前使用的是否为 Harness 公测版本。

检查运行日志。如果 ADK Agent 持续显示 tools: []，则无法通过重复执行 agentkit runtime update --mcp-toolset-id 完成工具注入。

若业务必须使用 MCP 工具，请暂时改用已支持 MCP 工具装载的 Agent 运行方式，等待 Harness 正式版提供 MCP 工具适配能力。

处理配额不足

MCP 调用提示额度不足或疑似超额

现象描述

MCP 服务或 MCP 工具集无法继续调用，页面或日志提示额度不足。

可能原因

共享网关：当前账号或项目的 MCP 配额已用尽。

专属网关：当前专属网关规格支持的额度已用尽，请提升网关规格。

处理步骤

专属网关额度用尽：请提升网关规格，详细操作请参见变更专属网关实例规格。

共享网关配额用尽：共享网关更偏向 POC/开发测试，正式生产环境推荐您使用专属网关。了解更多

前往火山引擎配额中心，查看 MCP 相关配额的当前用量和上限，默认配额可参考使用限制。

确认达到配额上限后，提交提升配额申请，等待申请审批通过并确认新配额已经生效，重新发起 MCP 调用，验证服务是否恢复。

如果无法自行提升配置，请联系客户经理申请。

MCP 请求计数与计费

一次工具调用在工具集和服务侧均产生请求记录

现象描述

调用 MCP 工具集后，在 MCP 工具集和关联的 MCP 服务两侧都存在请求次数；接入专属网关后，网关侧记录的请求次数高于工具调用 QPS。

可能原因

MCP 工具集收到请求后，会继续访问关联的 MCP 服务完成工具调用。因此，同一个业务请求会在 MCP 工具集侧和 MCP 服务侧各记录一次，并分别计入对应的用量统计。

对于接入专属网关的场景，网关侧实际承载的请求次数为工具调用 QPS 的 2 倍。例如，工具集访问 MCP 服务的 QPS 为 10 时，专属网关实际承载 20 次/秒请求。

处理步骤

分别查看 MCP 工具集和 MCP 服务的请求用量，不要将两侧记录误判为重复计费异常。

评估专属网关规格时，按工具调用 QPS 的 2 倍估算网关实际请求量，详细说明请参见 MCP 请求计数规则。

如果工具调用 QPS 为 10，按 20 次/秒核对专属网关的承载能力和监控数据。

如果实际请求量明显超过该口径，结合定期连接产生的请求继续核对。

如果仍不符合预期，请联系火山引擎技术支持人员处理。

注意

共享网关与专属网关的请求计数逻辑相同。专属网关额外提供网关维度的监控数据和规格 QPS 配置。

最近更新时间：2026.10.15 16:01:42

这个页面对您有帮助吗？

有用

无用