Spring AI MCP Server接入百炼问题排查

Spring AI MCP Server接入百炼问题排查

问题背景

在将基于Spring AI的MCP(Model Context Protocol)服务接入阿里云百炼平台时,遇到一个奇怪的问题:MCP服务在trae客户端上可以正常工作,但在百炼平台上却无法正常使用。具体表现为百炼平台发送第二个请求时,服务端接收不到请求体,导致请求失败。

公司有个AI对话智能体的需求,作为负责这个需求的后端开发,开发阶段被这个问题困扰了好久,不过最终还是然我找到原因了。所以写一篇博客分享一下,避免大家后续使用Spring MCP Server 接入百炼时踩坑!

问题现象

正常情况(trae客户端)

trae客户端每个请求都创建新的连接:

  1. 第一个连接发送initialize请求 → 响应后关闭连接
  2. 第二个连接发送notifications/initialized请求 → 响应后关闭连接
  3. 第三个连接发送tools/list请求 → 正常处理

异常情况(百炼平台)

百炼一直会提示:"获取工具异常,请确认MCP是否正常运行"

复制代码
"获取工具异常,请确认MCP是否正常运行
错误码:11200001
RequestId: dce6eab1-b35c-4471-bc97-d764639dff73

分析日志后发现是由于百炼平台会尝试复用连接导致的:

  1. 第一个连接发送initialize请求 → 响应后服务器关闭连接
  2. 在同一个连接上尝试发送第二个请求 → 但是此时MCP服务端Netty已经关闭链接了,这时候即使收到请求头,但是Netty的channel可能已经半关闭了,无法再继续接收请求内容,也无法正常响应内容。百炼那边等待超时就抛出异常了!

日志分析

从服务端日志可以看到关键信息:

log 复制代码
# 第一个请求正常处理
2025-12-13T11:43:58.745+08:00 INFO  REQUEST_BODY_DEBUG : MCP Request Body (207 bytes): {"jsonrpc":"2.0","method":"initialize","id":"3fe559ae-0",...}

# 服务器响应后关闭连接
2025-12-13T11:43:58.750+08:00 DEBUG r.n.http.server.HttpServerOperations : Last HTTP packet was sent, terminating the channel

# 第二个请求到达,但请求体为空
2025-12-13T11:44:58.805+08:00 INFO  REQUEST_BODY_DEBUG : MCP Request Body (0 bytes): 
2025-12-13T11:44:58.808+08:00 ERROR WebFluxStreamableServerTransportProvider : Failed to deserialize message: No content to map due to end-of-input

问题定位

通过深入分析日志,我们发现问题出现在几个方面:

1. HTTP/1.1连接复用问题

  • 服务器在发送完第一个响应后立即关闭了连接(terminating the channel)
  • 百炼平台认为连接仍然可用,尝试复用连接发送第二个请求
  • 由于连接已关闭,第二个请求的请求体无法被正确传输

2. 客户端-服务器行为不一致

  • trae:为每个请求创建新连接,符合服务器预期
  • 百炼:尝试复用连接以提升性能,但与服务器行为冲突

3. 协议处理差异

  • trae使用协议版本:2025-06-18
  • 百炼使用协议版本:2025-03-26
  • trae的capabilities为空对象
  • 百炼的capabilities包含roots.listChanged=true

排查过程

第一阶段:基础排查

  1. 检查协议兼容性:确认两个协议版本都支持
  2. 检查日志级别:启用DEBUG级别日志
  3. 对比请求差异:分析trae和百炼的请求头、请求体差异

第二阶段:深入分析

  1. 添加请求体调试过滤器:
java 复制代码
@Component
@Order(1)
public class RequestBodyDebugFilter implements WebFilter {
    // 记录请求头和请求体内容
}
  1. 发现关键证据:
  • 第二个请求的Content-Length: 54,但实际接收到的body是0字节
  • 请求在开始处理后等待60秒超时
  1. 排除可能性:
  • 排除100-continue问题(百炼没有发送Expect头)
  • 排除缓冲区大小问题
  • 排除JSON解析问题

第三阶段:问题根源确认

通过对比分析和日志追踪,确认问题是:
服务器在HTTP/1.1连接上过早关闭连接,但客户端仍尝试复用该连接

解决方案

最终解决方案:响应头中告诉百炼,链接已经关闭

java 复制代码
@Component
@Order(Integer.MIN_VALUE)
public class ForceConnectionCloseFilter implements WebFilter {
    
    @Override
    public Mono<Void> filter(ServerWebExchange exchange, WebFilterChain chain) {
        String path = exchange.getRequest().getURI().getPath();
        
        if (path.equals("/mcp")) {
            // 在响应头中强制设置Connection: close
            exchange.getResponse().getHeaders().set("Connection", "close");
            log.info("Forcing connection close for MCP request on connection: {}", 
                     exchange.getRequest().getId());
        }
        
        return chain.filter(exchange);
    }
}

方案原理

  1. 显式通信 :通过Connection: close头明确告诉客户端不要复用连接
  2. 客户端适配:百炼平台看到这个头后会为每个请求创建新连接
  3. 消除歧义:避免客户端和服务器对连接状态的理解不一致

其他尝试方案(未成功)

  1. 调整Netty配置尝试保持连接
  2. 修改HTTP解码器参数
  3. 添加Expect: 100-continue处理
  4. 调整连接超时时间

技术要点总结

1. HTTP/1.1连接管理

  • 默认情况下,HTTP/1.1支持连接复用(keep-alive)
  • 服务器可以通过Connection: close头显式关闭连接
  • Spring WebFlux/Netty在特定情况下可能过早关闭连接

2. Spring WebFlux行为

  • Reactive编程模型对连接管理有特殊处理
  • Netty默认配置可能不适合所有客户端
  • 需要显式配置来处理连接复用

3. 客户端差异

  • 不同HTTP客户端对连接复用的实现策略不同
  • 有些客户端更激进地尝试复用连接
  • 服务器需要能够处理各种客户端行为

经验教训

  1. 不要假设客户端行为一致:不同的HTTP客户端实现可能有显著差异
  2. 连接管理要显式:模糊的连接管理容易导致问题
  3. 日志是最好的调试工具:详细的日志可以快速定位问题
  4. 简单方案往往最有效 :复杂的配置调整不如简单的Connection: close
  5. 理解底层协议:对HTTP协议的理解有助于解决这类问题

结论

通过添加ForceConnectionCloseFilter,我们成功地解决了Spring AI MCP Server接入百炼平台的问题。这个问题的核心在于客户端和服务器对HTTP/1.1连接复用的行为不一致。解决方案虽然简单,但背后涉及对HTTP协议、Spring WebFlux连接管理和客户端兼容性的深入理解。

相关推荐
nice_lcj5202 天前
【从零理解 Spring AI · 13】RAG 要解决什么:把“闭卷考试“变成“开卷“
java·spring·检索增强·rag·spring ai·ai应用开发
Sakura_j_h_2 天前
MCP SDK 2.0 实战:用 MCPServer 搭本地笔记检索服务
开发语言·笔记·python·qt·ai工具·mcp·mcpserver
code2cat2 天前
【随笔】MCP长任务:查询已经返回,为什么任务还没有完成
javascript·人工智能·后端·mcp
装不满的克莱因瓶2 天前
【从零搭建】AI大模型之ReactAgent智能体对接MCP实战
java·人工智能·ai·springai·mcp·springaialibaba
xrlfreedom2 天前
MCP 面试高频考点:本地 AI 助手安全访问文件,Tools 与 Client 怎么协作?
tools·mcp·mcp client·python mcp sdk
code2cat3 天前
【随笔】MCP工具重试:任务已经创建,响应丢了怎么办
数据库·mcp
xrlfreedom3 天前
MCP 面试高频考点:远程 Tool 调用的认证、授权与最小权限怎么落地?
prompts·mcp·最小权限与审计日志·streamable http 传输
学编程就要猛5 天前
RAG(Retrieval Augmented Generation)
人工智能·spring ai
VIP_CQCRE5 天前
WorkBuddy 接入 Maestro 后,如何把一句需求变成可验收的视频任务
工作流·ai视频·maestro·mcp·workbuddy
张彦峰ZYF5 天前
浏览器调试接口的官方化:从 chrome-devtools-mcp 看 Agent 原生工具层的形成
人工智能·chrome·agent·mcp·apache-2.0许可·devtools-mcp·调试闭环