Spring AI 1.x 系列【42】MCP 服务端 Spring Boot 启动器

1. 概述

模型上下文协议（MCP）服务端是一种通过标准化协议接口向 AI 应用暴露特定能力的程序，每个服务端专注于某一领域的功能。

Spring AI MCP Server Boot Starter 为 Spring Boot 应用提供了 MCP 服务端自动配置能力，可无缝集成 MCP 服务端功能与 Spring Boot 自动配置体系。

本启动器具备以下能力：

• 自动配置 MCP 服务端组件，包括工具、资源、提示词
• 支持多种 MCP 协议版本：STDIO、SSE、Streamable-HTTP、Stateless
• 同时支持同步(SYNC)和异步(ASYNC)两种运行模式
• 提供多种传输层选项
• 灵活的工具、资源、提示词声明方式
• 变更通知能力
• 基于注解的服务端开发，支持自动 Bean 扫描与注册

---

2. 启动器与依赖配置

MCP 服务端支持多种协议与传输机制。请根据场景选择对应的启动器，并配置 spring.ai.mcp.server 属性。

2.1 STDIO（标准输入输出）

服务端类型	依赖	配置属性
STDIO	spring-ai-starter-mcp-server	spring.ai.mcp.server.stdio=true

2.2 WebMVC

服务端类型	依赖	配置属性
SSE WebMVC	spring-ai-starter-mcp-server-webmvc	spring.ai.mcp.server.protocol=SSE（或留空）
Streamable-HTTP WebMVC	spring-ai-starter-mcp-server-webmvc	spring.ai.mcp.server.protocol=STREAMABLE
Stateless WebMVC	spring-ai-starter-mcp-server-webmvc	spring.ai.mcp.server.protocol=STATELESS

2.3 WebFlux（响应式）

服务端类型	依赖	配置属性
SSE WebFlux	spring-ai-starter-mcp-server-webflux	spring.ai.mcp.server.protocol=SSE（或留空）
Streamable-HTTP WebFlux	spring-ai-starter-mcp-server-webflux	spring.ai.mcp.server.protocol=STREAMABLE
Stateless WebFlux	spring-ai-starter-mcp-server-webflux	spring.ai.mcp.server.protocol=STATELESS

---

3. 配置项说明

3.1 服务器能力

根据服务端类型与传输方式的不同，MCP 服务端可启用以下能力（默认全部开启）：

能力	说明
工具（Tools）	暴露可供语言模型调用的工具。应用上下文中所有可用工具均会发布为 MCP 工具，包括从 MCP 客户端获取的工具
资源（Resources）	以标准化方式向客户端暴露资源
提示词（Prompts）	以标准化方式向客户端暴露提示词模板
补全（Completions）	为提示词和资源 URI 提供参数自动补全建议
日志（Logging）	以标准化方式向客户端发送结构化日志消息
进度（Progress）	通过通知消息为长时间运行的操作提供进度跟踪
心跳（Ping）	可选的服务端健康检查机制，用于上报运行状态

关闭某项能力后，服务端将不再注册并向客户端暴露对应功能。

3.2 服务器协议

协议	说明	启用方式
STDIO	进程内协议（服务端运行在宿主应用内部），通过标准输入/输出通信	spring.ai.mcp.server.stdio=true
SSE	服务端推送事件协议，适用于实时更新场景；服务端作为独立进程运行，可处理多个客户端连接	默认协议，或 spring.ai.mcp.server.protocol=SSE
Streamable-HTTP	基于 HTTP POST/GET 的流式传输，可选 SSE 流式推送多条消息；替代传统 SSE 传输	spring.ai.mcp.server.protocol=STREAMABLE
Stateless	无状态服务端，请求之间不维护会话状态，适合微服务和云原生部署	spring.ai.mcp.server.protocol=STATELESS

3.3 同步/异步模式

模式	实现类	说明	配置
同步（SYNC）	McpSyncServer	默认模式，适用于传统请求-响应场景；仅注册同步 MCP 注解方法，异步方法会被忽略	spring.ai.mcp.server.type=SYNC
异步（ASYNC）	McpAsyncServer	适用于响应式非阻塞场景；仅注册异步 MCP 注解方法，同步方法会被忽略；内置 Project Reactor 支持	spring.ai.mcp.server.type=ASYNC

3.4 完整配置示例

spring:
  ai:
    mcp:
      server:
        type: SYNC  # 或 ASYNC
        annotation-scanner:
          enabled: true

---

4. MCP 服务端注解

Spring AI MCP Server Boot Starter 提供全面的注解驱动开发支持，可通过声明式 Java 注解替代手动配置来创建 MCP 服务端。

4.1 核心注解

注解	用途
@McpTool	标记方法为 MCP 工具，自动生成 JSON Schema
@McpResource	通过 URI 模板提供资源访问
@McpPrompt	生成用于 AI 交互的提示消息
@McpComplete	为提示词提供自动补全功能

4.2 特殊参数

注解系统支持以下特殊参数类型，可注入额外上下文信息：

参数类型	用途
McpMeta	访问 MCP 请求中的元数据
@McpProgressToken	接收长时间运行操作的进度令牌
McpSyncServerExchange / McpAsyncServerExchange	完整服务端上下文，用于高级操作
McpTransportContext	轻量级上下文，用于无状态操作
CallToolRequest	动态 Schema 支持，用于灵活工具定义

4.3 使用示例

@Component
public class CalculatorTools {

    @McpTool(name = "add", description = "将两个数相加")
    public int add(
            @McpToolParam(description = "第一个数", required = true) int a,
            @McpToolParam(description = "第二个数", required = true) int b) {
        return a + b;
    }

    @McpResource(uri = "config://{key}", name = "配置项")
    public String getConfig(String key) {
        return configData.get(key);
    }
}

---

5. 自动配置

通过 Spring Boot 自动配置，带有 MCP 注解的 Bean 会被自动检测并注册：

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

自动配置会完成以下工作：

1. 扫描所有带有 MCP 注解的 Bean
2. 创建对应的声明规范
3. 将声明注册到 MCP 服务端
4. 根据配置自动适配同步/异步实现

---