Spring AI + MCP 实战：构建标准化 AI 智能代理与上下文集成

Spring AI + MCP 实战：构建标准化 AI 智能代理与上下文集成

1. 序言：AI 应用开发的范式转移与 Java 生态的崛起

在人工智能技术浪潮中，大语言模型（LLM）的演进已经从单纯的"聊天对话"进化到了"智能代理（Agent）"阶段。早期的 AI 应用开发往往陷入一种"胶水代码"的泥潭：开发者需要为每一个外部工具、每一份私有文档编写繁琐的适配器代码。随着 Anthropic 发布了 Model Context Protocol（MCP，模型上下文协议），这一局面正在发生根本性的变化。对于广大 Java 开发者而言，Spring AI 框架敏锐地捕捉到了这一趋势，通过深度集成 MCP，为构建标准化、可扩展的 AI 应用提供了坚实的底座。

传统的集成模式下，我们将 LLM 连接到数据源（如数据库、本地文件、Slack 等）时，每个集成都是点对点的、私有的且不可复用的。这种方式在面对复杂企业级需求时，会导致代码库迅速膨胀，维护成本极高。而 MCP 的出现，旨在定义一套标准化的通信协议，让不同的 AI 模型能够通过统一的接口访问多样化的上下文数据和工具。本篇文章作为"AI 学习与实战系列"的重磅篇章，将带你深入探究 Spring AI 与 MCP 的结合，揭秘如何构建真正具备"感知力"和"执行力"的 AI 智能代理。

在接下来的内容中，我们将不仅停留在理论层面。我们将从 MCP 的核心哲学出发，剖析其在 Spring 生态系统中的实现机理，并手把手教你如何搭建一个完整的 MCP 架构体系。无论你是希望将公司的私有知识库喂给 AI，还是希望通过 AI 自动化操作复杂的后台系统，这篇文章都将为你提供从零到一的实战指南。Java 开发者不再是 AI 时代的旁观者，通过 Spring AI + MCP，我们将成为构建智能化企业应用的主力军。

2. 核心机理：什么是 Model Context Protocol (MCP)？

要理解 Spring AI 的实战，首先必须拆解 MCP 协议的内核。Model Context Protocol 是由 Anthropic 提出的一项开放协议，它在本质上解决了 AI 模型与外部世界通信的"语言障碍"。我们可以将 MCP 类比为 AI 领域的 USB 协议------无论你是哪种打印机（数据源/工具），只要符合 USB 标准（MCP），任何电脑（LLM/客户端）都能即插即用。

MCP 协议的核心架构由三个角色组成：Host（宿主应用） 、Client（客户端） 和 Server（服务端）。

1. Host：这是最终用户与之交互的应用，例如一个基于 Spring Boot 开发的智能客服后台或 IDE。
2. Client：位于 Host 内部，负责与 MCP Server 建立连接、发送请求并处理响应。在我们的实战中，Spring AI 充当了 Client 的角色。
3. Server：这是数据的提供者或工具的执行者。它通过 MCP 协议向外暴露三种核心能力：Resources（资源）、Tools（工具）和 Prompts（提示词模板）。

Resources（资源） 允许 Server 向模型提供只读的数据流，比如本地文件内容、数据库表结构或实时日志。模型可以将这些内容作为上下文背景信息。 Tools（工具） 则是动态的、可执行的函数。例如，一个 Server 可以暴露一个"发送邮件"或"查询订单状态"的工具，LLM 根据用户意图决定何时调用这些工具。 Prompts（提示词模板） 则是预定义的交互模式，帮助用户更高效地与模型协作。

MCP 采用了基于 JSON-RPC 的通信机制。这意味着它不依赖于特定的底层传输协议，既可以通过标准输入输出（stdio）进行本地进程间通信，也可以通过 HTTP/SSE（Server-Sent Events）进行远程通信。这种灵活性使得我们可以用 Python 或 Node.js 快速编写一个处理复杂业务逻辑的 MCP Server，然后在 Java 编写的 Spring Boot 应用中无缝调用它。这种跨语言的协作能力，极大地丰富了 AI 应用的生态边界。

3. Spring AI 架构中的 MCP 集成策略

Spring AI 作为 Spring 家族的新成员，其设计哲学始终保持着高度的抽象化与一致性。在集成 MCP 时，Spring AI 并没有简单地增加几个 API 接口，而是将其深度融入到了原有的 ChatModel 和 Advisor 体系中。理解这一架构设计，对于编写高性能、高可用的 AI 程序至关重要。

在 Spring AI 中，MCP 的实现主要围绕 McpClient 类展开。它充当了连接 Spring 应用与外部 MCP Server 的桥梁。Spring AI 提供了同步（Sync）和异步（Async）两种客户端实现，以适配不同的应用场景。对于大多数基于传统 Spring MVC 的 Web 应用，同步客户端提供了更直观的编程模型；而对于基于 WebFlux 的响应式应用，异步客户端则能提供更高的并发性能。

Spring AI 对 MCP 的集成策略可以归纳为"自动探测与动态注入"。当你在配置类中定义了一个 McpClient 豆（Bean）并将其与 ChatModel 关联时，Spring AI 会在模型生成响应前，自动向 MCP Server 发起同步请求。例如，如果 LLM 认为需要调用某个工具来回答用户问题，Spring AI 会拦截这个意图，将其转发给对应的 MCP Server 执行，并将执行结果作为上下文重新喂给 LLM。

这种架构的精妙之处在于它完全解耦了"智能决策"与"具体执行"。ChatModel 负责决策（即：我需要查一下 2024 年的销售额），而 McpClient 负责执行（即：去 sales-database-server 获取数据）。开发者只需要关注业务逻辑的定义，而无需手动处理复杂的协议细节、并发控制或异常回退机制。此外，Spring AI 还支持同时连接多个 MCP Server，这意味着你可以同时拥有一个负责文件读取的 Server、一个负责 Google 搜索的 Server 和一个负责执行 Python 脚本的 Server，所有的能力在 Spring AI 的调度下融为一体。

4. 实战第一步：构建与运行 MCP Server

在开始 Spring Boot 开发之前，我们需要一个能够提供能力的 MCP Server。虽然 MCP Server 可以用任何语言编写，但社区目前最成熟的是基于 TypeScript 和 Python 的 SDK。为了演示跨语言集成的魅力，我们将以 Python 为例，构建一个简单的"系统信息监控"Server。

这个 Server 将暴露一个名为 get_system_metrics 的工具，它能够获取当前服务器的 CPU 使用率、内存占用和磁盘空间。这在构建一个"自动化运维 AI 助手"时非常有用。首先，我们需要安装 mcp 库。在 Python 环境中，通过 pip install mcp 即可完成准备。

代码逻辑如下：我们创建一个 FastMCP 实例，并使用装饰器 @mcp.tool() 定义我们的工具函数。

from mcp.server.fastmcp import FastMCP
import psutil

mcp = FastMCP("SystemMonitor")

@mcp.tool()
def get_system_metrics() -> str:
    """获取当前系统的 CPU 和内存使用率状况"""
    cpu = psutil.cpu_percent(interval=1)
    memory = psutil.virtual_memory().percent
    return f"当前 CPU 使用率: {cpu}%, 内存使用率: {memory}%"

if __name__ == "__main__":
    mcp.run()

在这个简单的示例中，工具的文档字符串（Docstring）至关重要。MCP 协议会将这段描述传递给 LLM，LLM 正是基于这段描述来判断什么时候该调用这个函数。

运行该 Server 时，默认会使用 stdio 模式。在后续的 Spring AI 配置中，我们需要指定运行此 Python 脚本的命令（例如 python server.py）。这个 Server 就像一个随时待命的插件，等待着 Spring AI 发起连接。在生产环境中，你可以将其部署为独立的服务，通过 SSE 协议进行通信，从而实现更灵活的分布式架构。理解了 Server 端的构建，我们就掌握了 AI 能力供给的源头。

5. Spring AI 客户端配置详解

有了 Server 端提供的能力，接下来我们需要在 Spring Boot 应用中"接通"这些能力。这涉及到依赖引入、客户端初始化以及与 ChatModel 的绑定。

首先，在 pom.xml 中引入必要的依赖。除了 spring-ai-openai-spring-boot-starter（或你选用的其他模型 starter），关键在于引入 spring-ai-mcp 依赖：

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

接着，我们需要配置 McpClient。由于我们要连接的是一个基于 stdio 的 Python Server，我们需要配置 McpTransport。Spring AI 提供了 ProcessListMcpTransport 来启动并与外部进程通信：

@Bean
public McpClient mcpClient() {
    // 定义启动 Server 的命令
    var transport = new ProcessListMcpTransport("python", "path/to/your/server.py");
    
    // 创建同步客户端
    var mcpClient = new McpSyncClient(transport);
    mcpClient.initialize(); // 初始化连接
    return mcpClient;
}

配置好客户端后，最关键的一步是让 ChatModel 意识到这些工具的存在。在 Spring AI 中，这是通过 ToolCallbackProvider 实现的。Spring AI 提供了一个 McpToolCallbackProvider 类，它能自动将 MCP Server 暴露的所有工具转换为 Spring AI 内部的工具格式。

@Bean
public ToolCallbackProvider mcpToolCallbacks(McpSyncClient mcpClient) {
    return new McpToolCallbackProvider(mcpClient);
}

最后，在调用 AI 接口时，将这些回调注入到 ChatOptions 中：

public String askAI(String message) {
    var toolCallbacks = mcpToolCallbacks(mcpClient()).getToolCallbacks();
    var prompt = new Prompt(message, OpenAiChatOptions.builder()
            .withFunctionCallbacks(List.of(toolCallbacks))
            .build());
    return chatModel.call(prompt).getResult().getOutput().getContent();
}

通过这套配置，原本只能"纸上谈兵"的 LLM，现在拥有了查看你系统状态的真实权限。当你询问"我现在服务器压力大吗？"时，LLM 会自动调用 Python 脚本，获取数据，分析后再给出回答。

6. 深入探索：Resource 与 Prompt 的高级应用

虽然工具调用（Tool Calling）是 MCP 最引人注目的特性，但 Resources 和 Prompts 的应用同样能为 AI 应用带来质的飞跃。在企业级场景中，我们经常需要将海量的业务文档或数据库 Schema 提供给模型作为参考，而不需要模型去执行动作。这就是 Resources 的用武之地。

Resources 的实践 ：假设你有一个 MCP Server 负责管理公司的产品手册。Server 可以定义一个 Resource URI 模式，例如 docs://products/{id}。当 Spring AI Client 请求该资源时，Server 返回手册的文本内容。在 Spring AI 侧，你可以预先拉取这些资源，或者利用 Advisor 机制在对话开始前自动注入相关资源内容。与 Tool 不同，Resource 是被动的知识注入，它减少了模型误操作的风险，同时保证了上下文的准确性。

Prompts 的标准重用 ：在大型团队中，Prompt Engineering（提示词工程）往往是分散的。MCP 的 Prompts 特性允许我们在 Server 端集中维护高质量的提示词模板。例如，一个负责"代码审查"的 Server 可以提供一个 code-review 提示词。Spring AI Client 可以通过 mcpClient.listPrompts() 获取这些模板。这样做的好处是显而易见的：当提示词需要优化时，你只需要修改 Server 端的一行代码，所有连接到该 Server 的应用都会立即生效。

在实战中，建议采用"资源先行，工具后随"的策略。对于基础信息的获取，优先使用 Resources 来丰富 Context；对于需要产生副作用（改变系统状态）的操作，使用 Tools。通过 Spring AI 对 MCP 协议的完整支持，开发者可以构建出层次分明、逻辑清晰的 AI 上下文管理系统。例如，你可以构建一个"智能财报分析师"，其中 Resource 提供历年财报数据，Prompt 定义分析的维度和风格，而 Tool 则负责导出分析报告到 PDF 文件。这种组合拳式的开发模式，正是未来 AI Native 应用的标准形态。

7. 案例实战：构建 AI 驱动的数据库专家系统

为了让读者更有体感，我们将综合上述知识，构建一个"AI 数据库专家"。该系统能够根据用户的自然语言指令，查询数据库 Schema，分析数据趋势，甚至执行复杂的 SQL 优化建议。

在这个场景中，我们需要一个 MCP Server 来连接我们的 H2 或 MySQL 数据库。该 Server 暴露两个工具：get_table_schema 和 execute_query，以及一个资源 db://metadata。 Server 端实现逻辑（伪代码）：

• get_table_schema(table_name): 返回指定表的列名、类型和索引。
• execute_query(sql): 在只读模式下执行查询并返回 JSON 结果。

Spring AI 侧的逻辑 ： 我们需要创建一个 Advisor，在对话开始时，将 db://metadata 注入。这样，用户询问"系统中关于订单的信息存在哪？"时，LLM 已经提前知道了有哪些表。

@Service
public class DbExpertService {
    private final ChatClient chatClient;

    public DbExpertService(ChatClient.Builder builder, McpSyncClient mcpClient) {
        var mcpProvider = new McpToolCallbackProvider(mcpClient);
        this.chatClient = builder
                .defaultAdvisors(new MessageChatMemoryAdvisor(new InMemoryChatMemory()))
                .defaultFunctions(mcpProvider.getToolCallbacks().toArray(new ToolCallback[0]))
                .build();
    }

    public String solve(String userPrompt) {
        return chatClient.prompt()
                .user(userPrompt)
                .call()
                .content();
    }
}

实际交互演示： 用户： "帮我查一下上周订单总额最高的前三名客户。" AI 内部逻辑：

1. 模型识别出需要查询数据，但不知道表名。
2. 模型调用 get_table_schema 检查 orders 表。
3. 模型根据 Schema 构造出 SELECT customer_id, SUM(amount) FROM orders ...。
4. 模型调用 execute_query 执行 SQL。
5. 模型接收到 JSON 结果，转换为人类可读的文字返回给用户。

这个案例展示了 MCP 如何将复杂的后端能力转化为 LLM 的直观技能。开发者不再需要编写成百上千的逻辑判断，而是通过提供"工具"和"上下文"，让 AI 自主寻找解决路径。这种开发范式的转变，极大地提升了生产力。

8. 注意事项、安全性与性能优化

在享受 Spring AI + MCP 带来的便利时，我们也必须面对生产环境中的严峻挑战。AI 应用的鲁棒性往往取决于你对这些细节的掌控。

安全性（Security）：这是最重要的一环。MCP Server 赋予了 AI 调用代码的能力，如果处理不当，可能会导致 SQL 注入或敏感数据泄露。

• 最小权限原则：MCP Server 运行的账号应只有必要的权限。例如，数据库连接应为只读。
• 输入校验：即使是 LLM 生成的参数，在 Server 端执行前也必须经过严格的 Schema 验证。
• 审核日志：记录每一次 Tool 调用，包括模型输入的参数和返回的结果，以便在出现异常行为时进行审计。

性能优化（Performance）：

• 连接管理 ：对于 stdio 模式，频繁启动子进程开销巨大。Spring AI 的 McpClient 应该作为单例常驻内存。
• 上下文压缩：MCP 资源可能非常庞大。如果将整个数据库 Schema 塞入上下文，会消耗大量 Token 且增加延迟。建议在 Server 端先进行初步过滤，只返回与当前任务最相关的片段。
• 超时与重试 ：网络波动可能导致 MCP 调用失败。在配置 McpClient 时，务必设置合理的超时时间，并利用 Spring 的 @Retryable 机制处理暂态故障。

可观测性（Observability） ： 利用 Spring Boot Actuator 集成 AI 应用的监控。通过追踪（Tracing），你可以清晰地看到一个用户请求是如何流转到 ChatModel，再如何触发 McpClient 请求，最后返回结果的。在分布式 MCP 架构中，使用 OpenTelemetry 记录跨服务的调用链路是必不可少的。

9. 总结：学习路线与实践建议

Spring AI 与 MCP 的结合，为 Java 开发者打开了通往 Agentic AI 世界的大门。通过标准化的协议，我们能够以极低的成本将现有的企业服务资产转化为 AI 的超能力。

针对新手的学习路线建议：

1. 基础阶段 ：先熟悉 Spring Boot 3.x 和基本的 Spring AI 概念（如 ChatModel、Prompt）。
2. 协议理解：阅读 Anthropic 的 MCP 官方文档，理解 JSON-RPC 通信和 Server-Client 角色。
3. 动手实践：尝试用 Python FastMCP 编写一个本地工具 Server，并在 Spring Boot 应用中完成首次调用。
4. 进阶应用 ：学习如何在 Spring AI 中使用 Advisors 处理长对话，并探索 SSE 模式的远程 MCP Server 部署。
5. 工程化：研究 AI 安全防护（如 Prompt Injection 防御）和性能监控。

实践建议： 不要试图一步到位构建复杂的 Agent。从最简单的"只读资源"开始，先让 AI 能够看到你的数据，然后再逐步赋予它"执行工具"的能力。在企业内部，可以尝试建立一个统一的 MCP Server 仓库，将通用的业务能力标准化，让不同的 AI 小组能够按需调用，避免重复造轮子。

AI 的发展日新月异，但 Spring AI 的体系化封装和 MCP 的标准化趋势，为我们提供了在变局中寻找确定性的路径。希望这篇文章能成为你 AI 学习之旅的有力助推器。让我们一起在 Java 生态中，书写 AI 应用的新篇章！