1. 傳統(tǒng) Spring Boot 服務(wù)接入大模型生態(tài)的真實(shí)困境很多團(tuán)隊(duì)手里都有一套跑了三五年的 Spring Boot 業(yè)務(wù)系統(tǒng)接口穩(wěn)定、邏輯清晰但一到要接大模型就犯難。最直接的做法是在業(yè)務(wù)代碼里硬編碼調(diào)用某個(gè)模型的 SDK結(jié)果就是換模型要改代碼、加模型要加依賴、每個(gè)模型一套 Key 分散在配置文件里運(yùn)維排查時(shí)根本不知道哪個(gè)請求走了哪條通道。我見過一個(gè)項(xiàng)目光是模型鑒權(quán)配置就散落在四個(gè) yml 文件里出問題只能一個(gè)個(gè) grep。MCPModel Context Protocol出現(xiàn)之后思路變了。它不要求你把業(yè)務(wù)邏輯重寫成大模型能懂的格式而是把現(xiàn)有 HTTP 接口包裝成「工具」讓支持 MCP 的客戶端自動(dòng)發(fā)現(xiàn)并調(diào)用。Spring AI 從 1.0.0-M6 開始提供了 MCP Server 的 starter意味著一個(gè)普通的 Spring Boot 3.x 項(xiàng)目加幾個(gè)依賴、寫一個(gè)Tool注解的方法就能把自己的接口暴露成 MCP Server。原來的 Controller、Service、DAO 一行不用動(dòng)這就是標(biāo)題里說的「零代碼改造」——改造的是接入層不是業(yè)務(wù)層。但這里有個(gè)容易被忽略的環(huán)節(jié)MCP Server 本身不負(fù)責(zé)模型調(diào)用它只負(fù)責(zé)把工具描述給客戶端。真正跑模型的那一端鑒權(quán)和通道管理還是散的。所以本文的落地路徑是兩段前半段用 Spring AI MCP 把傳統(tǒng)服務(wù)變成可被發(fā)現(xiàn)的工具提供方后半段用 TaoToken 的統(tǒng)一 Key 和 API 通道把模型調(diào)用這一側(cè)的鑒權(quán)收攏到一個(gè)地方。這樣整條鏈路是客戶端 → MCP Server你的 Spring Boot 服務(wù)→ 業(yè)務(wù)接口以及客戶端 → 模型通道TaoToken→ 大模型。兩邊各管各的互不污染。適合誰看手上有 Spring Boot 3.x 項(xiàng)目、想讓現(xiàn)有接口被大模型或 AI 客戶端調(diào)用的后端同學(xué)正在做企業(yè)內(nèi)部 AI 助手、需要把內(nèi)部系統(tǒng)能力接進(jìn)去的架構(gòu)同學(xué)以及被多模型 Key 管理折磨過、想找個(gè)統(tǒng)一入口的運(yùn)維同學(xué)。下面從環(huán)境準(zhǔn)備開始一步步給可復(fù)制的配置。2. TaoToken 統(tǒng)一 Key 與 API 通道的前置準(zhǔn)備在寫 MCP Server 之前先把模型調(diào)用這一側(cè)的通道理清楚。原因很簡單MCP Server 暴露出去之后客戶端會(huì)頻繁調(diào)用模型來理解工具返回、決定下一步調(diào)哪個(gè)工具。如果每個(gè)客戶端、每個(gè)環(huán)境都配一套模型 Key很快就會(huì)亂。TaoToken 在這里的角色是統(tǒng)一入口——你只需要在它這里拿一個(gè) Key后面無論客戶端用哪個(gè)模型都走同一個(gè) Base URL 和同一個(gè) Key。先明確三個(gè)東西后面配置里會(huì)反復(fù)出現(xiàn)Base URL 用https://taotoken.net/api注意這個(gè)地址不帶任何查詢參數(shù)是純 API 端點(diǎn)。Key 在控制臺(tái)的 API Keys 頁面創(chuàng)建創(chuàng)建后只顯示一次復(fù)制下來存好。Model ID 按你實(shí)際要用的模型填比如做代碼理解可以用 claude 系列做通用對話可以用 gpt 系列具體以控制臺(tái)模型列表為準(zhǔn)。操作路徑是這樣的打開 https://taotoken.net/api-keys 創(chuàng)建 Key然后到 https://taotoken.net/doc 看接入文檔確認(rèn)當(dāng)前支持的模型名和參數(shù)格式。如果你后面要長期跑編碼類 Agent可以順帶看下 https://taotoken.net/coding-plan 它針對高頻編碼場景做了通道優(yōu)化比按次調(diào)用更劃算。想先驗(yàn)證模型通不通直接去 https://taotoken.net/model-chat 發(fā)一條消息能返回就說明 Key 和通道沒問題。這里有個(gè)細(xì)節(jié)要注意MCP Server 本身不直接調(diào)模型所以 Spring Boot 項(xiàng)目里其實(shí)不需要配 TaoToken 的 Key。TaoToken 的 Key 是配在「客戶端」那一側(cè)的——也就是 Cursor、Cline、Claude Code 這些支持 MCP 的工具里。很多同學(xué)第一次做會(huì)搞混把模型 Key 塞進(jìn) Spring Boot 的 application.yml結(jié)果 MCP Server 啟動(dòng)正常但客戶端調(diào)模型時(shí) 401。記住分工Spring Boot 管工具暴露TaoToken 管模型鑒權(quán)。如果你用的是 Claude Code 這類命令行客戶端它的配置方式和 GUI 客戶端不同需要單獨(dú)設(shè)置環(huán)境變量或配置文件。這部分在第四節(jié)驗(yàn)證環(huán)節(jié)會(huì)給出具體寫法?，F(xiàn)在先把 Spring Boot 這邊的依賴和配置搭起來。3. Spring AI MCP Server 可復(fù)制配置與依賴環(huán)境基線定死Spring Boot 3.4.2 JDK 17。Spring AI 的 MCP starter 對 Spring Boot 版本有要求3.4.2 是當(dāng)前驗(yàn)證過的組合別用 3.2 以下會(huì)缺自動(dòng)配置類。MCP Server 的傳輸方式有三種本文選 Spring MVC SSE原因是它和傳統(tǒng) Web 應(yīng)用集成最自然你原來的 Tomcat 線程模型不用改調(diào)試也方便瀏覽器直接能看 SSE 流。先看 Maven 依賴。父 POM 里用 dependencyManagement 鎖版本然后引入 MCP Server 的 webmvc starterdependencyManagement dependencies dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-dependencies/artifactId version3.4.2/version typepom/type scopeimport/scope /dependency /dependencies /dependencyManagement dependencies dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-mcp-server-webmvc-spring-boot-starter/artifactId version1.0.0-M6/version /dependency dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency dependency groupIdorg.projectlombok/groupId artifactIdlombok/artifactId optionaltrue/optional /dependency /dependencies注意 artifactId 是spring-ai-mcp-server-webmvc-spring-boot-starter不是spring-ai-starter-mcp-server-webmvc這兩個(gè)名字在不同版本里出現(xiàn)過M6 用的是前者。寫錯(cuò)了會(huì)報(bào)找不到依賴。然后是 application.yml。這里的關(guān)鍵是spring.ai.mcp.server這一段type 用 SYNCsse-endpoint 指定 SSE 的路徑spring: application: name: smd-mcp-server ai: mcp: server: name: smd-mcp-server version: 1.0.0 type: SYNC sse-endpoint: /sse server: port: 8089 smd: service: url: http://localhost:8080smd.service.url是你原有業(yè)務(wù)服務(wù)的地址MCP Server 通過 HTTP 轉(zhuǎn)發(fā)調(diào)用它。這樣做的意義是MCP Server 和業(yè)務(wù)服務(wù)可以分開部署業(yè)務(wù)服務(wù)該干嘛干嘛MCP Server 只做協(xié)議轉(zhuǎn)換。接下來是工具類。核心是用Tool注解標(biāo)記方法ToolParam描述參數(shù)Spring AI 會(huì)自動(dòng)把這些方法注冊成 MCP 工具Service public class SmdMcpService { Autowired private RestTemplate restTemplate; Value(${smd.service.url}) private String smdServiceUrl; Tool(name getSmdInfo, description 獲取表結(jié)構(gòu)信息) public String getSmdInfo( ToolParam(description 業(yè)務(wù)系統(tǒng)) String businessSystem, ToolParam(description 表名) SetString tableNames) { MapString, Object params new HashMap(); params.put(businessSystem, businessSystem); params.put(tableNames, tableNames); ResponseEntityString response restTemplate.postForEntity( smdServiceUrl /mcp/api/getSmdInfo, params, String.class); return response.getBody(); } Tool(name getCRUDCode, description 根據(jù)表名生成增刪改查代碼) public ListMapString, Object getCRUDByTable( ToolParam(description 業(yè)務(wù)系統(tǒng)) String businessSystem, ToolParam(description 表名) SetString tableNames, ToolParam(description 模塊名非必填) String moduleName) { MapString, Object params new HashMap(); params.put(businessSystem, businessSystem); params.put(tableNames, tableNames); params.put(moduleName, moduleName); params.put(author, smd-mcp); HttpEntityMapString, Object httpEntity new HttpEntity(params); ResponseEntityListMapString, Object response restTemplate.exchange( smdServiceUrl /mcp/api/crud, HttpMethod.POST, httpEntity, new ParameterizedTypeReferenceListMapString, Object() {}); return response.getBody(); } }最后是注冊配置把工具類交給 MCP 框架Configuration Slf4j public class McpConfig { Bean public ToolCallbackProvider smdToolCallbackProvider(SmdMcpService smdMcpService) { return MethodToolCallbackProvider.builder() .toolObjects(smdMcpService) .build(); } }到這里 Spring Boot 側(cè)的配置就齊了。啟動(dòng)后訪問http://localhost:8089/sse如果看到 SSE 流保持連接說明 MCP Server 起來了。注意 SSE 是長連接用瀏覽器直接打開會(huì)一直轉(zhuǎn)圈這是正常的用 curl 加-N參數(shù)能看到事件流。4. 驗(yàn)證 MCP 工具調(diào)用鏈路與客戶端配置服務(wù)起來之后要驗(yàn)證工具能不能被客戶端發(fā)現(xiàn)和調(diào)用。這里分兩步先驗(yàn)證 MCP Server 本身再驗(yàn)證客戶端到模型的整條鏈路。第一步用 curl 確認(rèn) SSE 端點(diǎn)活著curl -N http://localhost:8089/sse正常會(huì)返回類似event: endpoint和data: /mcp/message?sessionIdxxx的內(nèi)容。這個(gè) sessionId 后面客戶端會(huì)用到。第二步配置客戶端。以 Cursor 或 Trae 這類支持 MCP 的工具為例在 mcp.json 里加{ mcpServers: { smd-mcp-server: { url: http://localhost:8089/sse, env: { API_KEY: 你的TaoToken Key } } } }注意這里的 API_KEY 是給客戶端調(diào)模型用的走的是 TaoToken 的通道。客戶端在理解工具返回、決定下一步調(diào)用時(shí)會(huì)拿這個(gè) Key 去請求模型。所以這個(gè) Key 必須是 TaoToken 控制臺(tái)創(chuàng)建的那個(gè)Base URL 在客戶端設(shè)置里填https://taotoken.net/api。如果你用的是 Claude Code配置方式不一樣它讀的是環(huán)境變量或 settings 文件。在項(xiàng)目根目錄建.claude/settings.json{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: 你的TaoToken Key } }然后在 Claude Code 里通過 MCP 配置命令添加 server指向http://localhost:8089/sse。這樣 Claude Code 既能調(diào)模型又能發(fā)現(xiàn)你 Spring Boot 服務(wù)暴露的工具。配置完成后在客戶端里問一句「幫我看看 user 表的結(jié)構(gòu)」如果 MCP 鏈路通了客戶端會(huì)先調(diào)用getSmdInfo工具拿到表結(jié)構(gòu)再讓模型組織語言返回。你可以在 Spring Boot 控制臺(tái)看到對應(yīng)的 HTTP 轉(zhuǎn)發(fā)日志說明工具被真實(shí)調(diào)用了。這一步常見的成功標(biāo)志是客戶端工具列表里出現(xiàn)getSmdInfo和getCRUDCode并且調(diào)用后返回的是你業(yè)務(wù)接口的真實(shí)數(shù)據(jù)而不是模型編的。如果返回的是模型編的內(nèi)容說明工具沒被發(fā)現(xiàn)客戶端直接讓模型瞎猜了。5. 本篇常見報(bào)錯(cuò)排查401、local proxy failed、reading choices做這個(gè)鏈路報(bào)錯(cuò)基本集中在幾個(gè)地方。我按實(shí)際遇到的頻率排一下。401 Unauthorized。這個(gè)幾乎都是 Key 或 Base URL 配錯(cuò)。先確認(rèn)客戶端里填的 Base URL 是https://taotoken.net/api不是首頁地址也不是帶 UTM 的地址。然后確認(rèn) Key 是從 https://taotoken.net/api-keys 創(chuàng)建的沒有多余空格。如果用的是 Claude Code檢查ANTHROPIC_BASE_URL和ANTHROPIC_API_KEY兩個(gè)環(huán)境變量都設(shè)了只設(shè)一個(gè)也會(huì) 401。local proxy failed。這個(gè)報(bào)錯(cuò)通常出現(xiàn)在客戶端試圖連接 MCP Server 時(shí)。先確認(rèn) Spring Boot 服務(wù)真的在 8089 端口監(jiān)聽curl -N http://localhost:8089/sse能返回事件流。如果服務(wù)沒起來檢查spring-ai-mcp-server-webmvc-spring-boot-starter依賴是否引入成功啟動(dòng)日志里有沒有MCP Server started之類的字樣。另一個(gè)原因是端口被占換個(gè)端口重試。reading choices 相關(guān)報(bào)錯(cuò)。這個(gè)一般出現(xiàn)在模型返回格式不符合預(yù)期時(shí)根因往往是模型 ID 填錯(cuò)或者客戶端把非 chat 模型的響應(yīng)當(dāng) chat 解析。去 https://taotoken.net/doc 確認(rèn)當(dāng)前模型列表把 Model ID 改成文檔里明確支持的。如果用的是 coding-plan 通道確認(rèn)調(diào)用方式符合它的約定。工具被發(fā)現(xiàn)但調(diào)用返回空。檢查smd.service.url指向的業(yè)務(wù)服務(wù)是否可達(dá)以及業(yè)務(wù)接口的路徑、參數(shù)名是否和Tool方法里寫的一致。MCP Server 只是轉(zhuǎn)發(fā)業(yè)務(wù)接口 404 它也會(huì)把 404 的 body 返回給客戶端。SSE 連接頻繁斷開。Spring MVC 的 SSE 默認(rèn)超時(shí)時(shí)間可能偏短可以在 application.yml 里加spring.mvc.async.request-timeout: 300000延長到 5 分鐘。另外確認(rèn)沒有中間層比如某些網(wǎng)關(guān)把長連接掐了。排查順序建議先 curl SSE 確認(rèn) MCP Server 活著再在客戶端里看工具列表有沒有出現(xiàn)最后發(fā)一條會(huì)觸發(fā)工具調(diào)用的消息看日志。三步定位比盲目改配置快得多。6. 把統(tǒng)一 Key 通道用起來的后續(xù)路徑整條鏈路跑通之后你會(huì)發(fā)現(xiàn)真正省事的地方在于Spring Boot 那邊完全不用管模型是誰、Key 是什么它只負(fù)責(zé)把工具暴露好客戶端那邊只認(rèn)一個(gè) TaoToken 的 Base URL 和 Key換模型只改 Model ID不用動(dòng) MCP 配置。這種分工讓后續(xù)擴(kuò)展變得簡單——再加一個(gè)業(yè)務(wù)工具就在SmdMcpService里加一個(gè)Tool方法再加一個(gè)客戶端就復(fù)制一份 mcp.json 改個(gè)名字。如果你打算把這個(gè)模式用到團(tuán)隊(duì)里建議把 MCP Server 的配置模板化application.yml里的smd.service.url按環(huán)境注入工具類按業(yè)務(wù)域拆成多個(gè) Service每個(gè) Service 一個(gè)ToolCallbackProvider。這樣不同業(yè)務(wù)線可以各自維護(hù)自己的工具互不影響。模型通道這邊短期驗(yàn)證用 https://taotoken.net/model-chat 就夠長期跑編碼類任務(wù)可以看 https://taotoken.net/coding-plan 的通道策略。Key 的管理統(tǒng)一在 https://taotoken.net/api-keys 做接入細(xì)節(jié)以 https://taotoken.net/doc 為準(zhǔn)。把這兩側(cè)都收攏好傳統(tǒng)服務(wù)接大模型這件事就從「每個(gè)項(xiàng)目重來一遍」變成了「配一次到處復(fù)用」。