Spring AI + MCP 实战：构建企业级 Agent 生态的基石

一、引言：从单一模型到 Agent 生态的演进

在人工智能技术飞速发展的当下，我们已经从最初的"对话式 AI"迈向了"代理式 AI (Agentic AI)"的新阶段。早期的 AI 应用主要依赖于 Prompt Engineering，通过精巧的提示词引导模型输出。然而，随着企业级需求的复杂化，模型需要能够直接访问实时数据、操作外部工具并进行多步推理。这种需求催生了 LangChain、AutoGPT 等框架的兴起。

作为 Java 生态的基石，Spring 框架自然不会缺席这场变革。Spring AI 的出现，旨在为 Java 开发者提供一套统一、标准且符合 Spring 编程范式的 AI 开发接口。而 Anthropic 最近发布的 Model Context Protocol (MCP)，则为 AI 模型的上下文连接提供了一个革命性的标准协议。

本文将作为《AI 学习与实战》系列的核心篇章，深入解析 Spring AI 与 MCP 的结合。我们将探讨为什么这种组合是企业级 Agent 开发的最优解，并从底层协议原理到高层代码实现，带你从零构建一个具备工业级强度的 AI 代理系统。MCP 不仅仅是一个协议，它更像是一种"AI 时代的 USB 接口"，让不同的数据源和工具能够无缝接入大模型。

二、 MCP 协议深度解析：打破数据的孤岛

2.1 什么是 MCP？

Model Context Protocol (MCP) 是一个开放标准，旨在使开发人员能够构建安全的、双向的连接器，将 AI 模型（如 Claude, GPT-4）与本地或远程数据源、工具及服务连接起来。在 MCP 出现之前，每个开发者都需要为不同的工具编写特定的集成代码，这导致了严重的碎片化。

2.2 协议的核心组件

MCP 协议定义了三个核心角色：

MCP Host：集成 AI 模型的客户端应用（如 Claude Desktop、Spring AI 应用）。它负责发起请求并消费资源。
MCP Client：Host 内部的组件，负责与 MCP Server 建立连接。
MCP Server：对外暴露工具、资源或提示词模版的微服务。

2.3 交互机制

MCP 基于 JSON-RPC 2.0 协议，支持多种传输层（Transport），如 Stdio （标准输入输出，适用于本地进程）和 SSE（Server-Sent Events，适用于远程 Web 服务）。

Resources：类似于 READ-ONLY 数据，如日志文件、数据库记录或 API 文档。
Tools：可执行的函数，Agent 可以调用这些工具来改变外部系统的状态（如发送邮件、执行 SQL、查询实时天气）。
Prompts：预定义的模版，帮助用户快速构建高质量的上下文。

这种解耦的设计使得 AI 模型不再是一个孤岛。通过 MCP，模型可以像人类使用电脑一样，拥有了自己的"文件管理器"和"工具箱"。

三、 Spring AI 核心架构与 MCP 的融合逻辑

Spring AI 的核心设计理念是"抽象化"与"模块化"。它将大模型（Chat Models）、嵌入模型（Embedding Models）、向量存储（Vector Stores）等抽象为标准的 Java 接口。

3.1 抽象的艺术

在 Spring AI 中，ChatClient 是最高层的交互入口。它不仅支持流式输出、结构化数据映射，还支持通过 Advisor 机制动态干预对话。当引入 MCP 后，Spring AI 将 MCP Server 提供的 Tools 动态转换为 Spring AI 的 Function 调用。

3.2 动态发现机制

Spring AI 引入了对 MCP 客户端的自动配置支持。当你在 Spring 应用中配置了一个 MCP Server 的地址后，Spring AI 会在启动时通过 MCP 协议的 list_tools 接口获取所有可用工具，并将它们注册为 Spring Bean。这意味着，当你更新 MCP Server 端的工具逻辑时，Client 端无需重新编译，即可实现能力的无缝升级。

3.3 生态协同

Spring 强大的生态系统（如 Spring Data, Spring Security, Spring Cloud）为 MCP 提供了坚实的后盾。例如，你可以利用 Spring Security 为 MCP Server 的 SSE 端点提供复杂的身份验证，或者利用 Spring Cloud Gateway 对 MCP 请求进行限流和转发。这种"强强联手"让 AI 应用在具备智能的同时，也拥有了金融级的安全性与稳定性。

四、环境准备与基础设施构建

在开始实战之前，我们需要准备好开发环境。由于 Spring AI 和 MCP 协议都处于快速迭代期，建议使用最新的稳定版本。

4.1 技术栈要求

JDK: 17 或 21（推荐 21 以获得更好的协程支持）。
Spring Boot: 3.3.x 或更高版本。
Spring AI: 1.0.0-SNAPSHOT (目前需使用 Spring Milestone 仓库)。
Build Tool: Maven 3.8+ 或 Gradle 8+。
LLM API Key: 推荐 Anthropic Claude 3.5 Sonnet 或 OpenAI GPT-4o。

4.2 依赖配置 (Maven)

在 pom.xml 中，你需要添加 spring-ai-mcp-spring-boot-starter。此外，由于我们要演示 SSE 传输，还需要 WebFlux 支持。

xml 复制代码

<dependencies>
    <dependency>
        <groupId>org.springframework.ai</groupId>
        <artifactId>spring-ai-mcp-spring-boot-starter</artifactId>
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-webflux</artifactId>
    </dependency>
</dependencies>

4.3 MCP 传输层选择

对于企业内部开发，如果你打算构建一个独立的工具服务，SSE (Server-Sent Events) 是最佳选择。它允许跨网络调用，并且易于穿透防火墙。对于本地调试或桌面端应用，Stdio 传输则更为简单高效。

五、手把手教你编写 MCP Server：暴露核心能力

现在，我们将构建一个名为 Inventory-MCP-Server 的服务，该服务将模拟一个库存管理系统，向 AI 提供"查询库存"和"更新状态"的能力。

5.1 创建 MCP Server 实例

在 Spring AI 中，我们可以利用 McpServer 类来定义服务。

java 复制代码

@Bean
public McpServer mcpServer(McpServerTransport transport) {
    return McpServer.using(transport)
        .serverInfo("Inventory-Manager", "1.0.0")
        .capabilities(ServerCapabilities.builder()
            .resources(true) // 开启资源支持
            .tools(true)    // 开启工具支持
            .build())
        .build();
}

5.2 注册工具 (Tools)

工具是 MCP Server 的核心。我们需要定义工具的名称、描述以及输入参数的 JSON Schema。

java 复制代码

@Configuration
class McpToolConfig {
    @Bean
    public McpServer.ToolRegistration inventoryTool() {
        return new McpServer.ToolRegistration(
            new Tool("get_stock", "查询指定商品的实时库存数量", 
                Map.of("productId", "string")),
            (args) -> {
                String productId = (String) args.get("productId");
                // 模拟数据库查询
                return "商品 " + productId + " 当前库存为: 42 件";
            }
        );
    }
}

5.3 暴露 SSE 端点

为了让 Client 能够连接，我们需要通过 Controller 暴露 SSE 传输通道。Spring AI 提供了内置的适配器，只需几行代码即可完成对接。这种方式极大地简化了协议转换的复杂度，让开发者专注于业务逻辑。

六、客户端集成：在 Spring AI 应用中调用 MCP

有了 Server，下一步是在我们的主应用（Host）中接入这些能力。

6.1 配置 MCP Client

在 application.yml 中，我们可以定义连接到哪些 MCP Server。

yaml 复制代码

spring:
  ai:
    mcp:
      client:
        connections:
          inventory-service:
            type: sse
            url: http://localhost:8081/mcp/sse

6.2 结合 ChatClient 使用

Spring AI 的 ChatClient 可以非常方便地集成 MCP 工具。通过 McpToolCallbackProvider，所有 MCP Server 暴露的工具都会被自动识别为对话中的可用函数。

java 复制代码

@RestController
class AIController {
    private final ChatClient chatClient;

    public AIController(ChatClient.Builder builder, McpClient mcpClient) {
        this.chatClient = builder
            .defaultAdvisors(new McpToolAdvisor(mcpClient))
            .build();
    }

    @GetMapping("/ask")
    public String ask(@RequestParam String prompt) {
        return chatClient.prompt(prompt).call().content();
    }
}

6.3 自动调用的魅力

当用户询问："帮我看看 A102 商品还有多少货？"时，ChatClient 会识别出语义需求，自动通过 MCP 协议向 inventory-service 发起 get_stock 请求，获取结果后，再由 LLM 组织成自然语言回复用户。整个过程对用户和开发者几乎是透明的。

七、实战案例：构建一个供应链智能调度 Agent

为了体现 Spring AI + MCP 的真实威力，我们考虑一个更复杂的场景：一个能够根据库存情况自动生成补货建议并发送邮件通知的 Agent。

7.1 场景流程

用户指令："检查低库存商品并通知采购部。"
步骤一 ：Agent 调用 inventory-server 的 list_low_stock 工具。
步骤二：Agent 根据返回的数据（如：芯片 A 仅剩 5 片），结合预设的补货策略进行分析。
步骤三 ：Agent 调用 notification-server（另一个 MCP Server）的 send_email 工具。

7.2 跨 Server 的协同

在 Spring AI 中，你可以连接多个 MCP Client。McpToolAdvisor 可以同时聚合来自不同 Server 的工具集。这种微服务化的 Agent 架构具有极高的灵活性。如果采购系统的接口发生了变更，你只需要升级采购部的 MCP Server，而无需动 AI 主应用。

7.3 关键代码示例

在业务逻辑中，我们可以利用 Advisor 的链式调用，将上下文（Context）在多个步骤间传递。通过 VectorStore 存储的历史调度记录，Agent 甚至可以学习到不同供应商的响应速度，从而在补货建议中加入预测性分析。

八、生产环境优化、安全性与注意事项

将 MCP 应用于生产环境时，必须考虑稳定性与安全性。

8.1 性能优化：连接池与异步化

MCP 基于 JSON-RPC，频繁的网络往返会增加延迟。建议：

对 MCP Client 启用连接池。
利用 Spring 21 的虚拟线程（Project Loom）处理并发的 MCP 请求，避免阻塞主 IO 线程。
对不频繁变动的 Resource 使用本地缓存。

8.2 安全性限制

AI Agent 具有一定的"自主性"，因此必须对其权限进行严格限制。

沙箱执行：MCP Server 暴露的工具应当在受限的环境中执行。
确认机制 (Human-in-the-loop) ：对于敏感操作（如转账、删除），应在 MCP Tool 的实现逻辑中加入人工审核环节，或通过 Spring AI 的 Advisor 拦截请求并弹出确认。
传输加密：生产环境必须使用 HTTPS/WSS。

8.3 调试建议

由于涉及多端交互，调试 MCP 可能会比较困难。

使用 MCP Inspector 工具，它可以模拟 Host 与 Server 进行交互。
在 Spring Boot 中开启 DEBUG 级别的日志，观察 JSON-RPC 的原始报文，这对于排查参数类型不匹配的问题至关重要。

结语：迈向 Agent 原生应用

Spring AI 与 MCP 的结合，为 Java 开发者打开了一扇通往 Agentic AI 的大门。通过标准化协议，我们终于可以像拼积木一样构建 AI 的能力边界。

学习路线建议：

基础阶段：熟练掌握 Spring Boot 3.x 和 WebFlux 基础，理解响应式编程。
进阶阶段 ：学习 Spring AI 的 ChatClient 架构，动手实现一个简单的 Function Calling。
MCP 实战：参考本文，先跑通 Stdio 模式的 MCP Demo，再尝试 SSE 模式。
工程化阶段：研究如何将 MCP 接入现有的企业内部系统（如 ERP、CRM），并加入权限控制。

实践建议：不要试图一次性构建一个"万能 Agent"。从一个小而精的场景（如：自动化日志分析、企业内部文档问答）开始，利用 MCP 将其工具化，你会发现 AI 的落地比想象中更直接。

本文为 AI 学习与实战系列文章，旨在分享前沿 AI 技术在工程领域的应用。

Spring AI + MCP 实战：构建企业级 Agent 生态的基石