MCP Agent 连接 Streamable HTTP 服务时获取工具列表异常的分析与解决

问题背景

在使用 MCP Agent 连接 MCP 服务器时，开发者遇到了一个特殊现象：通过 FastMCP 客户端和 Postman 工具能够正常获取工具列表，但使用 MCP Agent 时却只能获取到 human_input，无法获取完整的工具列表。这一现象引发了我们对 MCP 协议实现细节的深入探究。

技术分析

经过对问题场景的复现和代码层面的深入分析，我们发现问题的根源在于 MCP 协议中的能力声明机制。MCP Agent 在设计上采用了更为严谨的交互方式，它会在执行任何操作前先检查服务器的能力声明（capabilities），而其他客户端工具可能没有实现这一检查机制。

在 MCP 协议规范中，服务器应当明确声明其支持的功能模块，包括：

• 工具（tools）管理能力
• 资源（resources）管理能力
• 提示（prompts）管理能力

解决方案

针对这一问题，我们提出了明确的解决方案：在服务器端配置中显式声明各项能力。以下是针对两种不同类型服务器的配置示例：

状态化服务器配置

@Module({
  imports: [
    McpModule.forRoot({
      name: 'playground-mcp-server',
      version: '0.0.1',
      capabilities: {
        tools: { listChanged: true },
        resources: { listChanged: true },
        prompts: { listChanged: true }
      },
      streamableHttp: {
        enableJsonResponse: false,
        sessionIdGenerator: () => randomUUID(),
        statelessMode: false
      }
    })
  ],
  providers: [GreetingResource, GreetingTool, GreetingPrompt]
})
class AppModule {}

无状态服务器配置

@Module({
  imports: [
    McpModule.forRoot({
      name: 'playground-mcp-server',
      version: '0.0.1',
      transport: McpTransportType.STREAMABLE_HTTP,
      capabilities: {
        tools: { listChanged: true },
        resources: { listChanged: true },
        prompts: { listChanged: true }
      },
      streamableHttp: {
        enableJsonResponse: true,
        sessionIdGenerator: undefined,
        statelessMode: true
      }
    })
  ],
  providers: [GreetingResource, GreetingTool, GreetingPrompt]
})
class AppModule {}

技术启示

这一问题的解决过程为我们提供了几个重要的技术启示：

1. 协议兼容性：不同客户端对协议规范的实现程度可能存在差异，开发者需要充分理解协议规范的全部要求。

2. 显式声明原则：服务器应当明确声明其支持的功能，这是构建健壮分布式系统的重要实践。

3. 客户端容错机制：虽然严格遵循协议规范是理想状态，但客户端也可以考虑增加适当的容错机制，在服务器能力声明不完整时尝试基本功能。

最佳实践建议

基于这一案例，我们建议开发者在实现 MCP 协议时遵循以下最佳实践：

1. 服务器端应当完整声明所有支持的能力模块
2. 客户端实现应当正确处理能力声明缺失的情况
3. 在开发阶段启用详细的日志记录，便于诊断协议交互问题
4. 定期验证客户端与不同服务器实现的兼容性

通过这一问题的分析和解决，我们不仅解决了具体的技术障碍，更深入理解了 MCP 协议的设计哲学和实现细节，为后续的开发工作奠定了更坚实的基础。