news 2026/4/23 20:43:46

基于 Spring AI 与 Streamable HTTP 构建 MCP Server 实践

作者头像

张小明

前端开发工程师

1.2k 24
文章封面图
基于 Spring AI 与 Streamable HTTP 构建 MCP Server 实践

基于 Spring AI 与 Streamable HTTP 构建 MCP Server 实践

面向专家读者的实战文章，目标是把“模型驱动工具调用（MCP）”从协议、架构到工程落地完整走通。本文强调可扩展、可观测与生产级交付。

1. 背景与目标

随着模型能力增强，单纯“对话式”应用难以满足真实业务需求：系统必须在受控环境中选择工具、调用外部能力、组合结果并持续推送。MCP（Model Context Protocol）提供了统一的工具暴露与调用规范；而Streamable HTTP则是解决“增量输出、低时延交互、服务端流式推送”的关键技术基础。

本文目标：

  • 以Spring AI为核心编排层
  • 通过Streamable HTTP实现低时延增量输出
  • 构建一个具备工具注册、工具发现、工具调用、结果流式回传的 MCP Server
  • 同时满足安全、可观测、扩展性等生产级要求

2. 总体架构设计

2.1 角色划分

  • MCP Server：提供工具注册、元信息描述、调用入口、流式返回
  • Spring AI：作为“模型侧编排器”，负责工具选择与调用
  • Tool Provider：实际业务能力（数据库、搜索、订单、风控、知识库）
  • Client（MCP Client/Agent）：可能是 IDE、AIGC 应用、或业务中台

2.2 核心链路

  1. Client 请求 MCP Server（描述任务）
  2. MCP Server 调用 Spring AI
  3. 模型判断调用工具，触发工具执行
  4. 工具执行结果被包装为增量事件流（Streamable HTTP）
  5. Client 以流式方式接收增量响应

3. 协议与数据结构约定

3.1 Tool Schema 结构

MCP 工具需要声明：

  • name：工具标识
  • description：用途说明
  • input_schema：输入参数结构（JSON Schema）
  • output_schema：输出结构

3.2 Streamable HTTP 事件模型

本文采用“事件类型 + payload + metadata”的格式，以便 Client 侧按事件增量渲染：

  • tool_call_start
  • tool_call_delta
  • tool_call_result
  • final

4. Spring AI 工程实现

4.1 依赖与工程结构

建议模块拆分：

  • mcp-server-core：协议、模型、流式响应
  • mcp-server-tools：工具实现
  • mcp-server-app：Spring Boot 启动层

4.2 MCP Server 接口定义

@RestController @RequestMapping("/mcp") public class McpController { private final McpService mcpService; public McpController(McpService mcpService) { this.mcpService = mcpService; } @PostMapping(value = "/invoke", produces = MediaType.TEXT_EVENT_STREAM_VALUE) public Flux<ServerSentEvent<McpEvent>> invoke(@RequestBody McpRequest request) { return mcpService.handleRequest(request) .map(event -> ServerSentEvent.builder(event).build()); } }

4.3 MCP 服务编排层

@Service public class McpService { private final AiClient aiClient; private final ToolRegistry toolRegistry; public McpService(AiClient aiClient, ToolRegistry toolRegistry) { this.aiClient = aiClient; this.toolRegistry = toolRegistry; } public Flux<McpEvent> handleRequest(McpRequest request) { return aiClient.chatStream(request.toPrompt(), toolRegistry.getToolSpecs()) .flatMap(this::handleModelOutput); } private Flux<McpEvent> handleModelOutput(AiDelta delta) { // 解析模型输出 → 工具调用 return Flux.just(McpEvent.delta(delta.getContent())); } }

5. Streamable HTTP 的核心实现

5.1 选择 SSE 还是 Chunked Response

  • SSE 简单、浏览器兼容好
  • Chunked Response 更自由，但需要自定义解析

本文采用 SSE（Spring WebFlux 原生支持）实现可控的增量输出。

5.2 工具调用事件流示例

public Flux<McpEvent> executeToolWithStream(ToolCall call) { return Flux.concat( Flux.just(McpEvent.start(call.getName())), toolRegistry.invoke(call) .flatMapMany(result -> Flux.just(McpEvent.result(result))), Flux.just(McpEvent.finalEvent()) ); }

6. 工具注册与发现

6.1 工具声明

@Component public class OrderQueryTool implements McpTool { @Override public String name() { return "order_query"; } @Override public String description() { return "根据订单号查询订单详情"; } @Override public JsonSchema inputSchema() { return JsonSchema.object() .field("orderId", JsonSchema.string().required()); } @Override public Mono<ToolResult> execute(JsonNode input) { String orderId = input.get("orderId").asText(); return Mono.just(new ToolResult("订单:" + orderId + " 状态: 已完成")); } }

6.2 工具注册中心

@Component public class ToolRegistry { private final Map<String, McpTool> tools = new ConcurrentHashMap<>(); public ToolRegistry(List<McpTool> toolList) { for (McpTool tool : toolList) { tools.put(tool.name(), tool); } } public List<ToolSpec> getToolSpecs() { return tools.values().stream() .map(ToolSpec::from) .collect(Collectors.toList()); } public Mono<ToolResult> invoke(ToolCall call) { McpTool tool = tools.get(call.getName()); return tool.execute(call.getArguments()); } }

7. 模型工具调用策略

7.1 关键问题

  • 如何防止模型乱调用工具？
  • 如何限制调用次数？
  • 如何校验参数合法性？

7.2 策略建议

  • 工具注册时带权限级别
  • 统一的 schema 校验层
  • 结果可信度过滤（必要时二次验证）

8. 可观测性与治理

8.1 日志设计

建议日志结构：

  • request_id
  • model_id
  • tool_name
  • latency
  • result_size

8.2 指标

  • 工具调用成功率
  • 工具耗时 P95/P99
  • 流式输出首包时间

8.3 追踪

结合 OpenTelemetry 统一关联模型调用链路。

9. 安全设计

  • 工具白名单：只允许注册白名单工具
  • 输入参数验证：JSON Schema 强校验
  • 速率限制：防止工具接口被刷
  • RBAC：不同客户端具备不同工具调用权限

10. 实战案例：订单+风控联合调用

10.1 场景

用户问：

“这个订单能否立即退款？”

模型需要：

  • 查询订单状态
  • 评估风控等级
  • 输出合并结论

10.2 工具调用链路

  1. order_query
  2. risk_check
  3. 合并结果 → 输出

流式返回：

  • tool_call_start(order_query)
  • tool_call_result(order_query)
  • tool_call_start(risk_check)
  • tool_call_result(risk_check)
  • final

11. 性能优化与可扩展性

  • 工具执行异步化：使用 Reactor 并行调度
  • 批量工具调用合并：减少模型交互次数
  • 工具结果缓存：避免重复调用

12. 生产落地建议

  • 先建立最小可用 MCP Server
  • 再逐步引入治理能力（权限、审计、灰度）
  • 再迭代性能（流式优化、并发调度）

13. 总结

Spring AI 提供了模型编排能力，Streamable HTTP 解决了用户体验问题，两者结合让 MCP Server 具备真正“生产级可用”的能力。对专家团队而言，关键不在于“是否能跑通”，而在于对工具生态、权限边界、可观测性、低延迟体验的系统化设计。

只要把“工具协议标准化 + 流式体验极致化 + 调用治理工程化”这三件事做好，MCP Server 就能成为企业级 AI 能力中枢。

版权声明: 本文来自互联网用户投稿，该文观点仅代表作者本人，不代表本站立场。本站仅提供信息存储空间服务，不拥有所有权，不承担相关法律责任。如若内容造成侵权/违法违规/事实不符，请联系邮箱：809451989@qq.com进行投诉反馈，一经查实，立即删除！
网站建设 2026/4/23 14:34:51

CC法混沌时间相空间重构+极限学习机ELM预测附Matlab代码

✅作者简介&#xff1a;热爱科研的Matlab仿真开发者&#xff0c;擅长毕业设计辅导、数学建模、数据处理、建模仿真、程序设计、完整代码获取、论文复现及科研仿真。 &#x1f34e; 往期回顾关注个人主页&#xff1a;Matlab科研工作室 &#x1f447; 关注我领取海量matlab电子书…

作者头像 李华
网站建设 2026/4/23 12:56:53

数字图像处理篇---均值滤波

我们用最直白的方式介绍「均值滤波」。你可以把它想象成图片的 “平均主义大锅饭” 。 一、一句话概括 均值滤波就是&#xff1a;把图片上每个像素点&#xff0c;都换成它自己和周围邻居们颜色的“平均值”。 二、核心比喻&#xff1a;班级平均分 想象一张图片是一个由很多小…

作者头像 李华
网站建设 2026/4/23 12:57:35

YAPI自动生成接口文档，解放测试人生产力...

Hi&#xff0c;大家好。如果接口文档信息不全或是没有接口文档的情况下&#xff0c;领导要求我们做接口自动化测试&#xff0c;这无异是一个非常艰辛的任务。但是编写接口文档的工作量很大&#xff0c;怎么办呢&#xff1f;有什么自动化工具可以协助我们生成文档呢&#xff1f;…

作者头像 李华
网站建设 2026/4/23 14:34:22

软测面试丨关于JMeter的面试问题，看这篇就够了！

JMeter是一款纯java编写负载功能测试和性能测试开源工具软件。相比Loadrunner而言&#xff0c;JMeter小巧轻便且免费&#xff0c;逐渐成为了主流的性能测试工具&#xff0c;是每个测试人员都必须要掌握的工具之一。下面松勤程老师列举分享一些关于JMeter问的最多的面试题。 1、…

作者头像 李华
网站建设 2026/4/23 16:02:56

基于灰狼算法优化孪生OS-ELM的多输入回归预测附Matlab代码

✅作者简介&#xff1a;热爱科研的Matlab仿真开发者&#xff0c;擅长毕业设计辅导、数学建模、数据处理、建模仿真、程序设计、完整代码获取、论文复现及科研仿真。 &#x1f34e; 往期回顾关注个人主页&#xff1a;Matlab科研工作室 &#x1f447; 关注我领取海量matlab电子书…

作者头像 李华