MCP 客户端出现 Error Code 504 通常意味着网关或代理服务器在规定时间内未收到上游 MCP 服务端的响应，排查重点应放在网关超时配置与上游服务健康状态上。

命令速用版

以下命令用于快速检查服务状态与网络连通性，需在网关服务器或客户端执行：

# 检查 MCP 服务端进程状态
systemctl status mcp-server

# 检查端口监听情况
ss -tuln | grep <port>

# 测试网关到上游的网络连通性
ping <upstream_ip>
telnet <upstream_ip> <port>

# 查看网关实时日志（以 Docker 为例）
docker logs -f mcp-gateway-container

# 抓取网络包分析握手过程
sudo tcpdump -i eth0 host <server_ip> -w mcp_capture.pcap

为什么会这样

504 Gateway Timeout 表示网关作为代理，未能及时从上游服务器收到响应。

在 MCP 架构中，客户端请求先到达网关，网关再转发给 MCP 服务端。如果 MCP 服务端处理过慢、进程阻塞、资源耗尽，或者网关与服务端之间的网络存在高延迟、丢包，网关在等待超过预设时间（如 30 秒）后就会向客户端返回 504 错误。这通常不是客户端直接连接服务端失败，而是链路中间环节等待超时。

分步处理

按照从上游到网关再到网络的顺序进行排查，避免盲目调整参数掩盖真实问题。

1. 检查上游 MCP 服务端健康状态

登录 MCP 服务端服务器，确认服务进程是否存活且无阻塞。

• 执行systemctl status mcp-server或ps -ef | grep mcp确认进程运行。
• 使用top或htop查看 CPU 和内存使用率，确认是否存在资源耗尽。
• 查看服务端应用日志，搜索是否有启动失败、内存溢出或线程阻塞错误。

2. 审查网关超时配置

如果服务端处理耗时确实较长，需调整网关等待时间。

• 对于 Nginx 网关，检查proxy_read_timeout和proxy_connect_timeout参数。
• 对于 Docker 部署的 MCP 网关，检查容器环境变量或配置文件中的超时设置。
• 适当增加超时时间（如从 30 秒调整至 300 秒），修改后执行重载命令生效。

3. 排查网络与安全策略

确认网关与 MCP 服务端之间的网络路径畅通。

• 使用traceroute或mtr检查路由路径是否存在延迟或丢包。
• 检查防火墙、安全组或 ACL 规则，确保网关 IP 被允许访问服务端端口。
• 使用tcpdump抓包分析 TCP 握手是否完成，是否有 RST 响应或 SYN 包未回应。

怎么验证是否生效

修改配置或修复服务后，需通过日志和请求测试确认问题是否解决。

• 观察网关访问日志，确认状态码是否从 504 变为 200。
• 检查日志中的request_time或upstream_response_time字段，确认响应时间在阈值内。
• 在客户端多次刷新页面或重试请求，确认错误不再复现。
• 若曾修改防火墙规则，使用telnet再次测试端口连通性。

常见坑

• 客户端超时与网关超时混淆：客户端设置的超时时间短于网关，可能导致客户端先断开，网关随后报 499 而非 504。
• 盲目调大超时参数：若服务端本身存在死锁或性能瓶颈，调大超时仅能延缓报错，无法根治问题。
• 忽略 DNS 解析：网关配置中使用域名连接上游，若 DNS 解析失败或波动，也会导致连接超时。
• 容器网络策略：在 Docker 或 K8s 环境中，容器间网络策略（Network Policy）可能拦截流量，需检查相关配置。

常见问题

504 错误和 502 错误有什么区别？

504 是网关等待上游响应超时，502 是网关收到上游无效响应或连接被拒绝。

修改 Nginx 配置后为什么还是报 504？

可能未执行 reload 重载配置，或上游服务端处理耗时超过了新的 timeout 设置。

客户端连接超时一定是 504 吗？

不一定，客户端直接连接服务端超时通常无 HTTP 状态码，504 特指经过网关代理时的超时。

参考来源

• HTTP 状态码 504 错误排查与解决方案详解
• Docker MCP 网关 502/504 频发？专家级错误追踪与快速定位全流程曝光
• MCP 客户端连接超时如何排查？
• 业务前端界面报错 504 排查思路和解决办法