Spring AI 学习篇（十二）| MCP协议：AI世界的USB接口

一、本章核心学习目标

学完本章，你将能够：

  1. 深刻理解MCP协议的本质与解决的核心痛点
  2. 掌握MCP协议的核心架构与通信原理
  3. 熟练使用Spring AI 1.0原生MCP支持
  4. 快速集成常用官方MCP服务器（文件系统、命令执行、数据库）
  5. 独立开发自定义MCP服务器
  6. 理解MCP与传统工具调用的区别与优势
  7. 基于MCP构建标准化、可复用的AI工具生态

二、前置知识准备

  • 已经完成第11篇的学习，熟练掌握Spring AI @Tool 工具调用
  • 了解传统工具调用的局限性
  • 熟悉Spring Boot配置与依赖注入
  • 了解HTTP与JSON-RPC通信基础

三、为什么我们需要MCP协议？

上一章我们学习了Spring AI @Tool 注解，它让我们可以很方便地开发自定义工具。但这种方式存在4个致命的缺陷，严重限制了AI工具生态的发展：

1. 紧耦合，无法复用

工具与应用代码紧耦合，你在A应用中开发的工具，无法直接在B应用中使用，更无法被Python、Go等其他语言开发的应用使用。

2. 没有标准化

每个框架都有自己的工具调用格式：OpenAI是一种格式，Anthropic是另一种格式，Spring AI又是一种格式。同一个工具需要为不同的框架编写不同的适配代码。

3. 生态碎片化

由于没有标准，AI工具生态极度碎片化，没有一个统一的工具市场。你需要自己开发几乎所有需要的工具，重复造轮子。

4. 安全与权限问题

传统工具调用没有统一的安全模型和权限控制机制，容易出现安全漏洞。

MCP协议就是为了解决这些问题而生的。它由Anthropic在2026年1月正式发布，现在已经成为AI工具调用的事实标准，得到了OpenAI、Google、Spring AI、Ollama等主流厂商的支持。

MCP的本质：AI世界的USB接口

通俗地说，MCP（Model Context Protocol）就是AI世界的USB接口。

  • 以前：每个工具都有自己的接口，你需要为每个工具编写专门的驱动
  • 现在：所有工具都遵循MCP标准，就像所有USB设备都遵循USB标准一样
  • 任何支持MCP的大模型，都可以直接使用任何支持MCP的工具，不需要任何适配代码

预告式提及：MCP是AI Agent的基础设施，下一章我们将学习如何基于MCP构建功能强大的AI Agent，它可以调用任何MCP工具来完成复杂任务。

四、MCP协议核心架构与原理

1. MCP核心架构

MCP采用经典的客户端-服务器架构：

┌─────────────────┐          ┌─────────────────┐
│   MCP客户端     │◄────────►│   MCP服务器     │
│ (大模型/应用)   │          │ (提供工具)      │
└─────────────────┘          └─────────────────┘
  • MCP客户端：大模型或AI应用，负责调用工具
  • MCP服务器：提供具体的工具实现，负责执行工具并返回结果
  • 通信协议：基于JSON-RPC 2.0，支持stdio和HTTP两种传输方式

2. MCP的三大核心能力

MCP协议定义了三大核心能力，所有MCP服务器都必须实现：

能力 说明
工具调用 服务器提供一组工具，客户端可以调用这些工具
资源访问 服务器提供一组资源，客户端可以读取这些资源（如文件、数据库表）
提示词模板 服务器提供一组提示词模板，客户端可以使用这些模板

3. MCP与传统工具调用的对比

对比维度 传统@Tool工具调用 MCP协议
耦合度 与应用代码紧耦合 完全解耦，独立部署
跨语言 只能在同一语言中使用 跨语言，服务器可以用任何语言开发
跨模型 只能在特定框架中使用 跨模型，支持所有主流大模型
复用性 无法复用 一次开发，到处使用
生态 碎片化 统一生态，大量现成工具可用
安全 没有统一安全模型 内置统一的安全与权限控制

五、Spring AI 1.0原生MCP支持

Spring AI 通过 ToolCallbackProvider 集成 MCP 工具（以下示例展示核心概念，具体 API 以实际版本和官方文档为准）：

1. 添加Maven依赖

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

2. 配置MCP服务器

Spring AI支持两种方式配置MCP服务器：配置文件方式和代码方式。

(1) 配置文件方式（推荐）

在application.yml中添加MCP服务器配置：

spring:
  ai:
    mcp:
      client:
        type: SYNC
        stdio:
          connections:
            # 文件系统MCP服务器
            file-system:
              command: npx
              args: ["-y", "@modelcontextprotocol/server-filesystem", "/data/documents"]
            # 命令执行MCP服务器
            command-exec:
              command: npx
              args: ["-y", "@modelcontextprotocol/server-command-execution"]
            # 数据库MCP服务器
            database:
              command: npx
              args: ["-y", "@modelcontextprotocol/server-sqlite", "/data/db.sqlite"]

说明：官方MCP服务器都是用Node.js开发的，所以需要先安装Node.js和npm。

(2) 代码方式

import org.springframework.ai.mcp.client.McpClient;
import org.springframework.ai.mcp.client.StdioMcpClient;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class McpConfig {

    @Bean
    public McpClient fileSystemMcpClient() {
        return StdioMcpClient.builder()
                .command("npx")
                .args("@modelcontextprotocol/server-filesystem", "/data/documents")
                .build();
    }
}

3. 注册MCP工具到ChatClient

配置好MCP客户端后，只需要将它们注册到ChatClient，大模型就可以自动调用所有MCP工具了：

import org.springframework.ai.chat.client.ChatClient;
import org.springframework.ai.mcp.client.McpClient;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

import java.util.List;

@Configuration
public class ChatClientConfig {

    @Bean
    public ChatClient chatClient(ChatClient.Builder builder, List<McpClient> mcpClients) {
        return builder
                // 注册所有MCP客户端
                .tools(mcpClients)
                .build();
    }
}

关键观察：不需要修改任何业务代码，不需要添加任何@Tool注解，只需要配置MCP服务器，大模型就可以自动调用所有工具。这就是MCP的强大之处。

4. 测试MCP工具调用

启动项目，访问以下地址测试文件系统MCP工具：

http://localhost:8080/agent/chat?message=列出/data/documents目录下的所有文件

大模型会自动调用文件系统MCP服务器的list_files工具，列出指定目录下的所有文件。

六、常用官方MCP服务器详解

MCP官方提供了多个常用的MCP服务器，可以直接使用，不需要自己开发。

1. 文件系统MCP服务器

允许大模型访问和操作本地文件系统。

spring:
  ai:
    mcp:
      client:
        type: SYNC
        stdio:
          connections:
            file-system:
              command: npx
              args: ["-y", "@modelcontextprotocol/server-filesystem", "/data/documents"]

支持的工具：

  • list_files：列出目录下的文件
  • read_file：读取文件内容
  • write_file：写入文件内容
  • delete_file：删除文件
  • create_directory：创建目录

2. 命令执行MCP服务器

允许大模型执行系统命令。

spring:
  ai:
    mcp:
      client:
        type: SYNC
        stdio:
          connections:
            command-exec:
              command: npx
              args: ["-y", "@modelcontextprotocol/server-command-execution"]

支持的工具：

  • run_command：执行系统命令

安全警告：命令执行MCP服务器非常强大，也非常危险。只在开发环境中使用，永远不要在生产环境中使用，除非你有非常严格的安全控制。

3. SQLite数据库MCP服务器

允许大模型查询SQLite数据库。

spring:
  ai:
    mcp:
      client:
        type: SYNC
        stdio:
          connections:
            sqlite:
              command: npx
              args: ["-y", "@modelcontextprotocol/server-sqlite", "/data/mydb.sqlite"]

支持的工具：

  • query：执行SQL查询
  • list_tables：列出所有表
  • describe_table：查看表结构

4. 浏览器MCP服务器

允许大模型控制浏览器，访问网页和搜索信息。

spring:
  ai:
    mcp:
      client:
        type: SYNC
        stdio:
          connections:
            browser:
              command: npx
              args: ["-y", "@modelcontextprotocol/server-browser"]

支持的工具：

  • navigate：导航到指定URL
  • click：点击页面元素
  • type：在输入框中输入文本
  • screenshot：截取页面截图
  • search：使用Google搜索信息

七、开发自定义MCP服务器

除了使用官方提供的MCP服务器，你还可以很方便地开发自己的自定义MCP服务器。

1. 使用Java开发MCP服务器

Spring AI提供了@McpServer注解，让你可以用Java快速开发MCP服务器。

(1) 添加依赖

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

(2) 开发MCP服务器

import org.springframework.ai.mcp.server.annotation.McpServer;
import org.springframework.ai.mcp.server.annotation.McpTool;
import org.springframework.ai.tool.annotation.ToolParam;
import org.springframework.stereotype.Component;

@Component
@McpServer(name = "weather-mcp-server", description = "提供天气查询服务的MCP服务器")
public class WeatherMcpServer {

    private final WeatherService weatherService;

    public WeatherMcpServer(WeatherService weatherService) {
        this.weatherService = weatherService;
    }

    @McpTool(description = "获取指定城市的实时天气")
    public String getCurrentWeather(
            @ToolParam("城市名称，例如：北京、上海") String city) {
        return weatherService.getCurrentWeather(city);
    }

    @McpTool(description = "获取指定城市未来7天的天气预报")
    public String getWeatherForecast(
            @ToolParam("城市名称，例如：北京、上海") String city) {
        return weatherService.getWeatherForecast(city);
    }
}

(3) 启动MCP服务器

Spring Boot会自动启动MCP服务器，并在标准输入输出上监听请求。

2. 集成自定义MCP服务器到Spring AI应用

开发好自定义MCP服务器后，你可以在其他Spring AI应用中集成它：

spring:
  ai:
    mcp:
      client:
        type: SYNC
        stdio:
          connections:
            weather:
              command: java
              args: ["-jar", "weather-mcp-server.jar"]

现在，任何支持MCP的大模型都可以调用你的天气查询工具了。

八、企业级最佳实践

1. MCP服务器部署最佳实践

  • 独立部署：每个MCP服务器独立部署，互不干扰
  • 容器化：使用Docker容器化部署MCP服务器，方便管理和扩展
  • 负载均衡：对于高并发的MCP服务器，使用负载均衡器
  • 服务发现：使用服务注册中心管理MCP服务器，实现动态发现

2. 安全与权限控制

  • 最小权限原则：MCP服务器只拥有完成任务所需的最小权限
  • 网络隔离：将MCP服务器部署在独立的网络区域，限制网络访问
  • 身份认证：为MCP服务器添加身份认证，只允许授权的客户端访问
  • 审计日志：记录所有MCP工具调用的详细日志，用于审计和安全分析
  • 沙箱环境：在沙箱环境中执行危险操作，如命令执行和文件操作

3. 性能优化

  • 缓存：缓存工具调用的结果，避免重复执行相同的操作
  • 异步执行：对于耗时较长的工具，使用异步执行
  • 批量处理：支持批量操作，减少网络往返
  • 超时控制：为每个工具调用设置超时时间，防止长时间阻塞

4. 工具生态建设

  • 标准化：所有工具都遵循MCP标准，确保兼容性
  • 文档化：为每个工具编写详细的文档，说明使用方法和注意事项
  • 版本控制：对MCP服务器进行版本控制，避免破坏性变更
  • 测试：为每个工具编写单元测试和集成测试，确保质量

九、常见坑与解决方案

1. ❌ MCP服务器启动失败

问题：MCP服务器无法启动，提示"command not found"
解决方案：

  • 确保已经安装了Node.js和npm
  • 确保MCP服务器包已经全局安装：npm install -g @modelcontextprotocol/server-filesystem
  • 检查命令路径是否正确

2. ❌ 大模型不调用MCP工具

问题：大模型不知道有MCP工具，或者不知道什么时候调用
解决方案：

  • 检查MCP服务器是否正确配置和启动
  • 在系统提示词中明确告诉大模型可以使用哪些工具
  • 给大模型提供几个使用工具的示例

3. ❌ 工具调用权限不足

问题：工具执行失败，提示"权限不足"
解决方案：

  • 确保运行MCP服务器的用户拥有足够的权限
  • 调整文件和目录的权限
  • 使用sudo运行需要更高权限的命令（谨慎使用）

4. ❌ 工具返回结果过长

问题：工具返回的结果太长，超过了大模型的上下文窗口限制
解决方案：

  • 对工具返回的结果进行压缩和摘要
  • 分页返回结果
  • 使用上下文压缩技术只保留相关信息

5. ❌ MCP工具名称冲突

问题：多个MCP服务器提供了同名的工具，导致调用混乱
解决方案：

  • 为工具添加命名空间前缀
  • 在配置文件中指定工具的优先级
  • 明确告诉大模型应该使用哪个工具

十、本章总结与下章预告

本章总结

  1. MCP协议解决了传统工具调用紧耦合、无法复用、生态碎片化的问题
  2. MCP是AI世界的USB接口，一次开发，到处使用
  3. Spring AI 1.0提供了原生的MCP支持，配置简单，使用方便
  4. 官方提供了文件系统、命令执行、数据库、浏览器等常用MCP服务器
  5. 使用Spring AI可以很方便地开发自定义MCP服务器
  6. 企业级MCP应用必须做好安全控制、性能优化和可观测性

预告式提及：我们现在已经掌握了工具调用和MCP协议这两个AI Agent的核心基础。下一章我们将学习AI Agent的核心原理与实现，看看如何将这些技术整合起来，构建一个能够自主思考、规划和执行复杂任务的智能Agent。

下章预告

下一章我们将学习AI Agent的核心原理与实现。你将学会：

  • 什么是AI Agent？Agent的核心组成部分
  • ReAct框架：思考-行动-观察循环
  • Spring AI Agent工作流详解
  • 记忆系统：短期记忆与长期记忆的实现
  • 规划能力：让Agent自己分解复杂任务

十一、课后练习

  1. 安装Node.js和npm，配置文件系统MCP服务器，测试文件读写功能
  2. 配置浏览器MCP服务器，实现让大模型搜索最新新闻的功能
  3. 开发一个自定义的邮件发送MCP服务器，支持发送邮件
  4. 将你之前开发的所有工具都改造成MCP服务器，实现工具的标准化和复用
  5. 为你的MCP服务器添加安全控制和审计日志功能
# spring # 人工智能 # 学习
Logo
MCP技术社区

欢迎加入 MCP 技术社区！与志同道合者携手前行，一同解锁 MCP 技术的无限可能！

更多推荐

cover

基于Spring AI的Docker自然语言管理实践

avatar MCP技术社区
cover

【本地AI进阶：Function Calling与MCP协议完全指南——让AI Agent帮你自动执行任务】

avatar MCP技术社区

企业级智能体开发实战指南：EnterpriseAgentFramework 项目深度解析、核心架构剖析与全流程部署使用方法

为企业级 AI 应用开发提供了一条捷径。它不仅屏蔽了底层大模型调用的复杂性，更提供了一套标准化的工程范式。通过该项目，开发者可以将精力集中在业务逻辑和智能体策略的设计上，而不是重复造轮子。无论你是想构建企业内部的知识库助手，还是自动化的客户服务系统，这个框架都是一个值得深入研究的优秀范本。

avatar MCP技术社区