Spring AI框架中集成MCP的完整指南：从服务端到客户端的全流程实践

🌺The Begin🌺点点关注，收藏不迷路🌺 ⬇ ⬇ 底部 ⬇ ⬇

随着Spring AI 1.1正式版的发布，模型上下文协议（MCP）的集成已成为Spring生态中AI开发的核心能力。Spring团队不仅主导了MCP Java SDK的开发，还提供了专用的Boot Starter和注解编程模型，让开发者能够以Spring惯用的方式快速构建MCP服务端和客户端。本文将带您从零开始，完整实践在Spring AI框架中集成MCP的全流程。

一、集成概览：Spring AI的MCP生态架构

Spring AI为MCP提供了全方位的支持，涵盖服务端和客户端两端，支持多种传输协议和部署模式。

Spring AI MCP的核心依赖

Spring AI 1.1提供了多款专用Starter，覆盖不同的使用场景和传输需求：

客户端Starter：

• spring-ai-starter-mcp-client：核心客户端，支持stdio和基于HTTP的SSE
• spring-ai-starter-mcp-client-webflux：基于WebFlux的响应式客户端

服务端Starter：

• spring-ai-starter-mcp-server：核心服务端，支持stdio传输
• spring-ai-starter-mcp-server-webmvc：基于Spring MVC的SSE服务端
• spring-ai-starter-mcp-server-webflux：基于WebFlux的响应式服务端

二、方式一：基于注解的MCP服务端开发（推荐）

Spring AI 1.1推荐使用注解驱动的开发方式，通过@McpTool、@McpResource、@McpPrompt等注解，将普通Spring Bean的方法暴露为MCP能力。

步骤1：添加Maven依赖

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-mcp-server-webmvc</artifactId>
</dependency>

步骤2：实现工具服务

使用@McpTool注解标记方法，框架会自动将其注册为MCP工具：

@Service
public class WeatherService {
    @McpTool(description = "获取指定城市的实时天气信息")
    public String getWeather(
            @McpToolParam(description = "城市名称", required = true) String city) {
        // 调用真实天气API
        return String.format("北京市当前天气：晴，温度25°C，湿度45%%");
    }
    @McpTool(description = "计算两个数字的数学运算")
    public double calculate(
            @McpToolParam(description = "第一个数字") double num1,
            @McpToolParam(description = "运算符 + - * /") String operator,
            @McpToolParam(description = "第二个数字") double num2) {
        switch (operator) {
            case "+": return num1 + num2;
            case "-": return num1 - num2;
            case "*": return num1 * num2;
            case "/": return num1 / num2;
            default: throw new IllegalArgumentException("不支持的运算符");
        }
    }
}

@McpTool注解的description属性会传递给AI模型，帮助模型理解工具的用途和调用时机。

步骤3：配置文件

spring:
  ai:
    mcp:
      server:
        name: my-weather-mcp-server
        version: 1.0.0
        protocol: STREAMABLE   # 支持STREAMABLE或SSE
        sse-endpoint: /sse
        sse-message-endpoint: /mcp/messages

注意：使用spring-ai-starter-mcp-server-webmvc时，需要配置protocol: STREAMABLE以启用HTTP流式传输。

三、方式二：基于SSE的远程MCP服务端

对于需要远程部署、支持多客户端并发访问的场景，SSE（Server-Sent Events）模式是更合适的选择。与stdio模式不同，SSE模式将MCP服务器暴露为标准的HTTP端点。

依赖配置

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-mcp-server-webmvc</artifactId>
</dependency>

服务端配置

spring:
  ai:
    mcp:
      server:
        name: remote-mcp-server
        version: 1.0.0
        stdio: false          # 关闭stdio模式
        type: ASYNC           # 异步处理
        sse-endpoint: /sse
        sse-message-endpoint: /mcp/messages
        capabilities:
          tool: true
          resource: true
          prompt: true

SSE模式下，客户端通过/sse端点建立长连接，服务器通过/mcp/messages端点接收消息，支持服务器主动推送实时通知和进度更新。

四、MCP客户端集成：连接与调用

步骤1：添加客户端依赖

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-mcp-client</artifactId>
</dependency>

步骤2：配置MCP服务器连接

创建src/main/resources/mcp-servers.json，配置需要连接的MCP服务：

{
  "mcpServers": {
    "weather-server": {
      "command": "java",
      "args": [
        "-jar",
        "-Dspring.ai.mcp.server.stdio=true",
        "-Dspring.main.web-application-type=none",
        "/path/to/your/mcp-server.jar"
      ]
    },
    "remote-sse-server": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://localhost:8080/sse"
      ]
    }
  }
}

步骤3：配置客户端属性

spring:
  ai:
    mcp:
      client:
        enabled: true
        name: my-agent-mcp-client
        version: 1.0.0
        type: SYNC                    # SYNC或ASYNC
        request-timeout: 30s
        toolcallback:
          enabled: true               # 启用工具回调
        stdio:
          servers-configuration: classpath:mcp-servers.json

步骤4：在ChatClient中使用MCP工具

通过ToolCallbackProvider将MCP工具注入到ChatClient中：

@Bean
public CommandLineRunner demo(ChatClient chatClient, ToolCallbackProvider mcpTools) {
    return args -> {
        String response = chatClient
            .prompt("北京今天的天气怎么样？")
            .tools(mcpTools)              // 注入MCP工具
            .call()
            .content();
        System.out.println(response);
    };
}

MCP客户端会自动发现服务器提供的所有工具，无需手动注册。框架通过tools/list请求在运行时获取工具列表，实现了动态工具发现。

五、Spring AI MCP的安全集成

在企业级部署中，MCP服务器的安全防护至关重要。Spring AI提供了与Spring Security的无缝集成，支持OAuth2认证。

添加安全依赖

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-oauth2-resource-server</artifactId>
</dependency>
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-oauth2-authorization-server</artifactId>
</dependency>

配置安全过滤器链

通过Spring Security的配置类，将MCP服务器同时配置为资源服务器（验证token）和授权服务器（颁发token）：

@Configuration
@EnableWebSecurity
public class SecurityConfiguration {
    @Bean
    SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
        return http
            .authorizeHttpRequests(auth -> auth.anyRequest().authenticated())
            .oauth2ResourceServer(resource -> resource.jwt(Customizer.withDefaults()))
            .csrf(CsrfConfigurer::disable)
            .cors(Customizer.withDefaults())
            .build();
    }
}

客户端配置OAuth2

在mcp-servers.json中为远程服务配置认证头：

{
  "mcpServers": {
    "secure-remote-server": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://secure-mcp.example.com/mcp",
        "--header",
        "Authorization: Bearer ${MCP_ACCESS_TOKEN}"
      ]
    }
  }
}

六、集成模式对比与选型建议

维度	stdio模式	SSE/Streamable HTTP模式
部署方式	客户端启动服务器子进程	服务器独立部署为HTTP服务
通信机制	标准输入/输出	HTTP + Server-Sent Events
生命周期	客户端完全控制	服务器独立运行
多客户端	通常一对一	支持多客户端并发
安全要求	较低（本地通信）	需配置OAuth2等认证机制
适用场景	本地工具集成、IDE插件	分布式系统、云端部署

总结

Spring AI通过专用的Boot Starter、注解驱动的编程模型以及与Spring Security的深度集成，为MCP协议提供了全方位的支持。开发者可以选择基于stdio的本地进程通信实现轻量级工具集成，也可以选择基于SSE/Streamable HTTP的远程部署模式构建分布式AI系统。掌握这套集成方案，将让您在使用Spring AI构建AI Agent应用时，能够以标准化、可扩展的方式接入各种外部工具和数据源。

🌺The End🌺点点关注，收藏不迷路🌺 ⬆ ⬆ 顶部 ⬆ ⬆