Streamable-HTTP MCP Server 技术详解与实战（含三种 mermaid 图表结构解析）

协议 STREAMABLE，能力自动到，通知流式推，Spring AI 轻松搞！

北漂老男孩

289人浏览 · 2025-11-23 00:15:00

北漂老男孩 · 2025-11-23 00:15:00 发布

Streamable-HTTP MCP Server 技术详解与实战（含三种 mermaid 图表结构解析）

概述

Streamable-HTTP MCP Server 是 Spring AI 体系下的新一代多通道 AI 工具服务端解决方案。它基于 HTTP/1.1 POST/GET，并可选支持 SSE（Server-Sent Events）流式推送，适合需要实时通知、动态资源管理的 AI 应用场景。本文将系统性梳理 Streamable-HTTP MCP Server 的核心概念、发展历史、架构原理、典型配置与开发实战，并用三类 mermaid 图表（flowchart、stateDiagram-v2、sequenceDiagram）分别对整体流程、状态变迁和交互序列进行结构化说明。

名词解释

MCP（Model Capability Protocol）：模型能力协议，定义 AI 服务端如何向客户端暴露工具、资源、提示词（Prompt）、补全等能力，并支持通知、日志、进度等多样交互。
Streamable-HTTP：一种基于 HTTP 的流式通讯协议，支持持久连接和 SSE 推送，取代原有 SSE 专用协议，提升兼容性和扩展性。
Spring AI：Spring 生态下的 AI 开发框架，支持多种 AI 服务端/客户端能力自动化注册与管理。
ToolCallback：Spring AI 的工具回调接口，开发者可通过注解或 bean 配置方式暴露自定义工具。
Resource/Prompt/Completion：分别代表服务端可暴露的资源、提示词模板和补全能力，均支持同步/异步调用和动态通知。

项目背景与发展历史

发展脉络

2023-2024：SSE Transport（Server-Sent Events）
传统 MCP Server 通过 SSE 实现服务端推送，但扩展性受限（如不易与主流 Web 框架深度融合）。
2025-03-26：Streamable-HTTP Spec 发布
官方推出 Streamable-HTTP MCP Server，完全兼容 Spring MVC/WebFlux，支持多客户端连接、HTTP POST/GET、SSE 推送，成为新一代推荐方案。
当前趋势
Streamable-HTTP MCP Server 逐渐取代 SSE Transport，成为 AI 工具服务端开发的主流架构。其能力注册、通知推送、持久连接等功能不断完善，极大提升了开发体验和系统可维护性。

参考资料

系统架构与配置

架构总览

Streamable-HTTP MCP Server 支持两种主流 Spring Web 框架：

Spring MVC（同步阻塞）
Spring WebFlux（响应式非阻塞）

可通过配置 spring.ai.mcp.server.protocol=STREAMABLE 启用，并根据实际场景选择 MVC 或 WebFlux 依赖。

典型配置示例

spring:
  ai:
    mcp:
      server:
        protocol: STREAMABLE
        name: streamable-mcp-server
        version: 1.0.0
        type: SYNC
        instructions: "This streamable server provides real-time notifications"
        resource-change-notification: true
        tool-change-notification: true
        prompt-change-notification: true
        streamable-http:
          mcp-endpoint: /api/mcp
          keep-alive-interval: 30s

依赖声明

MVC 版本依赖：

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-mcp-server-webmvc</artifactId>
</dependency>

WebFlux 版本依赖：

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-mcp-server-webflux</artifactId>
</dependency>

Streamable-HTTP MCP Server 核心能力

能力清单

能力类型	作用	典型配置项
工具 (Tool)	暴露可被模型调用的工具方法	capabilities.tool=true
资源	暴露静态/动态资源	capabilities.resource=true
提示词	暴露 Prompt 模板	capabilities.prompt=true
补全	暴露代码/文本补全能力	capabilities.completion=true
日志	服务端推送结构化日志	loggingConsumer
进度	服务端推送任务进度	progressConsumer
根变更	资源根列表变更通知	rootsChangeHandler
Ping/保活	客户端存活检测与周期性保活	keep-alive-interval

实战开发示例

1. 工具能力注册（ToolCallback）

@Service
public class WeatherService {
    @Tool(description = "Get weather information by city name")
    public String getWeather(String cityName) {
        // 实际天气查询逻辑
        return "北京：晴，25度";
    }
}

@SpringBootApplication
public class McpServerApplication {
    @Bean
    public ToolCallbackProvider weatherTools(WeatherService weatherService) {
        return MethodToolCallbackProvider.builder().toolObjects(weatherService).build();
    }
}

2. 资源能力注册

@Bean
public List<McpServerFeatures.SyncResourceSpecification> myResources() {
    var systemInfoResource = new McpSchema.Resource(...);
    var resourceSpecification = new McpServerFeatures.SyncResourceSpecification(systemInfoResource, (exchange, request) -> {
        var systemInfo = Map.of("os", "Linux", "cpu", "Intel");
        String jsonContent = new ObjectMapper().writeValueAsString(systemInfo);
        return new McpSchema.ReadResourceResult(
            List.of(new McpSchema.TextResourceContents(request.uri(), "application/json", jsonContent)));
    });
    return List.of(resourceSpecification);
}

3. 提示词能力注册

@Bean
public List<McpServerFeatures.SyncPromptSpecification> myPrompts() {
    var prompt = new McpSchema.Prompt("greeting", "A friendly greeting prompt",
        List.of(new McpSchema.PromptArgument("name", "The name to greet", true)));
    var promptSpecification = new McpServerFeatures.SyncPromptSpecification(prompt, (exchange, getPromptRequest) -> {
        String nameArgument = (String) getPromptRequest.arguments().get("name");
        var userMessage = new PromptMessage(Role.USER, new TextContent("Hello " + nameArgument + "!"));
        return new GetPromptResult("A personalized greeting message", List.of(userMessage));
    });
    return List.of(promptSpecification);
}

三类 mermaid 图表结构优化与简化说明

1. 流程图（flowchart）—— MCP Server 启动与能力注册流程

作用： 直观展示 MCP Server 启动和能力注册的自动化流程。

2. 状态图（stateDiagram-v2）—— 客户端连接生命周期

作用： 展示 MCP 客户端与服务端的连接、监听、消息接收的基本状态变迁。

3. 序列图（sequenceDiagram）—— 工具调用与通知推送交互

作用： 展示客户端调用 MCP Server 工具、服务端实际处理和多通道通知推送的交互序列。

速记口与系统性认知总结

速记口诀

“协议 STREAMABLE，能力自动到，通知流式推，Spring AI 轻松搞！”

系统性认知

Streamable-HTTP MCP Server 是 Spring AI 下的标准 AI 工具服务端协议，支持 HTTP/SSE 持久连接与推送，能力自动注册，适合多客户端、动态通知场景。
核心能力 包括工具、资源、提示词、补全、日志、进度、根变更、保活等，均可通过 Spring Bean 自动注册，支持同步/异步模式。
配置简洁，开发者只需声明 protocol 和所需能力，剩余自动化注册与推送由框架完成。
三类 mermaid 图表 分别从流程、状态和交互角度优化了理解路径，助力开发者系统掌握 MCP Server 运作机制。