快捷導(dǎo)航

Spring AI 框架中集成 MCP的方法

更新時間：2025年07月28日 09:14:53 作者：seven97-top

SpringAIMCP集成Java/Spring與模型上下文協(xié)議,支持stdio和SSE兩種通信模式,通過注解@Tool暴露AI工具,提供標(biāo)準(zhǔn)化接口與數(shù)據(jù)源交互,兼顧本地部署與遠(yuǎn)程調(diào)用場景,包含配置、工具注冊及性能安全等關(guān)鍵實現(xiàn)要點,本文介紹Spring AI框架中如何集成 MCP,感興趣的朋友一起看看吧

SpringAI MCP介紹

Spring AI MCP 為模型上下文協(xié)議提供 Java 和Spring 框架集成、它使 SpringAI 應(yīng)用程序能夠通過標(biāo)準(zhǔn)化的接口與不同的數(shù)據(jù)源和工是進行交互，支持同步和異步通信模式。整體架構(gòu)如下:

Spring Al 通過以下 Spring Boot 啟動器提供 MCP 集成：

客戶端啟動器

spring-ai-starter-mcp-client 核心啟動器提供 STDIO 和基于 HTTP 的 SSE 支持。
spring-ai-starter-mcp-client-webflux 基于WebFlux的SSE流式傳輸實現(xiàn)

服務(wù)端啟動器

spring-ai-starter-mcp-server 核心服務(wù)器具有 STDIO 傳輸支持
spring-ai-starter-mcp-server-webmvc 基于Spring MVC的SSE流式傳輸實現(xiàn)
spring-ai-starter-mcp-server-webflux 基于WebFlux的SSE流式傳輸實現(xiàn)

基于stdio標(biāo)準(zhǔn)流

MCP 服務(wù)端

基于 stdio 的實現(xiàn)是最常見的 MCP客戶端方案，它通過標(biāo)準(zhǔn)輸入輸出流與 MCP 服務(wù)器進行通信，這種方式簡單直觀，能夠直接通過進程間通信實現(xiàn)數(shù)據(jù)交互，避免了額外的網(wǎng)絡(luò)通信開銷，特別適用于本地部署的MCP服務(wù)器，可以在司一臺機器上啟動 MCP 服務(wù)器進程，與客戶端無縫對接。

引入依賴

<dependency>
  <groupId>org.springframework.ai</groupId>
  <artifactId>spring-ai-mcp-server-spring-boot-starter</artifactId>
  <version>1.0.0-M6</version>
</dependency>

配置MCP服務(wù)端

spring:
  application:
    name: mcp-server
  main:
    web-application-type: none # 必須禁用web應(yīng)用類型
    banner-mode: off # 禁用banner
  ai:
    mcp:
      server:
        stdio: true # 啟用stdio模式
        name: mcp-server # 服務(wù)器名稱
        version: 0.0.1 # 服務(wù)器版本

實現(xiàn)MCP工具

@Tool 是 SpingAI MCP框架中用于快速暴露業(yè)務(wù)能力為AI 工具的核心注解，該注解實現(xiàn)Java方法與MCP協(xié)議工具的自動銀蛇，并且可以通過注解的屬性description，有助于人工智能模型根據(jù)用戶輸入的信息決定是否調(diào)用這些工具，并返回相應(yīng)的結(jié)果.

@Service
public class OpenMeteoService {
    @Tool(description = "根據(jù)經(jīng)緯度獲取天氣預(yù)報")
    public String getAirQuality(
        @ToolParameter(description = "緯度，例如：39.9042") String latitude,
        @ToolParameter(description = "經(jīng)度，例如：116.4074") String longitude) {
        // 模擬數(shù)據(jù)，實際應(yīng)用中應(yīng)調(diào)用真實API
        return "當(dāng)前位置（緯度：" + latitude + "，經(jīng)度：" + longitude + "）的天氣信息：\n 多云轉(zhuǎn)陰";
    }
}

這個工具方法主要是用來根據(jù)經(jīng)緯度獲取天氣預(yù)報的，這里為了方便演示，寫了模擬數(shù)據(jù)

注冊MCP工具

最后向 MCP 服務(wù)注冊剛剛寫的工具：

    @Bean
    public ToolCallbackProvider serverTools(OpenMeteoService openMeteoService) {
        return MethodToolCallbackProvider.builder().toolObjects(openMeteoService).build();
    }

這段代碼定義了一個 Spring 的 Bean，用于將查詢天氣服務(wù) OpenMeteoService 中所有用 @Tool 注解標(biāo)記的方法注冊為工具，供 AI 模型調(diào)用。

ToolCallbackProvider 是Spring Al 中的一個接口，用于定義工具發(fā)現(xiàn)機制，主要負(fù)責(zé)將那些使用
@Tool 注解標(biāo)記的方法轉(zhuǎn)換為工具回調(diào)對象，并提供給 ChatClient 或ChatModel 使用，以便 AI 模型能夠在對話過程中調(diào)用這些工具。

MCP 客戶端

引入依賴

<dependency>
  <groupId>org.springframework.ai</groupId>
  <artifactId>spring-ai-mcp-client-spring-boot-starter</artifactId>
  <version>1.0.0-M6</version>
</dependency>

配置MCP服務(wù)器

因為服務(wù)端是通過 stdio 實現(xiàn)的，需要在 application.yml 中配置MCP服務(wù)器的一些參數(shù)：

spring:
  ai:
    mcp:
      client:
        stdio:
          # 指定MCP服務(wù)器配置文件
          servers-configuration: classpath:/mcp-servers-config.json
  mandatory-file-encoding: UTF-8

其中 mcp-servers-config.json 的配置如下：

{
  "mcpServers": {
    "weatherServer": {
      "command": "java",
      "args": [
        "-Dspring.ai.mcp.server.stdio=true",
        "-Dspring.main.web-application-type=none",
        "-Dlogging.pattern.console=",
        "-jar",
        "/Users/gulihua/Documents/mcp-server/target/mcp-server-0.0.1-SNAPSHOT.jar"
      ],
      "env": {}
    }
  }
}

這個配置文件設(shè)置了MCP客戶端的基本配置，包括 Java 命令參數(shù)，服務(wù)端 jar 包的絕對路徑等，上述的 JSON 配置文件也可以直接寫在 apllication.yaml 里，效果是一樣的。

    mcp:
      client:
        stdio:
         connections:
           server1:
             command: java
             args:
               - -Dspring.ai.mcp.server.stdio=true
               - -Dspring.main.web-application-type=none
               - -Dlogging.pattern.console=
               - -jar
               - /Users/gulihua/Documents/mcp-server/target/mcp-server-0.0.1-SNAPSHOT.jar

客戶端我們使用問里巴巴的通義千問模型，所以引入 spring-ai-alibaba-starter 依賴，如果使用的是其他的模型，也可以使用對應(yīng)的依賴項，比加 openAI 引入 sprine-ai-openai-spring-boot-starter 這個依賴就行了

配置大模型的密鑰等信息：

spring:
  ai:
    dashscope:
      api-key: ${通義千問的key}
      chat:
        options:
          model: qwen-max

初始化聊天客戶端

@Bean
public ChatClient initChatClient(ChatClient.Builder chatClientBuilder,
                                 ToolCallbackProvider mcpTools) {
    return chatClientBuilder
    .defaultTools(mcpTools)
    .build();
}

該代碼定義了一個 spring pean，用于初始化一個AI聊天客戶端，里面有兩個參數(shù)，chatcient.Buinider 是 SpnngAI 提供的AI聊天客戶端構(gòu)建器，用于構(gòu)建 ChatCient實例，是由 Spring AI 自動注入的，另一個是 ToolCallbackProvider，用于從MCP客服端發(fā)現(xiàn)并獲取AI工具。

然后就可以通過這個 chatclient 去調(diào)用了：

chatClient.prompt()
.user(request.getContent())
.call()
.content();

基于SSE

MCP服務(wù)端

除了基于 stdio 的實現(xiàn)外，Spring Al還提供了基于 Server-Sent vents(SSE)的 MCP客戶端方案。相較于 stdio方式，SSE 更適用于遠(yuǎn)程部署的 MCP 服務(wù)器，客戶端可以通過標(biāo)準(zhǔn) HTTP 協(xié)議與服務(wù)器建立連接，實現(xiàn)單向的實時數(shù)據(jù)推送?；?SSE的 MCP 服務(wù)器支持被多個客戶端的遠(yuǎn)程調(diào)用。

引入依賴

<dependency>
  <groupId>org.springframework.ai</groupId>
  <artifactId>spring-ai-mcp-server-webflux-spring-boot-starter</artifactId>
  <version>1.0.0-M6</version>
</dependency>

配置MCP服務(wù)端

server:
  port: 8090
spring:
  application:
    name: mcp-server
  ai:
    mcp:
      server:
        name: mcp-server # MCP服務(wù)器名稱
        version: 0.0.1   # 服務(wù)器版本號

除了引入的依賴包不一樣，以及配置文件不同，其他的不需要修改。

MCP 客戶端

引入依賴

<dependency>
  <groupId>org.springframework.ai</groupId>
  <artifactId>spring-ai-mcp-client-webflux-spring-boot-starter</artifactId>
  <version>1.0.0-M6</version>
</dependency>

配置MCP服務(wù)器

因為服務(wù)端是通過SSE實現(xiàn)的，需要在 application.yml 中配置MCP服務(wù)器的URL端口：

spring:
  ai:
    mcp:
      client:
        enabled: true
        name: mcp-client
        version: 1.0.0
        request-timeout: 30s
        type: ASYNC # 類型同步或者異步
        sse:
          connections:
            server1:
              url: http://localhost:8090

和MCP服務(wù)端的修改一樣，除了依賴和配置的修改，其他的也不需要調(diào)整

注意

除了上面基礎(chǔ)的用法和配置，還應(yīng)該考慮以下幾個方面:

工具設(shè)計
- 每個工具方法應(yīng)具備明確的功能定義及參數(shù)說明。
- 使用 @Tool 注解提供清晰、完整的工具描述，便于自動生成文檔或展示給前端。
- 使用 @ToolParameter 注解詳細(xì)說明每個參數(shù)的用途，提升使用者的理解與正確性。
錯誤處理
- 應(yīng)全面捕獲并妥善處理可能出現(xiàn)的異常，防止服務(wù)崩潰。
- 返回結(jié)構(gòu)化、具備可讀性的錯誤信息，便于客戶端識別錯誤原因并進行相應(yīng)處理。
性能優(yōu)化
- 對于可能耗時的任務(wù)，建議使用異步處理機制，避免阻塞主線程，
- 設(shè)置合理的超時時間，防止客戶端長時間等待，提高系統(tǒng)響應(yīng)性和穩(wěn)定性。
安全性考慮
- 對涉及敏感資源或關(guān)鍵操作的工具方法，應(yīng)添加嚴(yán)格的權(quán)限校驗邏輯
- 禁止在工具方法中執(zhí)行高風(fēng)險操作(如執(zhí)行任意系統(tǒng)命令)，以防止安全洞。
部署策略
- Stdio 模式：適用于嵌入式場景，可作為客戶端的子進程運行，便于集成與資源控制。
- SSE模式：更適合部署為獨立服務(wù)，支持多個客戶端同時訪問，適用于需要持續(xù)通信的遠(yuǎn)程調(diào)用場景。