1. 为什么 Java 开发者需要一个国产 MCP Server 方案MCPModel Context Protocol这两年在 AI 工具链里出现得越来越频繁它本质上是一套让大模型调用外部能力的协议模型负责理解意图MCP Server 负责把「查天气」「读文件」「调接口」这类动作真正执行掉。问题在于目前网上能搜到的 MCP Server 示例绝大多数是 Python 或 Node.js 写的Java 开发者想跟一手往往要先装一堆运行时环境或者干脆被劝退。Solon AI MCP 就是冲着这个痛点来的。Solon 本身是国产 Java 框架里比较活跃的一个主打轻量、启动快、依赖少而solon-ai-mcp是它新增的 AI 能力模块同时支持 Mcp Server 和 Mcp Client并且明确覆盖 Java 8 到 Java 24。这意味着你手上不管是老项目还是新项目都不用为了跑一个 MCP Server 去升级 JDK。这篇文章要做的就是带你从零搭一个最小的 Helloworld 工程写一个能被大模型调用的工具方法本地启动服务再用客户端验证一次调用是否成功。同时我会把 TaoToken 的统一 Key 配置一起接进来这样你后面接真实模型时不用再到处改配置。适合谁看有 Java 基础、想快速跑通第一个 MCP Server、又不想被环境问题卡住的开发者。2. TaoToken 前置准备统一 Key 与 API 通道在写代码之前先把「模型通道」这件事解决掉。MCP Server 本身只负责暴露工具真正决定模型怎么调用、走哪个通道的是你在客户端或 Agent 侧配置的 API 地址和 Key。TaoToken 在这里的作用就是提供一个统一的 Key 和 API 入口让你在 Solon 工程里配置一次后面切换模型或工具时不用反复改代码。你需要准备两样东西一个可用的 API Key以及 API 的基础地址。地址是https://taotoken.net/api注意这个地址不带任何查询参数直接作为 base url 使用。Key 的获取在控制台里完成登录后进入 API Keys 页面创建一个即可。拿到 Key 之后建议先把它放进环境变量而不是硬编码在代码里。比如在 macOS 或 Linux 下可以这样写export TAOTOKEN_API_KEY你的KeyWindows 下用 PowerShell$env:TAOTOKEN_API_KEY你的Key这样做的原因是后面无论你是用 Solon 的配置文件读取还是在测试类里注入都能保持一份来源避免 Key 散落在多个文件里。如果你还没创建 Key可以直接去控制台页面操作创建后复制保存页面关闭后一般不会再完整显示。注意Key 属于敏感信息不要提交到 Git 仓库。建议在.gitignore里把本地配置文件排除掉。3. 可复制配置pom.xml 依赖与 MCP Server 启动骨架3.1 pom.xml 依赖片段先建一个标准的 Maven 工程然后在pom.xml里加入 Solon 和 solon-ai-mcp 的依赖。版本号跟随 Solon 主版本当前用 3.2.0dependencies dependency groupIdorg.noear/groupId artifactIdsolon-ai-mcp/artifactId version3.2.0/version /dependency dependency groupIdorg.noear/groupId artifactIdsolon-web/artifactId version3.2.0/version /dependency dependency groupIdorg.projectlombok/groupId artifactIdlombok/artifactId version1.18.30/version scopeprovided/scope /dependency /dependencies这里solon-web是为了让服务能起一个 HTTP 端口MCP 的 SSE 端点需要它。Lombok 是可选的如果你不想用注解处理器把Slf4j换成手动声明 Logger 也行。Java 版本方面solon-ai-mcp支持 Java 8 到 Java 24。如果你用的是 Java 8编译插件里把 source 和 target 设成 1.8如果是 Java 17 或 21正常设置即可。下面是一个兼容 Java 8 的编译配置示例build plugins plugin groupIdorg.apache.maven.plugins/groupId artifactIdmaven-compiler-plugin/artifactId version3.11.0/version configuration source1.8/source target1.8/target encodingUTF-8/encoding /configuration /plugin /plugins /build如果你用的是 Java 17 以上把 source/target 改成 17 或 21 即可其他依赖不用动。3.2 启动类骨架Solon 的启动类非常简洁一个 main 方法加Solon.start就够了import org.noear.solon.Solon; public class App { public static void main(String[] args) { Solon.start(App.class, args); } }启动时 Solon 会自动扫描注解把McpServerEndpoint标记的类注册成 MCP 端点。你不需要额外写配置文件除非要改端口。默认端口是 8080如果想改可以在resources/app.yml里写server: port: 80803.3 工具类用注解写一个 hello 工具接下来是核心部分写一个能被大模型调用的工具。Solon AI MCP 的设计思路和 MVC 很像用McpServerEndpoint声明端点用ToolMapping声明工具方法用ToolParam描述参数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; } }这里有几个点值得展开。sseEndpoint /sse表示这个端点通过 SSE 协议暴露客户端连接http://localhost:8080/sse就能发现工具。ToolMapping的description属性非常关键它不是给你看的注释而是给大模型看的提示词。模型会根据这段描述判断「这个工具是干什么的、什么时候该调用它」。所以描述要写清楚别只写「测试」两个字。ToolParam同理参数的 description 会告诉模型这个参数填什么。比如你写「名字」模型就知道传一个人名进来。如果参数是数字或枚举描述里最好带上取值范围。3.4 TaoToken 统一 Key 的 settings.json 配置MCP 的客户端配置通常放在一个settings.json里不同工具比如 Claude Code、Cursor 等路径略有差异但结构类似。下面是一个把 TaoToken 作为模型通道的配置示例{ mcpServers: { solon-hello: { url: http://localhost:8080/sse } }, model: { apiBase: https://taotoken.net/api, apiKey: ${TAOTOKEN_API_KEY} } }这里mcpServers部分声明了本地启动的 Solon MCP Server 地址model部分则把模型请求指向 TaoToken 的 API 通道。${TAOTOKEN_API_KEY}是环境变量引用写法具体是否支持取决于你用的客户端如果不支持就手动替换成实际 Key但记得别提交到仓库。这样配置的好处是MCP Server 和模型通道解耦了。你换模型、换 Key只改model这一段你加新工具只改mcpServers和 Java 代码。两边互不影响。4. 验证请求本地启动与接口连通性测试4.1 启动服务在 IDE 里直接运行App.main或者在项目根目录执行mvn compile exec:java -Dexec.mainClassApp启动成功后控制台会打印 Solon 的 banner 和端口信息类似Solon 3.2.0 server started, port: 8080如果看到端口被占用改一下app.yml里的 port 再启动。4.2 用 curl 验证 SSE 端点服务起来后先确认 SSE 端点能连上。用 curl 发一个请求curl -N http://localhost:8080/sse-N表示不缓冲你会看到服务端持续推送事件。正常情况下会先收到一个 endpoint 事件里面包含后续消息的地址。这说明 MCP Server 已经在监听并且工具注册成功了。4.3 用客户端单测调用工具更贴近真实场景的验证方式是写一个单测用 McpClientToolProvider 直接调用工具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 java.util.Map; SolonTest(App.class) public class HelloTest extends HttpTester { Test public void hello() throws Exception { McpClientToolProvider provider McpClientToolProvider.builder() .apiUrl(http://localhost:8080/sse) .build(); String result provider.callToolAsText(hello, Map.of(name, solon)); System.out.println(result); } }运行这个测试如果控制台输出hello solon说明整条链路是通的客户端连上 SSE 端点发现 hello 工具传入参数服务端执行并返回结果。注意Map.of是 Java 9 以上才有的 API。如果你用 Java 8换成new HashMapString, Object()然后 put 进去或者用 Solon 自带的Maps.of工具类。4.4 成功结果说明当你看到hello solon这行输出时意味着三件事同时成立Solon 服务正常启动、MCP 端点注册成功、工具调用参数传递正确。这是最小可运行闭环。接下来你可以在这个基础上加更多工具比如查数据库、调外部 API、读文件只要用ToolMapping标注方法即可。5. 本篇常见错排查5.1 启动报 ClassNotFoundException: org.noear.solon.ai.mcp这个错误通常是依赖没拉下来或者版本号写错了。先确认pom.xml里solon-ai-mcp的版本是 3.2.0然后执行mvn clean compile -U-U强制更新快照。如果还是不行检查一下本地 Maven 仓库里有没有对应的 jar 包路径一般在~/.m2/repository/org/noear/solon-ai-mcp/。5.2 SSE 端点连不上curl 一直挂起先确认服务真的起来了看控制台有没有端口打印。如果端口是 8080 但被别的程序占了Solon 启动时会报错。改端口后重试。另外curl -N本身是长连接不会自动退出看到事件推送就说明正常按 CtrlC 结束即可。5.3 工具调用返回 null 或找不到工具最常见的原因是McpServerEndpoint的类没有被扫描到。Solon 默认扫描启动类所在包及其子包如果你的HelloService放在别的包路径下需要在启动类上加ComponentScan或者把包结构调整到启动类下面。另一个原因是ToolMapping的 description 写得太模糊模型在真实调用时可能不选这个工具但单测里直接指定工具名是不受影响的。5.4 Java 8 下 Map.of 编译不过前面提过Map.of是 Java 9 的 API。Java 8 项目里换成MapString, Object params new HashMap(); params.put(name, solon); String result provider.callToolAsText(hello, params);或者直接用 Solon 的Maps.of(name, solon)这个工具类在 Java 8 下可用。5.5 TaoToken Key 配置后请求 401先检查环境变量有没有生效可以在终端里echo $TAOTOKEN_API_KEY确认。如果客户端不支持环境变量引用就手动填 Key。另外确认 API 地址是https://taotoken.net/api不要多加路径或参数。如果还是 401去控制台确认 Key 是否被禁用或过期。6. 下一步把 Helloworld 扩展成真实工具跑通 Helloworld 之后你手上其实已经有了一个可用的 MCP Server 骨架。接下来要做的是把hello换成真正有用的工具。比如你想让模型能查订单状态就写一个ToolMapping(description 根据订单号查询订单状态)的方法参数是订单号内部调你的订单服务。模型会在对话中自动判断什么时候调用它。如果你打算长期做编码类或 Agent 类项目建议把模型通道固定成 TaoToken 的统一 Key这样在多个 MCP Server 之间切换时不用重复配置。需要创建或管理 Key 的话去控制台页面操作想先体验模型对话效果可以用模型对话页面如果是长期编码场景Coding Plan 会更合适。接入过程中遇到问题接入文档里有更细的说明。最后留一个实用建议每次加新工具后先用单测直接调一次确认参数和返回值都对再去接模型。因为模型调用有不确定性直接上模型排查会慢很多。单测跑通再让模型试效率会高不少。