Spring AI Alibaba MCP协议实战：模型上下文协议集成与工具调用

Spring AI Alibaba MCP协议实战模型上下文协议集成与工具调用导读MCPModel Context Protocol模型上下文协议是 Anthropic 于 2024 年末发布的开放标准旨在解决 AI 工具调用的碎片化问题。Spring AI Alibaba 1.1 版对 MCP 提供了完整支持。本文深入讲解 MCP 的三层架构、服务端开发、客户端接入以及与 Python MCP Server 的跨语言互通。一、MCP 的诞生背景在 MCP 出现之前每个 AI 应用都需要为自己的工具调用写一套独立的集成代码。你用的是通义千问我用的是 GPT他用的是 Claude各自的工具接口不通无法复用——这就是 AI 工具生态碎片化的现状。MCP 的价值在于定义了一套统一的工具调用协议类似于 REST API 之于 Web 服务的地位没有 MCP碎片化 Application A ←→ 自定义集成 ←→ Tool 1 Application B ←→ 自定义集成 ←→ Tool 2 Application C ←→ 自定义集成 ←→ Tool 3 有了 MCP标准化 Application A ──┐ Application B ──┤←→ MCP Protocol ←→ MCP ServerTool 1 Tool 2 Tool 3 Application C ──┘二、MCP 三层架构------------------- MCP Protocol ------------------ | Host宿主层 | ←←←←←←←←←←←←←←←←←← | Server服务层 | | | →→→→→→→→→→→→→→→→→→ | | | - AI 应用 | | - 工具实现 | | - 管理 Client | --------------- | - 资源暴露 | ------------------- | Client客户层| | - Prompt 模板 | | | - 工具发现 | ------------------ --→ 创建 Client → | - 工具调用 | | - 资源访问 | --------------- 传输协议 Stdio标准输入输出本地进程通信适合本地工具 SSEServer-Sent EventsHTTP 长连接适合远程服务 WebSocket双向通信适合高频实时交互三种能力类型MCP Server 可以暴露Tool可调用的函数最常用Resource可读取的资源如文件、数据库Prompt预定义的提示模板如角色扮演模板。三、依赖配置3.1 Server 端依赖!-- Spring AI MCP Server提供工具服务--dependencygroupIdorg.springframework.ai/groupIdartifactIdspring-ai-mcp-server-spring-boot-starter/artifactId/dependency!-- SSE 传输模式需要 Web 支持 --dependencygroupIdorg.springframework.boot/groupIdartifactIdspring-boot-starter-web/artifactId/dependency3.2 Client 端依赖!-- Spring AI MCP Client消费工具服务--dependencygroupIdorg.springframework.ai/groupIdartifactIdspring-ai-mcp-client-spring-boot-starter/artifactId/dependency!-- DashScope 模型 --dependencygroupIdcom.alibaba.cloud.ai/groupIdartifactIdspring-ai-alibaba-starter-dashscope/artifactId/dependency四、MCP Server 开发4.1 基于 SSE 传输的 MCP Serverpackagecom.example.mcp.server;importorg.springframework.ai.tool.annotation.Tool;importorg.springframework.ai.tool.annotation.ToolParam;importorg.springframework.stereotype.Component;importlombok.extern.slf4j.Slf4j;/** * 天气查询 MCP 工具 * 通过 MCP 协议暴露给任何兼容的 AI 应用 */Slf4jComponentpublicclassWeatherMcpTool{/** * 获取城市天气 * Tool 注解的方法会自动通过 MCP 协议暴露为工具 */Tool(description获取指定城市的实时天气信息包括温度、天气状况、湿度、风力等)publicWeatherInfogetWeather(ToolParam(description城市名称支持中文如北京、上海)Stringcity){log.info([MCP Tool] 天气查询{},city);// 实际项目调用真实天气 API和风天气、高德天气等returnnewWeatherInfo(city,晴转多云,22.5,68,东南风 3级);}/** * 获取天气预报未来 N 天 */Tool(description获取城市未来几天的天气预报最多7天)publicStringgetWeatherForecast(ToolParam(description城市名称)Stringcity,ToolParam(description预报天数1-7之间)intdays){log.info([MCP Tool] 天气预报查询{} 未来{}天,city,days);StringBuildersbnewStringBuilder(city).append( 未来).append(days).append(天预报\n);String[]conditions{晴,多云,阴,小雨,晴,多云,晴};int[]temps{22,20,18,16,19,21,23};for(inti0;iMath.min(days,7);i){sb.append(String.format(第%d天%s气温约%d°C\n,i1,conditions[i],temps[i]));}returnsb.toString();}publicrecordWeatherInfo(Stringcity,Stringcondition,doubletemperature,inthumidity,Stringwind){}}/** * 数据库查询 MCP 工具 */Slf4jComponentRequiredArgsConstructorpublicclassDatabaseMcpTool{privatefinalUserRepositoryuserRepository;privatefinalOrderRepositoryorderRepository;Tool(description根据用户ID查询用户基本信息)publicStringgetUserInfo(ToolParam(description用户ID)StringuserId){returnuserRepository.findById(userId).map(u-String.format(用户%s, 邮箱%s, 注册时间%s,u.getName(),u.getEmail(),u.getCreatedAt())).orElse(用户 userId 不存在);}Tool(description查询用户最近的订单记录)publicStringgetRecentOrders(ToolParam(description用户ID)StringuserId,ToolParam(description查询条数1-20之间)intlimit){ListOrderordersorderRepository.findByUserIdOrderByCreatedAtDesc(userId,PageRequest.of(0,Math.min(limit,20)));if(orders.isEmpty())return暂无订单记录;returnorders.stream().map(o-String.format(订单%s%s ¥%.2f [%s],o.getId(),o.getProductName(),o.getAmount(),o.getStatus())).collect(Collectors.joining(\n));}}4.2 Server 配置# application.ymlMCP Server 端spring:application:name:mcp-weather-serverai:mcp:server:# 服务名称客户端用于标识此 Servername:weather-and-database-tools# 版本version:1.0.0# 传输模式SSEHTTP 或 STDIO标准输入输出transport:SSE# 服务描述description:提供天气查询和数据库查询能力的 MCP Serverserver:port:8090启动后MCP Server 会自动在以下端点暴露工具信息GET /mcp/tools- 查询可用工具列表POST /mcp/call- 调用工具五、MCP Client 接入5.1 配置 MCP Client# application.ymlMCP Client 端spring:ai:mcp:client:# 配置多个 MCP Serverservers:# 本地天气服务SSE 模式weather-server:transport:SSEurl:http://localhost:8090# 超时配置connection-timeout:5srequest-timeout:30s# 远程数据分析服务SSE 模式analytics-server:transport:SSEurl:https://analytics.internal.company.com/mcp# 本地 Python MCP ServerStdio 模式python-tools:transport:STDIOcommand:pythonargs:[-m,my_mcp_server]5.2 在 ChatClient 中使用 MCP 工具ServiceRequiredArgsConstructorSlf4jpublicclassMcpChatService{privatefinalChatClientchatClient;// Spring AI 自动注入所有已配置的 MCP 工具privatefinalListMcpSyncClientmcpClients;/** * 使用 MCP 工具的智能对话 * Spring AI 自动处理 MCP 工具的发现和调用 */publicStringchatWithMcpTools(Stringmessage){log.info(使用 MCP 工具处理消息{},message);// 获取所有 MCP 工具的 ToolCallbackProviderListToolCallbackmcpToolCallbacksmcpClients.stream().flatMap(client-{// 工具发现获取 Server 暴露的所有工具vartoolsResultclient.listTools();returntoolsResult.tools().stream().map(tool-McpFunctionCallback.builder().mcpClient(client).tool(tool).build());}).collect(Collectors.toList());returnchatClient.prompt().user(message).tools(mcpToolCallbacks.toArray(newToolCallback[0])).call().content();}/** * 动态工具发现运行时查询 MCP Server 可用工具 */publicListStringdiscoverTools(){returnmcpClients.stream().flatMap(client-{StringserverNameclient.getServerInfo().name();returnclient.listTools().tools().stream().map(tool-serverName/tool.name()tool.description());}).collect(Collectors.toList());}}六、与 Python MCP Server 跨语言互通MCP 的一大优势是语言无关性。Python 社区有大量优秀的 MCP Server 实现如代码执行、数据分析等可以直接从 Java 侧接入# 接入 Python MCP ServerStdio 模式spring:ai:mcp:client:servers:python-analyzer:transport:STDIO# 启动 Python MCP Server 进程command:/usr/bin/python3args:[/opt/mcp-servers/data-analyzer/main.py]# 环境变量传入数据库连接等配置environment:DB_HOST:localhostDB_PORT:5432Python 侧 MCP Server 示例仅供理解协议不做重点展开# main.py - Python MCP Server 示例结构frommcp.serverimportServerfrommcp.server.stdioimportstdio_server appServer(data-analyzer)app.call_tool()asyncdefanalyze_data(name:str,arguments:dict)-list:ifnamerun_sql:queryarguments[query]# 执行 SQL 并返回结果return[{type:text,text:f查询结果:{execute_sql(query)}}]asyncdefmain():asyncwithstdio_server()asstreams:awaitapp.run(*streams,app.create_initialization_options())Java 侧通过 Stdio 模式调用 Python Server完全透明。七、安全机制7.1 Server 端安全隔离spring:ai:mcp:server:# 启用工具白名单只允许调用指定工具tool-whitelist:-getWeather-getWeatherForecast-getUserInfo# 不在列表中的工具不对外暴露# 启用请求鉴权security:enabled:trueapi-key:${MCP_SERVER_API_KEY}7.2 Client 端权限控制ConfigurationpublicclassMcpSecurityConfig{/** * MCP Client 请求拦截器添加认证头 */BeanpublicMcpClientCustomizermcpClientCustomizer(){return(clientBuilder)-clientBuilder// 为每个 MCP 请求添加认证 Header.requestInterceptor(request-{request.headers().add(X-MCP-API-Key,System.getenv(MCP_SERVER_API_KEY));returnrequest;})// 请求超时.requestTimeout(Duration.ofSeconds(30));}}八、企业内部 MCP Registry大型企业可以构建内部的 MCP 工具注册中心统一管理所有 MCP Server/** * MCP Registry企业内部工具注册中心 */RestControllerRequestMapping(/api/mcp/registry)RequiredArgsConstructorpublicclassMcpRegistryController{privatefinalMcpRegistryServiceregistryService;/** * 注册新的 MCP Server */PostMapping(/register)publicResponseEntityMcpServerInforegister(RequestBodyMcpServerRegistrationregistration){McpServerInfoinforegistryService.register(registration);returnResponseEntity.ok(info);}/** * 查询所有可用的 MCP Server 和工具 */GetMapping(/discover)publicResponseEntityListMcpServerInfodiscover(RequestParam(requiredfalse)Stringcategory,RequestParam(requiredfalse)Stringkeyword){returnResponseEntity.ok(registryService.discover(category,keyword));}/** * 健康检查验证所有注册的 MCP Server 是否在线 */GetMapping(/health)publicResponseEntityMapString,StringhealthCheck(){returnResponseEntity.ok(registryService.checkAllHealth());}}九、总结MCP 正在成为 AI 工具生态的通用插座本文的核心收获MCP 三层架构Host宿主→ Client客户端→ Server工具服务传输协议Stdio 适合本地进程SSE 适合远程 HTTP 服务三种能力Tool可调用函数、Resource可读资源、Prompt模板Server 开发Tool注解 Spring Boot几行代码构建 MCP Server跨语言互通通过 Stdio 模式接入 Python、Node.js 等语言的 MCP Server安全机制工具白名单 API Key 认证防止未授权访问。下一篇将进入 Deep Research 自动化调研领域探讨如何利用 Spring AI Alibaba 1.1 的推理模式实现多步骤深度研究报告自动生成。参考资料MCP 官方规范文档Spring AI MCP 集成文档Spring AI Alibaba MCP 示例