一文搞懂：如何用 Spring AI 搭建 MCP Server 和 Client

MCP 概述Model Context ProtocolMCP是一套标准化协议用于实现 AI 模型与外部工具或资源的交互。它提供一致的接口使 AI 模型能够访问数据库、API、文件系统及其他外部服务同时支持多种传输机制满足不同运行环境的需求。在没有 MCP 协议之前每个模型调用工具的方式各不相同接口格式不统一工具接入成本高模型调用外部资源缺乏标准化接入复杂且不稳定。有了MCP协议之后MCP核心就是把“模型调用工具”这件事标准化了。它让AI可以 让 AI 可以像程序一样稳定、标准地访问外部资源比如查询数据库调用接口API读写文件访问企业系统使用内部服务MCP Java SDK 架构官网地址 https://modelcontextprotocol.io/docs/sdkMCP Java SDK 采用三层架构以实现高内聚、低耦合和可扩展性Client/Server 层顶层McpClient负责客户端协议逻辑包括连接管理、工具调用和资源访问McpServer负责服务器端协议逻辑实现工具暴露、请求处理和客户端管理Session 层中间层McpSession会话管理核心接口McpClientSession / McpServerSession客户端/服务器会话实现负责维护连接状态及通信模式提供同步和异步操作支持Transport 层底层McpTransport消息传输和 JSON-RPC 序列化支持多种传输方式STDIO、HTTP/SSE、Streamable-HTTP 等为上层通信提供基础支持总的来说就是上层处理协议逻辑中层管理会话状态底层负责消息传输。与大模型的交互流程MCP Client 工具注册 / 上报能力真正的 MCP Client 通常是“包着大模型的那一层应用/框架”比如 CursorClineClaude Desktop等等触发点MCP Client 启动或大模型初始化时。功能上报可用工具列表给大模型例如数据库查询、文件访问、第三方 API 等。协商每个工具的能力、参数格式、权限范围。让大模型在生成调用指令时“知道自己能调用什么工具”。效果大模型可以在生成策略或回答时选择最合适的工具。大模型发起请求用户输入指令或触发事件。大模型参考 MCP Client 上报的工具能力决定使用哪种工具调用哪些参数MCP Client 封装请求将大模型的指令转成 MCP 标准消息发给给MCP Server。做版本与能力校验。支持同步或异步执行。MCP Server / 工具执行接收 MCP 消息。校验参数、权限。执行工具操作。返回结果或错误信息给MCP Client。MCP Client 返回结果MCP把结果进行格式化、封装结果。发送回大模型。大模型生成输出利用工具结果生成自然语言或结构化响应。返回给用户。与Tool Calling的对比对于大模型调用外部工具的能力之前的文章中已经讲过了一个Tool Calling 这里怎么又来一个MCP。这两者有什么区别吗这里我们把Tool Calling和MCP做一个对比。Tool Calling 本质上是模型调用外部工具的能力。依赖于模型本身的能力 如果模型本身没有“执行外部调用”的能力Tool Calling 就无法独立运作。MCP 是工具管理和调用的标准协议。 MCP 让模型可以像调用本地函数一样去访问各种工具解决了 不同工具接口不统一的问题MCP 并不赋能模型去调用工具它提供了安全、统一、可扩展的“通道”模型使用这个通道去执行工具调用。维度Tool CallingMCP层级模型能力系统协议作用决定“要不要调”定义“怎么调”是否执行工具不执行定义执行方式是否标准化各家不同统一协议是否跨进程/远程一般不涉及支持SpringAI中的MCPSpring AI 是 MCP Java SDK 的 Spring 封装 对 MCP 提供了全面支持通过 Boot Starters 和 Java 注解简化开发。它让开发者在 Spring Boot 环境中能用最少的配置和代码就使用 MCP 协议。在Spring AI使开发者可以轻松实现实现 MCP 客户端应用调用 MCP 服务器提供的工具和资源实现 MCP 服务器应用将服务或工具暴露给 MCP 客户端MCP Server Boot StartersMCP服务端Spring AI 提供自动配置的 Starter让你可以快速搭建 MCP 服务器包括多种协议、传输机制和开发模式一些核心特性自动配置 MCP Servers 组件工具/资源/提示/补全等多协议支持STDIO、SSE、Streamable‑HTTP、Stateless支持同步sync与异步async模式注解式开发支持基于 Spring Bean 扫描MCP Server支持同步和异步模式1. Synchronous Server同步服务器实现类McpSyncServer特点默认类型请求-响应模式blocking简单、直接适合大多数传统应用限制只注册同步MCP 方法异步方法会被忽略配置spring.ai.mcp.server.typeSYNC2. Asynchronous Server异步服务器实现类McpAsyncServer特点非阻塞、reactive 风格内置Project Reactor支持适合高并发、事件驱动或流式应用限制只注册异步MCP 方法同步方法会被忽略配置spring.ai.mcp.server.typeASYNC特性同步 (SYNC)异步 (ASYNC)编程模型阻塞、请求-响应非阻塞、Reactive注册方法同步方法异步方法性能场景普通请求处理高并发、流式数据内置支持自动同步工具注册Project Reactor 异步工具注册MCP Server的协议类型协议工作方式适用场景STDIO与宿主进程同一进程通过 stdin/stdout 通信内嵌到应用中无需独立服务器SSE独立服务器支持实时推送需要实时消息更新的多客户端场景Streamable-HTTP独立服务器通过 HTTP POST/GET 通信可选 SSE 流式推送HTTP 通信 多消息流场景Stateless独立服务器不维护会话状态微服务或云原生架构简化部署结合Cursor演示STDIO协议类型新建一个ai-mcp-server-std模块添加对应的依赖和配置dependenciesdependencygroupIdorg.springframework.ai/groupIdartifactIdspring-ai-starter-mcp-server/artifactId/dependencydependencygroupIdorg.springframework.ai/groupIdartifactIdspring-ai-starter-mcp-server-webmvc/artifactId/dependency/dependenciesserver:port:8086spring:ai:mcp:server:name:std-mcp-server version:1.0.0type:SYNCinstructions:这个服务提供了天气查询的功能capabilities:tool:trueresource:trueprompt:truecompletion:truekeep-alive-interval:30s stdio:true定义工具并添加配置类ComponentpublicclassWeatherTool{Tool(description根据城市查询天气)publicStringgetWeather(Stringcity){returncity 的天气是多云 20°C;}}ConfigurationpublicclassMcpServerConfig{BeanpublicToolCallbackProviderweatherTools(WeatherToolweatherTool){returnMethodToolCallbackProvider.builder().toolObjects(weatherTool).build();}}将项目打包后放在D:/jar文件夹下面打开cursor配置我们自己的MCP Server在mcp.json添加自己的mcp注意不要在json文件中写注释。{mcpServers:{std-mcp-server:{command:java,args:[-Dspring.ai.mcp.server.stdiotrue,-Dspring.main.web-application-typenone,-Dspring.main.banner-modeoff,-jar,D:/jar/ai-mcp-server-std]}}}在cursor中测试演示STREAMABLE-HTTP协议类型新建MCP Server新建一个ai-mcp-server-streamable模块添加对应的依赖和配置dependenciesdependencygroupIdorg.springframework.ai/groupIdartifactIdspring-ai-starter-mcp-server-webflux/artifactId/dependency/dependenciesserver:port:8087spring:ai:mcp:server:enabled:trueprotocol:STREAMABLEname:streamable-mcp-server version:1.0.0type:ASYNCinstructions:这个服务提供了天气查询的功能resource-change-notification:truetool-change-notification:trueprompt-change-notification:truecapabilities:tool:trueresource:trueprompt:truecompletion:truestreamable-http:mcp-endpoint:/mcp keep-alive-interval:30s定义工具并添加配置类ComponentpublicclassWeatherTool{Tool(description根据城市查询天气)publicStringgetWeather(Stringcity){returncity 的天气是多云 20°C;}}ConfigurationpublicclassMcpServerConfig{BeanpublicToolCallbackProviderweatherTools(WeatherToolweatherTool){returnMethodToolCallbackProvider.builder().toolObjects(weatherTool).build();}}启动项目结合Cursor使用继续在cursor中添加MCP Server由于没有认证Authorization就这样。{mcpServers:{std-mcp-server:{command:java,args:[-Dspring.ai.mcp.server.stdiotrue,-Dspring.main.web-application-typenone,-Dspring.main.banner-modeoff,-jar,D:/jar/ai-mcp-server-std.jar]},streamable-mcp-server:{type:streamable-http,url:http://localhost:8087/mcp,headers:{Authorization:Bearer your-token}}}}启用我们的mcp-server测试通过结合MCP Client使用下方讲解MCP Client时再配合使用。Stateless Streamable-HTTP协议类型和上述演示类似可在项目代码ai-mcp-server-stateless模块中查看MCP Client Boot StarterMCP 客户端启动器功能支持MCP Client Boot Starter 提供了管理多个 MCP 客户端实例自动初始化客户端可配置开启/关闭支持多种传输方式STDIO、HTTP/SSE、Streamable-HTTP、Stateless Streamable-HTTP与 Spring AI 的工具执行框架集成工具过滤与名称前缀定制生命周期管理Context 关闭时自动清理资源支持同步SYNC和异步ASYNC客户端支持注解方式的事件处理如进度、日志、采样、工具变更通知等可用的starter!--标准客户端 二选一--dependencygroupIdorg.springframework.ai/groupIdartifactIdspring-ai-starter-mcp-client/artifactId/dependency!--基于WebFlux的客户端二选一--dependencygroupIdorg.springframework.ai/groupIdartifactIdspring-ai-starter-mcp-client-webflux/artifactId/dependency新建Client配合STREAMABLE-HTTP服务新建一个ai-mcp-client模块dependenciesdependencygroupIdorg.springframework.ai/groupIdartifactIdspring-ai-starter-mcp-client/artifactId/dependencydependencygroupIdorg.springframework.boot/groupIdartifactIdspring-boot-starter-webflux/artifactId/dependency!--使用openai模型--dependencygroupIdorg.springframework.ai/groupIdartifactIdspring-ai-starter-model-openai/artifactId/dependency/dependenciesserver:port:8090spring:main:allow-bean-definition-overriding:trueai:openai:api-key:${qwen}base-url:https://dashscope.aliyuncs.com/compatible-mode chat:options:model:qwen3.5-plus temperature:0.7mcp:client:enabled:truename:spring-ai-mcp-client version:1.0.0type:ASYNCstreamable-http:connections:server1:url:http://localhost:8087endpoint:/mcp toolcallback:enabled:true添加配置代码和ControllerConfigurationpublicclassChatClientConfig{Bean(openAiModel)publicChatModelopenAiModel(OpenAiChatModelopenAiChatModel){returnopenAiChatModel;}BeanpublicChatClientopenAiChatClient(Qualifier(openAiModel)ChatModelchatModel,ToolCallbackProvidertools){returnChatClient.builder(chatModel)//通过了mcp协议获取了远程工具在配置文件中有相关的配置.defaultToolCallbacks(tools.getToolCallbacks()).build();}}RestControllerpublicclassChatController{AutowiredChatClientopenAiChatClient;GetMapping(/chat)publicFluxStringchat(Stringmsg){returnopenAiChatClient.prompt().user(msg).stream().content();}}先启动ai-mcp-server-streamable服务模块再启动ai-mcp-client客户端模块调用接口进行测试调用第三方的MCP Server这里一高德地图的mcp为例需要提前去高德开发平台获取apikeyhttps://lbs.amap.com/https://mcp.so/server/amap-maps/amap?tabtools新建一个mcp-servers.json{mcpServers:{amap-maps:{command:npx,args:[-y,amap/amap-maps-mcp-server],env:{AMAP_MAPS_API_KEY:自己的apikey}}}}修改配置增加servers-configurationspring:ai:mcp:client:enabled:truename:spring-ai-mcp-client version:1.0.0type:ASYNCstreamable-http:connections:streamable-mcp-server:url:http://localhost:8087endpoint:/mcp toolcallback:enabled:trueannotation-scanner:enabled:truestdio:servers-configuration:classpath:/mcp-servers.json新增一个接口进行测试GetMapping(/mcp/chat)publicFluxStringchatMcp(Stringmsg){returnopenAiChatClient.prompt().user(msg).stream().content();}调用接口测试通过这样我们就把高德的mcp功能集成进来了。MCP Server注解注解模块通常由 Starter 自动包含所以只要引入相关 Boot Starters就能直接使用。以下是一些常用的注解可以让你以声明式方式定义 Server 的行为dependencygroupIdorg.springframework.ai/groupIdartifactIdspring-ai-mcp-annotations/artifactId/dependencyMcpTool暴露一个可调用的函数如 API、脚本让 AI 模型在需要时主动执行特定操作McpResource定义对资源如文件、URL、数据库等的访问接口 提供只读的数据内容供 AI 读取并作为上下文参考McpPrompt定义可复用的提示词模板用于标准化与 AI 的交互流程如预设角色、步骤、示例McpComplete实现自动补全功能如参数建议McpTool/** * Mcptool是MCP协议专用的注解。Tool比它更高级也可以被识别成为MCP的工具 * 由于是异步模式返回的是Mono类型 * param op * param a * param b * return */McpTool(namecalculator,description简单的数学计算器)publicMonoDoublecalculate(McpToolParam(description运算符: add, sub, mul, div)Stringop,McpToolParam(description第一个操作数)doublea,McpToolParam(description第二个操作数)doubleb){doubleresultswitch(op){caseadd-ab;casesub-a-b;casemul-a*b;casediv-a/b;default-thrownewIllegalArgumentException(Unsupported operator);};returnMono.just(result);}McpPrompt/** * 让AI生成工作日报如果AI没有主动调用。可以明确使用daily_report工具。 */McpPrompt(namedaily_report,description生成工作日报)publicMonoPromptdailyReportPrompt(McpArg(namecontent,description今日工作内容)Stringcontent,McpArg(namerole,description你的角色)Stringrole){// 方法2手动构建 Prompt更灵活SystemMessagesystemMsgnewSystemMessage(String.format( 你是一个%s请根据用户的工作内容生成一份专业的工作日报。 日报需要包含工作摘要、完成情况、遇到的问题、明日计划。 使用 markdown 格式语气专业正式。 ,role));UserMessageuserMsgnewUserMessage(今日工作内容content);returnMono.just(newPrompt(systemMsg,userMsg));}McpResourceMcpResource(uriresource://docs/help)publicMonoStringgetHelpDoc(){returnMono.just( # 系统帮助文档 - 使用 getWeather 工具查询天气 - 使用 calculator 工具进行计算 );}在Cline中查看由于cursor不方便查看。这里使用cline其他软件类似添加MCP Servers3.4. 进行测试测试prompt结语至此我们已经基于 Spring AI 完整实现了 MCP Server 与 MCP Client 的搭建与调用流程从工具定义到客户端调用再到协议交互整体链路已经打通。相关示例代码已整理并开源地址如下https://github.com/byone421/springai-demo希望本文能帮助你快速理解 MCP 的使用方式并在实际项目中落地应用。