戰(zhàn) MCP：從零基礎(chǔ)到精通的配置與驗(yàn)證全流程)
1. 為什么 Java 開發(fā)者需要關(guān)注 Spring AI 與 MCP如果你寫過 Spring Boot大概率經(jīng)歷過這樣的場(chǎng)景想讓 AI 幫你讀一下項(xiàng)目里的某個(gè)文件、查一下數(shù)據(jù)庫、調(diào)一下內(nèi)部接口結(jié)果發(fā)現(xiàn)模型只能空口說白話它根本碰不到你的真實(shí)環(huán)境。MCPModel Context Protocol就是來解決這件事的——它是一套開放協(xié)議把模型和外部工具、數(shù)據(jù)源之間的連接方式標(biāo)準(zhǔn)化你可以把它理解成AI 世界的 USB-C 接口。而 Spring AI 是 Spring 生態(tài)里專門做大模型集成的框架它把 MCP 客戶端封裝成了 Spring Boot Starter意味著你不需要手寫協(xié)議解析、不需要自己管理 stdio 進(jìn)程通信只要在application.yml里寫幾行配置就能讓本地模型調(diào)用文件系統(tǒng)、數(shù)據(jù)庫、地圖等外部能力。這篇內(nèi)容面向的是有 Java 基礎(chǔ)、但沒接觸過 MCP 的開發(fā)者我會(huì)從依賴引入開始一步步帶你跑通Spring AI MCP 調(diào)用文件系統(tǒng)工具的完整鏈路包括配置骨架、工具注冊(cè)、端到端驗(yàn)證以及我實(shí)際踩過的幾個(gè)坑。核心檢索詞先明確Spring AI MCP 是 Spring AI 對(duì) MCP 協(xié)議的客戶端實(shí)現(xiàn)能讓你在 Java 項(xiàng)目里用注解和配置文件的方式接入 MCP Server它適合想給現(xiàn)有 Java 系統(tǒng)加 AI 工具調(diào)用能力的后端工程師也適合正在做 Agent 落地、需要標(biāo)準(zhǔn)化工具接入的團(tuán)隊(duì)。下面所有代碼和配置都可以直接復(fù)制到你的工程里。2. 前置準(zhǔn)備TaoToken 與本地模型環(huán)境在寫代碼之前有兩件事需要先確認(rèn)模型從哪來、MCP Server 怎么跑。模型這塊我建議用 TaoToken 做統(tǒng)一入口。它的作用是讓你用一套 API Key 就能切換不同模型不用每個(gè)廠商都去注冊(cè)一遍。對(duì)于 Spring AI 項(xiàng)目來說你只需要把 base-url 指向 TaoToken 的 API 地址模型名換成你想要的即可。訪問入口在這里官網(wǎng)地址https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 地址https://taotoken.net/api如果你只是想先跑通 MCP 鏈路用本地 Ollama 也完全可以我下面的示例會(huì)以 Ollama 為主因?yàn)椴灰蕾嚲W(wǎng)絡(luò)、調(diào)試更快。等你驗(yàn)證通了再把模型換成 TaoToken 上的云端模型即可。MCP Server 這邊你需要一個(gè)能提供工具的服務(wù)端。最省事的方式是用現(xiàn)成的 npm 包比如modelcontextprotocol/server-filesystem它提供文件讀寫、目錄列舉等工具。前提是你的機(jī)器上有 Node.js 和 npx 環(huán)境命令行執(zhí)行npx -v能輸出版本號(hào)就說明沒問題。如果沒有去 Node.js 官網(wǎng)下載 LTS 版本安裝即可這一步不涉及任何特殊網(wǎng)絡(luò)配置。另外確認(rèn)一下 JDK 版本Spring AI 1.0.0-M6 要求 Java 17 及以上。如果你本地還是 Java 8需要先升級(jí)否則啟動(dòng)會(huì)直接報(bào)UnsupportedClassVersionError。3. 可復(fù)制配置pom 依賴與 application.yml 骨架3.1 Maven 依賴引入新建一個(gè) Spring Boot 工程pom.xml里加上這幾個(gè)關(guān)鍵依賴。注意 Spring AI 的版本要用 BOM 統(tǒng)一管理避免版本沖突project xmlnshttp://maven.apache.org/POM/4.0.0 xmlns:xsihttp://www.w3.org/2001/XMLSchema-instance xsi:schemaLocationhttp://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd modelVersion4.0.0/modelVersion groupIdorg.yxy/groupId artifactIdspring-ai-mcp/artifactId version1.0-SNAPSHOT/version packagingjar/packaging properties java.version17/java.version project.build.sourceEncodingUTF-8/project.build.sourceEncoding /properties dependencies dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId version3.2.4/version /dependency dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-mcp-client-spring-boot-starter/artifactId version1.0.0-M6/version /dependency dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-ollama-spring-boot-starter/artifactId /dependency dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-test/artifactId scopetest/scope version3.2.4/version /dependency /dependencies dependencyManagement dependencies dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-bom/artifactId version1.0.0-M6/version typepom/type scopeimport/scope /dependency /dependencies /dependencyManagement /project這里有個(gè)細(xì)節(jié)spring-ai-ollama-spring-boot-starter沒有寫 version因?yàn)樗?BOM 統(tǒng)一管理。如果你用的是其他模型比如 OpenAI 兼容接口把 ollama starter 換成對(duì)應(yīng)的即可。3.2 application.yml 配置配置文件分兩塊模型配置和 MCP 客戶端配置。MCP 部分的關(guān)鍵是stdio模式它會(huì)以子進(jìn)程方式啟動(dòng) MCP Serverspring: application: name: spring-ai-mcp ai: ollama: base-url: http://localhost:11434 chat: options: model: qwen2.5-coder:7b mcp: client: enabled: true name: mcp-client version: 1.0.0 type: SYNC request-timeout: 30s stdio: servers-configuration: classpath:/mcp-servers-config.jsontype: SYNC表示同步調(diào)用模式適合大多數(shù)請(qǐng)求-響應(yīng)場(chǎng)景。如果你要做流式或高并發(fā)可以改成ASYNC但對(duì)應(yīng)的注入類也要換。3.3 MCP Server 配置文件在src/main/resources下新建mcp-servers-config.json內(nèi)容如下。注意 Windows 和 Mac/Linux 的 command 寫法不同{ mcpServers: { filesystem: { command: cmd, args: [ /c, npx, -y, modelcontextprotocol/server-filesystem, F:\\web ] } } }Mac 或 Linux 用戶把command: cmd改成command: npx并去掉/c這個(gè)參數(shù)。最后的路徑是你允許 MCP Server 操作的目錄建議先用一個(gè)測(cè)試目錄別直接指向項(xiàng)目根目錄。4. 工具注冊(cè)與端到端調(diào)用驗(yàn)證4.1 Controller 里注冊(cè) MCP 工具Spring AI 會(huì)自動(dòng)把 MCP Server 提供的工具封裝成SyncMcpToolCallbackProvider你只需要把它注入進(jìn)來然后在構(gòu)建 ChatClient 時(shí)通過defaultTools注冊(cè)package org.yxy.controller; import jakarta.annotation.Resource; import org.springframework.ai.chat.client.ChatClient; import org.springframework.ai.mcp.SyncMcpToolCallbackProvider; import org.springframework.ai.ollama.OllamaChatModel; import org.springframework.web.bind.annotation.GetMapping; import org.springframework.web.bind.annotation.RequestParam; import org.springframework.web.bind.annotation.RestController; RestController public class OllamaController { Resource private OllamaChatModel ollamaChatModel; Resource private SyncMcpToolCallbackProvider toolCallbackProvider; GetMapping(/ai/ollama) public String ollama(RequestParam(value msg) String msg) { ChatClient chatClient ChatClient.builder(ollamaChatModel) .defaultTools(toolCallbackProvider.getToolCallbacks()) .build(); String content chatClient.prompt(msg).call().content(); System.out.println(content); return content; } }toolCallbackProvider.getToolCallbacks()返回的是一個(gè)ToolCallback列表每個(gè)元素對(duì)應(yīng) MCP Server 暴露的一個(gè)工具。你可以打個(gè)斷點(diǎn)看一下數(shù)組內(nèi)容里面會(huì)有read_file、write_file、list_directory、list_allowed_directories等方法。4.2 啟動(dòng)并驗(yàn)證啟動(dòng) Spring Boot 應(yīng)用然后瀏覽器訪問http://localhost:8080/ai/ollama?msg幫我在F:\web目錄下創(chuàng)建一個(gè)test-mcp文件夾第一次請(qǐng)求可能會(huì)慢一些因?yàn)橐?npx 下載并啟動(dòng) MCP Server 子進(jìn)程本地模型推理也需要時(shí)間。等幾秒到幾十秒你會(huì)看到返回結(jié)果。如果模型正確調(diào)用了create_directory工具去F:\web目錄下就能看到新建的test-mcp文件夾。我實(shí)測(cè)下來用 qwen2.5-coder:7b 這個(gè)模型工具調(diào)用的準(zhǔn)確率還不錯(cuò)但偶爾會(huì)出現(xiàn)模型說它創(chuàng)建了、實(shí)際沒調(diào)用工具的情況。這時(shí)候你可以把請(qǐng)求寫得更明確比如請(qǐng)調(diào)用工具在 F:\web 下創(chuàng)建 test-mcp 目錄成功率會(huì)高很多。4.3 換成 TaoToken 云端模型如果你不想本地跑模型把a(bǔ)pplication.yml里的 ollama 配置換成 TaoToken 的 OpenAI 兼容配置即可。先去 TaoToken 控制臺(tái)創(chuàng)建一個(gè) API KeyAPI Keys 管理https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite然后把依賴換成spring-ai-openai-spring-boot-starter配置改成spring: ai: openai: base-url: https://taotoken.net/api api-key: 你的Key chat: options: model: 你想要的模型名MCP 部分的配置完全不用動(dòng)工具注冊(cè)代碼也不用改。這就是 Spring AI 抽象層的好處——模型換了工具調(diào)用鏈路不變。5. 本篇常見錯(cuò)誤排查啟動(dòng)報(bào)NoClassDefFoundError: SyncMcpToolCallbackProvider說明 MCP starter 沒引入或者版本不對(duì)。檢查spring-ai-mcp-client-spring-boot-starter是否在依賴?yán)锇姹臼欠窈?BOM 一致。MCP Server 啟動(dòng)失敗日志里出現(xiàn)npx: command not foundNode.js 環(huán)境沒裝好或者 npx 不在 PATH 里。命令行執(zhí)行npx -v確認(rèn)Windows 用戶注意cmd /c這個(gè)前綴不能少。工具調(diào)用返回空或者模型說我沒有這個(gè)能力大概率是defaultTools沒生效。檢查toolCallbackProvider.getToolCallbacks()是否返回了非空數(shù)組可以在 Controller 里打印一下長(zhǎng)度。如果長(zhǎng)度為 0說明 MCP Server 沒連上去看啟動(dòng)日志里有沒有 stdio 連接錯(cuò)誤。請(qǐng)求超時(shí)request-timeout: 30s對(duì)于本地小模型可能不夠尤其是首次加載?？梢哉{(diào)到60s試試。另外確認(rèn) MCP Server 配置的目錄路徑存在路徑不存在也會(huì)導(dǎo)致工具初始化失敗。Windows 路徑轉(zhuǎn)義問題JSON 里反斜杠要寫成\\比如F:\\web。如果寫成F:\webJSON 解析會(huì)報(bào)錯(cuò)。模型不調(diào)用工具直接編造答案這是小模型的通病。解決辦法有兩個(gè)一是換更大的模型二是把 prompt 寫得更指令化明確要求必須調(diào)用工具。另外qwen2.5-coder系列對(duì)工具調(diào)用的支持比通用模型更好建議優(yōu)先用 coder 版本。6. 下一步從跑通到落地跑通這個(gè) demo 之后你可以沿著幾個(gè)方向繼續(xù)深入。一是多 Server 配置在mcp-servers-config.json里加多個(gè) server比如同時(shí)接文件系統(tǒng)和數(shù)據(jù)庫Spring AI 會(huì)把所有工具合并注冊(cè)。二是異步模式把type改成ASYNC注入AsyncMcpToolCallbackProvider適合高并發(fā)場(chǎng)景。三是自定義 MCP Server用 Java SDK 寫自己的工具服務(wù)端把公司內(nèi)部接口暴露給模型。如果你在接入過程中遇到工具注冊(cè)或模型調(diào)用的問題可以先去 TaoToken 的接入文檔里對(duì)照配置接入文檔https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite想先驗(yàn)證模型本身能不能正常對(duì)話可以用模型對(duì)話頁面快速測(cè)一下模型對(duì)話https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentchatutm_campaignrewrite如果你打算把 MCP 用到長(zhǎng)期的編碼或 Agent 項(xiàng)目里建議了解一下 Coding Plan它在調(diào)用額度和模型切換上更適合持續(xù)開發(fā)場(chǎng)景Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite整個(gè)鏈路跑下來最花時(shí)間的其實(shí)不是寫代碼而是環(huán)境準(zhǔn)備和排錯(cuò)。把 MCP Server 的日志打開遇到問題先看子進(jìn)程有沒有正常啟動(dòng)再看工具列表有沒有注冊(cè)成功最后才懷疑模型。這個(gè)排查順序能幫你省掉大量試錯(cuò)時(shí)間。 Java 使用 Spring AI 實(shí)戰(zhàn) MCP：從零基礎(chǔ)到精通的配置與驗(yàn)證全流程
1. 為什么 Java 開發(fā)者需要關(guān)注 Spring AI 與 MCP如果你寫過 Spring Boot大概率經(jīng)歷過這樣的場(chǎng)景想讓 AI 幫你讀一下項(xiàng)目里的某個(gè)文件、查一下數(shù)據(jù)庫、調(diào)一下內(nèi)部接口結(jié)果發(fā)現(xiàn)模型只能空口說白話它根本碰不到你的真實(shí)環(huán)境。MCPModel Context Protocol就是來解決這件事的——它是一套開放協(xié)議把模型和外部工具、數(shù)據(jù)源之間的連接方式標(biāo)準(zhǔn)化你可以把它理解成AI 世界的 USB-C 接口。而 Spring AI 是 Spring 生態(tài)里專門做大模型集成的框架它把 MCP 客戶端封裝成了 Spring Boot Starter意味著你不需要手寫協(xié)議解析、不需要自己管理 stdio 進(jìn)程通信只要在application.yml里寫幾行配置就能讓本地模型調(diào)用文件系統(tǒng)、數(shù)據(jù)庫、地圖等外部能力。這篇內(nèi)容面向的是有 Java 基礎(chǔ)、但沒接觸過 MCP 的開發(fā)者我會(huì)從依賴引入開始一步步帶你跑通Spring AI MCP 調(diào)用文件系統(tǒng)工具的完整鏈路包括配置骨架、工具注冊(cè)、端到端驗(yàn)證以及我實(shí)際踩過的幾個(gè)坑。核心檢索詞先明確Spring AI MCP 是 Spring AI 對(duì) MCP 協(xié)議的客戶端實(shí)現(xiàn)能讓你在 Java 項(xiàng)目里用注解和配置文件的方式接入 MCP Server它適合想給現(xiàn)有 Java 系統(tǒng)加 AI 工具調(diào)用能力的后端工程師也適合正在做 Agent 落地、需要標(biāo)準(zhǔn)化工具接入的團(tuán)隊(duì)。下面所有代碼和配置都可以直接復(fù)制到你的工程里。2. 前置準(zhǔn)備TaoToken 與本地模型環(huán)境在寫代碼之前有兩件事需要先確認(rèn)模型從哪來、MCP Server 怎么跑。模型這塊我建議用 TaoToken 做統(tǒng)一入口。它的作用是讓你用一套 API Key 就能切換不同模型不用每個(gè)廠商都去注冊(cè)一遍。對(duì)于 Spring AI 項(xiàng)目來說你只需要把 base-url 指向 TaoToken 的 API 地址模型名換成你想要的即可。訪問入口在這里官網(wǎng)地址https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 地址https://taotoken.net/api如果你只是想先跑通 MCP 鏈路用本地 Ollama 也完全可以我下面的示例會(huì)以 Ollama 為主因?yàn)椴灰蕾嚲W(wǎng)絡(luò)、調(diào)試更快。等你驗(yàn)證通了再把模型換成 TaoToken 上的云端模型即可。MCP Server 這邊你需要一個(gè)能提供工具的服務(wù)端。最省事的方式是用現(xiàn)成的 npm 包比如modelcontextprotocol/server-filesystem它提供文件讀寫、目錄列舉等工具。前提是你的機(jī)器上有 Node.js 和 npx 環(huán)境命令行執(zhí)行npx -v能輸出版本號(hào)就說明沒問題。如果沒有去 Node.js 官網(wǎng)下載 LTS 版本安裝即可這一步不涉及任何特殊網(wǎng)絡(luò)配置。另外確認(rèn)一下 JDK 版本Spring AI 1.0.0-M6 要求 Java 17 及以上。如果你本地還是 Java 8需要先升級(jí)否則啟動(dòng)會(huì)直接報(bào)UnsupportedClassVersionError。3. 可復(fù)制配置pom 依賴與 application.yml 骨架3.1 Maven 依賴引入新建一個(gè) Spring Boot 工程pom.xml里加上這幾個(gè)關(guān)鍵依賴。注意 Spring AI 的版本要用 BOM 統(tǒng)一管理避免版本沖突project xmlnshttp://maven.apache.org/POM/4.0.0 xmlns:xsihttp://www.w3.org/2001/XMLSchema-instance xsi:schemaLocationhttp://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd modelVersion4.0.0/modelVersion groupIdorg.yxy/groupId artifactIdspring-ai-mcp/artifactId version1.0-SNAPSHOT/version packagingjar/packaging properties java.version17/java.version project.build.sourceEncodingUTF-8/project.build.sourceEncoding /properties dependencies dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId version3.2.4/version /dependency dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-mcp-client-spring-boot-starter/artifactId version1.0.0-M6/version /dependency dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-ollama-spring-boot-starter/artifactId /dependency dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-test/artifactId scopetest/scope version3.2.4/version /dependency /dependencies dependencyManagement dependencies dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-bom/artifactId version1.0.0-M6/version typepom/type scopeimport/scope /dependency /dependencies /dependencyManagement /project這里有個(gè)細(xì)節(jié)spring-ai-ollama-spring-boot-starter沒有寫 version因?yàn)樗?BOM 統(tǒng)一管理。如果你用的是其他模型比如 OpenAI 兼容接口把 ollama starter 換成對(duì)應(yīng)的即可。3.2 application.yml 配置配置文件分兩塊模型配置和 MCP 客戶端配置。MCP 部分的關(guān)鍵是stdio模式它會(huì)以子進(jìn)程方式啟動(dòng) MCP Serverspring: application: name: spring-ai-mcp ai: ollama: base-url: http://localhost:11434 chat: options: model: qwen2.5-coder:7b mcp: client: enabled: true name: mcp-client version: 1.0.0 type: SYNC request-timeout: 30s stdio: servers-configuration: classpath:/mcp-servers-config.jsontype: SYNC表示同步調(diào)用模式適合大多數(shù)請(qǐng)求-響應(yīng)場(chǎng)景。如果你要做流式或高并發(fā)可以改成ASYNC但對(duì)應(yīng)的注入類也要換。3.3 MCP Server 配置文件在src/main/resources下新建mcp-servers-config.json內(nèi)容如下。注意 Windows 和 Mac/Linux 的 command 寫法不同{ mcpServers: { filesystem: { command: cmd, args: [ /c, npx, -y, modelcontextprotocol/server-filesystem, F:\\web ] } } }Mac 或 Linux 用戶把command: cmd改成command: npx并去掉/c這個(gè)參數(shù)。最后的路徑是你允許 MCP Server 操作的目錄建議先用一個(gè)測(cè)試目錄別直接指向項(xiàng)目根目錄。4. 工具注冊(cè)與端到端調(diào)用驗(yàn)證4.1 Controller 里注冊(cè) MCP 工具Spring AI 會(huì)自動(dòng)把 MCP Server 提供的工具封裝成SyncMcpToolCallbackProvider你只需要把它注入進(jìn)來然后在構(gòu)建 ChatClient 時(shí)通過defaultTools注冊(cè)package org.yxy.controller; import jakarta.annotation.Resource; import org.springframework.ai.chat.client.ChatClient; import org.springframework.ai.mcp.SyncMcpToolCallbackProvider; import org.springframework.ai.ollama.OllamaChatModel; import org.springframework.web.bind.annotation.GetMapping; import org.springframework.web.bind.annotation.RequestParam; import org.springframework.web.bind.annotation.RestController; RestController public class OllamaController { Resource private OllamaChatModel ollamaChatModel; Resource private SyncMcpToolCallbackProvider toolCallbackProvider; GetMapping(/ai/ollama) public String ollama(RequestParam(value msg) String msg) { ChatClient chatClient ChatClient.builder(ollamaChatModel) .defaultTools(toolCallbackProvider.getToolCallbacks()) .build(); String content chatClient.prompt(msg).call().content(); System.out.println(content); return content; } }toolCallbackProvider.getToolCallbacks()返回的是一個(gè)ToolCallback列表每個(gè)元素對(duì)應(yīng) MCP Server 暴露的一個(gè)工具。你可以打個(gè)斷點(diǎn)看一下數(shù)組內(nèi)容里面會(huì)有read_file、write_file、list_directory、list_allowed_directories等方法。4.2 啟動(dòng)并驗(yàn)證啟動(dòng) Spring Boot 應(yīng)用然后瀏覽器訪問http://localhost:8080/ai/ollama?msg幫我在F:\web目錄下創(chuàng)建一個(gè)test-mcp文件夾第一次請(qǐng)求可能會(huì)慢一些因?yàn)橐?npx 下載并啟動(dòng) MCP Server 子進(jìn)程本地模型推理也需要時(shí)間。等幾秒到幾十秒你會(huì)看到返回結(jié)果。如果模型正確調(diào)用了create_directory工具去F:\web目錄下就能看到新建的test-mcp文件夾。我實(shí)測(cè)下來用 qwen2.5-coder:7b 這個(gè)模型工具調(diào)用的準(zhǔn)確率還不錯(cuò)但偶爾會(huì)出現(xiàn)模型說它創(chuàng)建了、實(shí)際沒調(diào)用工具的情況。這時(shí)候你可以把請(qǐng)求寫得更明確比如請(qǐng)調(diào)用工具在 F:\web 下創(chuàng)建 test-mcp 目錄成功率會(huì)高很多。4.3 換成 TaoToken 云端模型如果你不想本地跑模型把a(bǔ)pplication.yml里的 ollama 配置換成 TaoToken 的 OpenAI 兼容配置即可。先去 TaoToken 控制臺(tái)創(chuàng)建一個(gè) API KeyAPI Keys 管理https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite然后把依賴換成spring-ai-openai-spring-boot-starter配置改成spring: ai: openai: base-url: https://taotoken.net/api api-key: 你的Key chat: options: model: 你想要的模型名MCP 部分的配置完全不用動(dòng)工具注冊(cè)代碼也不用改。這就是 Spring AI 抽象層的好處——模型換了工具調(diào)用鏈路不變。5. 本篇常見錯(cuò)誤排查啟動(dòng)報(bào)NoClassDefFoundError: SyncMcpToolCallbackProvider說明 MCP starter 沒引入或者版本不對(duì)。檢查spring-ai-mcp-client-spring-boot-starter是否在依賴?yán)锇姹臼欠窈?BOM 一致。MCP Server 啟動(dòng)失敗日志里出現(xiàn)npx: command not foundNode.js 環(huán)境沒裝好或者 npx 不在 PATH 里。命令行執(zhí)行npx -v確認(rèn)Windows 用戶注意cmd /c這個(gè)前綴不能少。工具調(diào)用返回空或者模型說我沒有這個(gè)能力大概率是defaultTools沒生效。檢查toolCallbackProvider.getToolCallbacks()是否返回了非空數(shù)組可以在 Controller 里打印一下長(zhǎng)度。如果長(zhǎng)度為 0說明 MCP Server 沒連上去看啟動(dòng)日志里有沒有 stdio 連接錯(cuò)誤。請(qǐng)求超時(shí)request-timeout: 30s對(duì)于本地小模型可能不夠尤其是首次加載?？梢哉{(diào)到60s試試。另外確認(rèn) MCP Server 配置的目錄路徑存在路徑不存在也會(huì)導(dǎo)致工具初始化失敗。Windows 路徑轉(zhuǎn)義問題JSON 里反斜杠要寫成\\比如F:\\web。如果寫成F:\webJSON 解析會(huì)報(bào)錯(cuò)。模型不調(diào)用工具直接編造答案這是小模型的通病。解決辦法有兩個(gè)一是換更大的模型二是把 prompt 寫得更指令化明確要求必須調(diào)用工具。另外qwen2.5-coder系列對(duì)工具調(diào)用的支持比通用模型更好建議優(yōu)先用 coder 版本。6. 下一步從跑通到落地跑通這個(gè) demo 之后你可以沿著幾個(gè)方向繼續(xù)深入。一是多 Server 配置在mcp-servers-config.json里加多個(gè) server比如同時(shí)接文件系統(tǒng)和數(shù)據(jù)庫Spring AI 會(huì)把所有工具合并注冊(cè)。二是異步模式把type改成ASYNC注入AsyncMcpToolCallbackProvider適合高并發(fā)場(chǎng)景。三是自定義 MCP Server用 Java SDK 寫自己的工具服務(wù)端把公司內(nèi)部接口暴露給模型。如果你在接入過程中遇到工具注冊(cè)或模型調(diào)用的問題可以先去 TaoToken 的接入文檔里對(duì)照配置接入文檔https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite想先驗(yàn)證模型本身能不能正常對(duì)話可以用模型對(duì)話頁面快速測(cè)一下模型對(duì)話https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentchatutm_campaignrewrite如果你打算把 MCP 用到長(zhǎng)期的編碼或 Agent 項(xiàng)目里建議了解一下 Coding Plan它在調(diào)用額度和模型切換上更適合持續(xù)開發(fā)場(chǎng)景Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite整個(gè)鏈路跑下來最花時(shí)間的其實(shí)不是寫代碼而是環(huán)境準(zhǔn)備和排錯(cuò)。把 MCP Server 的日志打開遇到問題先看子進(jìn)程有沒有正常啟動(dòng)再看工具列表有沒有注冊(cè)成功最后才懷疑模型。這個(gè)排查順序能幫你省掉大量試錯(cuò)時(shí)間。