BytesRouter

主题

Spring AI 文档版本 2.1.0-SNAPSHOT 源快照 0c884489 更新于 2026-10-16

MCP 服务端 Boot Starter

模型上下文协议（MCP）服务端 是通过标准化协议接口向 AI 应用暴露特定能力的程序。每个服务端都为某个特定领域提供聚焦的功能。

Spring AI MCP 服务端 Boot Starter 为在 Spring Boot 应用中设置 MCP 服务端 提供自动配置。 它们使 MCP 服务端能力与 Spring Boot 自动配置系统无缝集成。

MCP 服务端 Boot Starter 提供：

  • MCP 服务端组件的自动配置，包括工具、资源和提示词
  • 对不同 MCP 协议版本的支持，包括 STDIO、SSE、Streamable-HTTP 和无状态服务端
  • 对同步与异步两种运行模式的支持
  • 多种传输层选项
  • 灵活的工具、资源和提示词规格
  • 变更通知能力
  • 基于注解的服务端开发，带自动 bean 扫描与注册

DANGER

基于 HTTP 的服务端传输（SSE、Streamable-HTTP 和无状态）默认暴露一个未经认证的 JSON-RPC 端点。 这些 starter 自身不施加任何认证或授权，因此任何能触达该端点的客户端都能列出并调用每个已注册的工具、资源和提示词。 在把一个 MCP 服务端暴露到 localhost 之外之前，你必须在它前面设一道安全边界。 细节参见 securing-the-mcp-server。 这对 STDIO 传输不适用，它在进程内运行、不可通过网络访问。

MCP 服务端 Boot Starter

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

STDIO

服务端类型
依赖
属性
标准输入/输出（STDIO）
spring-ai-starter-mcp-server
spring.ai.mcp.server.stdio=true

WebMVC

Server Type
依赖
配置项
SSE WebMVC （自 2.0.0 起弃用，请改用 STREAMABLE）
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

WebFlux（响应式）

Server Type
依赖
配置项
SSE WebFlux （自 2.0.0 起弃用，请改用 STREAMABLE）
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

服务端能力

依据服务端与传输类型的不同，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

WARNING

在默认配置下，MCP 端点（默认 POST /mcp）接受所有请求，允许任何可网络访问的客户端无需凭据就枚举并调用你已注册的工具、资源和提示词。

把注册一个工具、资源或提示词视为一次暴露它的决定，并在部署到 localhost 之外之前保护该端点。

同步/异步服务端 API 选项

MCP 服务端 API 支持命令式（即同步）与响应式（如异步）两种编程模型。

  • 同步服务端 - 使用 McpSyncServer 实现的默认服务端类型。 它专为应用中直截了当的请求-响应模式设计。 要启用此服务端类型，在你的配置中设置 spring.ai.mcp.server.type=SYNC。 启用后，它会自动处理同步工具规格的配置。

注意： SYNC 服务端只会注册同步的 MCP 注解方法。异步方法将被忽略。

  • 异步服务端 - 异步服务端实现使用 McpAsyncServer，为非阻塞操作而优化。 要启用此服务端类型，用 spring.ai.mcp.server.type=ASYNC 配置你的应用。 此服务端类型会自动设置带内建 Project Reactor 支持的异步工具规格。

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

MCP 服务端注解

MCP 服务端 Boot Starter 为基于注解的服务端开发提供全面支持，让你能用声明式的 Java 注解创建 MCP 服务端，而非手动配置。

关键注解

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

特殊参数

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

  • McpMeta - 访问来自 MCP 请求的元数据
  • @McpProgressToken - 为长时间运行操作接收进度令牌
  • McpSyncServerExchange/McpAsyncServerExchange - 供高级操作使用的完整服务端上下文
  • McpTransportContext - 供无状态操作使用的轻量上下文
  • CallToolRequest - 供灵活工具使用的动态模式支持

简单示例

java
@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：

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

对于 WebFlux（响应式）：

java
@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）访问该上下文。

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

    return "Successfully accessed protected resource.";
}

自动配置

借助 Spring Boot 自动配置，带注解的 bean 会被自动检测并注册：

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

自动配置将会：

  1. 扫描带 MCP 注解的 bean
  2. 创建合适的规格
  3. 把它们注册到 MCP 服务端
  4. 依据配置处理同步与异步两种实现

配置属性

配置服务端注解扫描器：

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

更多资源

示例应用

其他资源

友情链接

  • Agents.md面向 AI 编码助手的仓库说明文件规范
  • LangChainLangChain 是一个开放的Agent平台
  • LangSmithAgent 工程平台：可观测与评估、部署、Fleet、Engine 等
  • EmbabelEmbabel 是一个JVM平台Agent框架
  • SpringAISpringAI 是一个基于 Spring 的 AI 框架
  • MCPModel Context Protocol，连接 AI 应用与外部数据/工具的开放标准
  • LangChain4jJava 生态的 LLM 应用开发框架
  • LlamaIndex把数据接入 LLM 的框架与文档平台
  • LlamaParse智能体式 OCR 文档解析：把 PDF、扫描件变成 LLM 可用的文本与结构化数据
  • LiteParse本地优先、轻量的文档解析库，不需要 API key
  • CrewAI多智能体编排框架：以 Crew/Flow 组织自主协作的 AI Agent
  • MAFMicrosoft Agent Framework，企业级 .NET/Python 智能体框架

BytesRouter 是社区翻译站点，所有译文仅供参考，一切以官方英文原文为准。

© 2026 BytesRouter · 译文采用 CC BY 4.0 许可