【Spring AI MCP】六、SpringAI MCP 服务端 STDIO & SSE

Spring AI MCP学习目录

STDIO和SSE MCP服务器支持多种传输机制，每种机制都有其专用的启动器。

使用STDIO客户端或SSE客户端连接到STDIO和SSE服务器。

STDIO

通过STDIO服务器传输支持完整的MCP服务器功能。

xml 复制代码

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

适用于命令行和桌面工具
无需额外的Web依赖
基本服务器组件的配置
工具、资源和提示规范的处理
服务器功能和变更通知的管理
支持同步和异步服务器实现

SSE WebMVC

基于Spring MVC的SSE（服务器发送事件）服务器传输支持完整的MCP服务器功能，并提供可选的STDIO传输。

xml 复制代码

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

基于HTTP的传输，使用Spring MVC（WebMvcSseServerTransportProvider）
自动配置SSE端点
可选的STDIO传输（通过设置spring.ai.mcp.server.stdio=true启用）
包含spring-boot-starter-web和mcp-spring-webmvc依赖项

SSE WebFlux

基于Spring WebFlux的SSE（服务器发送事件）传输支持完整的MCP服务器功能，并提供可选的STDIO传输。

xml 复制代码

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

该启动器激活McpWebFluxServerAutoConfiguration 和McpServerAutoConfiguration自动配置，提供：

使用Spring WebFlux的反应式传输（WebFluxSseServerTransportProvider）
自动配置的反应式SSE端点
可选的STDIO传输（通过设置spring.ai.mcp.server.stdio=true启用）
包含spring-boot-starter-webflux和mcp-spring-webflux依赖

由于Spring Boot的默认行为，当类路径上同时存在org.springframework.web.servlet.DispatcherServlet和org.springframework.web.reactive.DispatcherHandler时，Spring Boot会优先使用DispatcherServlet。因此，如果项目使用spring-boot-starter-web，建议使用spring-ai-starter-mcp-server-webmvc而不是spring-ai-starter-mcp-server-webflux。

配置

公共配置

所有通用属性均以 spring.ai.mcp.server 作为前缀：

属性	说明	默认值
enabled	启用/禁用 MCP 服务器	true
tool-callback-converter	启用/禁用 Spring AI ToolCallbacks 到 MCP 工具规范的转换	true
stdio	启用/禁用 STDIO 传输	false
name	用于标识的服务器名称	mcp-server
version	服务器版本	1.0.0
instructions	可选的指导说明，向客户端提供与此服务器交互的指引	null
type	服务器类型（SYNC/ASYNC）	SYNC
capabilities.resource	启用/禁用资源能力	true
capabilities.tool	启用/禁用工具能力	true
capabilities.prompt	启用/禁用提示能力	true
capabilities.completion	启用/禁用自动补全能力	true
resource-change-notification	启用资源变更通知	true
prompt-change-notification	启用提示变更通知	true
tool-change-notification	启用工具变更通知	true
tool-response-mime-type	按工具名称设置可选的响应 MIME 类型。例如，spring.ai.mcp.server.tool-response-mime-type.generateImage=image/png 会将 image/png MIME 类型与 generateImage() 工具名称关联	-
request-timeout	请求超时前等待服务器响应的时长。适用于通过客户端进行的所有请求，包括工具调用、资源访问和提示操作	20 秒

注解

MCP服务器注解提供了一种使用Java注解实现MCP服务器处理程序的声明式方法。

服务器MCP注解属性以 spring.ai.mcp.server.annotation-scanner 作为前缀：

属性	说明	默认值
enabled	启用/禁用MCP服务器注解自动扫描	true

SSE

所有SSE属性均以spring.ai.mcp.server为前缀：

属性	说明	默认值
sse-message-endpoint	客户端用于发送消息的Web传输自定义SSE消息端点路径	/cp/message
sse-endpoint	Web传输自定义SSE端点路径	/sse
base-url	可选URL前缀（如base-url=/api/v1时，SSE端点路径为/api/v1/sse）	-
keep-alive-interval	连接保活间隔（null表示禁用）	null

特新&能力

MCP Server Boot Starter 允许服务端向客户端暴露工具、资源和提示词。它会根据服务器类型，自动将注册为 Spring Bean 的自定义能力处理器转换为同步或异步规范。

Tools

允许服务端暴露可被大语言模型调用的工具。MCP Server Boot Starter 提供以下功能：

变更通知支持
Spring AI 工具会根据服务器类型自动转换为同步或异步规范
通过 Spring Bean 自动注册工具规范：使用高层 API：

java 复制代码

@Bean
public ToolCallbackProvider myTools(...) {
    List<ToolCallback> tools = ...;
    return ToolCallbackProvider.from(tools);
}

或使用底层 API：

java 复制代码

@Bean
public List<McpServerFeatures.SyncToolSpecification> myTools(...) {
    List<McpServerFeatures.SyncToolSpecification> tools = ...;
    return tools;
}

自动配置会自动检测并注册来自以下来源的所有工具回调（tool callbacks）：

单个 ToolCallback 类型的 Bean
ToolCallback 列表类型的 Bean
ToolCallbackProvider 类型的 Bean

工具会按名称去重，每个工具名称仅保留首次出现的实例。

工具上下文支持

支持ToolContext，允许将上下文信息传递给工具调用。该对象在exchange键下包含一个McpSyncServerExchange实例，可通过McpToolUtils.getMcpExchange(toolContext)访问。示例演示了exchange.loggingNotification(...)和exchange.createMessage(...)的用法。

Resources

为服务器向客户端暴露资源提供标准化方式。

静态/动态资源规范
可选变更通知
支持资源模板
自动转换同步/异步资源规范
通过Spring Bean自动生成资源规范

java 复制代码

@Bean
public List<McpServerFeatures.SyncResourceSpecification> myResources(...) {
    var systemInfoResource = new McpSchema.Resource(...);
    var resourceSpecification = new McpServerFeatures.SyncResourceSpecification(systemInfoResource, (exchange, request) -> {
        try {
            var systemInfo = Map.of(...);
            String jsonContent = new ObjectMapper().writeValueAsString(systemInfo);
            return new McpSchema.ReadResourceResult(
                    List.of(new McpSchema.TextResourceContents(request.uri(), "application/json", jsonContent)));
        }
        catch (Exception e) {
            throw new RuntimeException("Failed to generate system info", e);
        }
    });

    return List.of(resourceSpecification);
}

Prompts

为服务器向客户端暴露提示模板提供标准化方式。

变更通知支持
模板版本控制
自动转换同步/异步提示规范
通过Spring Bean自动生成提示规范

java 复制代码

@Bean
public List<McpServerFeatures.SyncPromptSpecification> myPrompts() {
    var prompt = new McpSchema.Prompt("greeting", "A friendly greeting prompt",
        List.of(new McpSchema.PromptArgument("name", "The name to greet", true)));

    var promptSpecification = new McpServerFeatures.SyncPromptSpecification(prompt, (exchange, getPromptRequest) -> {
        String nameArgument = (String) getPromptRequest.arguments().get("name");
        if (nameArgument == null) { nameArgument = "friend"; }
        var userMessage = new PromptMessage(Role.USER, new TextContent("Hello " + nameArgument + "! How can I assist you today?"));
        return new GetPromptResult("A personalized greeting message", List.of(userMessage));
    });

    return List.of(promptSpecification);
}

Completions

为服务器向客户端暴露自动补全能力提供标准化方式。

支持同步和异步自动补全规范
通过Spring Bean自动注册。

java 复制代码

@Bean
public List<McpServerFeatures.SyncCompletionSpecification> myCompletions() {
    var completion = new McpServerFeatures.SyncCompletionSpecification(
        new McpSchema.PromptReference(
					"ref/prompt", "code-completion", "Provides code completion suggestions"),
        (exchange, request) -> {
            // Implementation that returns completion suggestions
            return new McpSchema.CompleteResult(List.of("python", "pytorch", "pyside"), 10, true);
        }
    );

    return List.of(completion);
}

Logging

为服务器向客户端发送结构化日志消息提供标准化方式。在工具、资源、提示或自动补全调用处理程序中，使用提供的McpSyncServerExchange/McpAsyncServerExchange交换对象发送日志消息：

java 复制代码

(exchange, request) -> {
    exchange.loggingNotification(LoggingMessageNotification.builder()
        .level(LoggingLevel.INFO)
        .logger("test-logger")
        .data("This is a test log message")
        .build());
}

在MCP客户端，可以注册日志消费者来处理这些消息：

java 复制代码

mcpClientSpec.loggingConsumer((McpSchema.LoggingMessageNotification log) -> {
    // 处理日志消息
});

Progress

为服务器向客户端发送进度更新提供标准化方式。在工具、资源、提示或自动补全调用处理程序中，使用提供的McpSyncServerExchange/McpAsyncServerExchange交换对象发送进度通知：

java 复制代码

(exchange, request) -> {
    exchange.progressNotification(ProgressNotification.builder()
        .progressToken("test-progress-token")
        .progress(0.25)
        .total(1.0)
        .message("tool call in progress")
        .build());
}

MCP客户端可以接收进度通知并相应更新其UI。为此需要注册一个进度消费者：

java 复制代码

mcpClientSpec.progressConsumer((McpSchema.ProgressNotification progress) -> {
    // 处理进度通知
});

Root List Changes

当根节点变更时，支持listChanged的客户端会发送根节点变更通知。

根节点变更监控
自动转换为响应式应用的异步消费者
通过Spring Bean可选注册

java 复制代码

@Bean
public BiConsumer<McpSyncServerExchange, List<McpSchema.Root>> rootsChangeHandler() {
    return (exchange, roots) -> {
        logger.info("Registering root resources: {}", roots);
    };
}

Ping

服务器健康检查机制：通过Ping消息验证客户端存活状态。在工具、资源、提示或自动补全调用处理程序中，使用提供的McpSyncServerExchange/McpAsyncServerExchange交换对象发送Ping消息。

java 复制代码

(exchange, request) -> {
        exchange.ping();
}

Keep Alive

服务器可定期向客户端发送Ping消息以验证连接健康状态。默认情况下保活功能处于禁用状态，需在配置中设置keep-alive-interval参数启用‌。

yaml 复制代码

spring:
  ai:
    mcp:
      server:
        keep-alive-interval: 30s

样例

样例代码：https://gitee.com/mqiqe/zixiai

STDIO

yaml 复制代码

# Using spring-ai-starter-mcp-server
spring:
  ai:
    mcp:
      server:
        name: stdio-mcp-server
        version: 1.0.0
        type: SYNC

WebMVC

yaml 复制代码

# Using spring-ai-starter-mcp-server-webmvc
spring:
  ai:
    mcp:
      server:
        name: webmvc-mcp-server
        version: 1.0.0
        type: SYNC
        instructions: "This server provides weather information tools and resources"
        capabilities:
          tool: true
          resource: true
          prompt: true
          completion: true
        # sse properties
        sse-message-endpoint: /mcp/messages
        keep-alive-interval: 30s

WebFlux

yaml 复制代码

# Using spring-ai-starter-mcp-server-webflux
spring:
  ai:
    mcp:
      server:
        name: webflux-mcp-server
        version: 1.0.0
        type: ASYNC  # Recommended for reactive applications
        instructions: "This reactive server provides weather information tools and resources"
        capabilities:
          tool: true
          resource: true
          prompt: true
          completion: true
        # sse properties
        sse-message-endpoint: /mcp/messages
        keep-alive-interval: 30s

MCP Server

java 复制代码

@Service
public class WeatherService {

    @Tool(description = "Get weather information by city name")
    public String getWeather(String cityName) {
        // Implementation
    }
}

@SpringBootApplication
public class McpServerApplication {

    private static final Logger logger = LoggerFactory.getLogger(McpServerApplication.class);

    public static void main(String[] args) {
        SpringApplication.run(McpServerApplication.class, args);
    }

	@Bean
	public ToolCallbackProvider weatherTools(WeatherService weatherService) {
		return MethodToolCallbackProvider.builder().toolObjects(weatherService).build();
	}
}