搞 Java 的这帮人这两年应该都挺憋屈的。眼看着 Python 那边写 MCP Server 一个装饰器就搞定Node 生态里一把一把的开箱即用脚手架轮到咱们 Java 社区要么被官方 SDK 的响应式 API 绕得头晕要么被“先升到 JDK 17 再来聊”的硬性要求直接劝退。尤其是那些生产环境还跑在 JDK 8 上的老项目想蹭一波 AI 应用的热度感觉比重构十年老代码还难。我自己在给公司内部系统接入 MCP 生态的时候就一直在想一个问题Java 这边最熟练的日常开发模式是什么是 Spring MVC 的 Controller。为什么不能把写 MCP Server 也变成“定义一个类加几个注解方法写完就完事”的体验带着这个想法我前后拆了几个版本的方案最后落地了一套轻量封装核心就两句话开发 Java MCP 就像写 Controller 一样简单并且非常坚定地支持 Java 8。这篇内容就围绕这个标题展开把我从选型到落地、从踩坑到打磨的完整过程都翻出来讲一遍相信对正在观望 MCP 的 Java 团队尤其是项目还锁死在 JDK 8 上的同学会是一次很实在的参考。1. 为什么 Java 开发 MCP 应该像写 Controller 一样简单1.1 MCP 火爆背后Java 开发者的现实尴尬MCPModel Context Protocol模型上下文协议做的事情简单来说就是把 AI 模型这个“大脑”和外部工具、数据源之间定义了一套标准化的“手脚连接”协议。模型可以通过统一的接口去调用你封装好的工具函数、读取你的业务资源、套用你预设的提示词模板整个过程的交互方式被协议固定下来避免了每个 AI 应用都自己搞一套私有接入方案的碎片化局面。这股风从 2024 年底开始吹到现在已经明显席卷了开发工具链。Cursor、Claude 桌面版、各种 IDE 插件都在抢着支持 MCP 接入。但对于 Java 开发者来说真正上手的时候才发现所谓的“生态支持”远没有想象中那么丝滑。我自己踩过最典型的一个坑按照官方 SDK 的示例代码写了一个最简单的工具光是研究Mono怎么把异步结果转换成同步返回就花了整整一个下午。好不容易把代码跑通了想让测试环境从 JDK 11 升到 JDK 17结果业务部门的老系统有一堆祖传依赖在 JDK 17 下直接抛异常。那一刻我就特别清楚地感受到对于国内大批还停留在 JDK 8 上的企业级应用来说MCP 的接入成本简直是几何级上升。更别提很多 Java 团队的现状是Spring Boot 2.x JDK 8 传统的 Servlet 容器。这些团队并不缺写业务的能力缺的是一个能把 MCP 接入成本和日常 CRUD 对齐的低门槛方案。说得难听一点如果接一个 AI 协议比维护一套老系统还费劲那这个技术再火也很难在 Java 的土壤里真正扎根。1.2 这个方案的核心把 MCP 接入成本拉回 CRUD 级别我最终落地的这套封装核心思路是一句话MCP Server 里的 Tool本质上就是一个接收参数、返回结构化结果的远程方法调用。这不就是 Controller 里的一个 RequestMapping 方法吗请求进来参数绑定业务逻辑执行结果序列化返回唯一差别只是协议从 HTTP JSON 换成了 MCP 定义好的一套消息格式。沿着这个思路我设计了一套完全基于注解和 Spring 容器管理的轻量框架内部代号就叫 mcp-servlet-spring-boot-starter后面为了方便我就叫它“MCP Starter”。使用方不需要理解 MCP 底层的 JSON-RPC 消息怎么组装、不需要手动维护工具列表的 JSON Schema、不需要处理 SSE 长连接的细节只需要像写一个RestController一样把工具方法写上剩下的协议转换、参数校验、路由注册、结果序列化全部由框架自动完成。这个过程做下来我最大的体会是很多时候我们觉得一个新技术难不是因为技术本身有多高深而是因为它打破了我们最熟悉的开发范式。Java 开发者最熟悉的就是“类方法注解”这套表达方式那 MCP 的接入就应该以这套方式呈现而不是把人拽进一个完全陌生的异步编程模型里去。2. 核心设计Controller 模式如何移植到 MCP 上2.1 注解驱动的三层抽象Tool / Resource / PromptMCP 协议规定了三种核心能力原语Tool工具模型主动发起调用、Resource资源向模型暴露业务数据、Prompt提示词模板预设交互上下文。如果做成一个规规矩矩的框架那应该为这三种能力分别提供对应的注解和扫描机制。我的实现就是基于这个思路来的。框架定义了三个核心注解对应关系非常直观注解对应 MCP 能力类比 Spring MVCMcpTool工具方法RequestMappingPostMappingMcpResource资源加载GetMapping返回静态/动态数据McpPrompt提示词模板GetMapping返回拼接后的字符串每个注解都可以标注在任意Component或Controller类的任意方法上。方法参数通过McpParam注解补充描述信息和默认值框架在启动阶段通过反射收集所有注解方法自动生成对应的 JSON Schema 注册表并在 MCP 握手阶段原样返回给客户端。这里有一个非常重要的设计决策方法返回值不需要像官方 SDK 那样强制封装成CallToolResult对象。普通的基础类型、String、自定义 POJO、Map、List框架统一转成 MCP 要求的content数组结构。如果你需要精细化控制也可以直接返回框架自带的McpToolResult两种方式共存互不干扰。考虑到会有相当一部分读者刚接触 MCP我再多解释一句 Tool 和 Resource 的区别。Tool 像是给模型提供的一把“扳手”模型遇到合适的场景就会主动拿起来用Resource 像是给模型提供的一扇“窗户”模型只能看、不能操作。举个实际例子一个“查询天气”的功能应该做成 Tool因为模型需要根据用户输入的城市名动态发起查询而一个“公司组织架构”的信息如果只是让模型理解背景做成 Resource 更合适。2.2 传输层选择为什么绕开官方 SDK 的响应式栈最早评估接入方案的时候我第一时间试了官方 Java SDK。技术选型本身很先进但问题恰恰出在“先进”上。官方 SDK 深度依赖 Project ReactorAPI 全是Mono、Flux这一套响应式写法对于习惯了“请求进来参数拿好return 结果”这种线性思维的团队来说理解成本非常不友好。更麻烦的是兼容性。官方 SDK 的较新版本明确要求 JDK 17而 Spring Boot 2.x 默认跑在 JDK 8 上。我当时做了一个测试把一个最简单的官方示例放到 JDK 8 环境编译报错信息直接指向 JDK 版本过低整个项目组当场沉默。这就是现实Java 8 的存量项目是巨大的沉默堡垒任何不能在这个版本运行的工具链都会被打入冷宫。所以我做传输层选型的时候走了另一条路底层基于 Servlet 3.0 规范直接用普通的 HTTP 端点承载 MCP 协议消息。MCP 的传输方式本来就支持 Streamable HTTP客户端通过 HTTP 请求发送 JSON-RPC 消息同时通过 SSE 流式接收服务端消息这套交互完全可以在 Servlet 容器上实现不需要任何响应式依赖。具体实现上框架内置了一个核心DispatcherServlet风格的端点处理器统一接收POST /mcp请求。请求体进来后先解析出 JSON-RPC 消息的方法名如tools/call、resources/read再根据方法名路由到对应的已注册注解方法上执行完业务逻辑后把结果包装成 MCP 协议消息返回。整个链路有清晰的职责划分协议解析归协议解析参数绑定归参数绑定业务执行归业务执行谁都不越界。这样做的好处非常明显。第一不引入任何响应式依赖项目原有的 Tomcat/Jetty/Tomcat 不管是什么版本都能直接跑。第二Spring Boot 2.x 的老项目可以直接把框架当作一个普通 Starter 引入不用改任何基础设施配置。第三调试体验贴近传统 Web 开发请求响应模型一目了然。2.3 坚持 Java 8 兼容的执念与底气很多同行问过我一个问题为什么不干脆要求 JDK 17反正新项目用 17 又没什么成本。这话对绿地项目没错但对存量系统来说就是站着说话不腰疼。我自己的支持逻辑很简单Java 8 在字节码层面、语法层面和标准库层面是一套完全成熟稳定的技术底座。只要我们这些做框架的人不去碰官方 SDK 里那些需要 JDK 9 才能用的 API比如java.lang.invoke的某些新特性、新的 HTTP Client、模块系统相关的东西Java 8 想跑什么都能跑。具体做到这点的办法是框架代码只用 JDK 8 的标准库和基本语法编译目标设置为 1.8同时用独立的 Maven profile 在 JDK 8 环境下做持续集成。一旦有同事不小心写了 JDK 9 的 API构建系统直接报错拦截。这种方法没有多高深但恰恰因为坚持了最基本的工程纪律才让“支持 Java 8”不是一句空话而是真正可验证的承诺。3. 实操从零写一个支持 Java 8 的 MCP Server3.1 工程结构与依赖引入方案要落地必须先说清楚怎么引入。我这里以一个标准的 Spring Boot 2.7 JDK 8 工程为例。如果你用的是 Spring Boot 3.x JDK 17也不冲突因为框架本身没有绑定 Spring Boot 主版本只是通过spring.factories和自动配置机制挂载。首先在pom.xml里引入核心依赖dependency groupIdcom.example/groupId artifactIdmcp-spring-boot-starter/artifactId version1.0.0/version /dependency就这一条依赖框架会自动帮你带上协议解析所需的 JSON 库这里用的是 Jackson 2.x、Servlet APIprovided 级别不和你项目里的容器冲突以及 Spring Boot 自动配置模块。如果你的项目不是 Spring Boot而是纯 Servlet 项目也没关系。框架额外提供了一个McpServletRegistrationBean你只需要在web.xml或者ServletContext初始化器里手动注册一个McpServlet即可。不过为了文章篇幅考虑下面所有示例都基于 Spring Boot。引入依赖后在application.yml里配几个关键参数mcp: server: path: /mcp # MCP 端点路径 name: demo-mcp-server # 服务名称 version: 1.0.0 # 服务版本 enabled: true # 是否启用 MCP 端点配置项很少没有多余的“魔法值”。path是客户端连接的 HTTP 端点默认是/mcp。配置完成、启动工程后框架会自动扫描所有McpController和标注了McpTool等注解的 Bean并把它们注册进 MCP 能力列表。3.2 第一个 McpController 示例这个标题既然叫“像写 Controller 一样简单”那就必须先上一个最直观的对比。假设我们要做一个“名片信息查询”的 MCP 能力用传统 Controller 实现一个 HTTP 接口是这样的RestController public class ContactController { GetMapping(/contact/query) public Contact query(RequestParam(name) String name) { return contactService.findByName(name); } }改成 MCP Tool用这套框架写就是这样McpController public class ContactMcpController { private final ContactService contactService; public ContactMcpController(ContactService contactService) { this.contactService contactService; } McpTool(name query_contact, description 根据姓名查询联系人信息) public Contact queryContact(McpParam(description 联系人姓名) String name) { return contactService.findByName(name); } }看到没有两个类的形状几乎是完全镜像的。区别只在于一个用的是 Spring MVC 的注解一个用的是 MCP 框架的注解一个返回视图层数据一个返回给 AI 模型的结构化数据。你不需要理解 MCP 协议里的任何底层方法名也不需要知道CallToolRequest长什么样业务方法写完功能就有了。这个示例里我特意加了一个自定义 POJO 类型Contact作为返回值。MCP Starter 会在启动阶段通过反射分析Contact类的字段结构自动生成 JSON Schema并在客户端调用时把返回结果序列化成协议要求的格式。这对老项目尤其友好你已有的 VO/DO 类可以直接复用不会因为接入 AI 就要再写一套 DTO。3.3 自定义参数对象与 JSON Schema 自动生成如果你的 MCP Tool 要接收一个复杂的对象参数而不是几个简单的字符串怎么写答案依然是像写 Controller 一样直接把对象类型写在方法参数上。McpTool(name create_order, description 创建一条采购订单) public OrderResult createOrder(McpParam(description 订单请求参数) OrderRequest request) { return orderService.create(request); } public static class OrderRequest { private String orderNo; private String supplierId; private ListOrderItem items; // getter / setter 省略 }框架在启动时会递归扫描OrderRequest的所有字段生成嵌套的 JSON Schema。这个过程底层依赖 Jackson 的BeanDescription机制先把字段名、类型、嵌套结构全部摸清再翻译成协议要求的 schema 格式。前端 AI 模型通过 schema 就能知道“这个工具需要什么参数、每个参数是什么类型”从而自主完成调用。这里有几个值得注意的实现细节字段名敏感性MCP 协议中参数名默认是下划线风格比如order_no如果你的 Java 字段是驼峰风格orderNo框架会自动做一次驼峰到下划线的转换并在反序列化时转回来。这一点可以在McpParam里通过name属性手动覆盖。必填与校验McpParam新增了requiredtrue和pattern属性对应 JSON Schema 里的required和pattern。如果模型调用时缺了必填参数框架会在真正执行业务方法前返回参数错误避免业务层被脏数据污染。嵌套泛型对于ListOrderItem这种泛型嵌套结构框架通过 Jackson 的TypeReference机制做完整解析不是简单地toString()所以复杂对象可以放心传。3.4 运行与本地验证用 AI 客户端连一次启动工程后框架会在控制台打印一条提示告诉你 MCP 端点已经就绪类似这样MCP server is ready: name: demo-mcp-server version: 1.0.0 endpoint: http://localhost:8080/mcp tools: [query_contact, create_order] resources: [] prompts: []到这一步最直观的验证方式是用支持 MCP 客户端的工具直接连上来试。比如 Claude Desktop、Curson 或其他 MCP 客户端添加一个自定义 MCP Server类型选择 HTTP/SSE地址填http://localhost:8080/mcp。客户端会先发起初始化握手然后通过tools/list拿到工具列表你就能在对话里直接调用到刚刚写的 Java 方法了。如果没有桌面客户端也可以用命令行 curl 模拟一次完整的tools/call请求。以query_contact为例curl -X POST http://localhost:8080/mcp \ -H Content-Type: application/json \ -d { jsonrpc: 2.0, id: 1, method: tools/call, params: { name: query_contact, arguments: { name: 张三 } } }返回结果会是一个标准的 MCP 消息结构里面content数组携带了你方法返回的数据。看到这个返回包的那一刻基本就能确认链路全通了。4. 踩坑实录客户端连不上、参数映射错、Java 8 兼容性4.1 连接不上端点先查这三处不管框架封装得多简单MCP 终究是一个网络协议级的东西客户端连不上端点的时候问题可能出现在多个层面。我整理了出现频率最高的三个坑按出现概率排序**第一个坑HTTP 路径配置被网关或上下文路径吞掉了。**Spring Boot 项目如果配置了server.servlet.context-path那么实际的 MCP 端点地址不是/mcp而是/你的context/mcp。客户端如果不知道这层前缀请求 404 是必然的。解决办法是在配置里把路径设置为${server.servlet.context-path:}/mcp或者干脆让客户端直接用完整的带前缀地址。**第二个坑鉴权配置导致握手失败。**很多团队给内部接口套了统一鉴权过滤器比如拦截所有/api/*的 Token 校验如果 MCP 端点落在被拦截的路径范围内握手请求会被业务过滤器拦住返回 401而客户端往往只是报一个笼统的“无法连接”。这时候可以用框架提供的mcp.server.path配合白名单机制把这个路径排除在业务鉴权之外MCP 自身的鉴权由框架提供的McpAuthInterceptor单独处理。**第三个坑Servlet 容器对 SSE 缓冲的干扰。**如果使用的是 Streamable HTTP 传输方式服务端需要持续向客户端推送 SSE 事件流。有些 Nginx 配置或者 Tomcat 的响应缓冲会拦截住块事件导致客户端一直等待超时。调试时建议先把代理层绕开直连应用端口验证确认根因后再决定是调大缓冲还是改传输方式。4.2 参数/返回值序列化不一致的排查这一节应该是 MCP 对接过程里最折磨人的模块了。客户端明明拿到了 schema生成的参数结构却和你 Java 方法期望的完全不匹配。我遇到过最诡异的一次客户端传了一个{supplier_id: S1001}但我的OrderRequest里字段叫supplierId结果就是null。排查过程分三层先看 schema 到底长什么样MCP 客户端一般会缓存tools/list的结果如果你改了 Java 代码里的字段但客户端还在用旧的 schema那怎么传都错。重启客户端或者开启 MCP 调试日志重新拉一次 tool 列表这一步能排除大部分“新旧 schema 混合”的问题。再看框架的命名转换规则默认驼峰转下划线这个规则对于supplierId来说schema 里就是supplier_id。客户端生成的参数键名是supplier_id而框架在反序列化时会自动转回 Java 字段名正常情况下没问题。如果你在McpParam里手动指定了name那一切以手动指定的名字为准别指望自动转换能覆盖。最后用 Debug 精准定位如果前两步都没问题就在框架的ArgumentResolver断点上停一下看反序列化用的 JSON 字符串和 Java 类型是否匹配。最常见的问题藏在时间格式上LocalDateTime 默认序列化出来是一串数组客户端完全看不懂。关于时间的处理我的建议是全局配置统一格式。在application.yml里加上spring: jackson: date-format: yyyy-MM-dd HH:mm:ss time-zone: GMT8同时给依赖里补充jackson-datatype-jsr310模块这样才能保证 LocalDateTime 正常序列化为字符串而不是一串数字。4.3 Java 8 与 Jakarta 命名空间的历史包袱如果你把项目从 JDK 8 迁到 JDK 17同时从 Spring Boot 2.x 升到 3.x那就一定会遇到一个让无数人头疼的命名空间问题javax.servlet变成了jakarta.servlet。老项目里所有直接引用javax.servlet的代码、Filter、Listener在改包名之前都无法编译。MCP Starter 的设计因此采用了一个非常“古老但可靠”的策略直接依赖 Servlet API 的 provided 版本且编译目标为 Java 8。在 Spring Boot 2.x 环境下运行时容器提供的是javax.servlet命名空间的 Servlet API在 Spring Boot 3.x 环境下容器提供的是jakarta.servlet。框架为了兼容这两个命名空间内部用了反射隔离核心协议处理和业务无关只有重写HttpServlet的入口处做了双命名空间适配。这个方案谈不上优雅但胜在实打实解决了问题。至少在我们公司内部从一个 JDK 8 Spring Boot 2.7 的项目切到 JDK 17 Spring Boot 3.2 的项目MCP 相关代码一行都没改只是换了个容器版本。对老项目来说能做到这种程度的兼容已经算是对历史包袱的最大尊重了。4.4 常见问题速查表为了方便大家直接“抄作业”我把实践中遇到的高频问题整理成了一张速查表按症状给原因和处置建议症状根因处置建议客户端报HTTP 404上下文路径未拼进地址检查 context-path让客户端使用完整路径客户端报401 Unauthorized业务鉴权过滤器拦截把 MCP 路径加入白名单用框架鉴权替代握手成功但 tools 列表为空注解扫描路径未覆盖确认McpController所在包会被组件扫描调用后方法收到null参数字段命名风格不一致检查驼峰/下划线转换或手动McpParam(name)LocalDateTime 返给客户端变成数组缺少 jsr310 模块或格式配置加依赖并配置 date-format长等待后客户端超时SSE 被代理缓冲直连验证调整代理缓冲或传输方式JDK 8 下编译直接失败代码误用了 JDK 9 API开启框架的 Java 8 profile 持续集成这张表看着简单每一条背后都是一次真实的调试经历。特别是“tools 列表为空”那个听上去最基础其实坑最深因为框架默认只扫描项目主类所在包及其子包。如果你把McpController放在了一个独立子模块里主类所在包覆盖不到那框架就静默忽略了它没有任何报错。5. 再进一步拦截器、自动扫描与生产化建议5.1 统一日志与鉴权给 McpController 加“切面”MCP Tool 和普通接口在治理方向上没有本质区别都需要把鉴权、日志、限流这些横切关注点管理起来。和 Spring MVC 里 Filter/Interceptor 的职责一样框架也提供了McpInterceptor接口让你在工具调用链路里插入自定义逻辑。public class AuditMcpInterceptor implements McpInterceptor { Override public boolean preHandle(String toolName, MapString, Object arguments) { log.info(tool invoke start: {}, args: {}, toolName, arguments); return true; // 返回 false 时拒绝本次调用 } Override public void afterCompletion(String toolName, Object result, Exception error) { log.info(tool invoke end: {}, result: {}, toolName, result); } }实现这个接口后把它注册为一个 Spring Bean 即可自动生效。这个机制最实用的场景是审计。AI 模型的调用是不可预测的你很难预判它会在什么场景下调用哪个 Tool、传什么参数如果没有完整的日志链路出了问题完全无从追溯。加上拦截器后每次调用的工具名、参数、返回值、耗时全部落库后续做安全分析和成本分析都有了依据。5.2 自动扫描与 Starter 化让多个模块共享 MCP当 MCP 工具数量多了以后一个现实问题就会出现不同业务模块的工具需要分散在各个 jar 包里统一注册。框架的处理方式和 Spring MVC 处理多 Controller 的方式一样通过ComponentScan让主工程自动扫描所有依赖 jar 包下的McpController类。但这里有一个细节必须提醒你的业务 jar 包必须被主工程的组件扫描路径覆盖到。如果扫描不到最简单的做法是在主启动类上显式声明ComponentScan(basePackages { com.example, com.example.biz.order, com.example.biz.contact }) public class McpServerApplication { // ... }当工具规模上了两位数之后我强烈建议给 MCP 工具做一次领域划分用McpTool的group属性给能力分组。客户端在拉取工具列表的时候可以直接按组过滤避免把几十个工具一次性全塞给模型降低选错工具的概率。5.3 生产部署建议内存、线程与兼容性说明最后聊几句生产化的事情。MCP Server 本质上是承载在 Servlet 容器上的 HTTP 服务所以部署形态上可以直接复用现有的 Tomcat/Jetty/Undertow 体系不需要单独引入 Netty 或者 Vert.x 这类新运行时。这意味着老项目的运维规范和监控体系可以直接平迁不用学新东西。性能方面我自己实测的单机表现在默认 Tomcat 线程池配置下一个普通查询类 Tool 的 P99 耗时在 30 毫秒左右完全够用。真正可能成为瓶颈的不是框架本身而是你业务方法里依赖的外部系统。如果某个 Tool 内部是一个慢 SQL模型调用时就会直接暴露在网络等待上。建议把耗时超过 1 秒的重逻辑拆成独立 Tool并给客户端做好调用前提示让模型自行判断是否调用。内存方面最容易被忽略的是 SSE 长连接泄露。如果使用的是 Streamable HTTP 传输方式框架每次连接会占用一个线程资源。建议在网关层对连接做空闲超时回收并在应用层通过拦截器统计活跃连接数超过阈值直接拒绝新连接。兼容性上框架支持 Java 8 和 Java 17 两条线Spring Boot 2.x 和 3.x 都验证过。我自己实际部署的版本组合是一组 JDK 8 Spring Boot 2.7另一组 JDK 21 Spring Boot 3.3两边跑同一个 MCP 服务包没有做任何代码分支差异。它不敢说兼容了整个世界但至少帮团队把“老系统接 MCP”这件最大难事几乎削平成了普通开发任务。我个人在实际操作中的体会是MCP 对 Java 老项目真正友好的点并不是它提供了多强大的能力而是它能让你用最熟悉的姿势把能力暴露出去。你不需要为了“上 AI”而额外学一套框架和异步模型只需要像 Spring MVC 时代那样组织代码。等你的工具逐渐被模型用起来之后后半段的工作重心自然就转移到怎么把工具定义得更清晰、把 Schema 设计得更准确上了。最后分享一个我个人非常推荐的搭配如果团队的项目正在从 JDK 8 往 JDK 17 升级不要卡着不动可以先在 JDK 8 上用这套 MCP Starter 把 AI 能力打通等升级计划排期到了一位再把 MCP 服务整体迁过去。毕竟业务能力先跑起来微服务升级的自然动力才会更强这个顺序比“先升 JDK 再拥抱 AI”要顺得多。