开发 Java MCP 就像写 Controller 一样简单：TaoToken 统一 Key 接入与 Java 8 兼容配置骨架

发布时间：2026/9/27 19:19:04来源：尧图网络

1. 为什么 Java 后端需要把 MCP 写成 ControllerMCPModel Context Protocol说白了就是给大模型和你的业务系统之间定一套“普通话”。在这套协议出现之前每个模型厂商的 Tool Call 格式都不一样你给 A 模型写一套适配换 B 模型又得重写一遍维护成本高得离谱。MCP 把这件事标准化了你写一次 MCP ServerClaude Desktop、各类 IDE、你自己的 Solon 应用都能直接连上来用。对 Java 后端来说这件事的吸引力在于——你不需要去啃 JSON-RPC 的底层细节也不需要手撸原生 MCP Java SDK 里那些又长又难维护的样板代码。Solon-AI 把 MCP 服务端的开发抽象成了类似 Spring MVC Controller 的写法一个类加几个注解方法就是工具参数就是入参返回值就是模型能读到的结果。你原来怎么写RestController现在就怎么写McpServerEndpoint。这篇面向的是已经在跑 Spring 或 Solon 项目、想快速把现有业务能力暴露成 MCP 工具的后端开发者尤其是还锁在 Java 8 环境里的团队。我会给出config.toml和settings.json的可复制骨架、TaoToken 统一 Key 的接入位置以及启动后用命令验证 MCP 端点连通性的完整过程。Java 8 兼容这块我会单独说清楚依赖版本和编译参数的坑避免你升到一半发现Unsupported class file major version。2. TaoToken 统一 Key 与 API 通道的前置准备在写 MCP Server 之前先把模型侧的通道打通。TaoToken 在这里扮演的角色是统一 Key 和统一 API 入口你不需要在代码里散落各家厂商的 Key而是拿一个 Key 走同一个 API 地址后面换模型只改配置不改代码。先到控制台创建 API Key入口在 https://taotoken.net/api-keys 。创建完复制出来注意它只显示一次。然后确认你的 API 基地址是 https://taotoken.net/api 这个地址不带任何查询参数直接作为apiUrl的基础。如果你后面要跑长期编码或 Agent 场景可以看下 Coding Plan 的额度说明https://taotoken.net/coding-plan 。只是想先验证模型通不通用模型对话页面手动发一条也行https://taotoken.net/models 。这里有个容易踩的点TaoToken 的 API 地址是https://taotoken.net/api而 ChatModel 的apiUrl通常需要带上具体路径。Solon-AI 里一般写成https://taotoken.net/api/v1/chat/completions这种完整形式具体以你用的模型协议为准。别把官网首页地址填进去那样请求会打到 HTML 上返回一堆标签而不是 JSON。依赖方面Java 8 环境下用 Solon-AI 的 MCP 模块核心就一个dependency groupIdorg.noear/groupId artifactIdsolon-ai-mcp/artifactId version3.x.x/version /dependency版本号建议用当前稳定版Java 8 能跑。如果你的项目是 Spring BootSolon-AI 也能作为独立依赖引入不一定非要换成 Solon 容器MCP 端点可以单独挂载。3. 可复制配置骨架config.toml 与 settings.json先给config.toml的骨架。这个文件放在src/main/resources下Solon 启动时会自动读。里面把 MCP 服务端的基本信息和 TaoToken 的 Key 分开写Key 用环境变量占位避免提交到仓库。# config.toml solon.app.name java-mcp-demo solon.app.group demo # MCP 服务端配置 mcp.server.name it-tools mcp.server.channel STREAMABLE mcp.server.endpoint /mcp # TaoToken 统一通道 taotoken.api.url https://taotoken.net/api/v1/chat/completions taotoken.api.key ${TAOTOKEN_API_KEY} taotoken.model claude-sonnet注意taotoken.api.key用的是${TAOTOKEN_API_KEY}运行时从环境变量注入。你在本地调试时可以在 IDE 的运行配置里加这个环境变量别直接写死在文件里。再给settings.json的骨架。这个文件主要给支持 MCP 的客户端比如 Claude Desktop 或某些 IDE读取用来告诉它去哪里连你的 MCP Server。放在项目根目录或客户端指定的配置目录都行。{ mcpServers: { it-tools: { url: http://localhost:8080/mcp, transport: streamable, headers: { Authorization: Bearer ${TAOTOKEN_API_KEY} } } } }transport填streamable对应服务端的McpChannel.STREAMABLE。如果你用的是 STDIO 模式这里要改成stdio并补上command和args字段。headers里的 Authorization 是给需要鉴权的端点用的如果你的 MCP Server 不校验可以去掉。Java 8 编译参数这块补一句在pom.xml里确认maven.compiler.source和target都是1.8并且不要引入需要 Java 11 的传递依赖。Solon-AI 的 MCP 模块本身兼容 Java 8但如果你项目里混进了高版本库编译期就会报Unsupported class file major version 55之类的错。4. 像写 Controller 一样写 MCP Server现在写服务端。核心类长这样注解风格和 Spring MVC 几乎一致import org.noear.solon.ai.mcp.server.annotation.McpServerEndpoint; import org.noear.solon.ai.mcp.server.annotation.ToolMapping; import org.noear.solon.ai.mcp.McpChannel; import org.noear.solon.annotation.Param; import org.noear.solon.annotation.Header; McpServerEndpoint(name it-tools, channel McpChannel.STREAMABLE, mcpEndpoint /mcp) public class MyMcpServer { ToolMapping(description 查询服务器负载) public String getServerLoad(Param(serverId) String id, Header(token) String token) { // 这里可以接你的真实业务逻辑比如查监控系统 return Server id load is 15%; } }McpServerEndpoint声明这是一个 MCP 服务端点name是服务名channel选传输方式mcpEndpoint是暴露的路径。ToolMapping标记的方法会被模型识别为可调用的工具description是给模型看的说明写清楚点模型才知道什么时候调它。Param是工具入参Header可以拿请求头里的字段比如鉴权 token。启动类就是普通的 Solon 启动import org.noear.solon.Solon; public class App { public static void main(String[] args) { Solon.start(App.class, args); } }跑起来之后MCP 端点就在http://localhost:8080/mcp。如果你项目里已经有 Spring 容器也可以把MyMcpServer注册成 BeanSolon-AI 的 MCP 模块会扫描注解并挂载端点不需要额外写路由。动态构建工具的场景用 Builder 模式适合工具数量不固定、需要运行时编排的情况import org.noear.solon.ai.mcp.server.McpServerEndpointProvider; import org.noear.solon.ai.mcp.McpChannel; import org.noear.solon.ai.chat.tool.FunctionToolDesc; import org.noear.solon.ai.chat.tool.MethodToolProvider; McpServerEndpointProvider serverEndpoint McpServerEndpointProvider.builder() .name(mcp-weather) .channel(McpChannel.STDIO) .build(); FunctionToolDesc weatherTool new FunctionToolDesc(get_weather) .description(获取指定城市的天气情况) .stringParamAdd(location, 根据用户提到的地点推测城市) .doHandle(map - 24度); serverEndpoint.addTool(new MethodToolProvider(weatherTool));这段代码把get_weather这个工具动态注册进去doHandle里写实际逻辑。Builder 模式的好处是工具可以在启动后按配置加载不用改代码重新编译。5. 验证 MCP 端点连通性与成功返回服务启动后先确认端口在监听curl -i http://localhost:8080/mcp如果返回200或405取决于你的端点是否只接受 POST说明端点已经挂载。接着发一个真正的 MCP 初始化请求验证协议层通不通curl -X POST http://localhost:8080/mcp \ -H Content-Type: application/json \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -d { jsonrpc: 2.0, id: 1, method: initialize, params: { protocolVersion: 2024-11-05, capabilities: {}, clientInfo: {name: curl-test, version: 1.0} } }预期返回里会有result.serverInfo.name等于it-tools以及result.capabilities.tools字段。如果返回-32601 Method not found说明端点路径或 channel 配错了回去检查mcpEndpoint和channel是否和请求方式匹配。再验证工具列表能不能拉出来curl -X POST http://localhost:8080/mcp \ -H Content-Type: application/json \ -d {jsonrpc:2.0,id:2,method:tools/list,params:{}}成功的话result.tools数组里会有getServerLoaddescription就是你注解里写的那句。到这一步MCP Server 本身已经通了。最后验证模型侧能不能通过 TaoToken 调到这个工具。用 Solon-AI 的客户端连一下import org.noear.solon.ai.mcp.client.McpClientProvider; import org.noear.solon.ai.mcp.McpChannel; McpClientProvider clientProvider McpClientProvider.builder() .channel(McpChannel.STREAMABLE) .url(http://localhost:8080/mcp) .build(); clientProvider.getTools();getTools()返回非空说明客户端能从服务端拉到工具原语。如果这里卡住或超时多半是url写成了https但服务端没配证书或者防火墙拦了本地回环。6. 本篇常见错排查报错一Unsupported class file major version 55这是 Java 版本不匹配。你的编译目标是 Java 8但某个依赖是用 Java 11 编译的。用mvn dependency:tree找到那个依赖降版本或排除掉。Solon-AI 的 MCP 模块本身没问题通常是传递依赖带进来的。报错二Connection refused或404on/mcp先确认mcpEndpoint的值和请求路径完全一致大小写敏感。再确认channel和请求方式匹配STREAMABLE走 HTTP POSTSTDIO是进程间通信不能用 curl 直接打。如果你在 Spring Boot 里挂载检查 Solon 的 MCP 扫描是否被 Spring 的包扫描覆盖了。报错三TaoToken 返回401或invalid api key检查环境变量TAOTOKEN_API_KEY是否真的注入到了运行进程里。在 IDE 里跑和用java -jar跑环境变量的来源不一样。另外确认apiUrl是https://taotoken.net/api/v1/chat/completions这种完整路径不是只写到/api。报错四工具列表为空ToolMapping的方法必须是public返回类型不能是void参数上要有Param或Header注解。如果方法在内部类里确保内部类是static的否则 Solon 扫描不到。报错五Java 8 下 Lambda 编译报错FunctionToolDesc的doHandle接收的是函数式接口Java 8 支持 Lambda但如果你项目里用了--release 8且依赖里有 Java 9 的 API会编译失败。检查pom.xml里有没有误加--release参数改成source/target1.8 即可。排障过程中如果卡在 Key 或接入配置上直接去 API Keys 页面重新生成一个对比测试https://taotoken.net/api-keys 。接入文档在 https://taotoken.net/doc 里面有各语言的最小请求示例对着改apiUrl和 header 格式最快。验证模型本身通不通用模型对话页面发一条消息就行https://taotoken.net/models 。长期跑编码 Agent 的话Coding Plan 的额度比按量更划算https://taotoken.net/coding-plan 。

网站建设高端定制企业官网