1. 从一次真实踩坑说起为什么 Java 开发者需要自己的 MCP ServerMCP Server 是什么简单说它是把「模型能调用的工具」用一套标准协议暴露出来的服务端。AI Agent 是什么就是那个会自己判断「现在该调哪个工具」的调度大脑。而 Spring AI 让 Java 开发者不用去啃 Node.js 生态直接用注解就能把方法注册成 MCP 工具。这套组合适合谁适合手上已经有 Spring Boot 项目、想让自己业务能力被 Claude、Cursor、CodeBuddy 这类客户端直接调用的后端同学。我试过最原始的玩法在客户端里写一堆 function call 的 JSON Schema每换一个模型平台就重写一遍集成代码。后来 MCP 协议出来理论上一次开发到处复用但早期生态几乎全是 Node.js 的 ServerJava 这边只能干看着。直到 Spring AI 把spring-ai-mcp-server-spring-boot-starter放出来Java 才算真正有了「春天」。这篇要做的闭环很具体先讲清 MCP 协议里 Client、Server、Tool 三者怎么串起来再落地一个能跑的 Spring AI MCP Server 项目最后用客户端真实调用验证。中间会给出可复制的 Maven 依赖、Tool注册代码、application.yml配置以及统一 Key 通道的 endpoint 写法。目标只有一个——你照着敲能一次跑通。需要提前说明的是MCP 的传输方式有好几种Stdio、SSE、Streamable HTTP 各有适用场景。本文聚焦 Stdio因为它最适合本地集成和命令行工具开发客户端启动时自动拉起 Server 进程通过标准输入输出通信不需要额外开端口调试也直观。理解了 Stdio 这一种其他传输方式的思路是相通的。2. 前置准备用 TaoToken 统一 Key 打通模型通道与 MCP 调用链路在动手写 Server 之前先把「模型从哪来」这件事解决掉。MCP Server 本身只负责暴露工具真正决定调不调、怎么调的是背后的大模型。如果你同时用 Claude、GPT、国产模型每个平台一套 Key、一套 Base URL管理起来很烦。TaoToken 在这里的作用就是提供统一的 API 通道一个 Key 走通多家模型省掉反复切换配置的麻烦。先拿 Key。打开官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 注册后在控制台创建 API Key。控制台地址是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite Key 列表在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。创建完记得复制保存页面刷新后就不再完整显示。拿到 Key 之后模型调用的 Base URL 统一填https://taotoken.net/api注意这个地址不带任何查询参数。如果你用的是 OpenAI 兼容的 SDK直接把它当作base_url即可如果是 Claude Code 这类工具走的是 Anthropic 兼容通道配置方式略有不同可以参考接入文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。这里要区分两个概念别搞混用途地址说明模型对话 / API 调用https://taotoken.net/api统一 Key 通道供 SDK、客户端调用模型MCP Server 本地服务无固定地址Stdio由客户端进程拉起不走网络端口也就是说TaoToken 负责「模型侧」的通道MCP Server 负责「工具侧」的能力两者通过客户端AI Agent串起来。客户端一边用 TaoToken 的 Key 调模型一边通过 Stdio 调你的 MCP Server模型决定调用哪个工具客户端负责转发。如果你打算长期做编码类 Agent 开发可以考虑 Coding Plan地址是 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 适合需要稳定额度、频繁调用的场景。想先验证模型通不通用模型对话页面 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentchatutm_campaignrewrite 发一条消息即可能正常返回就说明 Key 和通道没问题。前置准备清单JDK 17 或以上Spring AI 1.0.0-M6 要求Maven 3.9一个支持 MCP 的客户端CodeBuddy、Cursor、Claude Desktop 等TaoToken API Key用于模型侧调用一个你熟悉的业务接口本文以「发布文章」为例把这些准备好后面写代码就不会卡在环境上。3. 可复制配置Spring AI MCP Server 的 pom.xml 与 application.yml 完整片段这一节是全文最核心的可复制部分。先给pom.xml再给application.yml最后给工具注册代码。路径和文件名都按实际项目结构写你直接对照改。3.1 pom.xml 依赖配置关键依赖是spring-ai-mcp-server-spring-boot-starter配合spring-ai-bom统一版本。完整片段如下properties maven.compiler.source17/maven.compiler.source maven.compiler.target17/maven.compiler.target spring-ai.version1.0.0-M6/spring-ai.version spring-boot.version3.4.5/spring-boot.version project.build.sourceEncodingUTF-8/project.build.sourceEncoding /properties dependencies dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-mcp-server-spring-boot-starter/artifactId /dependency dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-test/artifactId scopetest/scope /dependency dependency groupIdorg.projectlombok/groupId artifactIdlombok/artifactId optionaltrue/optional /dependency dependency groupIdcom.squareup.retrofit2/groupId artifactIdretrofit/artifactId version2.9.0/version /dependency dependency groupIdcom.squareup.retrofit2/groupId artifactIdconverter-jackson/artifactId version2.9.0/version /dependency /dependencies dependencyManagement dependencies dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-bom/artifactId version${spring-ai.version}/version typepom/type scopeimport/scope /dependency /dependencies /dependencyManagement注意spring-ai-bom必须放在dependencyManagement里否则 starter 的版本会解析失败。Retrofit 是我用来调外部 HTTP 接口的你可以换成 WebClient 或 RestTemplate不影响 MCP 部分。3.2 application.yml 配置Stdio 模式下有几个必填项漏一个都启动不了spring: application: name: tencent-send-article-mcp-server main: web-application-type: none banner-mode: off ai: mcp: server: stdio: true name: tencent-send-article-mcp-server version: 1.0.0 logging: pattern: console: file: name: data/log/${spring.application.name}.log逐项说明web-application-type: none表示这不是 Web 应用不启 Tomcatbanner-mode: off关掉启动 banner因为 Stdio 模式下任何多余输出都会污染 JSON-RPC 通道stdio: true是核心开关name和version会出现在客户端看到的 Server 信息里。日志那块建议保留Stdio 模式下控制台输出会干扰协议通信写到文件里更安全。3.3 工具注册代码定义一个 Service用Tool注解标记要暴露的方法Service public class TencentArticleToolService { Resource private ITencentService iTencentService; Resource private TencentApiProperties tencentApiProperties; Tool(description 发布文章到腾讯云开发者社区) public ArticleFunctionResponse saveArticle(ArticleFunctionRequest request) { try { AddArticleRequest addArticleRequest new AddArticleRequest(); addArticleRequest.setTitle(request.getTitle()); addArticleRequest.setPlain(request.getMarkdowncontent()); addArticleRequest.setContent(addArticleRequest.getContent()); addArticleRequest.setSourceType(1); addArticleRequest.setUserSummary(request.getUserSummary()); CallAddArticleResponse call iTencentService.addArticle( tencentApiProperties.getCookie(), addArticleRequest); ResponseAddArticleResponse response call.execute(); ArticleFunctionResponse result new ArticleFunctionResponse(); if (response.isSuccessful() response.body() ! null) { result.setStatus(response.body().getStatus()); result.setArticleId(response.body().getArticleId()); result.setUrl(https://cloud.tencent.com/developer/article/ response.body().getArticleId()); } return result; } catch (Exception e) { log.error(发布失败, e); } return null; } }Tool的description很关键模型就是靠这句话判断「什么时候该调这个工具」。写得太模糊模型可能永远不调写得太长又浪费 token。建议一句话说清「做什么 对谁做」。然后在启动类里注册 ToolCallbackProviderBean public ToolCallbackProvider articleTools(TencentArticleToolService service) { return MethodToolCallbackProvider.builder() .toolObjects(service) .build(); }到这里一个最小可用的 MCP Server 就成型了。打包命令./mvnw clean install -DskipTests产物在target/目录下记住这个 jar 的绝对路径下一步客户端配置要用。4. 验证请求本地启动 MCP Server 并用客户端完成一次真实工具调用代码写完不算完得真跑起来。这一节分两步先本地启动确认 Server 能拉起再配客户端完成一次端到端调用。4.1 本地启动验证Stdio 模式的 Server 不能直接java -jar跑因为它等的是标准输入。你直接运行会看到进程挂起这是正常的。正确做法是通过客户端拉起或者用官方的 MCP Inspector 工具测试。先确认 jar 能正常加载java -Dfile.encodingUTF-8 -jar target/tencent-send-article-mcp-server-1.0.0.jar如果卡住不动、没有报错说明 Server 已经进入等待输入状态CtrlC 退出即可。如果报NoClassDefFoundError或ClassNotFoundException多半是依赖没打进去检查spring-boot-maven-plugin是否配置了 repackage。4.2 客户端配置以 CodeBuddy 为例在 MCP 配置里新增一段{ mcpServers: { tencent-send-article-mcp-server: { command: /你的JDK17路径/bin/java, args: [ -Dfile.encodingUTF-8, -jar, /你的项目路径/target/tencent-send-article-mcp-server-1.0.0.jar, --tencent.api.cookie你的Cookie值 ] } } }三个关键点command必须指向 JDK 17 以上的 java如果你系统默认是 JDK 8这里要写绝对路径args里的-Dfile.encodingUTF-8防止中文乱码--tencent.api.cookie是通过命令行参数注入配置对应ConfigurationProperties(prefix tencent.api)那个类。配置保存后客户端侧边栏应该能看到 Server 亮起。点开工具列表能看到saveArticle这个工具说明注册成功。4.3 发起一次真实调用在对话里输入类似这样的指令帮我发布一篇文章标题是「MCP Server 实战记录」内容是 Markdown 格式的一段介绍摘要是「一次跑通 Spring AI MCP Server」。模型会判断需要调用saveArticle然后客户端把参数通过 Stdio 传给 Server。Server 执行完返回结果客户端展示给你。如果返回里带了文章 ID 和 URL说明整条链路通了。这里有个细节模型传过来的markdowncontent是 Markdown 文本但目标平台要的是 ProseMirror 格式的 JSON。所以我在AddArticleRequest.getContent()里做了一层转换把 Markdown 转成 ProseMirror。这个转换器可以自己写也可以让 AI 帮你生成核心是把标题、段落、列表、代码块这些元素映射成对应的 JSON 节点。验证成功的标志有三个客户端显示工具调用成功、返回结果里有文章 ID、去目标平台能看到刚发布的文章。三个都满足闭环就算跑通了。5. 本篇常见错排查401、local proxy failed、reading choices 与 OAuth 报错对照跑不通是常态这一节把最常见的几类报错和排查思路列出来对照着看。5.1 401 Unauthorized这个报错分两种场景。如果是模型侧返回 401说明 TaoToken 的 Key 不对或过期了去控制台重新生成一个确认请求头里Authorization: Bearer key拼写正确。如果是工具侧返回 401说明你调的外部接口比如发布文章那个Cookie 失效了重新登录目标平台抓一份新的 Cookie更新到--tencent.api.cookie参数里。5.2 local proxy failed这个报错通常出现在客户端连不上 Server 的时候。排查顺序先确认command路径下的 java 能执行在终端里手动跑一遍java -version再确认 jar 路径是绝对路径且文件存在最后看args数组里的参数顺序-jar必须在 jar 路径前面。如果用了相对路径客户端的工作目录可能和你预期的不一样一律改成绝对路径最稳。5.3 reading choices 相关报错这类报错一般出现在模型返回结构解析失败的时候。常见原因是 Stdio 通道被污染了——比如 Server 启动时打印了 banner、日志输出到了 stdout。检查application.yml里banner-mode: off和web-application-type: none是否都配了日志是否写到了文件而不是控制台。Stdio 模式下stdout 只能走 JSON-RPC 消息任何多余输出都会导致客户端解析失败。5.4 OAuth 相关报错如果你用的是 Claude Code 这类走 Anthropic 通道的工具可能会遇到 OAuth 报错。这类问题多半是认证方式没选对。Claude Code 的接入方式参考文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里面区分了 API Key 和 OAuth 两种模式按你的场景选。如果只是本地开发调试用 API Key 模式更简单。5.5 工具注册了但模型不调用这不是报错但比报错更让人抓狂。原因通常是Tool的description写得太模糊模型不知道什么时候该用。解决办法是把描述写具体比如「发布文章到腾讯云开发者社区需要标题、Markdown 内容和摘要三个参数」让模型能明确判断触发条件。另外确认ToolCallbackProvider的 Bean 确实被 Spring 扫描到了可以在启动日志里搜一下工具注册信息。5.6 中文乱码Stdio 模式下中文乱码很常见根源是编码不一致。三处都要设成 UTF-8pom.xml里的project.build.sourceEncoding、启动参数里的-Dfile.encodingUTF-8、以及application.yml里的server.servlet.encoding.charset。三处对齐基本就不会乱码了。排查这类问题的通用思路是先看客户端报错信息定位是模型侧还是工具侧再看 Server 日志文件确认请求有没有到达最后用最小化配置复现逐步加回参数。别一上来就怀疑代码八成是配置问题。6. 把 MCP Server 接进你的 AI Agent 工作流到这里一个能跑的 Spring AI MCP Server 已经完成了。但单个 Server 只是起点真正的价值在于把多个 Server 串起来让 AI Agent 自己调度。回到开头的场景你有一个发布文章的 Server、一个操作文件的 Server、一个查数据库的 Server。客户端AI Agent拿到用户指令后会自己判断该调哪个、按什么顺序调。比如「把这篇草稿发布出去然后在本地的记录文件里追加一条日志」Agent 会先调发布工具再调文件工具全程不需要你写编排代码。这就是 MCP 协议最大的意义——把「工具」和「调度」解耦。如果你想继续深入几个方向可以试试。一是把 Stdio 换成 SSE 或 Streamable HTTP让 Server 能远程部署多个客户端共享二是把工具的参数校验做严用 JSON Schema 约束输入减少模型传错参数的概率三是把多个工具按业务域拆成多个 Server客户端按需加载避免一次性暴露太多工具导致模型选择困难。模型侧的统一通道还是用 TaoTokenBase URL 固定https://taotoken.net/api换模型不用改代码。工具侧就是你刚写的这个 Server加新能力就是加一个Tool方法。两边通过客户端串起来这套结构跑顺了后面加什么业务都只是重复这个模式。最后留一个实用技巧开发阶段把 Server 日志级别调到 DEBUG能看到完整的 JSON-RPC 请求和响应排查问题效率翻倍。上线前再调回 INFO避免日志文件膨胀。工具描述定期 review 一遍模型调用的准确率会随着描述优化明显提升。 
长河君 · 2026/10/18 1:00:32 · 阅读 1.2k 一条龙开发指南：用 TaoToken 统一 Key 打通 MCP AI Agent 理论+项目实战开发你的 MCP Server
1. 从一次真实踩坑说起为什么 Java 开发者需要自己的 MCP ServerMCP Server 是什么简单说它是把「模型能调用的工具」用一套标准协议暴露出来的服务端。AI Agent 是什么就是那个会自己判断「现在该调哪个工具」的调度大脑。而 Spring AI 让 Java 开发者不用去啃 Node.js 生态直接用注解就能把方法注册成 MCP 工具。这套组合适合谁适合手上已经有 Spring Boot 项目、想让自己业务能力被 Claude、Cursor、CodeBuddy 这类客户端直接调用的后端同学。我试过最原始的玩法在客户端里写一堆 function call 的 JSON Schema每换一个模型平台就重写一遍集成代码。后来 MCP 协议出来理论上一次开发到处复用但早期生态几乎全是 Node.js 的 ServerJava 这边只能干看着。直到 Spring AI 把spring-ai-mcp-server-spring-boot-starter放出来Java 才算真正有了「春天」。这篇要做的闭环很具体先讲清 MCP 协议里 Client、Server、Tool 三者怎么串起来再落地一个能跑的 Spring AI MCP Server 项目最后用客户端真实调用验证。中间会给出可复制的 Maven 依赖、Tool注册代码、application.yml配置以及统一 Key 通道的 endpoint 写法。目标只有一个——你照着敲能一次跑通。需要提前说明的是MCP 的传输方式有好几种Stdio、SSE、Streamable HTTP 各有适用场景。本文聚焦 Stdio因为它最适合本地集成和命令行工具开发客户端启动时自动拉起 Server 进程通过标准输入输出通信不需要额外开端口调试也直观。理解了 Stdio 这一种其他传输方式的思路是相通的。2. 前置准备用 TaoToken 统一 Key 打通模型通道与 MCP 调用链路在动手写 Server 之前先把「模型从哪来」这件事解决掉。MCP Server 本身只负责暴露工具真正决定调不调、怎么调的是背后的大模型。如果你同时用 Claude、GPT、国产模型每个平台一套 Key、一套 Base URL管理起来很烦。TaoToken 在这里的作用就是提供统一的 API 通道一个 Key 走通多家模型省掉反复切换配置的麻烦。先拿 Key。打开官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 注册后在控制台创建 API Key。控制台地址是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite Key 列表在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。创建完记得复制保存页面刷新后就不再完整显示。拿到 Key 之后模型调用的 Base URL 统一填https://taotoken.net/api注意这个地址不带任何查询参数。如果你用的是 OpenAI 兼容的 SDK直接把它当作base_url即可如果是 Claude Code 这类工具走的是 Anthropic 兼容通道配置方式略有不同可以参考接入文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。这里要区分两个概念别搞混用途地址说明模型对话 / API 调用https://taotoken.net/api统一 Key 通道供 SDK、客户端调用模型MCP Server 本地服务无固定地址Stdio由客户端进程拉起不走网络端口也就是说TaoToken 负责「模型侧」的通道MCP Server 负责「工具侧」的能力两者通过客户端AI Agent串起来。客户端一边用 TaoToken 的 Key 调模型一边通过 Stdio 调你的 MCP Server模型决定调用哪个工具客户端负责转发。如果你打算长期做编码类 Agent 开发可以考虑 Coding Plan地址是 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 适合需要稳定额度、频繁调用的场景。想先验证模型通不通用模型对话页面 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentchatutm_campaignrewrite 发一条消息即可能正常返回就说明 Key 和通道没问题。前置准备清单JDK 17 或以上Spring AI 1.0.0-M6 要求Maven 3.9一个支持 MCP 的客户端CodeBuddy、Cursor、Claude Desktop 等TaoToken API Key用于模型侧调用一个你熟悉的业务接口本文以「发布文章」为例把这些准备好后面写代码就不会卡在环境上。3. 可复制配置Spring AI MCP Server 的 pom.xml 与 application.yml 完整片段这一节是全文最核心的可复制部分。先给pom.xml再给application.yml最后给工具注册代码。路径和文件名都按实际项目结构写你直接对照改。3.1 pom.xml 依赖配置关键依赖是spring-ai-mcp-server-spring-boot-starter配合spring-ai-bom统一版本。完整片段如下properties maven.compiler.source17/maven.compiler.source maven.compiler.target17/maven.compiler.target spring-ai.version1.0.0-M6/spring-ai.version spring-boot.version3.4.5/spring-boot.version project.build.sourceEncodingUTF-8/project.build.sourceEncoding /properties dependencies dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-mcp-server-spring-boot-starter/artifactId /dependency dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-test/artifactId scopetest/scope /dependency dependency groupIdorg.projectlombok/groupId artifactIdlombok/artifactId optionaltrue/optional /dependency dependency groupIdcom.squareup.retrofit2/groupId artifactIdretrofit/artifactId version2.9.0/version /dependency dependency groupIdcom.squareup.retrofit2/groupId artifactIdconverter-jackson/artifactId version2.9.0/version /dependency /dependencies dependencyManagement dependencies dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-bom/artifactId version${spring-ai.version}/version typepom/type scopeimport/scope /dependency /dependencies /dependencyManagement注意spring-ai-bom必须放在dependencyManagement里否则 starter 的版本会解析失败。Retrofit 是我用来调外部 HTTP 接口的你可以换成 WebClient 或 RestTemplate不影响 MCP 部分。3.2 application.yml 配置Stdio 模式下有几个必填项漏一个都启动不了spring: application: name: tencent-send-article-mcp-server main: web-application-type: none banner-mode: off ai: mcp: server: stdio: true name: tencent-send-article-mcp-server version: 1.0.0 logging: pattern: console: file: name: data/log/${spring.application.name}.log逐项说明web-application-type: none表示这不是 Web 应用不启 Tomcatbanner-mode: off关掉启动 banner因为 Stdio 模式下任何多余输出都会污染 JSON-RPC 通道stdio: true是核心开关name和version会出现在客户端看到的 Server 信息里。日志那块建议保留Stdio 模式下控制台输出会干扰协议通信写到文件里更安全。3.3 工具注册代码定义一个 Service用Tool注解标记要暴露的方法Service public class TencentArticleToolService { Resource private ITencentService iTencentService; Resource private TencentApiProperties tencentApiProperties; Tool(description 发布文章到腾讯云开发者社区) public ArticleFunctionResponse saveArticle(ArticleFunctionRequest request) { try { AddArticleRequest addArticleRequest new AddArticleRequest(); addArticleRequest.setTitle(request.getTitle()); addArticleRequest.setPlain(request.getMarkdowncontent()); addArticleRequest.setContent(addArticleRequest.getContent()); addArticleRequest.setSourceType(1); addArticleRequest.setUserSummary(request.getUserSummary()); CallAddArticleResponse call iTencentService.addArticle( tencentApiProperties.getCookie(), addArticleRequest); ResponseAddArticleResponse response call.execute(); ArticleFunctionResponse result new ArticleFunctionResponse(); if (response.isSuccessful() response.body() ! null) { result.setStatus(response.body().getStatus()); result.setArticleId(response.body().getArticleId()); result.setUrl(https://cloud.tencent.com/developer/article/ response.body().getArticleId()); } return result; } catch (Exception e) { log.error(发布失败, e); } return null; } }Tool的description很关键模型就是靠这句话判断「什么时候该调这个工具」。写得太模糊模型可能永远不调写得太长又浪费 token。建议一句话说清「做什么 对谁做」。然后在启动类里注册 ToolCallbackProviderBean public ToolCallbackProvider articleTools(TencentArticleToolService service) { return MethodToolCallbackProvider.builder() .toolObjects(service) .build(); }到这里一个最小可用的 MCP Server 就成型了。打包命令./mvnw clean install -DskipTests产物在target/目录下记住这个 jar 的绝对路径下一步客户端配置要用。4. 验证请求本地启动 MCP Server 并用客户端完成一次真实工具调用代码写完不算完得真跑起来。这一节分两步先本地启动确认 Server 能拉起再配客户端完成一次端到端调用。4.1 本地启动验证Stdio 模式的 Server 不能直接java -jar跑因为它等的是标准输入。你直接运行会看到进程挂起这是正常的。正确做法是通过客户端拉起或者用官方的 MCP Inspector 工具测试。先确认 jar 能正常加载java -Dfile.encodingUTF-8 -jar target/tencent-send-article-mcp-server-1.0.0.jar如果卡住不动、没有报错说明 Server 已经进入等待输入状态CtrlC 退出即可。如果报NoClassDefFoundError或ClassNotFoundException多半是依赖没打进去检查spring-boot-maven-plugin是否配置了 repackage。4.2 客户端配置以 CodeBuddy 为例在 MCP 配置里新增一段{ mcpServers: { tencent-send-article-mcp-server: { command: /你的JDK17路径/bin/java, args: [ -Dfile.encodingUTF-8, -jar, /你的项目路径/target/tencent-send-article-mcp-server-1.0.0.jar, --tencent.api.cookie你的Cookie值 ] } } }三个关键点command必须指向 JDK 17 以上的 java如果你系统默认是 JDK 8这里要写绝对路径args里的-Dfile.encodingUTF-8防止中文乱码--tencent.api.cookie是通过命令行参数注入配置对应ConfigurationProperties(prefix tencent.api)那个类。配置保存后客户端侧边栏应该能看到 Server 亮起。点开工具列表能看到saveArticle这个工具说明注册成功。4.3 发起一次真实调用在对话里输入类似这样的指令帮我发布一篇文章标题是「MCP Server 实战记录」内容是 Markdown 格式的一段介绍摘要是「一次跑通 Spring AI MCP Server」。模型会判断需要调用saveArticle然后客户端把参数通过 Stdio 传给 Server。Server 执行完返回结果客户端展示给你。如果返回里带了文章 ID 和 URL说明整条链路通了。这里有个细节模型传过来的markdowncontent是 Markdown 文本但目标平台要的是 ProseMirror 格式的 JSON。所以我在AddArticleRequest.getContent()里做了一层转换把 Markdown 转成 ProseMirror。这个转换器可以自己写也可以让 AI 帮你生成核心是把标题、段落、列表、代码块这些元素映射成对应的 JSON 节点。验证成功的标志有三个客户端显示工具调用成功、返回结果里有文章 ID、去目标平台能看到刚发布的文章。三个都满足闭环就算跑通了。5. 本篇常见错排查401、local proxy failed、reading choices 与 OAuth 报错对照跑不通是常态这一节把最常见的几类报错和排查思路列出来对照着看。5.1 401 Unauthorized这个报错分两种场景。如果是模型侧返回 401说明 TaoToken 的 Key 不对或过期了去控制台重新生成一个确认请求头里Authorization: Bearer key拼写正确。如果是工具侧返回 401说明你调的外部接口比如发布文章那个Cookie 失效了重新登录目标平台抓一份新的 Cookie更新到--tencent.api.cookie参数里。5.2 local proxy failed这个报错通常出现在客户端连不上 Server 的时候。排查顺序先确认command路径下的 java 能执行在终端里手动跑一遍java -version再确认 jar 路径是绝对路径且文件存在最后看args数组里的参数顺序-jar必须在 jar 路径前面。如果用了相对路径客户端的工作目录可能和你预期的不一样一律改成绝对路径最稳。5.3 reading choices 相关报错这类报错一般出现在模型返回结构解析失败的时候。常见原因是 Stdio 通道被污染了——比如 Server 启动时打印了 banner、日志输出到了 stdout。检查application.yml里banner-mode: off和web-application-type: none是否都配了日志是否写到了文件而不是控制台。Stdio 模式下stdout 只能走 JSON-RPC 消息任何多余输出都会导致客户端解析失败。5.4 OAuth 相关报错如果你用的是 Claude Code 这类走 Anthropic 通道的工具可能会遇到 OAuth 报错。这类问题多半是认证方式没选对。Claude Code 的接入方式参考文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里面区分了 API Key 和 OAuth 两种模式按你的场景选。如果只是本地开发调试用 API Key 模式更简单。5.5 工具注册了但模型不调用这不是报错但比报错更让人抓狂。原因通常是Tool的description写得太模糊模型不知道什么时候该用。解决办法是把描述写具体比如「发布文章到腾讯云开发者社区需要标题、Markdown 内容和摘要三个参数」让模型能明确判断触发条件。另外确认ToolCallbackProvider的 Bean 确实被 Spring 扫描到了可以在启动日志里搜一下工具注册信息。5.6 中文乱码Stdio 模式下中文乱码很常见根源是编码不一致。三处都要设成 UTF-8pom.xml里的project.build.sourceEncoding、启动参数里的-Dfile.encodingUTF-8、以及application.yml里的server.servlet.encoding.charset。三处对齐基本就不会乱码了。排查这类问题的通用思路是先看客户端报错信息定位是模型侧还是工具侧再看 Server 日志文件确认请求有没有到达最后用最小化配置复现逐步加回参数。别一上来就怀疑代码八成是配置问题。6. 把 MCP Server 接进你的 AI Agent 工作流到这里一个能跑的 Spring AI MCP Server 已经完成了。但单个 Server 只是起点真正的价值在于把多个 Server 串起来让 AI Agent 自己调度。回到开头的场景你有一个发布文章的 Server、一个操作文件的 Server、一个查数据库的 Server。客户端AI Agent拿到用户指令后会自己判断该调哪个、按什么顺序调。比如「把这篇草稿发布出去然后在本地的记录文件里追加一条日志」Agent 会先调发布工具再调文件工具全程不需要你写编排代码。这就是 MCP 协议最大的意义——把「工具」和「调度」解耦。如果你想继续深入几个方向可以试试。一是把 Stdio 换成 SSE 或 Streamable HTTP让 Server 能远程部署多个客户端共享二是把工具的参数校验做严用 JSON Schema 约束输入减少模型传错参数的概率三是把多个工具按业务域拆成多个 Server客户端按需加载避免一次性暴露太多工具导致模型选择困难。模型侧的统一通道还是用 TaoTokenBase URL 固定https://taotoken.net/api换模型不用改代码。工具侧就是你刚写的这个 Server加新能力就是加一个Tool方法。两边通过客户端串起来这套结构跑顺了后面加什么业务都只是重复这个模式。最后留一个实用技巧开发阶段把 Server 日志级别调到 DEBUG能看到完整的 JSON-RPC 请求和响应排查问题效率翻倍。上线前再调回 INFO避免日志文件膨胀。工具描述定期 review 一遍模型调用的准确率会随着描述优化明显提升。