mcp-server

MCP 服务 - Spring Boot 3

在 Spring Boot 应用中，优先使用 Spring AI MCP 服务启动器。让 Spring AI BOM 管理其 MCP SDK 依赖；不要在基于启动器的应用中强制指定独立 SDK 版本。

依赖

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

对于不使用 Spring AI 的原始 SDK 应用，请使用当前 MCP Java SDK 2.x 版本，并遵循其迁移指南。不要假设原始 SDK 示例与 Spring AI 1.x 管理的版本相匹配。

<dependency>
    <groupId>io.modelcontextprotocol.sdk</groupId>
    <artifactId>mcp</artifactId>
    <version>2.0.0</version>
</dependency>

Spring AI 1.x 工具回调集成

Spring AI 1.0.x 仅通过显式的 MethodToolCallbackProvider 暴露 @Tool 方法——仅有带 @Tool 方法的 @Component 不会注册任何内容。Spring AI 1.1.x 还支持原生的 @McpTool/@McpToolParam，需启用 spring.ai.mcp.server.annotation-scanner.enabled=true；这些注解来自 org.springaicommunity.mcp.annotation（Spring AI 2.0 将它们移至 org.springframework.ai.mcp.annotation）。每个工具只选择一种注册方式。

@Configuration
class McpToolsConfiguration {
    @Bean
    ToolCallbackProvider orderTools(OrderMcpTools tools) {
        return MethodToolCallbackProvider.builder()
            .toolObjects(tools)
            .build();
    }
}

@Component
final class OrderMcpTools {
    private final OrderService orderService;

    OrderMcpTools(OrderService orderService) {
        this.orderService = orderService;
    }

    @Tool(description = "Get an order by UUID with line items and status history")
    OrderResponse getOrder(
            @ToolParam(description = "Order UUID") String orderId) {
        return OrderResponse.from(orderService.findById(UUID.fromString(orderId)));
    }
}

• 返回 DTO，而不是序列化后的 JPA 实体。
• 每个工具对象只注册一次；重复的提供者会创建重复的能力。
• 保持工具名称和描述稳定，因为客户端和模型会依赖它们。
• 限制结果大小、执行时间和下游调用次数。
• 对于原始 SDK 代码，请使用 CallToolResult.builder() 等构建器；旧构造函数已移除。

传输配置

spring:
  main:
    banner-mode: "off"
  ai:
    mcp:
      server:
        name: order-service-mcp
        version: 1.0.0
        type: SYNC
        stdio: true

本地客户端启动 jar 时使用 stdio。当所选 Spring AI 1.x 版本支持时，远程服务应使用匹配的 MVC 或 WebFlux 启动器以及 Streamable HTTP。stdio 模式下请保持 stdout 干净，因为它承载 JSON-RPC 帧。

安全与验证

• 对远程 MCP 端点及每项底层域操作进行身份验证和授权。
• 验证标识符、枚举值、分页参数和结果限制。
• 不要暴露机密信息、堆栈跟踪、持久化实体或不受限制的管理工具。
• 使用真实 MCP 客户端测试发现、无效参数、授权、超时和关闭行为。
• 复制 2.0 注解示例前，请先查看所选 Spring AI 1.x 版本的发行说明。

示例

• 请参阅 examples/OrderMcpTools.java、examples/good-order-tools.java 和 examples/bad-order-tools.java。

官方资料

• Spring AI MCP 概览：https://docs.spring.io/spring-ai/reference/api/mcp/mcp-overview.html
• MCP Java SDK 发行版：https://github.com/modelcontextprotocol/java-sdk/releases
• MCP Java SDK 2.0 迁移指南：https://github.com/modelcontextprotocol/java-sdk/blob/main/MIGRATION-2.0.md

常见问题

• Agent 在 Spring AI 1.x 中覆盖 MCP SDK——应让 Spring AI BOM 管理它。
• Agent 将 Spring AI 2.0 的 org.springframework.ai.mcp.annotation 导入语句复制到 1.1 项目中——1.1 使用 org.springaicommunity.mcp.annotation，而 1.0 完全没有 MCP 注解。
• Agent 认为普通 @Component 上的 @Tool 方法会在 1.x 中显示为 MCP 工具——应通过 ToolCallbackProvider bean 注册它们。
• Agent 传入 --spring.ai.mcp.server.transport=stdio——不存在此属性；Boot 会静默忽略它。请使用 spring.ai.mcp.server.stdio=true。
• Agent 在原始 SDK 代码中使用已移除的 new CallToolResult(...) 构造函数——请使用构建器。
• Agent 在 stdio 模式下向 stdout 写日志——请将日志输出到 stderr 或文件，并禁用横幅。
• Agent 将同一个工具对象注册两次——每项能力只保留一个回调提供者。
• Agent 暴露实体或无界集合——请返回有界 DTO 契约。