1. SpringBoot3 项目里为什么还要引入 SolonMCP如果你手上已经有一个跑得好好的 SpringBoot3 后端现在产品或者架构那边提了个需求把现有的几个业务方法暴露成 MCP 工具让 Claude Code、Cline 这类客户端能直接调用。第一反应可能是上 Spring AI但真动手会发现两件事一是 Spring AI 的 MCP 模块版本迭代快二是把已有 Service 改造成工具类要动不少注解和配置。这时候 SolonMCPsolon-ai-mcp就是一个很轻的替代路径——它本身是 Solon AI 的扩展但支持内嵌到 SpringBoot3 里用注解把普通 Bean 标成 MCP 端点不需要你把整个项目迁到 Solon 体系。MCP 是什么用一句话说它是一个让大模型客户端按标准协议发现并调用你服务端能力的通道。你写一个getWeather方法客户端就能在工具列表里看到它传参调用拿到返回值。适合谁适合那些已经有 Java 后端、想快速给 AI 编码工具或 Agent 暴露内部接口的团队尤其是你不想为了一个 MCP 能力去重构整个依赖树的情况。我试过在 SpringBoot3.2 JDK17 的环境里把 SolonMCP 嵌进去整体感受是依赖只多两个包配置类一个工具类按普通 Spring 组件写启动后通过 SSE 端点验证注册结果。下面按依赖配置、初始化、工具方法、验证请求、排错、联调通道的顺序走一遍每一步都给可复制的代码。需要先明确一点SolonMCP 在 SpringBoot3 下和 SpringBoot2 的差别主要就是 servlet 容器那层依赖包名不同因为 Jakarta EE 改名了。SpringBoot3 用solon-web-servlet-jakartaSpringBoot2 用旧的solon-web-servlet-javax。其余 API 基本一致所以 SpringBoot2 的经验可以平移过来。2. 前置准备依赖、目录与 SolonMCP 初始化配置2.1 pom.xml 里加什么依赖SpringBoot3 项目引入 SolonMCP核心是两个依赖solon-ai-mcp提供 MCP 服务端能力solon-web-servlet-jakarta负责把 Solon 的 Servlet 过滤器挂到 SpringBoot3 的 Jakarta 容器上。版本号建议用当前稳定版下面给一个可复制的片段properties java.version17/java.version solon.version3.0.5/solon.version /properties dependencies !-- SpringBoot3 Web 基础 -- dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency !-- SolonMCP 核心提供 McpServerEndpoint、ToolMapping 等注解 -- dependency groupIdorg.noear/groupId artifactIdsolon-ai-mcp/artifactId version${solon.version}/version /dependency !-- SpringBoot3 专用 Servlet 适配Jakarta 命名空间 -- dependency groupIdorg.noear/groupId artifactIdsolon-web-servlet-jakarta/artifactId version${solon.version}/version /dependency /dependencies这里有个容易踩的坑如果你从 SpringBoot2 的项目复制依赖很可能带进来的是solon-web-servlet-javax在 SpringBoot3 下启动会报ClassNotFoundException: javax.servlet.Filter。因为 SpringBoot3 全面切到jakarta.servlet所以必须换成 jakarta 版本。这也是 SpringBoot3 和 SpringBoot2 使用 SolonMCP 唯一的依赖差异。2.2 目录结构建议为了让 SpringBoot 的组件扫描和 Solon 的端点收集不打架建议单独开一个包放 MCP 相关类src/main/java/com/example/demo/ ├── HelloApp.java // 启动类 └── mcpserver/ ├── IMcpServerEndpoint.java // 标记接口 ├── McpServerConfig.java // 初始化配置 └── tool/ └── McpServerTool.java // 具体工具端点2.3 标记接口与初始化配置先定义一个空接口作用只是让 Spring 能按类型收集所有 MCP 端点组件package com.example.demo.mcpserver; public interface IMcpServerEndpoint { }然后是配置类它做三件事启动 Solon 生命周期、把收集到的端点转成McpServerEndpointProvider、注册 Solon 的 Servlet 过滤器到/mcp/*package com.example.demo.mcpserver; import org.noear.solon.Solon; import org.noear.solon.ai.mcp.server.McpServerEndpointProvider; import org.noear.solon.ai.mcp.server.annotation.McpServerEndpoint; import org.noear.solon.ai.mcp.server.tool.MethodToolProvider; import org.noear.solon.ai.mcp.server.resource.MethodResourceProvider; import org.noear.solon.ai.mcp.server.prompt.MethodPromptProvider; import org.noear.solon.web.servlet.SolonServletFilter; import org.springframework.boot.web.servlet.FilterRegistrationBean; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import org.springframework.core.annotation.AnnotationUtils; import jakarta.annotation.PostConstruct; import jakarta.annotation.PreDestroy; import java.util.List; Configuration public class McpServerConfig { PostConstruct public void start() { Solon.start(McpServerConfig.class, new String[]{--cfgmcpserver.yml}); } PreDestroy public void stop() { if (Solon.app() ! null) { Solon.stopBlock(false, Solon.cfg().stopDelay()); } } Bean public McpServerConfig init(ListIMcpServerEndpoint serverEndpoints) { for (IMcpServerEndpoint serverEndpoint : serverEndpoints) { // 注意SpringBoot 下必须用 Spring 的 AnnotationUtils // 否则拿不到 McpServerEndpoint 注解 McpServerEndpoint anno AnnotationUtils.findAnnotation( serverEndpoint.getClass(), McpServerEndpoint.class); if (anno null) { continue; } McpServerEndpointProvider provider McpServerEndpointProvider.builder() .from(serverEndpoint.getClass(), anno) .build(); provider.addTool(new MethodToolProvider(serverEndpoint)); provider.addResource(new MethodResourceProvider(serverEndpoint)); provider.addPrompt(new MethodPromptProvider(serverEndpoint)); provider.postStart(); } return this; } Bean public FilterRegistrationBeanSolonServletFilter mcpServerFilter() { FilterRegistrationBeanSolonServletFilter filter new FilterRegistrationBean(); filter.setName(SolonFilter); filter.addUrlPatterns(/mcp/*); filter.setFilter(new SolonServletFilter()); return filter; } }这里AnnotationUtils用的是org.springframework.core.annotation.AnnotationUtils不是 Solon 自带的那个。因为 Spring 的代理机制会给 Bean 生成子类直接getClass().getAnnotation()可能拿不到注解必须用 Spring 的工具去查父类。这个点我在第一次写的时候没注意结果端点一直注册不上日志里也没有报错排查了半天。3. 可复制配置MCP 工具方法、SSE 端点与 mcpserver.yml3.1 工具端点类怎么写工具类就是一个普通 Spring 组件实现刚才的标记接口加上McpServerEndpoint注解。注解里的name是端点名sseEndpoint是客户端连接的 SSE 路径package com.example.demo.mcpserver.tool; import com.example.demo.mcpserver.IMcpServerEndpoint; import org.noear.solon.ai.chat.message.ChatMessage; import org.noear.solon.ai.mcp.server.annotation.McpServerEndpoint; import org.noear.solon.ai.mcp.server.annotation.Param; import org.noear.solon.ai.mcp.server.annotation.PromptMapping; import org.noear.solon.ai.mcp.server.annotation.ResourceMapping; import org.noear.solon.ai.mcp.server.annotation.ToolMapping; import org.springframework.stereotype.Component; import java.util.Arrays; import java.util.Collection; Component McpServerEndpoint(name demo1, sseEndpoint /mcp/demo1/sse) public class McpServerTool implements IMcpServerEndpoint { ToolMapping(description 查询天气预报) public String getWeather(Param(description 城市位置) String location) { return 晴14度; } ResourceMapping(uri config://app-version, description 获取应用版本号) public String getAppVersion() { return v3.2.0; } ResourceMapping(uri db://users/{user_id}/email, description 根据用户ID查询邮箱) public String getEmail(Param(description 用户Id) String user_id) { return user_id example.com; } PromptMapping(description 生成关于某个主题的提问) public CollectionChatMessage askQuestion(Param(description 主题) String topic) { return Arrays.asList( ChatMessage.ofUser(请解释一下 topic 的概念) ); } }Component这个注解别用错Solon 里也有同名的Component如果你 import 成了org.noear.solon.annotation.ComponentSpring 扫描不到端点就不会注册。建议在 IDE 里确认 import 是org.springframework.stereotype.Component。3.2 编译参数与参数名Param注解里写了 description但参数名location、user_id要能被反射拿到需要在编译时保留参数名。Maven 里加build plugins plugin groupIdorg.apache.maven.plugins/groupId artifactIdmaven-compiler-plugin/artifactId configuration parameterstrue/parameters /configuration /plugin /plugins /build如果不加-parameters客户端调用时可能报参数缺失或者你得在Param里显式写name location。两种方式都行但加编译参数更省事。3.3 mcpserver.yml 配置Solon 启动时会读--cfgmcpserver.yml这个文件放在src/main/resources下。最小配置如下solon: app: name: demo-mcp-server # 关闭 Solon 自带的 HTTP 服务只借用它的 MCP 能力 # 因为 Web 容器由 SpringBoot 提供 server: port: 0把 Solon 自己的 server 端口设为 0 或者干脆不启用避免和 SpringBoot 的 8080 冲突。MCP 的请求实际是通过 SpringBoot 的 Servlet 容器进来的Solon 只负责处理/mcp/*路径下的协议逻辑。3.4 启动类启动类保持标准 SpringBoot 写法即可package com.example.demo; import org.springframework.boot.SpringApplication; import org.springframework.boot.autoconfigure.SpringBootApplication; SpringBootApplication public class HelloApp { public static void main(String[] args) { SpringApplication.run(HelloApp.class, args); } }启动后SpringBoot 监听 8080Solon 的过滤器挂在/mcp/*客户端连http://localhost:8080/mcp/demo1/sse就能拿到工具列表。4. 验证请求确认工具注册与调用是否生效4.1 用 curl 看 SSE 端点启动应用后先确认 SSE 端点能连上。MCP 的 SSE 是长连接用 curl 加-N禁用缓冲curl -N http://localhost:8080/mcp/demo1/sse正常的话会看到类似event: endpoint和data: /mcp/demo1/message?sessionIdxxx的输出说明端点已注册客户端可以拿这个 sessionId 去发消息。4.2 写一个 Java 客户端验证工具调用更直观的方式是写个测试类用McpClientProvider连上去调工具import org.noear.solon.ai.mcp.client.McpClientProvider; import java.util.Collections; import java.util.Map; public class McpClientTest { public static void main(String[] args) throws Exception { McpClientProvider toolProvider McpClientProvider.builder() .apiUrl(http://localhost:8080/mcp/demo1/sse) .build(); // 工具调用 MapString, Object map Collections.singletonMap(location, 杭州); String rst toolProvider.callToolAsText(getWeather, map).getContent(); System.out.println(工具返回: rst); // 资源读取 String version toolProvider.readResourceAsText(config://app-version).getContent(); System.out.println(资源返回: version); } }跑起来应该输出工具返回: 晴14度 资源返回: v3.2.0如果callToolAsText返回空或者抛异常先检查getWeather方法上的ToolMapping是否被扫描到再看McpServerConfig里的init方法有没有真的执行——可以在里面加一行日志打印serverEndpoints.size()。4.3 把 MCP 客户端当 LLM 工具集用SolonMCP 还支持把 MCP 客户端直接挂到 ChatModel 上让模型自己决定调哪个工具。本地测试可以用 Ollamaimport org.noear.solon.ai.chat.ChatModel; import org.noear.solon.ai.chat.ChatResponse; import org.noear.solon.ai.mcp.client.McpClientProvider; public class McpWithLlmTest { public static void main(String[] args) throws Exception { McpClientProvider toolProvider McpClientProvider.builder() .apiUrl(http://localhost:8080/mcp/demo1/sse) .build(); ChatModel chatModel ChatModel.of(http://127.0.0.1:11434/api/chat) .provider(ollama) .model(qwen2.5:1.5b) .defaultToolsAdd(toolProvider) .build(); ChatResponse resp chatModel.prompt(杭州今天的天气怎么样).call(); System.out.println(resp.getMessage()); } }模型会先调getWeather拿到「晴14度」再组织成自然语言回答。这一步验证的是工具注册和模型调用链都通了。5. 本篇常见错排查401、local proxy failed 与 reading choices5.1 启动报 ClassNotFoundException: javax.servlet.Filter这是 SpringBoot3 下最常见的错原因就是依赖引成了solon-web-servlet-javax。检查 pom确保是artifactIdsolon-web-servlet-jakarta/artifactIdSpringBoot3 的spring-boot-starter-web带的是jakarta.servlet-api两者命名空间必须一致。5.2 端点注册不上客户端连 /mcp/demo1/sse 返回 404先看McpServerConfig里的init方法有没有被调用。如果ListIMcpServerEndpoint是空的说明 Spring 没扫描到McpServerTool。检查两点一是Component的 import 是不是 Spring 的二是McpServerTool所在的包是否在SpringBootApplication的扫描范围内。还有一种情况是AnnotationUtils用错了包。必须用org.springframework.core.annotation.AnnotationUtils用 Solon 的AnnotationUtils在 Spring 代理下拿不到注解anno为 null 就直接 continue 了端点静默丢失。5.3 客户端调用报 401 或 local proxy failed如果你把 MCP 服务端地址指向了远程统一通道比如 TaoToken 的 API 通道出现 401 通常是 Key 没带或者带错位置。MCP 客户端配置里要同时给全三件套Base URL、API Key、Model ID。以 Cline 或 Claude Code 这类客户端为例配置片段长这样{ mcpServers: { demo1: { url: https://taotoken.net/api/mcp/demo1/sse, headers: { Authorization: Bearer sk-你的Key } } } }local proxy failed一般是客户端本地代理层连不上目标地址先确认url能不能在浏览器或 curl 里通再确认 Key 有没有过期。如果是 Codex 的auth.json方式字段名要对齐{ base_url: https://taotoken.net/api, api_key: sk-你的Key, model: claude-sonnet-4-5 }5.4 报 reading choices 或返回体解析失败reading choices这类错通常出现在把 MCP 端点和 OpenAI 兼容接口混用的时候。MCP 的 SSE 返回的是事件流不是choices结构。如果你用 OpenAI SDK 去请求 MCP 的/sse路径解析器会找不到choices字段而报错。正确做法是MCP 客户端用McpClientProvider或支持 MCP 协议的客户端只有走 LLM 对话接口时才用 OpenAI 兼容格式两者路径不同。5.5 OAuth 相关报错部分客户端在连远程 MCP 时会尝试 OAuth 流程如果服务端没开对应能力会报OAuth discovery failed之类。这种情况下在客户端配置里显式指定用 Bearer Token 认证跳过 OAuth 发现。TaoToken 的 API 通道用统一 Key 即可不需要额外 OAuth 配置。6. 把服务端地址切到 TaoToken 统一通道联调本地验证通过后下一步通常是把 MCP 服务端暴露到能被外部客户端访问的地址。如果你不想自己维护公网入口和 Key 管理可以把请求通道切到 TaoToken 的统一 Key/API 通道。它的 API 入口是https://taotoken.net/api官网是https://taotoken.net/?utm_sourcetaotoken_aicg_blog_end。具体做法分两步。第一步在 TaoToken 控制台创建一个 API Key路径是 console 里的 API Keys 页面。第二步把客户端配置里的url从http://localhost:8080/mcp/demo1/sse换成统一通道地址并在 headers 里带上 Key。这样你的 SpringBoot3 服务端不用改代码只是客户端连接的目标变了。联调时建议先用模型对话页面确认 Key 本身可用再切到 MCP 客户端。如果对话能通、MCP 报 401那问题就在 MCP 客户端的 header 配置而不是 Key 本身。长期跑编码 Agent 或需要稳定调用额度的场景可以看下 Coding Plan 的额度方案比按次调用更适合高频工具调用。最后留一个实操建议MCP 工具方法的返回值尽量保持简单字符串或小 JSON别在工具里做重业务查询。因为客户端调用工具是同步等待的一个慢查询会拖住整个对话轮次。把重逻辑放到异步任务里工具方法只负责触发和返回任务 ID这样联调时不容易超时。
1. SpringBoot3 项目里为什么还要引入 SolonMCP如果你手上已经有一个跑得好好的 SpringBoot3 后端现在产品或者架构那边提了个需求把现有的几个业务方法暴露成 MCP 工具让 Claude Code、Cline 这类客户端能直接调用。第一反应可能是上 Spring AI但真动手会发现两件事一是 Spring AI 的 MCP 模块版本迭代快二是把已有 Service 改造成工具类要动不少注解和配置。这时候 SolonMCPsolon-ai-mcp就是一个很轻的替代路径——它本身是 Solon AI 的扩展但支持内嵌到 SpringBoot3 里用注解把普通 Bean 标成 MCP 端点不需要你把整个项目迁到 Solon 体系。MCP 是什么用一句话说它是一个让大模型客户端按标准协议发现并调用你服务端能力的通道。你写一个getWeather方法客户端就能在工具列表里看到它传参调用拿到返回值。适合谁适合那些已经有 Java 后端、想快速给 AI 编码工具或 Agent 暴露内部接口的团队尤其是你不想为了一个 MCP 能力去重构整个依赖树的情况。我试过在 SpringBoot3.2 JDK17 的环境里把 SolonMCP 嵌进去整体感受是依赖只多两个包配置类一个工具类按普通 Spring 组件写启动后通过 SSE 端点验证注册结果。下面按依赖配置、初始化、工具方法、验证请求、排错、联调通道的顺序走一遍每一步都给可复制的代码。需要先明确一点SolonMCP 在 SpringBoot3 下和 SpringBoot2 的差别主要就是 servlet 容器那层依赖包名不同因为 Jakarta EE 改名了。SpringBoot3 用solon-web-servlet-jakartaSpringBoot2 用旧的solon-web-servlet-javax。其余 API 基本一致所以 SpringBoot2 的经验可以平移过来。2. 前置准备依赖、目录与 SolonMCP 初始化配置2.1 pom.xml 里加什么依赖SpringBoot3 项目引入 SolonMCP核心是两个依赖solon-ai-mcp提供 MCP 服务端能力solon-web-servlet-jakarta负责把 Solon 的 Servlet 过滤器挂到 SpringBoot3 的 Jakarta 容器上。版本号建议用当前稳定版下面给一个可复制的片段properties java.version17/java.version solon.version3.0.5/solon.version /properties dependencies !-- SpringBoot3 Web 基础 -- dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency !-- SolonMCP 核心提供 McpServerEndpoint、ToolMapping 等注解 -- dependency groupIdorg.noear/groupId artifactIdsolon-ai-mcp/artifactId version${solon.version}/version /dependency !-- SpringBoot3 专用 Servlet 适配Jakarta 命名空间 -- dependency groupIdorg.noear/groupId artifactIdsolon-web-servlet-jakarta/artifactId version${solon.version}/version /dependency /dependencies这里有个容易踩的坑如果你从 SpringBoot2 的项目复制依赖很可能带进来的是solon-web-servlet-javax在 SpringBoot3 下启动会报ClassNotFoundException: javax.servlet.Filter。因为 SpringBoot3 全面切到jakarta.servlet所以必须换成 jakarta 版本。这也是 SpringBoot3 和 SpringBoot2 使用 SolonMCP 唯一的依赖差异。2.2 目录结构建议为了让 SpringBoot 的组件扫描和 Solon 的端点收集不打架建议单独开一个包放 MCP 相关类src/main/java/com/example/demo/ ├── HelloApp.java // 启动类 └── mcpserver/ ├── IMcpServerEndpoint.java // 标记接口 ├── McpServerConfig.java // 初始化配置 └── tool/ └── McpServerTool.java // 具体工具端点2.3 标记接口与初始化配置先定义一个空接口作用只是让 Spring 能按类型收集所有 MCP 端点组件package com.example.demo.mcpserver; public interface IMcpServerEndpoint { }然后是配置类它做三件事启动 Solon 生命周期、把收集到的端点转成McpServerEndpointProvider、注册 Solon 的 Servlet 过滤器到/mcp/*package com.example.demo.mcpserver; import org.noear.solon.Solon; import org.noear.solon.ai.mcp.server.McpServerEndpointProvider; import org.noear.solon.ai.mcp.server.annotation.McpServerEndpoint; import org.noear.solon.ai.mcp.server.tool.MethodToolProvider; import org.noear.solon.ai.mcp.server.resource.MethodResourceProvider; import org.noear.solon.ai.mcp.server.prompt.MethodPromptProvider; import org.noear.solon.web.servlet.SolonServletFilter; import org.springframework.boot.web.servlet.FilterRegistrationBean; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import org.springframework.core.annotation.AnnotationUtils; import jakarta.annotation.PostConstruct; import jakarta.annotation.PreDestroy; import java.util.List; Configuration public class McpServerConfig { PostConstruct public void start() { Solon.start(McpServerConfig.class, new String[]{--cfgmcpserver.yml}); } PreDestroy public void stop() { if (Solon.app() ! null) { Solon.stopBlock(false, Solon.cfg().stopDelay()); } } Bean public McpServerConfig init(ListIMcpServerEndpoint serverEndpoints) { for (IMcpServerEndpoint serverEndpoint : serverEndpoints) { // 注意SpringBoot 下必须用 Spring 的 AnnotationUtils // 否则拿不到 McpServerEndpoint 注解 McpServerEndpoint anno AnnotationUtils.findAnnotation( serverEndpoint.getClass(), McpServerEndpoint.class); if (anno null) { continue; } McpServerEndpointProvider provider McpServerEndpointProvider.builder() .from(serverEndpoint.getClass(), anno) .build(); provider.addTool(new MethodToolProvider(serverEndpoint)); provider.addResource(new MethodResourceProvider(serverEndpoint)); provider.addPrompt(new MethodPromptProvider(serverEndpoint)); provider.postStart(); } return this; } Bean public FilterRegistrationBeanSolonServletFilter mcpServerFilter() { FilterRegistrationBeanSolonServletFilter filter new FilterRegistrationBean(); filter.setName(SolonFilter); filter.addUrlPatterns(/mcp/*); filter.setFilter(new SolonServletFilter()); return filter; } }这里AnnotationUtils用的是org.springframework.core.annotation.AnnotationUtils不是 Solon 自带的那个。因为 Spring 的代理机制会给 Bean 生成子类直接getClass().getAnnotation()可能拿不到注解必须用 Spring 的工具去查父类。这个点我在第一次写的时候没注意结果端点一直注册不上日志里也没有报错排查了半天。3. 可复制配置MCP 工具方法、SSE 端点与 mcpserver.yml3.1 工具端点类怎么写工具类就是一个普通 Spring 组件实现刚才的标记接口加上McpServerEndpoint注解。注解里的name是端点名sseEndpoint是客户端连接的 SSE 路径package com.example.demo.mcpserver.tool; import com.example.demo.mcpserver.IMcpServerEndpoint; import org.noear.solon.ai.chat.message.ChatMessage; import org.noear.solon.ai.mcp.server.annotation.McpServerEndpoint; import org.noear.solon.ai.mcp.server.annotation.Param; import org.noear.solon.ai.mcp.server.annotation.PromptMapping; import org.noear.solon.ai.mcp.server.annotation.ResourceMapping; import org.noear.solon.ai.mcp.server.annotation.ToolMapping; import org.springframework.stereotype.Component; import java.util.Arrays; import java.util.Collection; Component McpServerEndpoint(name demo1, sseEndpoint /mcp/demo1/sse) public class McpServerTool implements IMcpServerEndpoint { ToolMapping(description 查询天气预报) public String getWeather(Param(description 城市位置) String location) { return 晴14度; } ResourceMapping(uri config://app-version, description 获取应用版本号) public String getAppVersion() { return v3.2.0; } ResourceMapping(uri db://users/{user_id}/email, description 根据用户ID查询邮箱) public String getEmail(Param(description 用户Id) String user_id) { return user_id example.com; } PromptMapping(description 生成关于某个主题的提问) public CollectionChatMessage askQuestion(Param(description 主题) String topic) { return Arrays.asList( ChatMessage.ofUser(请解释一下 topic 的概念) ); } }Component这个注解别用错Solon 里也有同名的Component如果你 import 成了org.noear.solon.annotation.ComponentSpring 扫描不到端点就不会注册。建议在 IDE 里确认 import 是org.springframework.stereotype.Component。3.2 编译参数与参数名Param注解里写了 description但参数名location、user_id要能被反射拿到需要在编译时保留参数名。Maven 里加build plugins plugin groupIdorg.apache.maven.plugins/groupId artifactIdmaven-compiler-plugin/artifactId configuration parameterstrue/parameters /configuration /plugin /plugins /build如果不加-parameters客户端调用时可能报参数缺失或者你得在Param里显式写name location。两种方式都行但加编译参数更省事。3.3 mcpserver.yml 配置Solon 启动时会读--cfgmcpserver.yml这个文件放在src/main/resources下。最小配置如下solon: app: name: demo-mcp-server # 关闭 Solon 自带的 HTTP 服务只借用它的 MCP 能力 # 因为 Web 容器由 SpringBoot 提供 server: port: 0把 Solon 自己的 server 端口设为 0 或者干脆不启用避免和 SpringBoot 的 8080 冲突。MCP 的请求实际是通过 SpringBoot 的 Servlet 容器进来的Solon 只负责处理/mcp/*路径下的协议逻辑。3.4 启动类启动类保持标准 SpringBoot 写法即可package com.example.demo; import org.springframework.boot.SpringApplication; import org.springframework.boot.autoconfigure.SpringBootApplication; SpringBootApplication public class HelloApp { public static void main(String[] args) { SpringApplication.run(HelloApp.class, args); } }启动后SpringBoot 监听 8080Solon 的过滤器挂在/mcp/*客户端连http://localhost:8080/mcp/demo1/sse就能拿到工具列表。4. 验证请求确认工具注册与调用是否生效4.1 用 curl 看 SSE 端点启动应用后先确认 SSE 端点能连上。MCP 的 SSE 是长连接用 curl 加-N禁用缓冲curl -N http://localhost:8080/mcp/demo1/sse正常的话会看到类似event: endpoint和data: /mcp/demo1/message?sessionIdxxx的输出说明端点已注册客户端可以拿这个 sessionId 去发消息。4.2 写一个 Java 客户端验证工具调用更直观的方式是写个测试类用McpClientProvider连上去调工具import org.noear.solon.ai.mcp.client.McpClientProvider; import java.util.Collections; import java.util.Map; public class McpClientTest { public static void main(String[] args) throws Exception { McpClientProvider toolProvider McpClientProvider.builder() .apiUrl(http://localhost:8080/mcp/demo1/sse) .build(); // 工具调用 MapString, Object map Collections.singletonMap(location, 杭州); String rst toolProvider.callToolAsText(getWeather, map).getContent(); System.out.println(工具返回: rst); // 资源读取 String version toolProvider.readResourceAsText(config://app-version).getContent(); System.out.println(资源返回: version); } }跑起来应该输出工具返回: 晴14度 资源返回: v3.2.0如果callToolAsText返回空或者抛异常先检查getWeather方法上的ToolMapping是否被扫描到再看McpServerConfig里的init方法有没有真的执行——可以在里面加一行日志打印serverEndpoints.size()。4.3 把 MCP 客户端当 LLM 工具集用SolonMCP 还支持把 MCP 客户端直接挂到 ChatModel 上让模型自己决定调哪个工具。本地测试可以用 Ollamaimport org.noear.solon.ai.chat.ChatModel; import org.noear.solon.ai.chat.ChatResponse; import org.noear.solon.ai.mcp.client.McpClientProvider; public class McpWithLlmTest { public static void main(String[] args) throws Exception { McpClientProvider toolProvider McpClientProvider.builder() .apiUrl(http://localhost:8080/mcp/demo1/sse) .build(); ChatModel chatModel ChatModel.of(http://127.0.0.1:11434/api/chat) .provider(ollama) .model(qwen2.5:1.5b) .defaultToolsAdd(toolProvider) .build(); ChatResponse resp chatModel.prompt(杭州今天的天气怎么样).call(); System.out.println(resp.getMessage()); } }模型会先调getWeather拿到「晴14度」再组织成自然语言回答。这一步验证的是工具注册和模型调用链都通了。5. 本篇常见错排查401、local proxy failed 与 reading choices5.1 启动报 ClassNotFoundException: javax.servlet.Filter这是 SpringBoot3 下最常见的错原因就是依赖引成了solon-web-servlet-javax。检查 pom确保是artifactIdsolon-web-servlet-jakarta/artifactIdSpringBoot3 的spring-boot-starter-web带的是jakarta.servlet-api两者命名空间必须一致。5.2 端点注册不上客户端连 /mcp/demo1/sse 返回 404先看McpServerConfig里的init方法有没有被调用。如果ListIMcpServerEndpoint是空的说明 Spring 没扫描到McpServerTool。检查两点一是Component的 import 是不是 Spring 的二是McpServerTool所在的包是否在SpringBootApplication的扫描范围内。还有一种情况是AnnotationUtils用错了包。必须用org.springframework.core.annotation.AnnotationUtils用 Solon 的AnnotationUtils在 Spring 代理下拿不到注解anno为 null 就直接 continue 了端点静默丢失。5.3 客户端调用报 401 或 local proxy failed如果你把 MCP 服务端地址指向了远程统一通道比如 TaoToken 的 API 通道出现 401 通常是 Key 没带或者带错位置。MCP 客户端配置里要同时给全三件套Base URL、API Key、Model ID。以 Cline 或 Claude Code 这类客户端为例配置片段长这样{ mcpServers: { demo1: { url: https://taotoken.net/api/mcp/demo1/sse, headers: { Authorization: Bearer sk-你的Key } } } }local proxy failed一般是客户端本地代理层连不上目标地址先确认url能不能在浏览器或 curl 里通再确认 Key 有没有过期。如果是 Codex 的auth.json方式字段名要对齐{ base_url: https://taotoken.net/api, api_key: sk-你的Key, model: claude-sonnet-4-5 }5.4 报 reading choices 或返回体解析失败reading choices这类错通常出现在把 MCP 端点和 OpenAI 兼容接口混用的时候。MCP 的 SSE 返回的是事件流不是choices结构。如果你用 OpenAI SDK 去请求 MCP 的/sse路径解析器会找不到choices字段而报错。正确做法是MCP 客户端用McpClientProvider或支持 MCP 协议的客户端只有走 LLM 对话接口时才用 OpenAI 兼容格式两者路径不同。5.5 OAuth 相关报错部分客户端在连远程 MCP 时会尝试 OAuth 流程如果服务端没开对应能力会报OAuth discovery failed之类。这种情况下在客户端配置里显式指定用 Bearer Token 认证跳过 OAuth 发现。TaoToken 的 API 通道用统一 Key 即可不需要额外 OAuth 配置。6. 把服务端地址切到 TaoToken 统一通道联调本地验证通过后下一步通常是把 MCP 服务端暴露到能被外部客户端访问的地址。如果你不想自己维护公网入口和 Key 管理可以把请求通道切到 TaoToken 的统一 Key/API 通道。它的 API 入口是https://taotoken.net/api官网是https://taotoken.net/?utm_sourcetaotoken_aicg_blog_end。具体做法分两步。第一步在 TaoToken 控制台创建一个 API Key路径是 console 里的 API Keys 页面。第二步把客户端配置里的url从http://localhost:8080/mcp/demo1/sse换成统一通道地址并在 headers 里带上 Key。这样你的 SpringBoot3 服务端不用改代码只是客户端连接的目标变了。联调时建议先用模型对话页面确认 Key 本身可用再切到 MCP 客户端。如果对话能通、MCP 报 401那问题就在 MCP 客户端的 header 配置而不是 Key 本身。长期跑编码 Agent 或需要稳定调用额度的场景可以看下 Coding Plan 的额度方案比按次调用更适合高频工具调用。最后留一个实操建议MCP 工具方法的返回值尽量保持简单字符串或小 JSON别在工具里做重业务查询。因为客户端调用工具是同步等待的一个慢查询会拖住整个对话轮次。把重逻辑放到异步任务里工具方法只负责触发和返回任务 ID这样联调时不容易超时。
