1. 为什么 Java 开发者需要一个国产 MCP Server 方案MCPModel Context Protocol这两年在 AI 圈子里热度一直不低它的核心价值是把大模型和外部工具、数据源用一套标准协议连起来。你写一个工具方法模型就能在对话里按需调用它不用为每个模型单独适配一遍。但如果你去搜 MCP Server 的入门教程会发现一个很尴尬的现实绝大多数示例都是 Python 或者 Node.js 写的。Java 开发者想跟做要么找不到对应依赖要么找到的 SDK 文档稀薄、版本对不上跑一半就卡在环境上。我自己是常年写 Java 的第一次接触 MCP 的时候翻了半天资料能直接复制粘贴跑通的 Java 示例少得可怜。更麻烦的是版本兼容问题——很多新框架默认要求 Java 17 甚至 Java 21而不少公司生产环境还停在 Java 8。你总不能为了跑一个 MCP 工具就把整个项目的 JDK 升上去。Solon AI MCP 就是在这个背景下值得关注的一个国产解决方案。Solon 本身是国内开发者很熟悉的 Java 框架轻量、启动快、对低版本 JDK 友好。它新增的 solon-ai-mcp 模块同时支持 Mcp Server 和 Mcp Client官方明确支持 Java 8 到 Java 24版本号跟随 Solon 主线走当前是 3.2.0。这意味着你手头不管是老项目还是新项目基本都能直接引入。这篇文章要解决的就是一件事让你从零跑通第一个 Solon AI MCP Server 的 Helloworld。我会给出完整的 Maven 依赖、可复制的端点配置、工具方法写法以及一个用 McpClientToolProvider 写的单元测试来验证工具真的被调用了。整个过程不需要你懂 MCP 协议的底层细节照着写就行。适合谁适合有 Java 基础、想快速把 MCP 能力接进自己项目的开发者尤其是那些被 Python 示例劝退、或者被 JDK 版本卡住的人。2. Solon AI MCP 前置准备与依赖引入踩坑记录在动手写代码之前先把环境理清楚。Solon AI MCP 的前置条件其实很宽松这也是它相比其他方案的一个明显优势。JDK 方面官方声明支持 Java 8 到 Java 24。我实测下来Java 8、Java 11、Java 17 都能正常编译运行没有出现因为语言特性导致的编译失败。构建工具用 Maven 就行Gradle 也可以但本文以 Maven 为主因为大部分 Java 项目还是 Maven 居多。Solon 的版本管理比较集中solon-ai-mcp 的版本号跟 Solon 主版本保持一致当前是 3.2.0你不需要单独去记一个独立的版本号。引入依赖这一步看起来简单但有几个坑我踩过提前说清楚能帮你省时间。第一个坑是依赖坐标写错。solon-ai-mcp 的 groupId 是 org.noearartifactId 是 solon-ai-mcp不是 solon-ai 也不是 solon-mcp。网上有些文章写的是旧版本或者笔误复制过去会直接报找不到依赖。第二个坑是只引了 solon-ai-mcp 却没引 Solon 的核心依赖。solon-ai-mcp 是建立在 Solon 运行时之上的你需要确保项目里有 solon 的核心包。如果你是用 Solon 官方脚手架生成的项目核心依赖已经在了如果是往一个普通 Maven 项目里加记得补上。第三个坑是版本冲突。如果你的项目里已经有其他 AI 相关的 SDK注意检查有没有传递依赖把 Solon 的版本拉低或者拉高。我遇到过一次因为另一个库引入了不同版本的 noear 包导致启动时报类找不到最后用 dependencyManagement 锁死版本才解决。下面是完整的 Maven 依赖片段你可以直接复制到 pom.xml 的 dependencies 里dependency groupIdorg.noear/groupId artifactIdsolon-ai-mcp/artifactId version3.2.0/version /dependency如果你是从零建项目建议再补上 Solon 的基础依赖和测试依赖方便后面写单元测试dependency groupIdorg.noear/groupId artifactIdsolon-web/artifactId version3.2.0/version /dependency dependency groupIdorg.noear/groupId artifactIdsolon-test/artifactId version3.2.0/version scopetest/scope /dependency这里有个细节值得说solon-ai-mcp 支持多端点架构你可以手动构建端点也可以用注解构建。注解方式对 Java 开发者来说最友好因为它跟写 Spring MVC 的 Controller 几乎一模一样学习成本极低。这也是我推荐新手从这个方案入手的原因——你不需要理解 MCP 的 JSON-RPC 消息格式注解会帮你处理掉。另外提醒一句Solon 的启动类写法跟 Spring Boot 不同它用的是 Solon.start 而不是 SpringApplication.run。如果你之前没接触过 Solon这一点要适应一下但也就一行代码的事。3. 可复制的 MCP Server 端点与工具配置片段这一节是核心我会把完整的代码结构拆开讲每一段都可以直接复制。Solon AI MCP 的注解体系设计得很像 MVC你只要理解三个注解就能写出第一个工具。先看整体结构。一个最小的 MCP Server 需要两部分一个启动类一个带 McpServerEndpoint 注解的服务类。启动类负责把 Solon 跑起来服务类负责暴露工具。启动类长这样import org.noear.solon.Solon; public class App { public static void main(String[] args) { Solon.start(App.class, args); } }就这么简单。Solon.start 会自动扫描注解把 McpServerEndpoint 标记的类注册成 MCP 端点。你不需要额外写配置文件也不需要手动注册路由。接下来是工具服务类这是重点import org.noear.solon.ai.mcp.server.annotation.McpServerEndpoint; import org.noear.solon.ai.mcp.server.annotation.ToolMapping; import org.noear.solon.ai.mcp.server.annotation.ToolParam; McpServerEndpoint(sseEndpoint /sse) public class HelloService { ToolMapping(description 你好世界) public String hello(ToolParam(description 名字) String name) { return hello name; } }逐行解释一下。McpServerEndpoint(sseEndpoint /sse) 表示这个类是一个 MCP 服务端点对外暴露的 SSE 地址是 /sse。SSE 是 MCP 常用的传输方式之一客户端通过这个地址建立连接。你可以把它理解成 Web 里的 RestController 加 RequestMapping 的组合。ToolMapping 标记这个方法是一个可被模型调用的工具。description 属性非常关键它不是给你看的注释而是给大模型看的提示词。模型会根据这段描述判断什么时候该调用这个工具。所以描述要写清楚工具的功能别写得太模糊。比如你写“处理数据”模型根本不知道处理什么数据写“根据名字返回问候语”模型就能准确判断。ToolParam 标记方法参数description 同样会传给模型告诉它这个参数是什么含义。模型在调用时会根据参数描述来填充值。方法体就是普通的 Java 代码你可以在里面做任何事——查数据库、调外部接口、做计算都行。返回值会被序列化后返回给客户端。这里有个容易忽略的点ToolMapping 的方法返回值类型。简单类型比如 String、int 可以直接返回复杂对象 Solon 会帮你转成 JSON。我建议第一个 Helloworld 就用 String跑通之后再试复杂类型。如果你需要多个工具就在同一个类里写多个 ToolMapping 方法或者建多个 McpServerEndpoint 类。Solon 支持多端点每个端点可以有自己独立的 sseEndpoint 路径。配置层面Solon 默认端口是 8080。如果你想改端口可以在 resources 下建一个 app.ymlserver: port: 8080这个文件不是必须的但建议加上方便你后面调整。Solon 的配置文件格式支持 yml 和 properties跟 Spring Boot 类似迁移过来没什么障碍。把这三段代码放好目录结构大概是src/main/java/App.java src/main/java/HelloService.java src/main/resources/app.yml启动 main 方法控制台会打印 Solon 的启动信息和端点注册信息。看到类似“McpServerEndpoint registered: /sse”的日志就说明端点注册成功了。4. 验证 Helloworld 工具调用用 McpClientToolProvider 写单测服务跑起来了但你怎么确认工具真的能被调用光看启动日志不够得实际发一次请求。Solon AI MCP 提供了 McpClientToolProvider可以很方便地在单元测试里模拟客户端调用。先看测试类的完整代码import lombok.extern.slf4j.Slf4j; import org.junit.jupiter.api.Test; import org.noear.solon.ai.mcp.client.McpClientToolProvider; import org.noear.solon.test.SolonTest; import org.noear.solon.test.HttpTester; import org.noear.solon.core.util.Maps; import java.io.IOException; Slf4j SolonTest(App.class) public class HelloTest extends HttpTester { Test public void hello() throws IOException { McpClientToolProvider clientToolProvider McpClientToolProvider.builder() .apiUrl(http://localhost:8080/sse) .build(); String rst clientToolProvider.callToolAsText(hello, Maps.of(name, solon)); log.warn(rst); } }拆解一下这段测试。SolonTest(App.class) 是 Solon 的测试注解它会启动一个测试用的 Solon 容器加载 App 类里的所有配置和端点。这样你不需要手动先启动 main 方法测试框架会帮你把服务拉起来。McpClientToolProvider.builder() 构建一个客户端工具提供者apiUrl 指向服务端的 SSE 地址。注意这里的地址要跟 McpServerEndpoint 里配的 sseEndpoint 对应上端口也要一致。callToolAsText 是调用工具的方法第一个参数是工具名也就是 ToolMapping 标记的方法名 hello第二个参数是参数 Mapkey 是 ToolParam 的 namevalue 是你要传的值。这里传了 solon。运行这个测试如果一切正常控制台会打印出hello solon看到这行输出就说明整条链路通了客户端通过 SSE 连上服务端服务端找到 hello 工具传入 name 参数执行方法返回结果客户端拿到文本。我实测的时候第一次跑报了个连接超时的错排查后发现是测试启动的端口跟我本地已经跑着的服务冲突了。解决办法是在测试配置里指定一个不同的端口或者先把本地服务停掉。这个坑后面排障章节会详细说。如果你想验证更复杂的场景比如传多个参数、返回 JSON 对象可以把 hello 方法改成接收两个参数返回一个 Map。callToolAsText 会返回 JSON 字符串你用 JSON 库解析一下就能验证字段对不对。还有一点值得提McpClientToolProvider 不仅能调工具还能列出服务端注册了哪些工具。你可以在测试里加一行 clientToolProvider.listTools() 看看返回的工具列表确认 hello 工具确实被注册了。这个在调试阶段很有用。到这里一个完整的 Helloworld 就闭环了。从依赖引入、端点配置、工具编写到客户端验证每一步都有可复制的代码。接下来把常见的报错整理一下帮你少走弯路。5. 本篇常见报错排查401、连接失败与工具找不到跑第一个 MCP Server 的时候报错基本集中在几个地方。我把遇到过的和社区里反馈比较多的问题整理成对照表你对着排查会快很多。报错一启动时报 ClassNotFoundException: org.noear.solon.ai.mcp.xxx这个通常是依赖没引全或者版本不对。先检查 pom.xml 里 solon-ai-mcp 的版本是不是 3.2.0再确认有没有其他依赖把 noear 的包版本覆盖了。用 mvn dependency:tree 看一下依赖树找到冲突的包用 exclusions 排除掉或者在 dependencyManagement 里锁死版本。报错二客户端连接 http://localhost:8080/sse 返回 404说明端点没注册上。检查三件事McpServerEndpoint 注解有没有加在类上sseEndpoint 的值是不是 /sse启动类有没有用 Solon.start 并且传了正确的 App.class。如果注解加了但没生效可能是包扫描路径不对Solon 默认扫描启动类所在包及其子包你的服务类要放在这个范围内。报错三callToolAsText 返回 null 或者抛异常说工具不存在工具名写错了。callToolAsText 的第一个参数必须跟 ToolMapping 方法的名称完全一致大小写敏感。另外确认方法是不是 public 的private 方法不会被注册。报错四连接超时或者 Connection refused服务没起来或者端口不对。先确认 main 方法跑起来了控制台有没有 Solon 启动成功的日志。如果端口被占用改 app.yml 里的 server.port同时记得把测试里的 apiUrl 也改掉。我踩过一次坑是本地已经有一个服务占着 8080测试启动时静默失败了日志里只有一行不起眼的警告找了半天才发现。报错五OAuth 相关的认证错误如果你接的是需要认证的 MCP 服务端可能会遇到 OAuth 报错。Solon AI MCP 的客户端支持配置认证信息在 builder 后面加 .header(Authorization, Bearer xxx) 就行。但 Helloworld 阶段一般用不到本地服务不需要认证。如果你确实遇到了检查一下是不是误连了外部服务。报错六reading choices 解析失败这个报错通常出现在客户端解析服务端返回时。MCP 协议对返回格式有要求如果你的工具方法返回了一个无法序列化的对象客户端解析就会失败。解决办法是确保返回值是基本类型或者标准的 POJO别返回 InputStream 这类无法直接序列化的东西。报错七local proxy failed这个多半是网络层面的问题比如本地代理设置干扰了 localhost 的连接。检查一下系统代理配置把 localhost 和 127.0.0.1 加到代理排除列表里。这个报错在 Windows 上比较常见。排查的时候有个通用思路先看服务端日志确认端点注册和请求接收再看客户端日志确认连接建立和请求发送最后看返回值确认数据格式。三段日志对着看问题基本定位得到。6. 从 Helloworld 到实际项目下一步怎么走Helloworld 跑通之后你手里已经有一个能工作的 MCP Server 了。接下来可以往几个方向扩展。第一个方向是加更多工具。在 HelloService 里继续写 ToolMapping 方法每个方法是一个独立工具。比如加一个查天气的工具、一个算数学表达式的工具。注意每个工具的 description 要写清楚这是模型能否正确调用的关键。第二个方向是接真实数据源。工具方法里可以注入 Solon 的 Bean连数据库、调 Redis、请求外部 API 都行。Solon 的依赖注入跟 Spring 类似用 Inject 或者构造函数注入都可以。这样你的 MCP Server 就不只是玩具而是能真正干活的组件。第三个方向是接入大模型做联调。MCP Server 本身只是提供工具真正调用它的是大模型客户端。你可以用支持 MCP 的客户端连上你的 /sse 端点然后在对话里让模型调用你的工具。这一步能验证工具描述写得够不够清楚——如果模型总是调错工具或者不调用说明 description 需要优化。如果你打算长期做 AI 相关的编码和 Agent 开发可以考虑用 Coding Plan 这类方案来管理你的开发环境和模型调用额度省去自己折腾配置的时间。验证模型调用效果的时候模型对话页面可以直接测试工具是否被正确触发。接入过程中遇到配置问题API Keys 页面和接入文档里有详细的参数说明。回到技术本身Solon AI MCP 这个方案最大的价值在于它降低了 Java 开发者进入 MCP 生态的门槛。你不需要学 Python不需要升 JDK用熟悉的注解和 Maven 就能写出符合 MCP 协议的服务。对于国内团队来说国产框架在文档、社区响应和版本节奏上也有天然优势。最后一个实用建议把 Helloworld 的代码提交到 Git作为你后续项目的模板。每次新建 MCP Server 的时候直接复制改改工具方法就行。我自己的模板里还加了日志切面和异常处理工具调用出问题的时候能快速定位。这些都是在实际项目里一点点攒出来的比任何教程都管用。