网关按两倍计：MCP 故障要分开查

MCP 调用失败时，不要把工具集、服务和网关的请求次数加在一起当异常。火山引擎 AgentKit 的 MCP 故障处理，按创建、连接、私网、工具装载、配额和计数六类分开看。MCP 在这里指 Model Context Protocol，模型上下文协议。下面只记排障约束，不记某一次调用的修复结果。

创建卡住，先看时间

创建 MCP 服务后，状态停在「创建中」不一定是故障。文档写正常创建大约要 7 到 8 分钟。超过 30 分钟还没完成，才按异常处理。原因要么是底层资源还在初始化，要么是部署过程本身失败。

处理顺序是：先等满 7 到 8 分钟再刷新列表，看有没有变成「运行中」。刷新后如果变成「不可用」，只对「部署 MCP 服务」这种方式有效：鼠标悬停状态，打开「查看日志」，在日志里搜 error。也可以调用 GetMCPService，部分部署失败会在 FailedLogFileUrl 里给出失败日志地址。超过 30 分钟仍停在创建中，并且这些步骤都修不好，要记下服务名称、创建时间和当前状态，再找技术支持。

创建后直接显示不可用，文档给了一条网络线：部署时要从公网拉 GitHub 依赖，拉取时间超过 2 分钟，就可能把创建打失败。确认日志里有依赖拉取超时后，可以重新创建。文档把这当成概率性问题，重试有可能恢复。多次仍失败，再带上服务名称、创建时间和日志去找支持。

接口文件已经解析成功，点确认却提示「内部异常」，问题在文件本身。必须是规范的 Swagger 2.0 或 OpenAPI 3.0，格式只能是 .json、.yaml 或 .yml，大小不超过 5 MiB。Word、PDF、网页说明和普通 Markdown 都不能当接口文件上传。格式和大小都对、仍然报内部异常，要记下操作时间、文件格式、文件大小和错误提示。

连不上外部服务

用第三方地址创建 MCP 服务后连接失败，常见原因不是 Agent 业务，而是地址和协议对不上。填进去的可能是普通 REST API，而不是标准 MCP Server。协议、域名、端口、路径，以及传输协议，只要和后端不一致，服务就会不可用。公网后端还要单独看 DNS、TLS 证书和证书域名是否匹配、后端是否允许公网访问。后端要 API Key、Token 或自定义 Header 时，必须配在 MCP 服务的后端出站凭据里。返回 HTTP 401 或 403，先查出站凭据有没有缺、填错或过期，Header 名称和认证前缀是否和后端一致。控制台连接测试还可能被浏览器 CORS 挡住。服务短暂异常后也可能自己恢复。

改配置的入口是详情页的后端服务配置。再次调用时，要确认返回的是 MCP 协议响应，不是普通 REST 响应。

私网不会自动放通

MCP 配成 VPC 私网后，访问不了同一 VPC 里的云服务器，不代表私网开关没生效。文档写明：打开私网只是具备访问 VPC 资源的网络条件，不会自动放通所有云服务器和端口。所属网关如果是专属网关，MCP 的网络配置跟着这个专属网关走。

要逐项核对：MCP 和目标云服务器在不在同一 VPC，或中间有没有可用网络连接；安全组入方向有没有放行所需协议和端口；子网网络 ACL 有没有拦入站或出站；系统防火墙有没有放行目标端口；后端有没有启动，并且监听的是 VPC 内其他资源能访问的地址和端口。部署出来的代码，只能访问网络可达且已放行的资源。导入 MCP 或 HTTP 转 MCP，必须明确选函数、容器、云服务器及端口，或配固定域名。只开放业务真正要用的机器和端口。

内网域名解析只对火山引擎 VPC 内部资源有效。先用目标 IP 和端口验证连通，通了但域名仍解析不了，可以临时在访问端 hosts 里写域名到 IP 的映射。文档把改 hosts 限定成临时验证，生产环境的解析要按实际网络架构来，不能靠 hosts 长期顶着。

工具列表是空的

已经建了 MCP Service 和 Toolset，也用 --mcp-toolset-id 把工具集绑到 Harness Runtime，运行日志里 ADK Agent 仍显示 tools: []，工具没有装上。文档给出的原因是：当前公测版 Harness 还没有适配 MCP 工具。agentkit runtime update --mcp-toolset-id 只在 Runtime 层建立关联，不会把 MCP 工具注入 Harness 内部创建的 Agent。日志里如果一直是 tools: []，重复执行这条 update 也注不进去。业务必须用 MCP 工具时，先改用已经支持装载的 Agent 运行方式，等 Harness 正式版适配。

额度用尽和双倍计数

调用提示额度不足时，先分网关。共享网关看的是当前账号或项目的 MCP 配额。专属网关看的是当前规格支持的额度，用尽就提升网关规格。文档把共享网关定位成 POC 和开发测试，正式生产推荐专属网关。配额数字到配额中心看当前用量和上限，默认值另见使用限制。到顶后提交提升申请，审批生效后再打一次调用。自己提不了，找客户经理。

计数更容易看错。调用一次 MCP 工具集，工具集和它关联的 MCP 服务两边都会记一次请求，并且分别计入用量。这不是重复计费。接入专属网关后，网关实际承载的请求次数是工具调用 QPS 的 2 倍。文档举例：工具集访问 MCP 服务的 QPS 是 10，专属网关实际承载 20 次/秒。估规格、对监控，都按这个 2 倍口径。实际请求量明显超过这个口径，还要加上定期连接产生的请求再核。共享网关和专属网关的计数逻辑相同。专属网关多出来的，是网关维度的监控和规格 QPS 配置。

这一页没有给出某次故障的失败率、恢复时长，也没有修复前后的监控曲线。7 到 8 分钟、30 分钟、2 分钟、5 MiB、401 与 403、QPS 的 2 倍和 10 对 20，是排障约束，不是线上效果。

字节，火山引擎 AgentKit 文档，MCP 故障处理，2026-10-15，https://docs.volcengine.com/docs/agentkit/mcp-troubleshooting