​

MCP 服务器启动器文档

Spring AI MCP 服务器启动器 (spring-ai-mcp-server-boot-starter) 简化了符合模型上下文协议 (MCP) 的服务器应用程序的创建。

​

概述

MCP 服务器启动器提供了：

• 自动配置 MCP 端点。
• 用于处理 MCP 请求的组件。
• 与 Spring Boot 应用程序的无缝集成。

​

入门

要开始使用 MCP 服务器启动器，请将以下依赖项添加到您的 pom.xml 文件中：

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

​

配置

MCP 服务器启动器可以通过 application.properties 或 application.yml 文件进行配置。以下是一些常见的配置选项：

​

服务器属性

• spring.ai.mcp.server.enabled: 启用或禁用 MCP 服务器 (默认为 true)。
• spring.ai.mcp.server.path: MCP API 端点的基础路径 (默认为 /mcp)。
• spring.ai.mcp.server.port: MCP 服务器监听的端口 (默认为应用程序的服务器端口)。

示例 application.properties：

spring.ai.mcp.server.path=/api/mcp

​

模型配置

您需要配置您的 Spring AI 模型 (例如，ChatModel、EmbeddingModel)。MCP 服务器将使用这些已配置的模型来处理传入的请求。 确保您已按照各个模型文档中的说明配置了所需的模型 bean。

例如，要配置 OpenAI 聊天模型：

spring.ai.openai.api-key=YOUR_OPENAI_API_KEY
spring.ai.openai.chat.options.model=gpt-4o

​

用法

一旦配置完成，MCP 服务器启动器将自动暴露处理 MCP 请求所需的端点。

​

MCP 端点

默认情况下，MCP 服务器在 /mcp/v1/chat/completions (对于聊天模型) 和 /mcp/v1/embeddings (对于嵌入模型) 上暴露端点。这些路径可以通过 spring.ai.mcp.server.path 属性进行自定义。

​

处理程序

启动器提供了 McpChatHandler 和 McpEmbeddingHandler 来处理相应的 MCP 请求。这些处理程序使用已配置的 Spring AI 模型与底层 AI 提供程序进行交互。

您可以自定义这些处理程序的行为，或者通过提供您自己的 McpChatHandler 或 McpEmbeddingHandler bean 来提供您自己的实现。

​

自定义 McpChatHandler

@Bean
public McpChatHandler customMcpChatHandler(ChatModel chatModel) {
    // 自定义逻辑
    return new McpChatHandler(chatModel, new McpChatOptions(), null);
}

其中 McpChatOptions 可以包含特定于聊天的选项，如默认提示模板或后处理器。

​

请求和响应格式

服务器期望请求并以 MCP 指定的格式发送响应。有关详细信息，请参阅 MCP 规范。

​

示例：创建一个简单的 MCP 服务器

1. 添加依赖项：如上所述，将 spring-ai-mcp-server-boot-starter 和模型特定的启动器 (例如，spring-ai-openai-spring-boot-starter) 添加到您的 pom.xml 中。

2. 配置属性：在 application.properties 中配置您的 AI 模型凭证和可选的 MCP 服务器属性。

   # OpenAI 配置
   spring.ai.openai.api-key=YOUR_OPENAI_API_KEY
   spring.ai.openai.chat.options.model=gpt-4o
   
   # MCP 服务器配置 (可选)
   # spring.ai.mcp.server.path=/custom-mcp-path
   

3. 运行应用程序：启动您的 Spring Boot 应用程序。

MCP 服务器现在应该正在运行并准备好在配置的路径上处理 MCP 请求。

​

安全性

保护您的 MCP 端点非常重要。考虑使用 Spring Security 或其他身份验证/授权机制来保护您的 API。

以下是使用 Spring Security 进行基本身份验证的简单示例：

1. 添加 Spring Security 依赖项：

   <dependency>
       <groupId>org.springframework.boot</groupId>
       <artifactId>spring-boot-starter-security</artifactId>
   </dependency>
   

2. 配置安全规则：

   import org.springframework.context.annotation.Bean;
   import org.springframework.context.annotation.Configuration;
   import org.springframework.security.config.annotation.web.builders.HttpSecurity;
   import org.springframework.security.config.annotation.web.configuration.EnableWebSecurity;
   import org.springframework.security.core.userdetails.User;
   import org.springframework.security.core.userdetails.UserDetails;
   import org.springframework.security.provisioning.InMemoryUserDetailsManager;
   import org.springframework.security.web.SecurityFilterChain;
   
   import static org.springframework.security.config.Customizer.withDefaults;
   
   @Configuration
   @EnableWebSecurity
   public class SecurityConfig {
   
       @Bean
       public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
           http
               .authorizeHttpRequests(authorizeRequests ->
                   authorizeRequests
                       .requestMatchers("/mcp/**").authenticated() // 保护 MCP 端点
                       .anyRequest().permitAll()
               )
               .httpBasic(withDefaults());
           return http.build();
       }
   
       @Bean
       public InMemoryUserDetailsManager userDetailsService() {
           UserDetails user = User.withDefaultPasswordEncoder()
               .username("user")
               .password("password")
               .roles("USER")
               .build();
           return new InMemoryUserDetailsManager(user);
       }
   }
   

​

故障排除

• 404 未找到：验证 MCP 端点路径是否正确配置，并且您的应用程序是否正在运行。
• 身份验证错误：确保您的 AI 模型凭证正确无误且具有必要的权限。
• 依赖项冲突：检查您的 pom.xml 是否存在可能导致问题的冲突依赖项。

有关更多详细信息和高级配置，请参阅 Spring AI MCP 参考文档 和 GitHub 仓库。