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