ModelContextProtocol C SDK 客户端连接问题分析与解决方案

问题背景

在使用 ModelContextProtocol C# SDK 开发过程中，开发者遇到了客户端连接服务器时出现的连接挂起问题。具体表现为在使用 McpClientFactory.CreateAsync 方法创建客户端时，SSE (Server-Sent Events) 传输层连接无法正常建立，导致客户端无法获取服务器响应。

问题现象

开发者尝试通过以下方式创建 MCP 客户端：

1. 创建自定义的日志处理 Handler 包装默认的 HttpClientHandler
2. 配置 SSE 客户端传输选项，包括端点 URL 和附加头信息
3. 使用 McpClientFactory.CreateAsync 方法创建客户端

但在实际运行过程中，连接在 SSE 传输层建立阶段挂起，无法继续执行后续操作。

根本原因分析

经过深入排查，发现问题出在自定义的日志处理 Handler 实现上。具体原因包括：

1. 内容读取逻辑缺陷：日志处理 Handler 中直接调用了 response.Content.ReadAsync 方法，而没有先检查响应内容是否为空。当响应没有内容时，这个方法会无限等待输入，导致连接挂起。

2. SSE 协议特性：SSE 协议依赖于分块传输编码（HTTP/1.1）或数据帧（HTTP/2/3），不需要预先确定 Content-Length。而原代码错误地依赖了 Content-Length 头来判断是否有内容。

3. 异步处理流程：McpClientFactory.CreateAsync 方法需要等待服务器发送初始化响应（作为 SSE 事件），而如果自定义 Handler 没有及时返回响应，整个流程就会被阻塞。

解决方案

修正后的日志处理 Handler 实现应包含以下改进：

1. 安全的内容读取检查：在读取响应内容前，先检查内容是否存在且长度大于0。
2. 状态码过滤：只对非200/202状态码的响应进行详细日志记录。
3. 响应头收集：独立记录所有响应头信息，便于调试。

修正后的代码示例：

public class LoggingHandler : DelegatingHandler
{
    public List<string> ResponseLog { get; } = new();
    public List<string> ResponseHeadersLog { get; } = new();

    public LoggingHandler(HttpMessageHandler innerHandler)
        : base(innerHandler) { }

    protected override async Task<HttpResponseMessage> SendAsync(
        HttpRequestMessage request, CancellationToken cancellationToken)
    {
        var response = await base.SendAsync(request, cancellationToken);
        
        if (response.StatusCode != System.Net.HttpStatusCode.OK &&
            response.StatusCode != System.Net.HttpStatusCode.Accepted)
        {
            ResponseLog.Add($"Status Code: {response.StatusCode}");

            if (response.Content != null &&
                response.Content.Headers.ContentLength.HasValue &&
                response.Content.Headers.ContentLength.Value > 0)
            {
                var content = await response.Content.ReadAsStringAsync();
                ResponseLog.Add(content);
            }
        }

        foreach (var header in response.Headers)
        {
            ResponseHeadersLog.Add($"{header.Key}: {string.Join(", ", header.Value)}");
        }

        return response;
    }
}

最佳实践建议

1. 谨慎处理响应内容：在自定义 HTTP Handler 中，处理响应内容时要特别注意空内容的情况，避免阻塞。

2. 理解协议特性：使用 SSE 等特定协议时，要充分了解其传输机制，不要假设传统的 HTTP 响应模式。

3. 调试技巧：

   • 对于中间层服务（如 API 管理服务），可以利用其提供的跟踪功能辅助调试
   • 独立记录请求和响应的各个部分（状态码、头信息、内容等）

4. 版本更新：及时更新到 SDK 的最新版本（如问题中提到的 preview.12），以获取最新的修复和改进。

总结

在 ModelContextProtocol C# SDK 的使用过程中，自定义 HTTP 处理程序需要特别注意与 SSE 协议的兼容性。正确处理响应内容和理解协议特性是避免类似连接问题的关键。通过遵循上述解决方案和最佳实践，开发者可以构建稳定可靠的 MCP 客户端连接。