首页 维修案例文章正文

2026年4月9日：Spring AI助手配置MCP协议全攻略

维修案例 2026年04月20日 21:33 4 小编

一、开篇引入

在2026年的AI应用开发中，如何让大模型高效、安全地调用外部工具，已成为开发者绕不开的核心命题。Model Context Protocol（MCP，模型上下文协议） 正是为解决这一命题而生的标准化协议，它如同一把通用的“USB-C接口”，让AI助手能够与外部数据源、工具和服务实现标准化互联-18。

许多学习者在接触MCP时往往陷入困惑：@Tool注解和MCP Server究竟什么关系？MCP Client又该如何配置？面试时被问到“MCP与Function Calling有何区别”不知如何作答？本文将从零出发，带你系统掌握Spring AI中MCP协议的配置与实战，覆盖概念讲解、代码示例、底层原理和高频面试考点，助你建立完整的知识链路。

二、痛点切入：为什么需要MCP？

传统AI工具调用的困境

在MCP出现之前，让大模型调用外部工具主要依赖Function Calling机制。开发者需要为每个模型平台编写不同的适配代码，大致流程如下：

java
复制
下载
// 传统方式：为每个模型平台定义不同的工具Schema
// OpenAI版本
{
  "type": "function",
  "function": {
    "name": "get_weather",
    "parameters": {...}
  }
}

// Claude版本——完全不同的格式
{
  "name": "get_weather",
  "input_schema": {...}
}

传统方式的三大痛点

  1. 碎片化严重：OpenAI、Claude、文心、通义等模型各有各的工具调用格式，跨平台适配耗时耗力，跨平台工具集成平均消耗开发周期的47%-50。

  2. 耦合度高：每次增加新工具都需要修改AI助手代码并重启服务，工具与AI助手之间存在强耦合关系-8。

  3. 生态割裂：开发者需为每个AI平台单独维护工具代码，缺乏标准化的工具发现和复用机制-51。

MCP如何解决这些问题？

MCP协议由Anthropic于2024年底开源，2025年起被各大厂商广泛采纳-51。它通过三层架构设计（Host → Client → Server）和标准化JSON-RPC 2.0通信，将AI应用与外部工具的耦合彻底解耦-18。截至2026年，MCP已在Claude、ChatGPT、VS Code、Cursor等主流平台获得支持，生态服务器数量达数百个，覆盖GitHub、Slack、PostgreSQL等常用服务-18-16。

三、核心概念讲解：MCP（模型上下文协议）

标准定义

MCP（Model Context Protocol，模型上下文协议） 是一个开放标准，旨在标准化AI大模型与外部工具、资源和服务之间的交互方式-58。

关键词拆解

  • Model：指大语言模型（LLM）或AI智能体

  • Context：指模型运行时需要的上下文信息——有哪些工具可用、有哪些资源可读、有哪些预设提示词可调

  • Protocol：定义了一套标准化的通信规则

生活化类比

可以把MCP理解为AI世界的USB-C接口-18：

  • 在USB-C出现前，不同手机要用不同的充电线——就像过去不同模型要用不同的Function Calling格式

  • USB-C统一了接口标准，一根线通吃所有设备——MCP统一了AI工具调用标准，一个协议通吃所有模型

MCP的价值

  • 一次开发，多端适配：开发者只需编写一个MCP Server，即可被所有兼容MCP的AI客户端调用

  • 动态能力发现：AI可自主识别服务器提供的工具，无需预定义映射关系

  • 安全可控：内置OAuth 2.1、PKCE等安全机制-18

四、关联概念讲解：@Tool注解与MCP Server

@Tool注解定义

@Tool是Spring AI提供的方法级注解，用于将Java方法标记为可供AI模型调用的“工具”。Spring AI支持两种Tool注解：

  • @Tool：Spring AI原生注解，用于定义工具能力-1

  • @McpTool：MCP专用注解，在MCP Server场景中暴露工具-2

当应用程序启动时，Spring AI会自动扫描被注解的方法，分析其签名并构建工具定义-2。

MCP Server定义

MCP Server是运行在服务端、按MCP协议暴露能力的组件，负责将项目中的业务能力封装成可供外部客户端发现和调用的标准化工具-1。

两者的关系与差异

维度@Tool注解MCP Server
角色定位声明式标记完整的服务组件
作用范围单方法级别整个服务级别
对外暴露仅在应用内部通过MCP协议对外暴露
依赖要求仅需注解依赖需要spring-ai-starter-mcp-server等完整依赖

一句话总结：@Tool是“声明我有这个能力”，MCP Server是“把我的能力以标准协议对外提供服务”-1。

五、概念关系与区别总结

逻辑关系图

text
复制
下载
MCP协议（标准规范）
    ├── MCP Host（AI应用，如Claude Desktop、ChatGPT）
    ├── MCP Client（协议处理器，负责与服务端通信）
    └── MCP Server（服务提供方）
            └── 内部使用 @Tool / @McpTool 注解暴露具体方法

一句话记忆

MCP是协议标准，Server是服务端实现，@Tool是暴露具体能力的方法级注解。

核心区分要点

  • MCP ≠ @Tool：@Tool只是能力声明，真正暴露为MCP服务还需要MCP Server依赖和自动配置-1

  • MCP Server ≠ 普通的Spring Bean：MCP Server需要配置传输协议（Stdio/Streamable-HTTP）和服务元数据

六、代码实战：从零搭建Spring AI MCP Server

环境要求（2026年最新版本搭配）

组件版本要求说明
JDK21+LTS版本，支持虚拟线程
Spring Boot3.5.x+需要Spring Boot 3.x以上
Spring AI1.1.2+MCP Starter依赖版本-2

步骤一：添加Maven依赖

xml
复制
下载
运行
<!-- MCP Server核心依赖 -->
<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-mcp-server</artifactId>
    <version>1.1.2</version>
</dependency>

-2

步骤二：编写业务服务类

java
复制
下载
@Service
public class WeatherService {
    
    @Tool(description = "根据城市名称获取天气预报")
    public String getWeatherByCity(String city) {
        // 模拟天气查询逻辑
        Map<String, String> weatherMap = Map.of(
            "北京", "晴，22℃~28℃，南风2级",
            "上海", "多云，18℃~25℃，东风3级",
            "深圳", "阵雨，24℃~30℃，西南风2级"
        );
        return weatherMap.getOrDefault(city, "暂无该城市天气信息");
    }
}

-1

步骤三：配置application.yml（Streamable-HTTP协议）

yaml
复制
下载
server:
  port: 8014
spring:
  application:
    name: mcp-server-demo
  ai:
    mcp:
      server:
        type: async
        protocol: STREAMABLE
        name: weather-mcp-server
        version: 1.0.0

-1

步骤四：MCP Client端配置

在AI助手项目中添加客户端依赖并配置服务地址：

yaml
复制
下载
 AI助手项目的 application.yml
spring:
  ai:
    mcp:
      client:
        enabled: true
        url: http://localhost:8014
        endpoint: /mcp

-1

关键点解析

  • @Tool注解的description字段至关重要——LLM正是通过这个描述来判断何时调用该工具，描述越清晰，调用准确率越高-2

  • 使用Stdio传输时，必须关闭控制台日志输出，否则会污染JSON-RPC协议消息-2

  • MCP Server启动后会自动扫描所有@Tool注解的方法并生成工具定义，无需手动注册-5

七、底层原理与技术支撑

MCP协议的三层架构

MCP采用主机-客户端-服务器三层架构，各组件职责清晰且解耦-49：

  1. MCP Host（主机）：AI应用本身（如Claude Desktop、ChatGPT），负责维护对话上下文、管理工具调用权限

  2. MCP Client（客户端）：Host内部的协议处理器，负责与Server通信、工具发现与调用

  3. MCP Server（服务器）：真正提供工具能力的服务端

通信机制

MCP基于JSON-RPC 2.0进行消息通信，支持两种传输方式-48：

  • Stdio（标准输入输出） ：用于本地场景，AI Client将Java应用作为子进程启动，通过控制台进行JSON-RPC通信

  • Streamable-HTTP：用于云端/远程场景，支持HTTP流式传输，适合生产环境部署

Spring AI的底层依赖

Spring AI的MCP模块构建在MCP Java SDK之上，SDK内部处理了协议版本协商、能力协商、消息序列化、会话管理等底层细节-60。框架层面的自动配置（@ConditionalOnMissingBean、@AutoConfiguration）进一步简化了开发者的配置工作。

八、高频面试题与参考答案

面试题1：什么是MCP协议？它与Function Calling有什么区别？

参考答案：

MCP（Model Context Protocol，模型上下文协议）是Anthropic开源的开放标准，用于标准化AI大模型与外部工具、资源和服务之间的交互方式。它采用三层架构（Host-Client-Server），基于JSON-RPC 2.0通信。

与Function Calling的区别：

  • Function Calling是各模型厂商各自的私有实现，标准不统一，切换模型需重写适配代码

  • MCP是跨模型的开放标准，一次开发可被所有兼容MCP的客户端调用，实现“一次编写，到处运行”

  • MCP还提供了更完善的安全机制（OAuth 2.1、增量授权）和动态能力发现机制-51-58

面试题2：Spring AI中如何将本地方法暴露为MCP服务？

参考答案：

分三步：

  1. 添加spring-ai-starter-mcp-server依赖

  2. 在Service类的方法上标注@Tool注解，并填写清晰的description

  3. 配置application.yml，设置protocol为STREAMABLE或stdio，并配置端口

框架启动时会自动扫描@Tool注解，通过MethodToolCallbackProvider生成工具定义并注册到MCP Server-5。

面试题3：@Tool注解和MCP Server是什么关系？

参考答案：

@Tool是声明式注解，标记某个方法可作为工具能力；MCP Server是完整的服务组件，负责将这些能力按MCP协议对外暴露。@Tool本身不等于MCP Server——只有添加了MCP Server依赖和自动配置后，被@Tool标注的方法才能真正以MCP服务的形式被外部客户端调用-1。

面试题4：MCP支持哪些传输方式？各适用于什么场景？

参考答案：

MCP支持两种主要传输方式：

  • Stdio：通过标准输入输出通信，AI Client将Server作为子进程启动，适用于本地桌面应用场景。使用时必须关闭控制台日志，避免污染JSON-RPC消息。

  • Streamable-HTTP：基于HTTP的流式传输，适用于云端/远程部署的生产环境，支持负载均衡和水平扩展-48。

面试题5：如何测试MCP工具？

参考答案：

MCP工具本质上是普通的应用程序代码，具有确定性行为（不同于LLM的非确定性输出），因此可以编写自动化测试。测试策略包括：

  • 单元测试：直接测试@Tool注解的方法

  • 集成测试：使用@SpringBootTest启动完整上下文，验证MCP Server的工具注册和调用链路

  • 使用McpClient模拟客户端调用进行端到端验证-3

九、结尾总结

核心知识点回顾

知识点核心结论
MCP协议AI工具调用的“USB-C接口”，解决N×M的集成碎片化问题
三层架构Host（AI应用）→ Client（协议处理器）→ Server（能力提供方）
@Tool注解声明式标记方法为工具能力，description字段对LLM决策至关重要
MCP Server完整的服务组件，需配合MCP Starter依赖和传输协议配置
易混淆点@Tool ≠ MCP Server，前者只是标记，后者才是完整服务

重点强调与易错提示

  • ⚠️ @Tool注解不等于MCP Server：很多初学者误以为加个@Tool就能对外提供MCP服务，实际上必须添加MCP Server依赖并配置传输协议

  • ⚠️ Stdio模式必须关闭控制台日志：任何额外输出都会破坏JSON-RPC通信，这是生产环境踩坑的高发区

  • ⚠️ description字段要写清楚：LLM依赖这个描述来判断何时调用工具，描述越精确，调用准确率越高

下篇预告

本文重点讲解了MCP Server端的配置与实现。下一篇我们将聚焦MCP Client端的配置与调用，深入探讨如何在AI助手中发现和调用外部MCP服务，以及如何通过Nacos实现MCP Server的动态注册与热加载。

本文基于Spring AI 1.1.2、Spring Boot 3.5.x编写，代码示例均经过验证。建议使用Spring Initializr生成基础项目结构，避免手动配置导致的版本冲突问题。

相关文章

上海羊羽卓进出口贸易有限公司 备案号：沪ICP备2024077106号