1. Spring AI MCP 服務(wù)端接入模型通道時(shí)到底卡在哪如果你正在用 Spring AI 寫 MCP 服務(wù)端大概率會(huì)遇到一個(gè)很具體的場(chǎng)景工具方法寫好了Tool注解也加了ToolCallbackProvider也注冊(cè)成 Bean 了但服務(wù)端一啟動(dòng)模型側(cè)就是沒反應(yīng)。日志里翻來翻去要么是連接超時(shí)要么是 401要么是reading choices解析失敗。問題往往不在 MCP 協(xié)議本身而在服務(wù)端到模型服務(wù)這一段通道沒有配通。Spring AI MCP 服務(wù)端本質(zhì)上是一個(gè)“工具暴露層”。它把 Java 方法包裝成 MCP 工具通過 STDIO 或 SSE 傳輸層暴露給客戶端。但工具要被模型調(diào)用服務(wù)端自己得先能訪問模型服務(wù)。也就是說MCP 服務(wù)端同時(shí)扮演兩個(gè)角色對(duì)客戶端它是工具提供方對(duì)模型服務(wù)它是調(diào)用方。很多人只關(guān)注了前者忽略了后者結(jié)果就是工具注冊(cè)成功、SSE 端點(diǎn)也能連上但模型請(qǐng)求發(fā)不出去。這篇面向的是本地開發(fā)與聯(lián)調(diào)場(chǎng)景。你不需要先搞一套復(fù)雜的網(wǎng)關(guān)也不需要把每個(gè)模型廠商的 SDK 都接一遍。核心思路是用統(tǒng)一的 Key 和統(tǒng)一的 API 通道讓 Spring AI MCP 服務(wù)端通過一套配置同時(shí)完成“工具暴露”和“模型調(diào)用”兩件事。配置一次服務(wù)端到模型的請(qǐng)求鏈路就能跑通。適合誰看正在用 Spring AI 1.0 以上版本寫 MCP 服務(wù)端的 Java 開發(fā)者需要本地聯(lián)調(diào) MCP 工具與模型交互的后端同學(xué)以及想把現(xiàn)有 Spring Boot 服務(wù)快速改造成 MCP 服務(wù)端的團(tuán)隊(duì)。下面會(huì)給出可復(fù)制的application.yml、Maven 依賴、啟動(dòng)參數(shù)以及一次完整的調(diào)用驗(yàn)證動(dòng)作。你照著做能少走不少?gòu)澛贰?. TaoToken 統(tǒng)一 Key 與 API 通道的前置準(zhǔn)備在動(dòng)手改配置之前先把“統(tǒng)一 Key 與 API 通道”這件事說清楚。Spring AI 本身支持多種模型服務(wù)但不同廠商的 Base URL、鑒權(quán)頭、模型 ID 格式都不一樣。如果你在 MCP 服務(wù)端里直接寫死某一家后面換模型就得改代碼。更麻煩的是MCP 服務(wù)端通常還要同時(shí)處理工具調(diào)用和普通對(duì)話如果通道不統(tǒng)一聯(lián)調(diào)時(shí)很難判斷問題出在工具層還是模型層。TaoToken 在這里的角色是一個(gè)統(tǒng)一的 API 通道。你只需要一個(gè) Key就可以通過同一個(gè) Base URL 訪問不同的模型。對(duì) Spring AI 來說這意味著spring.ai.openai.base-url和spring.ai.openai.api-key可以固定下來模型 ID 通過配置切換。MCP 服務(wù)端的工具注冊(cè)邏輯完全不用動(dòng)換模型只是改一行配置。前置準(zhǔn)備分三步。第一步拿到 Key。訪問https://taotoken.net/api-keys在控制臺(tái)里創(chuàng)建一個(gè) API Key。注意這個(gè) Key 只在創(chuàng)建時(shí)完整顯示一次復(fù)制后先存到本地環(huán)境變量里不要直接寫進(jìn)代碼倉(cāng)庫(kù)。第二步確認(rèn) Base URL。TaoToken 的 API 入口是https://taotoken.net/api這個(gè)地址后面會(huì)用在application.yml里。第三步確認(rèn)你要用的模型 ID。不同模型在工具調(diào)用能力上差異很大MCP 場(chǎng)景建議選支持 function calling 的模型否則Tool注冊(cè)了也不會(huì)被調(diào)用。這里有個(gè)容易踩的坑Spring AI 的 OpenAI 兼容層默認(rèn)會(huì)拼接/v1/chat/completions。如果你填的 Base URL 末尾多了斜杠或者少了路徑請(qǐng)求就會(huì) 404。TaoToken 的 API 地址是https://taotoken.net/apiSpring AI 會(huì)自動(dòng)補(bǔ)全后續(xù)路徑所以配置里不要手動(dòng)加/v1。另外Key 建議通過環(huán)境變量注入比如TAOTOKEN_API_KEY這樣本地聯(lián)調(diào)和 CI 環(huán)境可以用同一套配置。如果你還沒決定用哪個(gè)模型可以先到模型對(duì)話頁面試一下工具調(diào)用效果。地址是https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite。在對(duì)話里發(fā)一個(gè)需要調(diào)用工具的問題看模型是否能正確返回 tool_calls。這一步能幫你提前排除模型不支持工具調(diào)用的情況省得后面在 Spring AI 里反復(fù)調(diào)試。3. 可復(fù)制的 application.yml 與 Maven 配置片段這一節(jié)是核心。我會(huì)給出完整的 Maven 依賴和application.yml你可以直接復(fù)制到項(xiàng)目里。先看依賴。Spring AI MCP 服務(wù)端有三種傳輸方式STDIO、WebMVC SSE、WebFlux SSE。本地聯(lián)調(diào)最常用的是 WebMVC SSE因?yàn)樗詭?HTTP 端點(diǎn)方便用 curl 或 Postman 驗(yàn)證。Maven 配置如下dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-starter-mcp-server-webmvc/artifactId /dependency dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-starter-model-openai/artifactId /dependency第一個(gè)依賴提供 MCP 服務(wù)端自動(dòng)配置和 SSE 傳輸層第二個(gè)依賴提供 OpenAI 兼容的模型客戶端。兩個(gè)都加上才能同時(shí)完成工具暴露和模型調(diào)用。版本方面Spring AI 1.0.0 及以上都支持建議用最新的穩(wěn)定版。接下來是application.yml。這份配置同時(shí)覆蓋了 MCP 服務(wù)端和模型通道兩部分server: port: 8080 spring: ai: openai: base-url: https://taotoken.net/api api-key: ${TAOTOKEN_API_KEY} chat: options: model: gpt-4o-mini temperature: 0.7 mcp: server: name: spring-ai-mcp-server version: 1.0.0 type: SYNC instructions: This server provides weather and time tools sse-message-endpoint: /mcp/messages capabilities: tool: true resource: true prompt: true completion: true request-timeout: 30s幾個(gè)關(guān)鍵點(diǎn)解釋一下。base-url填https://taotoken.net/api不要加/v1。api-key用環(huán)境變量注入啟動(dòng)前先export TAOTOKEN_API_KEY你的Key。model填你要用的模型 ID比如gpt-4o-mini或claude-3-5-sonnet具體支持列表可以在文檔里查。type: SYNC表示同步模式本地聯(lián)調(diào)夠用如果你的工具方法里有阻塞操作可以改成ASYNC。sse-message-endpoint是客戶端發(fā)送消息的路徑默認(rèn)是/mcp/messages保持默認(rèn)即可。如果你用的是 STDIO 傳輸配置會(huì)不一樣。STDIO 模式不需要server.port也不需要 SSE 端點(diǎn)但需要把spring.ai.mcp.server.stdio設(shè)為true。不過 STDIO 模式下模型調(diào)用仍然走spring.ai.openai那一段所以 Base URL 和 Key 的配置是一樣的。本地聯(lián)調(diào)建議先用 WebMVC SSE因?yàn)榭梢灾苯佑?HTTP 請(qǐng)求驗(yàn)證不用掛客戶端。還有一個(gè)細(xì)節(jié)request-timeout默認(rèn)是 20 秒我改成了 30 秒。因?yàn)楣ぞ哒{(diào)用加上模型推理有時(shí)候會(huì)超過 20 秒尤其是模型在決定是否調(diào)用工具時(shí)。如果你發(fā)現(xiàn)請(qǐng)求偶爾超時(shí)可以適當(dāng)調(diào)大這個(gè)值。但也不要設(shè)太大否則客戶端會(huì)一直等。配置寫完后啟動(dòng)類里需要注冊(cè)ToolCallbackProvider。參考代碼如下SpringBootApplication public class McpServerApplication { public static void main(String[] args) { SpringApplication.run(McpServerApplication.class, args); } Bean public ToolCallbackProvider weatherTools(WeatherService weatherService) { return MethodToolCallbackProvider.builder() .toolObjects(weatherService) .build(); } }WeatherService里用Tool注解標(biāo)記方法。這樣 MCP 服務(wù)端啟動(dòng)時(shí)會(huì)自動(dòng)掃描這些工具并注冊(cè)到 SSE 端點(diǎn)。模型側(cè)通過spring.ai.openai的配置訪問 TaoToken 通道工具調(diào)用請(qǐng)求會(huì)帶著工具定義一起發(fā)給模型。4. 啟動(dòng)服務(wù)端并完成一次完整調(diào)用驗(yàn)證配置就緒后啟動(dòng)服務(wù)端。在項(xiàng)目根目錄執(zhí)行export TAOTOKEN_API_KEY你的Key ./mvnw spring-boot:run啟動(dòng)日志里會(huì)看到McpWebMvcServerAutoConfiguration和McpServerAutoConfiguration被激活SSE 端點(diǎn)注冊(cè)在/sse消息端點(diǎn)在/mcp/messages。如果看到Tomcat started on port 8080說明服務(wù)端起來了。接下來驗(yàn)證模型通道。先確認(rèn)服務(wù)端能訪問 TaoToken。用一個(gè)簡(jiǎn)單的 curl 測(cè)試curl -X POST https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -H Content-Type: application/json \ -d { model: gpt-4o-mini, messages: [{role: user, content: 你好}] }如果返回正常的choices結(jié)構(gòu)說明 Key 和通道沒問題。如果返回 401檢查 Key 是否復(fù)制完整如果返回 404檢查 Base URL 是否多了/v1。然后驗(yàn)證 MCP 服務(wù)端的工具調(diào)用。先連上 SSE 端點(diǎn)curl -N http://localhost:8080/sse這個(gè)命令會(huì)保持連接你會(huì)看到類似event: endpoint和data: /mcp/messages?sessionIdxxx的輸出。記下sessionId然后另開一個(gè)終端發(fā)送一個(gè)工具調(diào)用請(qǐng)求curl -X POST http://localhost:8080/mcp/messages?sessionId你的sessionId \ -H Content-Type: application/json \ -d { jsonrpc: 2.0, id: 1, method: tools/call, params: { name: getWeather, arguments: {cityName: 北京} } }如果工具方法正確注冊(cè)你會(huì)收到工具執(zhí)行結(jié)果。但這一步只驗(yàn)證了工具層還沒驗(yàn)證模型層。要驗(yàn)證模型是否真的能通過 TaoToken 調(diào)用工具需要在 Spring AI 里發(fā)一個(gè)帶工具的對(duì)話請(qǐng)求。最簡(jiǎn)單的方式是寫一個(gè)CommandLineRunner在啟動(dòng)后自動(dòng)發(fā)一條消息Bean public CommandLineRunner testModelCall(ChatClient.Builder builder) { return args - { String response builder.build() .prompt(北京今天天氣怎么樣) .tools(new WeatherService()) .call() .content(); System.out.println(模型返回: response); }; }啟動(dòng)后觀察控制臺(tái)。如果模型返回了天氣信息說明整條鏈路通了Spring AI 把工具定義發(fā)給 TaoToken 通道模型決定調(diào)用getWeather工具執(zhí)行后結(jié)果回傳給模型模型生成最終回答。如果模型沒有調(diào)用工具檢查Tool的description是否足夠清晰以及模型是否支持 function calling。實(shí)測(cè)下來最容易出問題的是模型 ID 和工具描述。有些模型對(duì)工具描述很敏感描述太模糊就不會(huì)調(diào)用。另外temperature設(shè)太高也會(huì)影響工具調(diào)用的穩(wěn)定性聯(lián)調(diào)階段建議設(shè)成 0.2 到 0.7 之間。5. 常見報(bào)錯(cuò)排查401、local proxy failed、reading choices聯(lián)調(diào)過程中會(huì)遇到幾類典型報(bào)錯(cuò)這里逐一拆解。第一類401 Unauthorized。這個(gè)最直接Key 不對(duì)或者沒傳。檢查TAOTOKEN_API_KEY環(huán)境變量是否生效可以在啟動(dòng)日志里搜索api-key確認(rèn)。如果用的是 IDE 啟動(dòng)注意 IDE 的環(huán)境變量配置可能和終端不一樣。另外Key 如果包含特殊字符YAML 里要用引號(hào)包起來。還有一種情況是 Key 被禁用或額度用完去控制臺(tái)確認(rèn)一下狀態(tài)。第二類local proxy failed或連接超時(shí)。這個(gè)報(bào)錯(cuò)通常出現(xiàn)在服務(wù)端無法訪問taotoken.net的時(shí)候。先確認(rèn)本機(jī)網(wǎng)絡(luò)能正常訪問外網(wǎng)然后檢查base-url是否寫錯(cuò)。注意不要配置任何本地代理相關(guān)的環(huán)境變量Spring AI 的 HTTP 客戶端會(huì)讀取系統(tǒng)代理設(shè)置如果代理配置有問題請(qǐng)求會(huì)直接失敗?？梢耘R時(shí)取消HTTP_PROXY和HTTPS_PROXY環(huán)境變量再試。第三類reading choices解析失敗。這個(gè)報(bào)錯(cuò)說明請(qǐng)求發(fā)出去了但返回的 JSON 結(jié)構(gòu)不符合 OpenAI 格式。常見原因有兩個(gè)一是 Base URL 路徑不對(duì)比如填了https://taotoken.net/api/v1Spring AI 又拼了一次/v1導(dǎo)致請(qǐng)求打到了錯(cuò)誤的路由二是模型 ID 不存在服務(wù)端返回了錯(cuò)誤信息而不是正常的choices數(shù)組。檢查base-url只保留https://taotoken.net/api模型 ID 從文檔里復(fù)制不要手寫。第四類OAuth 或鑒權(quán)頭沖突。如果你在項(xiàng)目里同時(shí)引入了其他模型 SDK可能會(huì)有多個(gè)Authorization頭。Spring AI 的 OpenAI 客戶端默認(rèn)用Bearer方式如果和其他客戶端的配置沖突請(qǐng)求會(huì)被拒絕。檢查application.yml里是否有多余的spring.ai配置只保留一份。第五類工具注冊(cè)了但模型不調(diào)用。這個(gè)不是報(bào)錯(cuò)但很常見。先確認(rèn)模型支持 function calling然后在Tool的description里寫清楚“什么時(shí)候用這個(gè)工具”。比如“Get weather information by city name”就比“weather”好很多。另外ToolParam的description也要寫模型需要知道參數(shù)格式。排查時(shí)建議打開 Spring AI 的 debug 日志logging: level: org.springframework.ai: DEBUG這樣能看到完整的請(qǐng)求和響應(yīng)體定位問題會(huì)快很多。如果日志里看到請(qǐng)求發(fā)出去了但響應(yīng)是空的大概率是模型側(cè)的問題換個(gè)模型 ID 試試。6. 統(tǒng)一通道下的后續(xù)擴(kuò)展與接入入口鏈路跑通之后你可以在這個(gè)基礎(chǔ)上做幾件事。第一把模型 ID 抽成配置項(xiàng)通過 Spring Profile 切換不同模型比如application-dev.yml用輕量模型application-prod.yml用能力更強(qiáng)的模型。第二把工具方法按業(yè)務(wù)域拆分每個(gè)域一個(gè)ToolCallbackProvider這樣 MCP 服務(wù)端的工具列表會(huì)更清晰。第三如果你要長(zhǎng)期跑編碼類 Agent可以考慮用 Coding Plan地址是https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite它針對(duì)長(zhǎng)時(shí)間編碼場(chǎng)景做了通道優(yōu)化。接入文檔在https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite里面有各語言 SDK 的配置示例和模型列表。如果你在配置過程中遇到 Key 或通道問題先去 API Keys 頁面確認(rèn) Key 狀態(tài)地址是https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite?？刂婆_(tái)入口是https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite可以查看調(diào)用量和余額。最后提醒一點(diǎn)MCP 服務(wù)端的工具方法不要直接連生產(chǎn)數(shù)據(jù)庫(kù)。本地聯(lián)調(diào)階段用 mock 數(shù)據(jù)或者測(cè)試庫(kù)等鏈路穩(wěn)定后再考慮接入真實(shí)數(shù)據(jù)源。工具方法的返回值盡量保持結(jié)構(gòu)簡(jiǎn)單復(fù)雜的嵌套對(duì)象會(huì)增加模型解析的負(fù)擔(dān)也容易導(dǎo)致reading choices類錯(cuò)誤。配置一次跑通之后后面換模型、加工具都只是改配置和加注解的事不用再動(dòng)通道層。