1. 先別急著改代碼這個坑八成不在 MCP 服務(wù)里如果你用 Spring AI 的mcp-server-webmvcstarter 把CalculatorTool、SystemInfoResource、CodeReviewPrompt暴露到/mcpcurl走initialize能拿到Mcp-Session-Idtools/list也能列出calculate但一掛進 Codex 當(dāng)客戶端tools/call就是發(fā)不出去——先別懷疑Tool注解寫錯了也別急著翻MethodToolCallbackProvider的源碼。我踩過的坑是MCP 端點地址和模型通道地址填混了。這兩個地址長得像作用卻完全不同。MCP 地址是http://localhost:8080/mcp它負(fù)責(zé)把你的CalculatorTool暴露給客戶端模型通道地址是https://taotoken.net/api它負(fù)責(zé)讓客戶端里的模型能正常對話、決定要不要調(diào)工具。很多人把模型通道的 Base URL 順手填成了http://localhost:8080/mcp結(jié)果客戶端把tools/call當(dāng)成聊天請求發(fā)給了本地 MCP 服務(wù)握手通了才怪。這篇就按排障視角走一遍先確認(rèn) MCP 服務(wù)本身沒問題再把客戶端里兩個地址拆開最后用一次真實的tools/call驗證請求確實走到了CalculatorTool。適合正在用 Java StreamableHTTP 搭 MCP 服務(wù)、并且已經(jīng)卡在客戶端調(diào)用這一步的人。2. 前置MCP 服務(wù)歸 MCP模型通道歸 TaoToken先把職責(zé)劃清楚后面排查才不會亂。MCP 服務(wù)這一側(cè)你只需要保證http://localhost:8080/mcp能正常響應(yīng) JSON-RPC。它不認(rèn)識什么模型、什么 Key只認(rèn)initialize、tools/list、tools/call這些方法。Spring AI 的 starter 已經(jīng)把 transport 層、JSON-RPC 解析、會話管理全自動做完了你寫的CalculatorTool只要被Tool標(biāo)注就會被注冊成 MCP tool。模型通道這一側(cè)是客戶端里真正“動腦子”的部分。Codex 這類客戶端需要一個大模型來決定“用戶這句話要不要調(diào)calculate”這個模型請求得走一個獨立的 Base URL。這里用 TaoToken 作為模型通道Base URL 寫https://taotoken.net/apiKey 到https://taotoken.net/?utm_sourcetaotoken_aicg_blog_end注冊后創(chuàng)建。注意MCP 地址和模型通道地址是兩條獨立的鏈路。MCP 地址指向你本地的8080模型通道地址指向taotoken.net。兩者填反握手能通tools/call必掛。如果你還沒建 Key進控制臺創(chuàng)建即可https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite。創(chuàng)建完在 API Keys 頁面復(fù)制https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite。接入細(xì)節(jié)可以對照文檔https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite。3. 可復(fù)制配置把兩個地址徹底拆開3.1 先確認(rèn) MCP 服務(wù)端配置沒跑偏application.yml里這段是 StreamableHTTP 的開關(guān)enabled: true才會走/mcp單端點模式否則 starter 會退回舊的 SSE transportspring: ai: mcp: server: type: SYNC streamable-http: enabled: true endpoint: /mcp啟動后先用curl把三步走完確認(rèn)服務(wù)端自身是好的。第一步initialize重點看響應(yīng)頭里的Mcp-Session-Idcurl -i -X POST http://localhost:8080/mcp \ -H Content-Type: application/json \ -d {jsonrpc:2.0,id:1,method:initialize,params:{protocolVersion:2025-03-26,capabilities:{},clientInfo:{name:test,version:1.0}}}第二步tools/list把上一步拿到的 session id 填進去應(yīng)該能看到calculatecurl -X POST http://localhost:8080/mcp \ -H Content-Type: application/json \ -H Mcp-Session-Id: 上一步響應(yīng)頭里的值 \ -d {jsonrpc:2.0,id:2,method:tools/list}第三步直接tools/call這一步能返回42說明 MCP 服務(wù)端完全沒問題curl -X POST http://localhost:8080/mcp \ -H Content-Type: application/json \ -H Mcp-Session-Id: 同一個 session id \ -d {jsonrpc:2.0,id:3,method:tools/call,params:{name:calculate,arguments:{operation:multiply,a:6,b:7}}}3.2 客戶端里兩個地址分開填這是整篇最關(guān)鍵的一步。在 Codex 這類客戶端的配置里MCP server 的地址填本地{ mcpServers: { calculator: { url: http://localhost:8080/mcp } } }模型通道單獨配置Base URL 指向 TaoTokenKey 用你剛創(chuàng)建的那串{ model: { baseUrl: https://taotoken.net/api, apiKey: sk-你的TaoToken密鑰, model: claude-sonnet-4-5 } }兩處分開之后客戶端的行為就對了它先通過http://localhost:8080/mcp完成initialize和tools/list知道有個calculate工具當(dāng)用戶說“6 乘 7 等于幾”時模型請求走h(yuǎn)ttps://taotoken.net/api模型返回一個tools/call意圖客戶端再把tools/call發(fā)回http://localhost:8080/mcp。請求這才真的走得到CalculatorTool。3.3 用環(huán)境變量兜底避免手滑如果你不想在配置文件里寫死 Key用環(huán)境變量更穩(wěn)export TAOTOKEN_API_KEYsk-你的TaoToken密鑰 export TAOTOKEN_BASE_URLhttps://taotoken.net/api export MCP_SERVER_URLhttp://localhost:8080/mcp然后在客戶端配置里引用這些變量。這樣即使換機器也不會把localhost和taotoken.net填反。4. 驗證請求確認(rèn) tools/call 真的到了 CalculatorTool配置改完重啟客戶端做一次端到端驗證。最直接的辦法是在CalculatorTool的calculate方法里加一行日志Tool(description 四則運算計算器支持 add/subtract/multiply/divide) public double calculate(String operation, double a, double b) { System.out.println([MCP] tools/call 到達(dá) CalculatorTool: operation a b); return switch (operation) { case add - a b; case subtract - a - b; case multiply - a * b; case divide - a / b; default - throw new IllegalArgumentException(不支持的運算: operation); }; }然后在客戶端里輸入“幫我算一下 6 乘 7”。預(yù)期結(jié)果有兩層第一層客戶端控制臺或日志里能看到模型通道請求成功說明https://taotoken.net/api這條鏈路是通的。第二層你的 Spring Boot 應(yīng)用控制臺打印出[MCP] tools/call 到達(dá) CalculatorTool: multiply 6.0 7.0說明tools/call確實發(fā)到了http://localhost:8080/mcp并且被路由到了CalculatorTool。如果第一層通、第二層沒打印那基本就是 MCP 地址填錯了或者客戶端把tools/call發(fā)到了模型通道地址。反過來如果第二層打印了但客戶端沒顯示結(jié)果那問題在響應(yīng)回傳跟地址無關(guān)。想單獨驗證模型通道是否正?？梢缘侥Ｐ蛯υ掜撁姘l(fā)一條普通消息https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentchatutm_campaignrewrite。如果那邊能正?；貜?fù)說明 Key 和 Base URL 沒問題問題就鎖定在 MCP 地址這一側(cè)。5. 本篇常見錯排查5.1 把 MCP 地址填成了模型通道地址最常見的錯?？蛻舳死?MCP server 的url寫成了https://taotoken.net/api結(jié)果initialize請求發(fā)給了模型通道返回的是一段模型回復(fù)而不是Mcp-Session-Id。表現(xiàn)就是“握手看起來通了但tools/call發(fā)不出去”。改回http://localhost:8080/mcp即可。5.2 把模型通道地址填成了 MCP 地址反過來也常見。Base URL 寫成http://localhost:8080/mcp客戶端把聊天請求發(fā)給本地 MCP 服務(wù)MCP 服務(wù)只認(rèn) JSON-RPC收到普通聊天請求直接報錯。表現(xiàn)是模型完全不回復(fù)或者回復(fù)一段 JSON-RPC 錯誤。Base URL 必須是https://taotoken.net/api。5.3 session id 沒帶上tools/call必須帶Mcp-Session-Id請求頭這個值來自initialize的響應(yīng)頭。有些客戶端會自動管理有些需要手動配置。如果你用curl測試時忘了帶服務(wù)端會返回會話不存在的錯誤。檢查客戶端是否在initialize之后正確保存并復(fù)用了 session id。5.4 endpoint 路徑寫錯application.yml里endpoint: /mcp客戶端地址就必須是http://localhost:8080/mcp。如果寫成http://localhost:8080/mcp/多了斜杠或者h(yuǎn)ttp://localhost:8080少了路徑都可能 404。Spring MVC 對路徑匹配比較嚴(yán)格建議完全按配置來。5.5 端口被占用或服務(wù)沒起來8080是常見端口容易被其他服務(wù)占用。啟動時看日志有沒有Tomcat started on port 8080。如果端口沖突改server.port并同步改客戶端里的 MCP 地址。這個錯的表現(xiàn)是initialize直接連接失敗跟地址填混的表現(xiàn)不一樣容易區(qū)分。5.6 模型通道 Key 無效如果模型通道返回 401客戶端可能根本走不到tools/call這一步。先確認(rèn) Key 是在https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite創(chuàng)建的并且沒有多余空格。Key 無效時模型不會返回工具調(diào)用意圖自然也就沒有tools/call。6. 地址分開之后鏈路才真的通回到最初那個現(xiàn)象initialize通了tools/call調(diào)不動。根因不是 Spring AI 的 starter 有問題也不是CalculatorTool注冊失敗而是客戶端里兩個地址混在了一起。MCP 地址負(fù)責(zé)工具暴露模型通道地址負(fù)責(zé)模型推理兩者必須分開。你現(xiàn)在可以這樣收尾MCP 地址保持http://localhost:8080/mcp模型通道 Base URL 寫https://taotoken.net/apiKey 到https://taotoken.net/?utm_sourcetaotoken_aicg_blog_end注冊后創(chuàng)建。如果你后面要長期跑編碼類 Agent可以考慮 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite。接入過程中遇到報錯先翻文檔https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite大部分地址和鑒權(quán)問題那里都有對照。最后留一個實用習(xí)慣每次改完客戶端配置先在CalculatorTool里看那行日志有沒有打印。日志打印了說明tools/call真的到了沒打印就回去檢查兩個地址是不是又填混了。這比盯著客戶端界面猜要快得多。