MCP协议实战：用Spring Boot构建AI工具调用服务

1. 从一次接口联调说起MCP 到底在解决什么问题去年底我接手了一个内部工具链整合的活儿需求听起来不复杂让公司自研的 AI 助手能直接读取 Jira 上的工单、查询 Confluence 里的文档、还能调用内部的部署平台触发一次灰度发布。按照过去的思路我得给每个系统写一套适配层Jira 一套 REST 封装、Confluence 一套 SDK 调用、部署平台再来一套 HTTP 客户端然后把这些能力硬编码进 AI 助手的工具调用列表里。光是接口鉴权、参数映射、错误处理这三件事就够我折腾两周。后来同事甩给我一个词MCP。全称Model Context Protocol翻译过来叫模型上下文协议。第一次听到这个名字的时候我下意识觉得又是一个营销概念毕竟这两年各种协议框架满天飞。但真正读完它的设计文档、动手写了一个 MCP Server 之后我改变了看法——它解决的是一个非常具体、非常痛的问题AI 应用和外部工具/数据源之间的标准化连接。你可以把 MCP 理解成 AI 世界里的USB-C 接口。在 MCP 出现之前每个 AI 应用要对接一个外部工具就得写一套专属的适配代码每个工具想被不同的 AI 应用调用又得针对每个应用做一遍集成。这是一个典型的 M×N 问题。MCP 做的事情是把 M 和 N 解耦——工具方只需要实现一个 MCP ServerAI 应用方只需要实现一个 MCP Client两边通过统一的协议通信。M 加 N 变成了 M 加 N 的加法而不是乘法。这篇文章我打算把 MCP 从理论到实战完整讲一遍重点放在Java 生态下的落地也就是Spring AI和Spring Boot怎么跟 MCP 结合。为什么聚焦 Java因为大部分企业级后端系统是 Java 写的而 MCP 的官方示例和社区讨论大量集中在 Python 和 TypeScriptJava 开发者想上手往往找不到一条完整的路径。我会把协议本身的核心概念、Spring AI 对 MCP 的支持现状、一个可运行的 MCP Server 实现、以及实际踩过的坑都摊开来讲。适合有 Spring Boot 基础、想把自己的业务系统接入 AI 能力的后端开发者也适合想理解 MCP 协议本质的技术负责人。2. MCP 协议的三个核心角色与通信机制在动手写代码之前必须先把 MCP 的架构模型搞清楚。很多人一上来就找 Spring AI 的 MCP 依赖结果发现配置了一堆东西还是跑不通根本原因是对协议里的角色划分和通信方式没有概念。我见过不止一个同事把 MCP Server 和 MCP Client 的职责搞反导致调试了半天。2.1 Host、Client、Server谁调用谁MCP 的架构里有三个角色理解它们的关键是搞清楚谁发起、谁执行。Host宿主是最终面向用户的那个应用比如一个 AI 聊天客户端、一个 IDE 插件、或者你公司内部的智能助手。Host 负责管理整个会话决定什么时候需要调用外部能力。Client客户端是 Host 内部的一个组件负责和 Server 建立连接、发送请求、接收响应。一个 Host 可以同时管理多个 Client每个 Client 对应一个 Server 连接。你可以把 Client 理解成 Host 伸出去的手每只手抓着一个工具。Server服务端是真正提供能力的一方。它暴露三类东西Tools工具、Resources资源、Prompts提示模板。Tools 是可被调用的函数比如查询订单状态Resources 是可读取的数据比如某份文档的内容Prompts 是预定义的提示模板方便 Host 复用。这里有个容易混淆的点MCP Server 不是传统意义上的服务端。它不一定是一个独立部署的 HTTP 服务它可以是运行在本地的一个进程通过标准输入输出和 Host 通信。这一点非常关键后面讲传输方式的时候会展开。2.2 两种传输方式stdio 与 HTTPMCP 目前主流的传输方式有两种选择哪种直接决定了你的部署形态。stdio标准输入输出是最简单的方式。Server 作为一个子进程被 Host 启动两者通过 stdin/stdout 交换 JSON-RPC 消息。这种方式的好处是零网络配置、天然隔离、启动快。缺点是 Server 必须和 Host 在同一台机器上无法跨网络调用。本地工具类场景比如让 AI 读取本地文件、操作本地数据库用 stdio 最合适。HTTP含 SSE方式下Server 是一个独立的网络服务Host 通过 HTTP 请求和它通信。早期 MCP 用的是 HTTP 加 Server-Sent Events 的组合后来协议演进出了 Streamable HTTP 这种更简洁的方案。这种方式适合 Server 需要被多个 Host 共享、或者 Server 部署在远端的情况。企业内部的工具平台通常会用这种方式。我个人的经验是开发调试阶段优先用 stdio因为不用管端口、不用管网络、日志直接打在终端里排查问题快得多。等逻辑跑通了再改成 HTTP 方式部署。很多新手一上来就搞 HTTP结果卡在跨域、鉴权、连接保活这些和 MCP 本身无关的问题上非常打击信心。2.3 JSON-RPC 2.0消息长什么样MCP 的底层消息格式是JSON-RPC 2.0。这意味着所有通信都是一个个 JSON 对象包含jsonrpc、method、params、id这些字段。你不需要手写这些 JSONSDK 会帮你处理但理解消息结构对调试很有帮助。一次典型的工具调用流程是这样的Client 先发送initialize请求做握手协商协议版本和双方能力然后发送tools/list获取 Server 提供的工具列表Host 把工具列表转成 AI 模型能理解的格式模型决定调用某个工具后Client 发送tools/call请求带上工具名和参数Server 执行完返回结果。{ jsonrpc: 2.0, id: 1, method: tools/call, params: { name: queryOrderStatus, arguments: { orderId: ORD-20240115-001 } } }看到这个结构你就明白了MCP 本质上就是一套约定好的函数调用协议。AI 模型输出一个函数名和参数Client 把它翻译成上面这个 JSON 发给 ServerServer 执行完把结果塞回result字段。所谓让 AI 调用工具底层就是这么回事。提示调试 MCP 通信时把日志级别调到 DEBUG把收发的原始 JSON 打出来比盯着 SDK 的封装对象猜问题高效得多。我排查过一个参数类型不匹配的 bug就是因为模型传的是字符串 123而 Server 期望的是数字 123看原始 JSON 一眼就发现了。3. Spring AI 对 MCP 的支持现状与选型考量搞清楚协议之后问题就变成了在 Java 里怎么实现 MCP答案目前基本只有一个——Spring AI。Spring AI 是 Spring 官方推出的 AI 应用开发框架它对 MCP 提供了比较完整的客户端和服务端支持。但在动手之前有几个选型上的现实问题必须先说清楚否则你可能会在版本兼容上浪费大量时间。3.1 Spring AI 的 MCP 模块拆解Spring AI 把 MCP 相关的能力拆成了几个独立的模块你需要根据自己的角色引入对应的依赖。模块作用适用场景spring-ai-mcpMCP 协议核心实现底层依赖通常不直接引入spring-ai-starter-mcp-clientMCP 客户端 Starter你的应用要作为 Host 调用外部工具spring-ai-starter-mcp-serverMCP 服务端 Starter你的应用要暴露工具给别人调用spring-ai-starter-mcp-server-webmvc基于 WebMVC 的服务端用 HTTP 方式暴露 MCP Server这里有个关键判断你到底是要做 Client 还是 Server很多人的业务系统是被调用的一方也就是要把自己的接口暴露成 MCP 工具给 AI 用那你要做的是 Server。反过来如果你想在自己的 AI 应用里调用别人写好的 MCP 工具那你做的是 Client。这两个方向的依赖和配置完全不同先想清楚再动手。3.2 版本兼容最容易翻车的地方Spring AI 迭代速度非常快MCP 相关的 API 在不同版本之间有过多次调整。我踩过的最大的坑就是版本不匹配——照着某篇博客的代码写结果编译报错因为那篇博客用的是 1.0.0-M 系列的里程碑版本而我项目里是另一个版本。我的建议是锁定一个明确的版本然后以官方文档为准不要混用不同来源的示例代码。截至我写这篇文章时Spring AI 的正式版本已经相对稳定MCP 的 Starter 也趋于成熟。但即便如此你仍然要注意 Spring Boot 版本和 Spring AI 版本的对应关系。Spring AI 通常要求 Spring Boot 3.x如果你还在用 Spring Boot 2.x那第一步是升级没有捷径。另外Spring AI 的仓库配置也需要留意。早期版本需要额外配置里程碑仓库正式版发布后一般从中央仓库就能拉到。如果你拉不到依赖先检查仓库配置而不是怀疑网络。3.3 为什么不用官方 Java SDK 手写MCP 官方提供了多语言 SDKJava 也有对应的实现。那为什么不直接用官方 SDK 手写而要用 Spring AI 的封装原因在于集成成本。官方 SDK 给你的是协议层的原语你需要自己管理连接生命周期、自己处理 JSON 序列化、自己把工具注册到 Spring 容器里。而 Spring AI 的 Starter 把这些都做成了自动配置——你只要在方法上加个注解它就被注册成一个 MCP 工具你只要在配置文件里写几行Client 就能连上 Server。对于 Spring Boot 项目来说这种约定优于配置的体验是巨大的效率提升。当然如果你要做一些 Spring AI 没覆盖的定制比如自定义传输层、特殊的鉴权逻辑那还是得回到官方 SDK 层面。但对 90% 的场景Spring AI 的封装足够了。4. 用 Spring Boot 写一个可运行的 MCP Server理论铺垫够了现在进入实战。这一节我会完整走一遍用 Spring Boot 加 Spring AI 写一个 MCP Server暴露几个工具然后用一个 Client 连上去调用。代码我会尽量给全同时解释每一步为什么这么写。4.1 项目骨架与依赖配置先建一个标准的 Spring Boot 3.x 项目。我习惯用 Mavenpom.xml里除了常规的 web 依赖核心是加上 Spring AI 的 MCP Server Starter。dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-starter-mcp-server/artifactId /dependency如果你打算用 HTTP 方式暴露把上面这个换成spring-ai-starter-mcp-server-webmvc。用 stdio 方式的话保持上面这个即可。这里有个细节Spring AI 的依赖管理建议通过 BOM 引入避免版本号写得到处都是。在dependencyManagement里引入 Spring AI 的 BOM然后具体依赖不写版本号这样升级的时候只改一处。dependencyManagement dependencies dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-bom/artifactId version你的版本号/version typepom/type scopeimport/scope /dependency /dependencies /dependencyManagement注意Spring AI 的版本号一定要和 Spring Boot 版本匹配。我建议直接去 Spring AI 官方文档的Getting Started页面确认当前推荐的组合不要凭记忆写。版本问题导致的报错往往信息很隐晦排查起来很痛苦。4.2 用注解暴露工具从方法到 MCP ToolSpring AI 提供了Tool注解加在方法上就能把它注册成一个 MCP 工具。这是整个实战里最舒服的部分——你几乎不用写任何协议相关的代码。Component public class OrderTools { Tool(description 根据订单号查询订单的当前状态返回状态描述和更新时间) public String queryOrderStatus( ToolParam(description 订单号格式如 ORD-20240115-001) String orderId) { // 这里替换成真实的业务查询逻辑 if (orderId null || orderId.isBlank()) { return 订单号不能为空; } // 模拟查询 return 订单 orderId 当前状态已发货更新时间2024-01-16 10:30; } Tool(description 查询指定用户在指定时间范围内的订单数量) public int countUserOrders( ToolParam(description 用户ID) String userId, ToolParam(description 开始日期格式 yyyy-MM-dd) String startDate, ToolParam(description 结束日期格式 yyyy-MM-dd) String endDate) { // 真实场景下这里查数据库 return 42; } }这段代码有几个点值得展开。description不是可有可无的注释它是给 AI 模型看的。模型根据这个描述判断什么时候该调用这个工具、参数该怎么填。描述写得含糊模型就可能该调用的时候不调用或者传错参数。我见过有人把 description 写成查询订单结果模型分不清它和查询物流的区别。描述要具体到输入什么、输出什么、什么场景用。ToolParam的 description 同样重要。模型需要知道每个参数的含义和格式。像日期这种有格式要求的参数一定要在描述里写清楚格式否则模型可能传 2024年1月15日 这种它自己觉得合理但你的代码解析不了的格式。返回值类型也有讲究。简单类型String、int、boolean最省事Spring AI 会自动序列化。如果返回复杂对象它会转成 JSON模型也能理解但要注意对象别太大否则会占用大量上下文。4.3 注册工具与启动配置光有Tool注解还不够你得告诉 Spring AI 去扫描这些工具。通常通过一个配置类来完成。Configuration public class McpServerConfig { Bean public ToolCallbackProvider orderToolCallbackProvider(OrderTools orderTools) { return MethodToolCallbackProvider.builder() .toolObjects(orderTools) .build(); } }这个ToolCallbackProvider的作用是把带有Tool注解的方法收集起来转换成 MCP 协议能识别的工具定义。MethodToolCallbackProvider会扫描传入对象的所有方法找出带Tool的生成对应的 schema。然后是application.yml的配置。如果用 stdio 方式配置相对简单主要是给 Server 起个名字、设置日志。spring: ai: mcp: server: name: order-mcp-server version: 1.0.0 type: SYNCtype有 SYNC 和 ASYNC 两种SYNC 是同步执行ASYNC 是异步。大多数场景用 SYNC 就够了除非你的工具方法里有耗时的 IO 操作才考虑 ASYNC。如果用 HTTP 方式webmvc starter还需要配置端口和端点路径并且要注意 SSE 相关的设置。这部分配置项比较多建议直接参考官方文档的示例不要自己猜。4.4 用 Client 连上去验证Server 写完了怎么验证它能用最直接的办法是写一个 MCP Client 去连它。Spring AI 同样提供了 Client Starter。dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-starter-mcp-client/artifactId /dependencyClient 的配置里要指定怎么连接 Server。stdio 方式下配置里写清楚启动 Server 的命令和参数HTTP 方式下写清楚 Server 的地址。spring: ai: mcp: client: stdio: connections: order-server: command: java args: - -jar - /path/to/order-mcp-server.jar配置好之后Client 会自动发现 Server 提供的工具并把它们注册到 ChatClient 的工具列表里。然后你就可以像平常调用 AI 一样问它帮我查一下订单 ORD-20240115-001 的状态模型会自动决定调用queryOrderStatus工具拿到结果后再组织成自然语言回复。这个自动决定调用的过程就是 MCP 的价值所在。你不需要在代码里写if 用户问订单 then 调用查询订单模型根据工具的 description 自己判断。这也是为什么前面反复强调 description 要写好——它是模型决策的唯一依据。5. 实战中那些文档不会告诉你的坑代码跑通只是开始真正把 MCP 用到生产环境会遇到一堆文档里不会写的问题。这一节我把踩过的坑整理出来都是实打实的经验。5.1 工具描述写不好模型就是不用这是最高频的问题。你明明注册了工具但模型就是不调用或者调用了错误的工具。九成情况下问题出在 description 上。我遇到过一个典型案例有两个工具一个叫getUserInfo描述是获取用户信息另一个叫getUserProfile描述是获取用户资料。模型完全分不清这两个该用哪个经常随机选。后来我把描述改成根据用户ID获取用户的基本信息包括姓名、手机号、注册时间和根据用户ID获取用户的扩展资料包括头像、个人简介、偏好设置模型立刻就能正确区分了。写 description 的原则说清楚这个工具做什么、输入是什么、输出是什么、什么场景下用。如果两个工具功能相近一定要在描述里点明它们的区别。宁可描述写长一点也不要让模型去猜。5.2 参数类型不匹配的隐蔽 bugJSON-RPC 传过来的参数类型是由模型决定的。模型可能把数字传成字符串把布尔值传成 true 字符串。如果你的方法签名是int count而模型传了5就可能出问题。Spring AI 会做一些类型转换但不是万能的。我的做法是在工具方法内部做一次参数校验和转换不要完全信任传进来的类型。对于数字参数用Integer.parseInt包一层对于日期参数用LocalDate.parse并捕获异常返回友好的错误提示而不是抛异常。Tool(description 查询指定日期的订单数量日期格式 yyyy-MM-dd) public String countOrdersByDate(ToolParam(description 日期格式 yyyy-MM-dd) String date) { try { LocalDate parsed LocalDate.parse(date); // 正常查询逻辑 return 该日期订单数量 queryCount(parsed); } catch (Exception e) { return 日期格式不正确请使用 yyyy-MM-dd 格式例如 2024-01-15; } }返回友好的错误提示模型看到之后往往能自我纠正重新用正确的格式调用一次。这比直接抛异常导致整个调用链断掉要好得多。5.3 上下文膨胀与工具数量控制MCP 的工具定义是要塞进模型的上下文窗口的。每个工具的 name、description、参数 schema 都占 token。如果你注册了几十个工具光工具定义就可能吃掉几千 token留给实际对话的空间就少了而且模型在几十个工具里选择的准确率也会下降。我的经验是单个 MCP Server 暴露的工具控制在 10 个以内超过就考虑拆分。按业务域拆订单相关的放一个 Server用户相关的放一个 ServerClient 按需连接。这样每个 Server 的工具列表都很聚焦模型选择起来也准。另外工具的 description 也不是越长越好。够用就行把关键信息说清楚不要写成一篇文章。我见过有人把 description 写成三段话结果 token 消耗翻倍效果还没提升。5.4 日志与可观测性MCP 的调用链路是用户提问 → 模型决策 → Client 发请求 → Server 执行 → 返回结果 → 模型组织回复。这条链路上任何一环出问题用户看到的都是AI 答非所问。排查的时候要在每一环都打日志。Client 侧记录发出了什么请求、收到了什么响应Server 侧记录收到了什么参数、执行结果是什么。Spring AI 的日志配置里可以开启 MCP 相关的 DEBUG 日志把原始 JSON 打出来。我习惯在工具方法的第一行和最后一行各打一条日志记录入参和返回值。这样一旦出问题能快速定位是参数传错了还是业务逻辑执行错了还是结果返回时出了问题。提示生产环境不要把完整的请求响应都打出来可能包含敏感数据。用脱敏后的摘要日志或者只在排查问题时临时开启详细日志。6. 从单机工具到企业级集成MCP 的扩展思路把单个 MCP Server 跑通之后很自然会想到怎么把它用到企业级场景里这一节聊聊扩展方向也是我在实际项目中正在探索的部分。6.1 多 Server 编排与工具路由企业里往往有多个业务系统每个系统都可能暴露自己的 MCP Server。Client 侧可以同时连接多个 ServerSpring AI 会把所有 Server 的工具汇总起来。但工具一多前面说的上下文膨胀和选择准确率问题就来了。一个思路是做工具路由。不是把所有工具都塞给模型而是先根据用户意图判断该用哪个 Server只加载那个 Server 的工具。这需要一层前置的意图识别可以用一个轻量模型或者规则引擎来做。这样每次给模型的工具列表都是精简的准确率和 token 消耗都能优化。另一个思路是工具命名加前缀。不同 Server 的工具名加上业务域前缀比如order_queryStatus、user_getProfile减少命名冲突也让模型更容易理解工具的归属。6.2 鉴权与权限控制MCP 协议本身对鉴权的定义比较基础企业场景下需要自己补。核心问题是怎么确保调用工具的用户有权限stdio 方式下Server 是本地进程权限通常继承自启动它的用户相对简单。HTTP 方式下Server 是网络服务必须做鉴权。常见的做法是在 HTTP 层加认证比如 Token 校验然后在工具方法内部再做一次业务级的权限检查。这里有个容易忽略的点MCP 的调用是模型发起的不是用户直接发起的。所以你不能简单地把用户身份透传下去需要在 Client 侧把当前用户身份绑定到会话上Server 侧根据会话身份做权限判断。这块目前没有标准方案需要根据自己系统的架构来设计。6.3 与现有 Spring Boot 系统的融合大多数企业的业务逻辑已经在 Spring Boot 应用里了不可能为了 MCP 重写一遍。合理的做法是在现有应用里加一个 MCP 适配层把已有的 Service 方法包装成Tool方法。Component public class ExistingServiceMcpAdapter { private final OrderService orderService; public ExistingServiceMcpAdapter(OrderService orderService) { this.orderService orderService; } Tool(description 查询订单状态) public String queryOrderStatus(ToolParam(description 订单号) String orderId) { Order order orderService.findByOrderId(orderId); return order null ? 订单不存在 : order.getStatusDesc(); } }这样业务逻辑完全复用MCP 只是一个薄薄的适配层。适配层里做参数转换、异常处理、结果格式化把领域对象转成模型能理解的字符串或简单结构。这种分层方式让 MCP 的引入对现有系统几乎无侵入也是我推荐的做法。6.4 本地模型与 MCP 的结合现在很多团队在尝试本地部署模型比如用 DeepSeek 这类可以私有化部署的模型。Spring AI 对本地模型的支持也在完善通过配置不同的模型客户端可以让 MCP 工具和本地模型配合工作。这个组合的价值在于数据不出内网。工具调用的数据、模型的推理过程全在内部完成。对于数据敏感的企业场景这是刚需。配置上的关键是把模型客户端的 base-url 指向本地服务然后确保 MCP Client 的工具注册流程和用云端模型时一致。Spring AI 的抽象层在这里体现了价值——换模型基本只改配置业务代码不动。不过本地模型的工具调用能力通常不如云端大模型description 要写得更明确参数格式要更宽容。我实测下来同样的工具描述云端模型能准确调用本地小模型可能需要多轮引导。这是模型能力差异不是 MCP 的问题选型时要心里有数。7. 我个人的一些实践体会MCP 这个协议我越用越觉得它的设计克制而聪明。它没有试图解决所有问题只是把AI 调用外部能力这件事标准化了。剩下的鉴权、路由、编排留给上层去发挥。这种克制反而让它容易被各种生态接纳。对 Java 开发者来说现在是最好的入场时机。Spring AI 的封装已经足够成熟写一个 MCP Server 的成本低到令人发指——加个依赖、写个Tool注解、配几行 yml就能让 AI 调用你的业务接口。真正花时间的不是写代码而是想清楚哪些能力值得暴露给 AIdescription 怎么写才能让模型用对。我最后再分享一个小心得先用 stdio 把逻辑跑通再考虑 HTTP 部署。stdio 方式下没有网络、没有鉴权、没有跨域所有精力都能放在工具逻辑本身。等工具描述调优好了、参数处理健壮了再迁移到 HTTP 方式这时候遇到的问题都是纯粹的部署问题好排查得多。反过来一上来就搞 HTTP各种环境问题混在一起很容易让人怀疑是不是 MCP 本身有问题。工具描述这件事值得反复打磨。我现在的习惯是每加一个工具先自己扮演模型看描述能不能让我准确判断什么时候该用、参数怎么填。如果我自己都要想一下模型大概率也会犹豫。这个自检方法很土但特别有效。