1. 從 stdio 到 Streamable HTTP為什么要把 MCP Server 的 endpoint 改到 TaoToken如果你已經(jīng)用 Spring AI 寫過 stdio 版本的 MCP Server大概率會遇到一個尷尬本地 IDE 能跑但一旦想讓遠程客戶端、團隊其他成員或者 CI 環(huán)境調(diào)用stdio 的進程間通信模型就完全不夠用了。stdio 的本質(zhì)是 MCP Client 和 MCP Server 跑在同一臺主機上靠標準輸入輸出做 JSON-RPC 2.0 的消息交換適合本地工具接入但沒法跨網(wǎng)絡(luò)。Streamable HTTP 就是來解決這個問題的。它基于 HTTP 協(xié)議MCP Client 可以遠程調(diào)用 MCP Server 暴露的 endpoint服務(wù)端通過流式響應(yīng)把工具調(diào)用結(jié)果推回來。相比早期的 SSE 方案Streamable HTTP 的通信模型更統(tǒng)一新版本的客戶端和服務(wù)端都更偏向它。Spring AI 從 1.1.x 開始對 Streamable HTTP 的支持已經(jīng)比較完整依賴是spring-ai-starter-mcp-server-webmvc底層走 Servlet 棧。那為什么要把 endpoint 改到 TaoToken因為 MCP Server 本身只負責(zé)暴露工具真正要驗證工具調(diào)用鏈路是否正常需要一個能發(fā)起模型請求的客戶端。TaoToken 提供統(tǒng)一的 API endpoint兼容主流模型調(diào)用格式你可以把 MCP Client 的模型請求指向 TaoToken讓模型來決定調(diào)用哪個工具、傳什么參數(shù)然后觀察 Streamable HTTP 的流式返回是否正常。這樣整條鏈路——模型決策、工具調(diào)用、流式響應(yīng)——就都能在真實請求下驗證。這篇面向的是已經(jīng)了解 MCP 基本概念、想動手把 Spring AI MCP Server 跑起來并完成端到端測試的 Java 開發(fā)者。我會從依賴引入開始給出可復(fù)制的application.yml、工具注冊代碼、MCP 客戶端配置片段然后演示把 endpoint 改到 TaoToken 后用 curl 和單元測試驗證工具調(diào)用與流式返回。整個過程我試過幾輪踩過的坑會放在排障章節(jié)里。2. TaoToken 前置準備API Key、Base URL 與模型 ID 三件套在寫代碼之前先把 TaoToken 這邊的接入信息準備好。不管你是用 Cline、Claude Code 還是自己寫的 MCP Client核心就是三件套Base URL、API Key、Model ID。這三個東西缺一個請求就會在鑒權(quán)或路由階段掛掉。Base URL 用https://taotoken.net/api注意這個地址不帶任何查詢參數(shù)直接作為 API 根路徑。API Key 需要到控制臺創(chuàng)建路徑是 console 頁面下的 api-keys 管理。創(chuàng)建的時候建議按項目命名比如spring-ai-mcp-demo方便后面排查是哪個 key 在調(diào)用。Model ID 根據(jù)你要用的模型填比如claude-sonnet-4-20250514這類標識具體以模型列表頁為準。如果你用的是 Claude Code 這類工具配置方式會略有不同。Claude Code 的接入文檔在 doc 頁面有詳細說明核心是把 Base URL 指向 TaoToken 的 API 地址然后填入 Key。對于 Spring AI 的 MCP Client我們是在application.yml里配置spring.ai.openai.base-url和spring.ai.openai.api-key模型名通過spring.ai.openai.chat.options.model指定。這里有個容易混淆的點MCP Server 的 endpoint 和模型 API 的 endpoint 是兩個不同的東西。MCP Server 暴露的是/mcp這個路徑供 MCP Client 調(diào)用工具而 TaoToken 的/api是模型推理接口供 MCP Client 內(nèi)部的 ChatClient 調(diào)用。兩者不要搞混。我們在application-http.yml里配置的mcp-endpoint: /mcp是前者TaoToken 的 Base URL 是后者。另外如果你打算長期跑編碼類 Agent 任務(wù)可以了解下 Coding Plan它針對高頻編碼場景做了額度優(yōu)化。單純驗證工具調(diào)用的話按量調(diào)用模型對話接口就夠了。需要先拿到 Key 的話直接去 API Keys 頁面創(chuàng)建然后對照接入文檔確認參數(shù)格式。3. 可復(fù)制配置application.yml、工具注冊與 MCP 客戶端片段這一節(jié)給出完整的可復(fù)制配置。工程結(jié)構(gòu)是標準的 Spring Boot Maven 項目Java 17Spring Boot 3.4.xSpring AI 1.1.4。pom 里需要引入spring-ai-starter-mcp-server-webmvc來啟用 Streamable HTTP 模式同時引入spring-ai-starter-model-openai作為 MCP Client 側(cè)的模型調(diào)用依賴。先看application.yml的主配置spring: application: name: java-mcp-server-demo profiles: active: http ai: mcp: server: name: java-mcp-server-demo version: 0.0.1 type: SYNC instructions: | This server provides demo tools for Java MCP development. Use getWeather for city weather lookup and sumNumbers for calculation.然后是application-http.yml這是 Streamable HTTP 模式的核心配置spring: config: activate: on-profile: http main: web-application-type: servlet ai: mcp: server: protocol: STREAMABLE streamable-http: mcp-endpoint: /mcp server: port: 8080注意protocol: STREAMABLE和mcp-endpoint: /mcp這兩行前者指定傳輸協(xié)議后者定義 MCP Client 要訪問的路徑。啟動后完整的 endpoint 是http://localhost:8080/mcp。工具類用Tool和ToolParam注解標記Service public class WeatherService { Tool(name getWeather, description 根據(jù)城市名稱獲取天氣信息) public String getWeather( ToolParam(description 城市名稱, required true) String city) { return 城市: city , 溫度: 25°C, 天氣: 晴; } Tool(name sumNumbers, description 計算兩個數(shù)字之和) public String sumNumbers( ToolParam(description 第一個數(shù)字) double a, ToolParam(description 第二個數(shù)字) double b) { return String.valueOf(a b); } }工具注冊配置類把WeatherService里的Tool方法注冊為 MCP 工具Configuration public class ToolRegistrationConfiguration { Autowired private WeatherService weatherService; Bean public ToolCallbackProvider toolCallbackProvider() { return MethodToolCallbackProvider.builder() .toolObjects(new Object[]{weatherService}) .build(); } }接下來是 MCP Client 側(cè)的配置把模型請求指向 TaoToken。在application-client.yml里spring: ai: openai: base-url: https://taotoken.net/api api-key: ${TAOTOKEN_API_KEY} chat: options: model: claude-sonnet-4-20250514 temperature: 0.7 mcp: client: streamable-http: connections: demo-server: url: http://localhost:8080/mcp這里base-url指向 TaoToken 的 API 地址api-key從環(huán)境變量讀取避免硬編碼。mcp.client.streamable-http.connections下面配置 MCP Server 的地址demo-server是連接名可以自定義。這樣 MCP Client 啟動時會自動連接本地 MCP Server拉取工具列表然后在模型請求中把工具定義一起發(fā)給 TaoToken。如果你用的是 Cline 或 Claude Code 這類外部客戶端配置方式類似核心還是 Base URL、Key、Model ID 三件套加上 MCP Server 的 URL。Claude Code 的配置在 doc 里有說明Cline 的 MCP 配置在 settings 里填http://localhost:8080/mcp即可。4. 驗證請求curl 與單元測試檢查工具調(diào)用和流式返回配置寫完之后先啟動 MCP Server。用mvn spring-boot:run -Dspring-boot.run.profileshttp啟動看到 start輸出說明服務(wù)起來了。然后分兩步驗證先用 curl 直接打 MCP endpoint確認 JSON-RPC 握手和工具列表正常再用單元測試走完整的模型調(diào)用鏈路。curl 驗證 MCP 初始化請求curl -X POST http://localhost:8080/mcp \ -H Content-Type: application/json \ -H Accept: application/json, text/event-stream \ -d { jsonrpc: 2.0, id: 1, method: initialize, params: { protocolVersion: 2024-11-05, capabilities: {}, clientInfo: {name: curl-test, version: 1.0} } }正常返回會包含serverInfo和capabilities說明 Streamable HTTP 鏈路通了。注意Accept頭必須同時包含application/json和text/event-stream否則服務(wù)端可能拒絕流式響應(yīng)。接著查工具列表curl -X POST http://localhost:8080/mcp \ -H Content-Type: application/json \ -H Accept: application/json, text/event-stream \ -d { jsonrpc: 2.0, id: 2, method: tools/list, params: {} }返回里應(yīng)該能看到getWeather和sumNumbers兩個工具的定義包括參數(shù) schema。如果這里返回空列表說明工具注冊配置沒生效檢查ToolCallbackProvider是否被 Spring 掃描到。單元測試用 Spring AI 的ChatClient發(fā)起帶工具的請求驗證模型是否會調(diào)用工具SpringBootTest ActiveProfiles(client) class McpClientIntegrationTest { Autowired private ChatClient.Builder chatClientBuilder; Test void shouldCallWeatherTool() { ChatClient chatClient chatClientBuilder.build(); String response chatClient.prompt() .user(北京今天天氣怎么樣) .call() .content(); System.out.println(模型返回: response); assertThat(response).isNotBlank(); } }跑這個測試之前確保TAOTOKEN_API_KEY環(huán)境變量已設(shè)置。測試通過的標準是模型返回了包含天氣信息的文本并且日志里能看到工具調(diào)用的記錄。如果模型直接回答而沒有調(diào)用工具可能是工具描述不夠清晰或者模型不支持 function calling。流式返回的驗證用stream()方法Test void shouldStreamResponse() { ChatClient chatClient chatClientBuilder.build(); FluxString stream chatClient.prompt() .user(幫我算一下 12 加 30 等于多少) .stream() .content(); ListString chunks stream.collectList().block(); System.out.println(流式片段數(shù): chunks.size()); assertThat(chunks).isNotEmpty(); }流式返回正常的話chunks會有多個片段而不是一次性返回完整文本。這一步驗證的是 Streamable HTTP 的流式推送能力如果只收到一個片段說明流式配置有問題。5. 常見報錯排查401、local proxy failed、reading choices 與 OAuth這一節(jié)對照幾個真實報錯給出排查路徑。這些錯誤我在調(diào)試過程中都遇到過按順序檢查基本能定位。401 Unauthorized最常見的原因是 API Key 沒設(shè)置或設(shè)置錯了。檢查TAOTOKEN_API_KEY環(huán)境變量是否在當(dāng)前 shell 會話里生效echo $TAOTOKEN_API_KEY確認一下。如果 Key 是對的檢查base-url是否寫成了https://taotoken.net/api少寫/api或者多寫斜杠都會導(dǎo)致鑒權(quán)失敗。另外注意 Key 有沒有多余空格從控制臺復(fù)制的時候容易帶上換行。local proxy failed / connection refused這個報錯通常出現(xiàn)在 MCP Client 連接 MCP Server 的階段。檢查 MCP Server 是否真的在 8080 端口監(jiān)聽curl http://localhost:8080/mcp能不能通。如果 Server 沒起來檢查application-http.yml里的web-application-type: servlet有沒有配配成none的話 Web 容器不會啟動。還有一種情況是端口被占用換個端口或者殺掉占用進程。reading choices 相關(guān)報錯這個一般出現(xiàn)在模型返回解析階段說明請求發(fā)出去了但響應(yīng)格式不對。檢查model參數(shù)是否填了 TaoToken 支持的模型 ID填錯模型名會導(dǎo)致返回體里沒有choices字段。另外檢查spring.ai.openai.chat.options下的配置有沒有拼寫錯誤比如temperature寫成temprature這種。OAuth / 鑒權(quán)頭缺失如果你用的是 Claude Code 或 Cline 這類客戶端報 OAuth 相關(guān)錯誤通常是客戶端配置里沒填 Key或者填到了錯誤的字段。Claude Code 的配置參考 doc 頁面Cline 的 MCP 配置里 Base URL 和 Key 要分開填。對于 Spring AI 的 MCP Client鑒權(quán)是通過spring.ai.openai.api-key走的不需要額外配 OAuth。工具列表為空MCP Server 起來了但tools/list返回空。檢查ToolRegistrationConfiguration類是否在SpringBootApplication的掃描路徑下WeatherService是否被Service標記。還有一個坑是Tool注解的name屬性如果和已有工具重名后面的會覆蓋前面的導(dǎo)致看起來少了工具。流式返回中斷stream()調(diào)用收到部分片段后斷開。檢查Accept頭是否包含text/event-stream以及服務(wù)端有沒有設(shè)置響應(yīng)超時。Spring MVC 的異步請求超時默認是 30 秒長任務(wù)需要調(diào)spring.mvc.async.request-timeout。6. 把 endpoint 改到 TaoToken 后的完整鏈路與后續(xù)方向整條鏈路跑通之后回顧一下數(shù)據(jù)流MCP Client 啟動時連接本地 MCP Server 的/mcpendpoint拉取工具列表用戶發(fā)起請求時ChatClient 把用戶消息和工具定義一起發(fā)給 TaoToken 的/api接口TaoToken 返回模型決策如果決定調(diào)用工具MCP Client 通過 Streamable HTTP 把工具調(diào)用請求發(fā)給 MCP ServerMCP Server 執(zhí)行工具方法把結(jié)果流式返回給 MCP ClientMCP Client 再把工具結(jié)果發(fā)給模型生成最終回答。這個鏈路里TaoToken 承擔(dān)的是模型推理角色MCP Server 承擔(dān)的是工具執(zhí)行角色兩者通過 MCP Client 串聯(lián)。把 endpoint 改到 TaoToken 的意義在于你可以用統(tǒng)一的 API 接口驗證不同模型對工具調(diào)用的支持情況而不需要為每個模型單獨適配。后續(xù)如果要擴展幾個方向可以考慮一是增加更多工具比如數(shù)據(jù)庫查詢、文件操作注意 MCP 的安全邊界不要讓工具直接訪問生產(chǎn)庫二是把 MCP Server 部署到遠程用真實的 HTTP 地址替代 localhost驗證跨網(wǎng)絡(luò)場景下的流式穩(wěn)定性三是接入多個 MCP Server在 MCP Client 配置里加多個 connection讓模型自己選擇調(diào)用哪個服務(wù)的工具。需要創(chuàng)建 API Key 的話去 API Keys 頁面配置細節(jié)對照接入文檔想先試試模型對話效果可以直接在模型對話頁面發(fā)幾條帶工具調(diào)用的請求觀察返回結(jié)構(gòu)。長期跑編碼 Agent 任務(wù)的話Coding Plan 的額度模型更適合高頻調(diào)用場景。