Java SolonMCP 实现 MCP 实践全解析：SSE 与 STDIO 通信模式详解｜TaoToken 统一 Key 接入

1. 本地工具链与远端模型混用时Java SolonMCP 的通道到底怎么选如果你正在用 Java 写 MCP 服务大概率会遇到一个很实际的问题工具跑在本地模型服务在远端中间这条通道到底走 SSE 还是 STDIO这不是一个纯理论问题它直接决定了你的进程模型、调试方式、部署形态甚至鉴权放在哪一层。MCP 全称 Model Context Protocol你可以把它理解成一套“模型调用外部工具”的专属 RPC 协议。它规定了模型怎么发现工具、怎么传参、怎么拿回结果。SolonMCP 则是基于 Java 的 MCP 服务端框架用注解就能把普通方法暴露成工具、资源、提示模板省掉了手写协议报文的麻烦。它适合谁适合已经有 Java 技术栈、想把内部系统能力查库、调接口、算数据接给大模型用的后端开发者。SSE 模式适合服务常驻、多客户端连接、需要 HTTP 鉴权的场景STDIO 模式适合本地命令行工具、IDE 插件、一次性进程调用的场景。两者不是替代关系而是两条并行的通道。我试过把同一个计算器工具分别用两种通道跑起来SSE 那边要处理端口和连接生命周期STDIO 那边则完全靠标准输入输出进程一退服务就没了。理解这个差异后面配置才不会拧巴。这篇会给出 SolonMCP 的工程依赖、SSE 与 STDIO 两套可复制配置用 curl 和日志分别验证连接建立与消息往返最后说明怎么把 endpoint 和鉴权统一到 TaoToken让本地工具链和远端模型服务用同一套 Key 管理。2. TaoToken 前置准备统一 Key 与 endpoint 的接入姿势在写 SolonMCP 代码之前先把“模型侧”的接入信息准备好否则你工具写完了却不知道往哪连。TaoToken 在这里扮演的是统一入口的角色你不需要为每个模型厂商单独维护一套 Key 和 Base URL而是用同一个 Key、同一个 endpoint 去访问不同模型。官网地址是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 基址是 https://taotoken.net/api 。注意 API 地址不带 UTM 参数配置里填干净的 https://taotoken.net/api 就行。你需要准备三样东西我把它叫做“三件套”配置项取值示例说明Base URLhttps://taotoken.net/api所有请求的统一入口API Keysk-xxxxxxxx在控制台创建注意保密Model IDclaude-sonnet-4-5 等按你实际要调的模型填创建 Key 的入口在控制台的 API Keys 页面路径是 https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite 。进去之后新建一个 Key复制出来存到环境变量里别硬编码进代码。注意Key 一旦泄露要立刻在控制台吊销重建。本地调试可以用环境变量TAOTOKEN_API_KEYCI 里用密钥管理不要提交到 Git。如果你只是想先验证模型能不能通可以直接用模型对话页面 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite 发一条消息确认 Key 有效、额度正常再去写 SolonMCP 的代码。这一步能帮你排除掉一半“连不上”的误判。对于长期做编码和 Agent 的场景可以考虑 Coding Plan入口在 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite 它更适合高频调用、需要稳定配额的情况。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite 遇到参数细节可以对照查。把这三件套准备好后面 SolonMCP 无论走 SSE 还是 STDIO模型侧的 endpoint 和鉴权都是同一套切换通道时不用改模型配置。3. 可复制配置SolonMCP 工程依赖与 SSE/STDIO 两套写法这一节是全文的核心给出能直接抄的依赖和配置。先说工程依赖Maven 和 Gradle 两种都列出来。Maven 依赖dependency groupIdorg.noear/groupId artifactIdsolon-ai-mcp/artifactId version3.3.1-M1/version /dependencyGradle 依赖implementation org.noear:solon-ai-mcp:3.3.1-M1版本号以你实际拉到的为准3.3.1-M1 是写这篇时的可用版本。拉不下来就检查仓库配置Solon 系列一般在 Maven Central 能拿到。3.1 STDIO 模式配置STDIO 模式的核心是McpServerEndpoint(channel McpChannel.STDIO)服务通过标准输入读请求、标准输出写响应。下面是一个计算器工具类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.Param; import org.noear.solon.ai.mcp.server.constant.McpChannel; McpServerEndpoint(channel McpChannel.STDIO) public class CalculatorTools { ToolMapping(description 将两个数字相加) public int add(Param int a, Param int b) { return a b; } ToolMapping(description 从第一个数中减去第二个数) public int subtract(Param int a, Param int b) { return a - b; } ToolMapping(description 将两个数相乘) public int multiply(Param int a, Param int b) { return a * b; } ToolMapping(description 将第一个数除以第二个数) public float divide(Param float a, Param float b) { return a / b; } }打包成可执行胖包后运行方式是java -jar demo.jar进程启动后会阻塞等待标准输入。任何支持 STDIO 的 MCP 客户端都可以通过管道把请求喂进来响应从标准输出返回。这种模式没有端口、没有 HTTP天然适合本地进程间通信。3.2 SSE 模式配置SSE 模式用sseEndpoint指定路径服务以 HTTP 常驻方式运行。下面是一个天气服务示例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.ResourceMapping; import org.noear.solon.ai.mcp.server.annotation.Param; import org.noear.solon.annotation.Produces; import org.noear.solon.core.mvc.MimeType; import java.util.Arrays; import java.util.List; McpServerEndpoint(sseEndpoint /mcp/sse) public class WeatherTools { ToolMapping(description 获取指定城市的当前天气) public String get_weather(Param String city) { return {city: city , temperature:[10,25], condition:[sunny, clear, hot], unit:celsius}; } Produces(MimeType.APPLICATION_JSON_VALUE) ResourceMapping(uri weather://cities, description 获取所有可用的城市列表) public ListString get_available_cities() { return Arrays.asList(Tokyo, Sydney, Tokyo); } ResourceMapping(uri weather://forecast/{city}, description 获取指定城市的天气预报资源) public String get_forecast(Param String city) { return {city: city , temperature:[10,25], condition:[sunny, clear, hot], unit:celsius}; } }运行同样是java -jar demo.jar服务默认监听 8080 端口SSE 端点是http://localhost:8080/mcp/sse。注意Produces那行是给前端用的返回严格 JSON 格式别漏。3.3 把模型 endpoint 统一到 TaoToken无论哪种通道模型侧的配置都用同一套。如果你用配置文件管理可以写成这样{ model: { baseUrl: https://taotoken.net/api, apiKey: ${TAOTOKEN_API_KEY}, modelId: claude-sonnet-4-5 }, mcp: { channel: SSE, sseEndpoint: /mcp/sse, port: 8080 } }apiKey用环境变量占位别写死。channel字段切换 SSE 和 STDIO模型配置不用动。这样本地工具链和远端模型服务就通过 TaoToken 的统一 Key 串起来了。4. 验证请求用 curl 与日志确认连接建立和消息往返配置写完不算完得验证连接真的建立、消息真的往返。SSE 和 STDIO 的验证方式完全不同分开说。4.1 SSE 模式验证先启动服务观察日志里有没有端口监听成功的输出。然后开一个终端用 curl 建立 SSE 连接curl -N -H Accept: text/event-stream http://localhost:8080/mcp/sse-N关闭缓冲让你能实时看到事件流。连接成功后你会看到类似event: endpoint和data: /mcp/message?sessionIdxxx的输出这说明 SSE 通道已经建立服务端分配了会话 ID。拿到 sessionId 后另开一个终端发工具调用请求curl -X POST http://localhost:8080/mcp/message?sessionId你的sessionId \ -H Content-Type: application/json \ -d { jsonrpc: 2.0, id: 1, method: tools/call, params: { name: get_weather, arguments: {city: 杭州} } }如果返回里带result字段和天气数据说明消息往返正常。如果返回error看错误码和 message常见的是方法名拼错或参数类型不匹配。也可以用 Java 客户端验证代码更直观McpClientProvider clientProvider McpClientProvider.builder() .apiUrl(http://localhost:8080/mcp/sse) .build(); String rst1 clientProvider.callToolAsText(get_weather, Map.of(city, 杭州)) .getContent(); String rst2 clientProvider.readResourceAsText(weather://cities) .getContent();callToolAsText调工具readResourceAsText读资源两个都返回内容就说明通道和协议都通了。4.2 STDIO 模式验证STDIO 没有端口验证靠管道。你可以手动构造一条 JSON-RPC 请求喂给进程echo {jsonrpc:2.0,id:1,method:tools/call,params:{name:add,arguments:{a:3,b:5}}} | java -jar demo.jar如果标准输出里返回{result:8}之类的内容说明 STDIO 通道工作正常。注意 STDIO 模式下日志要打到标准错误stderr不能污染标准输出否则客户端解析会失败。这是很多人第一次踩的坑。4.3 日志观察要点SSE 模式重点看端口绑定日志、SSE 连接建立日志、sessionId 分配日志、工具调用入参出参日志。STDIO 模式重点看进程启动日志、标准输入读取日志、标准输出写入日志。日志里出现channelSTDIO或sseEndpoint/mcp/sse能帮你确认当前跑的是哪种模式。验证通过后把 endpoint 和 Key 统一到 TaoToken 的配置就生效了。模型侧调用时Base URL 填 https://taotoken.net/api Key 用控制台创建的那个Model ID 按需选。5. 本篇常见错排查401、local proxy failed、reading choices、OAuth这一节列几个真实会撞上的报错对照着排查。401 Unauthorized最常见。先确认 API Key 有没有填对、有没有过期、有没有多余空格。TaoToken 的 Key 在控制台 API Keys 页面管理路径是 https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite 。如果 Key 是从环境变量读的确认变量名拼写一致echo $TAOTOKEN_API_KEY看有没有值。Base URL 也要确认是 https://taotoken.net/api 别多写或少写路径。local proxy failed这个报错通常出现在客户端配置了本地转发但转发进程没起来或者端口被占用。检查你的本地服务是否在监听、端口是否冲突。如果你用的是 IDE 插件或 CLI 工具确认它的代理配置指向了正确的本地地址。注意不要配置任何非官方的转发工具直接用 TaoToken 的 API 地址即可。reading choices 相关报错这类错误一般出现在解析模型响应时说明返回结构和你预期的字段对不上。先确认 Model ID 填的是 TaoToken 支持的模型再确认请求体格式符合对应模型的规范。可以用模型对话页面 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite 先手动发一条看返回结构长什么样再对照代码里的解析逻辑。OAuth 相关报错如果你在配置 Claude Code 或类似工具时遇到 OAuth 报错检查是不是把鉴权方式搞混了。TaoToken 用的是 API Key 鉴权不是 OAuth 流程。在 Claude Code 场景下配置项要写全三件套Base URL 填 https://taotoken.net/api API Key 填控制台创建的 KeyModel ID 填你要用的模型。缺任何一个都会导致鉴权失败。SSE 连接建立后收不到消息检查Accept头是不是text/event-stream检查服务端有没有正确 flush。有些框架默认缓冲响应需要手动 flush 才能把事件推出去。STDIO 模式无响应检查日志是不是打到了标准输出污染了协议通道。把日志级别调到 stderr或者用日志框架配置输出目标。另外确认请求 JSON 是单行、以换行结尾有些客户端对格式敏感。排查顺序建议先确认 Key 和 Base URL再确认通道配置最后看协议报文。大部分问题出在前两步。6. 把 SolonMCP 接入落到日常从验证到长期使用走到这里你应该已经能用 SolonMCP 把 Java 方法暴露成 MCP 工具并且用 SSE 或 STDIO 两种通道跑通。接下来是怎么把它用顺。日常开发里我建议先用 STDIO 模式做本地调试因为进程模型简单日志直接看终端改完代码重新打包就能测。等工具逻辑稳定了再切到 SSE 模式做常驻服务让多个客户端共享。切换时只改McpServerEndpoint的注解参数和配置文件里的 channel 字段模型侧的 TaoToken 配置完全不用动。如果你要做长期编码或 Agent 场景建议把 Key 管理、endpoint 配置、模型选择都收敛到一处。TaoToken 的 Coding Plan 入口在 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite 适合高频调用。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite 参数细节对照查。需要新建或轮换 Key 就去 https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite 。一个实用技巧把 SSE 的 sessionId 和工具调用日志关联起来出问题时能快速定位是哪个会话、哪次调用出的错。STDIO 模式则建议在请求里带一个自增 id方便对账。最后提醒一句SSE 模式暴露 HTTP 端口时注意访问控制别把内部工具直接开到公网。本地开发用 localhost生产环境加鉴权和限流。STDIO 模式天然隔离但要注意进程生命周期管理别让僵尸进程堆积。工具写出来是给人用的通道选对了后面维护成本会低很多。