MCP 服务端启动器

模型上下文协议（MCP）服务器 是通过标准化协议接口向 AI 应用程序提供特定功能的程序。每个服务器都针对特定领域提供专门的功能。

Spring AI 的 MCP 服务器 Boot Starters 为在 Spring Boot 应用中搭建 MCP 服务器 提供了自动配置支持，使 MCP 服务器的功能能够无缝集成到 Spring Boot 的自动配置系统中。

MCP 服务器 Boot Starters 提供的功能包括：

• MCP 服务器组件的自动配置，包括工具、资源和提示（prompts）
• 支持不同的 MCP 协议版本，包括 STDIO、SSE、Streamable-HTTP 以及无状态服务器
• 支持同步和异步操作模式
• 多种传输层选项
• 灵活的工具、资源和提示定义方式
• 支持变更通知功能
• 基于注解的服务器开发，自动扫描并注册 Bean

MCP 服务器 Boot Starters

MCP 服务器支持多种协议和传输机制。请使用专用的 Starter，并通过正确设置 spring.ai.mcp.server.protocol 属性来配置服务器：

STDIO

WebMVC

WebMVC（响应式）

服务器功能

根据服务器类型和传输方式，MCP 服务器可以支持多种功能，例如：

• 工具（Tools） —— 允许服务器暴露可被语言模型调用的工具
• 资源（Resources） —— 为服务器提供向客户端暴露资源的标准化方式
• 提示（Prompts） —— 为服务器提供向客户端暴露提示模板的标准化方式
• 实用功能/补全（Utility/Completions） —— 为服务器提供对提示和资源 URI 的参数自动补全建议
• 实用功能/日志（Utility/Logging） —— 为服务器提供向客户端发送结构化日志消息的标准化方式
• 实用功能/进度（Utility/Progress） —— 可选的长时间操作进度跟踪，通过通知消息发送
• 实用功能/Ping（Utility/Ping） —— 可选的健康检查机制，用于服务器报告自身状态

所有功能默认均已启用。禁用某项功能将阻止服务器注册并向客户端暴露对应的功能。

服务器协议

MCP 提供了多种协议类型，包括：

• STDIO —— 进程内协议（例如服务器运行在宿主应用内）。通信通过标准输入（stdin）和标准输出（stdout）进行。启用 STDIO 协议请设置 spring.ai.mcp.server.stdio=true。
• SSE —— 服务器发送事件（Server-Sent Events）协议，用于实时更新。服务器作为独立进程运行，可处理多个客户端连接。
• Streamable-HTTP —— 可流式 HTTP 传输协议，允许 MCP 服务器作为独立进程运行，通过 HTTP POST 和 GET 请求处理多个客户端连接，同时可选支持 SSE 流式传输多个服务器消息，取代了 SSE 传输。启用 STREAMABLE 协议请设置 spring.ai.mcp.server.protocol=STREAMABLE。
• 无状态（Stateless） —— 无状态 MCP 服务器设计用于简化部署，不在请求之间维护会话状态，非常适合微服务架构和云原生部署。启用 STATELESS 协议请设置 spring.ai.mcp.server.protocol=STATELESS。

同步/异步服务器 API 选项

MCP 服务器 API 支持命令式（同步）和响应式（异步）编程模型。

• 同步服务器（Synchronous Server） —— 默认服务器类型，由 McpSyncServer 实现，适用于应用中的简单请求-响应模式。要启用此服务器类型，请在配置中设置 spring.ai.mcp.server.type=SYNC。启用后，它会自动处理同步工具规格的配置。

• 异步服务器（Asynchronous Server） —— 异步服务器由 McpAsyncServer 实现，优化用于非阻塞操作。要启用此服务器类型，请在配置中设置 spring.ai.mcp.server.type=ASYNC。此类型服务器会自动设置异步工具规格，并内置支持 Project Reactor。

MCP 服务器注解

MCP 服务器 Boot Starters 提供了对基于注解的服务器开发的全面支持，使你可以通过声明式的 Java 注解创建 MCP 服务器，而无需手动配置。

关键注解

• @McpTool —— 将方法标记为 MCP 工具，并自动生成 JSON Schema
• @McpResource —— 通过 URI 模板提供对资源的访问
• @McpPrompt —— 为 AI 交互生成提示消息
• @McpComplete —— 为提示提供自动补全功能

特殊参数

注解系统支持提供额外上下文的 特殊参数类型：

• McpMeta —— 访问 MCP 请求中的元数据
• @McpProgressToken —— 接收长时间操作的进度令牌
• McpSyncServerExchange / McpAsyncServerExchange —— 用于高级操作的完整服务器上下文
• McpTransportContext —— 无状态操作的轻量级上下文
• CallToolRequest —— 支持动态 schema，用于灵活的工具调用

简单示例

@Component
public class CalculatorTools {

    @McpTool(name = "add", description = "Add two numbers together")
    public int add(
            @McpToolParam(description = "First number", required = true) int a,
            @McpToolParam(description = "Second number", required = true) int b) {
        return a + b;
    }

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

自动配置

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

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

自动配置将会：

1. 扫描带有 MCP 注解的 Bean
2. 创建相应的工具或资源规格
3. 将其注册到 MCP 服务器
4. 根据配置处理同步和异步实现

配置属性

配置服务器注解扫描器：

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

附加资源

• 服务器注解参考 — 服务器注解完整指南
• 特殊参数 — 高级参数注入
• 示例 — 全面示例与使用场景

示例应用

• 天气服务器（SSE WebFlux） —— 使用 WebFlux 传输的 Spring AI MCP 服务器 Boot Starter
• 天气服务器（STDIO） —— 使用 STDIO 传输的 Spring AI MCP 服务器 Boot Starter
• 天气服务器手动配置 —— 不使用自动配置，而是通过 Java SDK 手动配置服务器的 Spring AI MCP 服务器 Boot Starter
• Streamable-HTTP WebFlux/WebMVC 示例—— 待完成
• 无状态 WebFlux/WebMVC 示例—— 待完成

附加资源

• MCP 服务器注解 —— 使用注解进行声明式服务器开发
• 特殊参数 —— 高级参数注入与上下文访问
• MCP 注解示例 —— 全面示例与使用场景
• Spring AI 文档
• 模型上下文协议（MCP）规范
• Spring Boot 自动配置