跳到主要内容
版本：2.0.1

MCP Server Boot Starter

QWen 3.8 中英对照 MCP Server Boot Starters MCP Server Boot Starter

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

Spring AI MCP Server Boot Starters 为在 Spring Boot 应用中配置 MCP Servers 提供自动配置功能。它们使得 MCP 服务器功能能够与 Spring Boot 的自动配置系统无缝集成。

MCP Server Boot Starters 提供：

  • MCP 服务器组件的自动配置，包括工具、资源和提示词

  • 支持不同的 MCP 协议版本，包括 STDIO、SSE、Streamable-HTTP 以及无状态服务器

  • 支持同步和异步两种操作模式

  • 多种传输层选项

  • 灵活的工具、资源和提示词定义

  • 变更通知能力

  • 基于注解的服务器开发（Annotation-based server development），支持自动 Bean 扫描和注册

注意

基于 HTTP 的服务器传输方式（SSE、Streamable-HTTP 和 Stateless）默认会暴露一个未认证的 JSON-RPC 端点。初始模板（Starters）本身不施加任何认证或授权机制，因此任何能够访问该端点的客户端都可以列出并调用所有已注册的工具（Tool）、资源（Resource）和提示（Prompt）。在将 MCP 服务器暴露到 localhost 之外之前，必须在服务器前设置安全边界。详情请参阅 Securing the MCP Server。

此说明不适用于 STDIO 传输方式，因为它是在进程内运行的，且不通过网络访问。

MCP 服务器启动器​

MCP 服务器支持多种协议和传输机制。请使用专用的 starter 以及正确的 spring.ai.mcp.server.protocol 属性来配置您的服务器：

STDIO​

服务器类型依赖项属性
标准输入/输出 (STDIO)spring-ai-starter-mcp-serverspring.ai.mcp.server.stdio=true

WebMVC​

服务器类型依赖属性
SSE WebMVC _(自 2.0.0 起已弃用，请使用 STREAMABLE)spring-ai-starter-mcp-server-webmvcspring.ai.mcp.server.protocol=SSE
Streamable-HTTP WebMVCspring-ai-starter-mcp-server-webmvcspring.ai.mcp.server.protocol=STREAMABLE
Stateless WebMVCspring-ai-starter-mcp-server-webmvcspring.ai.mcp.server.protocol=STATELESS

WebFlux (响应式)​

服务器类型依赖项属性
SSE WebFlux _(自 2.0.0 起弃用，请改用 STREAMABLE)spring-ai-starter-mcp-server-webfluxspring.ai.mcp.server.protocol=SSE
Streamable-HTTP WebFluxspring-ai-starter-mcp-server-webfluxspring.ai.mcp.server.protocol=STREAMABLE
Stateless WebFluxspring-ai-starter-mcp-server-webfluxspring.ai.mcp.server.protocol=STATELESS

服务器功能​

根据服务器和传输类型的不同，MCP 服务器可支持各种功能，例如：

  • Tools - 允许服务器暴露可由语言模型调用的工具

  • Resources - 为服务器向客户端暴露资源提供标准化的方式

  • Prompts - 为服务器向客户端暴露提示词模板提供标准化的方式

  • Utility/Completions - 为服务器提供提示词和资源 URI 的参数自动补全建议提供标准化的方式

  • Utility/Logging - 为服务器向客户端发送结构化日志消息提供标准化的方式

  • Utility/Progress - 通过通知消息为长时运行操作提供可选的进度跟踪

  • Utility/Ping - 用于服务器报告其状态的可选健康检查机制

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

服务器协议​

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

  • STDIO - 进程内（例如服务器运行在宿主应用内部）协议。通信通过标准输入和标准输出进行。要启用 STDIO，请设置 spring.ai.mcp.server.stdio=true。

  • SSE - 用于实时更新的服务器发送事件协议。服务器作为独立进程运行，可以处理多个客户端连接。

  • Streamable-HTTP - Streamable HTTP 传输 允许 MCP 服务器作为独立进程运行，使用 HTTP POST 和 GET 请求处理多个客户端连接，并可选地通过服务器发送事件（SSE）流式传输多条服务器消息。它取代了 SSE 传输。要启用 STREAMABLE 协议，请设置 spring.ai.mcp.server.protocol=STREAMABLE。

  • Stateless - 无状态 MCP 服务器专为简化部署而设计，请求之间不维护会话状态。它们非常适合微服务架构和云原生部署。要启用 STATELESS 协议，请设置 spring.ai.mcp.server.protocol=STATELESS。

保护 MCP 服务器​

MCP 服务器传输层在设计上是与认证机制无关的：自动配置仅负责端点的装配，并不强制实施认证或授权。与任何其他 Spring Web 端点一样，保护基于 HTTP 的 MCP 服务器（SSE、Streamable-HTTP 或 Stateless）的责任，在于你在其前面添加的专用安全层——这并非由传输层本身提供。安全库的示例包括 Spring Security 和 MCP Security。

important

在默认配置下，MCP 端点（默认为 POST /mcp）接受所有请求，允许任何可访问网络的客户端在无需凭据的情况下枚举并调用你注册的工具、资源和提示词。请将注册工具、资源或提示词视为决定将其对外暴露的行为，并在部署到 localhost 以外的环境之前确保该端点的安全性。

同步/异步服务器 API 选项​

MCP Server API 支持命令式（即同步）和响应式（如异步）编程模型。

  • 同步服务器 - 使用 McpSyncServer 实现的默认服务器类型。它专为应用程序中简单直接的请求-响应模式而设计。要启用此服务器类型，请在配置中设置 spring.ai.mcp.server.type=SYNC。启用后，它将自动处理同步工具规范的配置。

注意： SYNC 服务器仅会注册同步的 MCP 注释方法。异步方法将被忽略。

  • 异步服务器（Asynchronous Server） - 异步服务器实现使用 McpAsyncServer，并针对非阻塞操作进行了优化。要启用此服务器类型，请将应用程序配置为 spring.ai.mcp.server.type=ASYNC。此服务器类型会自动设置带有内置 Project Reactor 支持的异步工具规范。

注意： ASYNC 服务器仅注册异步的 MCP 注解方法。同步方法将被忽略。

MCP 服务器注解​

MCP Server Boot Starters 提供全面的注解式服务器开发支持，允许您使用声明式 Java 注解来创建 MCP 服务器，而无需手动配置。

关键注释​

  • @McpTool - 将方法标记为 MCP 工具，并自动生成 JSON schema

  • @McpResource - 通过 URI 模板提供对资源的访问

  • @McpPrompt - 为 AI 交互生成提示消息

  • @McpComplete - 为提示提供自动补全功能

特殊参数​

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

  • McpMeta - 访问来自 MCP 请求的元数据

  • @McpProgressToken - 接收用于长时运行的操作的进度令牌

  • McpSyncServerExchange/McpAsyncServerExchange** - 用于高级操作的完整服务器上下文

  • McpTransportContext - 用于无状态操作的轻量级上下文

  • CallToolRequest - 支持动态模式以实现灵活的

简单示例​

@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);
    }
}

向 McpTransportContext 添加数据​

默认情况下，McpTransportContext 为空（McpTransportContext.EMPTY）。这是出于设计考虑，旨在保持 MCP 服务器与传输机制的解耦。

如果你的工具需要传输层特有的元数据（例如，HTTP 头、远程主机等），请在传输提供者上配置 TransportContextExtractor。

对于 WebMVC：

@Bean
public WebMvcStreamableServerTransportProvider transport() {
    return WebMvcStreamableServerTransportProvider.builder()
        .contextExtractor(serverRequest -> {
            String authorization = serverRequest.headers().firstHeader("Authorization");
            return McpTransportContext.create(Map.of("authorization", authorization));
        })
        .build();
}

对于 WebFlux（响应式）：

@Bean
public WebFluxStreamableServerTransportProvider transport() {
    return WebFluxStreamableServerTransportProvider.builder()
        .contextExtractor(serverRequest -> {
            String authorization = serverRequest.headers().firstHeader("Authorization");
            return McpTransportContext.create(Map.of("authorization", authorization));
        })
        .build();
}

配置完成后，在工具中通过 McpSyncRequestContext（或 McpAsyncRequestContext）访问上下文。

@McpTool
public String accessProtectedResource(McpSyncRequestContext requestContext) {
    McpTransportContext context = requestContext.transportContext();
    String authorization = (String) context.get("authorization");

    return "Successfully accessed protected resource.";
}

自动配置​

借助 Spring Boot 自动配置，标注的 Bean 会被自动检测并注册：

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

自动配置将：

  1. 扫描带有 MCP 注解的 beans
  2. 创建相应的规范
  3. 将它们注册到 MCP server
  4. 根据配置处理同步和异步实现

配置属性​

配置服务器注释扫描器：

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

更多资源​

示例应用​

附加资源​

章节摘要​