SpringAI：MCP 协议介绍与接入方法

**摘要：**本文介绍 MCP 模型上下文协议，讲解其架构、核心概念，以及在云平台、客户端和 Spring AI 中接入使用的方法。

一需求分析

目前我们的 CSDN AI 助手已具备项目知识问答与工具调用能力，现在新增一项实用功能：根据代码仓库信息，快速查询项目开发状态。

你会怎么实现呢？按照之前所学，思路主要有三种：

靠预训练知识理解 Git 相关概念，但无法获取实时仓库信息，结果不准确。
使用 RAG 知识库：提前录入 Git 相关文档，无法实时查询提交、变更等动态信息。
使用工具调用：开发专门 Git 工具，直接调用 Git 命令或 JGit 获取数据，信息最新且准确。

显然，第三种方式效果最好。但既然要操作 Git，我们还需要从零开发工具吗？为什么不能直接让标准化服务对接 AI？

其实已经有了，这就是我们今天的主角 ------MCP。

二 MCP 必知必会

什么是 MCP？

MCP（Model Context Protocol，模型上下文协议）是一种开放标准，旨在增强 AI 与外部系统的交互能力。它为 AI 提供了与外部工具、资源和服务交互的标准化方式，使 AI 能够访问最新数据、执行复杂操作，并与现有系统集成。

按照官方定义，MCP 是一种开放协议，标准化了应用向大模型提供上下文的方式。可以把 MCP 理解为 AI 应用的 USB 接口：正如 USB 为设备连接各类外设提供了统一标准，MCP 为 AI 模型连接不同数据源和工具提供了标准化的实现方式。

前面讲的可能有些抽象，我举几个例子帮大家更好地理解 MCP 的作用。

首先，MCP 能够增强 AI 的能力。通过 MCP 协议，AI 应用可以便捷地接入第三方提供的服务，实现更丰富的功能，比如搜索网页、查询数据库、调用第三方 API、执行计算等。

其次，MCP 本质是一种协议或标准，它本身并不提供具体服务，只是定义了一套统一的交互规范，供服务提供者和服务使用者共同遵守。这一点和 HTTP 协议很相似：如今前端向后端发起请求基本都使用 HTTP，GET/POST 请求方式、401/404 状态码等统一标准，极大降低了开发者的学习与对接成本。

此外，标准化还能避免重复开发。举个例子：以前想给 AI 增加地图查询能力，需要自己开发工具对接第三方地图 API；如果多个项目或多位开发者都需要相同能力，就会出现重复造轮子的情况，不仅浪费人力，功能质量和效果也参差不齐。而如果有官方将地图查询封装成标准化服务，谁需要谁直接接入，既能节省开发成本，又能保证效果统一。当越来越多的服务商开放自身服务后，就会形成一个服务市场，让所有开发者受益。

标准可以造就生态。这其实并不陌生：前端开发者可以类比 NPM 包，后端开发者可以联想 Maven 仓库和 Docker 镜像源，即使不懂编程的人，也可以通过手机应用市场来理解这种模式。

这就是 MCP 的三大作用：

轻松增强 AI 的能力
统一标准，降低使用和理解成本
打造服务生态，造福广大开发者

MCP 架构

1 宏观架构

MCP 的核心是"؜؜客户端 - 服务器"架构，其中 MCP⁠⁠⁠⁠⁠ 客户端主机可以连接到多个服务器。客户端‏‏‏‏‏主机是指希望访问 MCP 服务的程序，比‌‌‌‌‌如 Claude Desktop、IDE‏‏‏‏‏、AI 工具或部署在服务器上的项目。

2 SDK 3 层架构

如果我们要在程序中使用 MCP 或开发 MCP 服务，可以引入 MCP 官方的 SDK，如 Java SDK。让我们先通过 MCP 官方文档了解 MCP SDK 的架构，主要分为 3 层：

分别来看每一层的作用：

客户端 / 服务器层：McpClient 处理客户端操作，而 McpServer 管理服务器端协议操作。两者都使用 McpSession 进行通信管理。
会话层（McpSession）：通过 DefaultMcpSession 实现管理通信模式和状态。
传输层（McpTransport）：处理 JSON-RPC 消息序列化和反序列化，支持多种传输实现，比如 Stdio 标准 IO 流传输和 HTTP SSE 远程传输。

客户端和服؜؜؜؜务端؜需要先经过⁠下⁠面⁠的⁠流程建立‏连接‏，⁠之‏后才能‏‌正常交‌换消息‌：‏

3 MCP 客户端

MCP Client 是؜؜؜؜؜ MCP 架构中的关键组件，主要负责和 MCP⁠⁠⁠⁠⁠ 服务器建立连接并进行通信。它能自动匹配服务器‏‏‏‏‏的协议版本、确认可用功能、负责数据传输和 JS‌‌‌‌‌ON-RPC 交互。此外，它还能发现和使用各种‏‏‏‏‏工具、管理资源、和提示词系统进行交互。

除了这些核心功؜؜؜؜؜能，MCP 客户端还支持一⁠⁠⁠⁠⁠些额外特性，比如根管理、采‏‏‏‏‏样控制，以及同步或异步‌‌‌‌操作‌。为了适应不同场景，它提供‏‏‏‏‏了多种数据传输方式，包括：

Stdio 标准输入 / 输出：适用于本地调用
基于 Java HttpClient 和 WebFlux 的 SSE 传输：适用于远程调用

客户端可以؜؜؜؜؜通过不同传输方⁠⁠⁠式⁠调⁠用不同的 ‏‏‏MC‏P ‏服务，‌‌‌可以是‌本地的‌、‏‏‏也可以‏是远程的。‏如图：

4 MCP 服务端

MCP S؜؜؜؜؜erver 是整⁠⁠⁠⁠⁠个 MCP 架构的‏‏‏‏‏关键组件，主要用来‌‌‌‌‌为客户端提供各种工‏‏‏‏‏具、资源和功能支持。

它负责处理客户端؜؜؜؜؜的请求，包括解析协议、提供工具⁠⁠⁠⁠⁠、管理资源以及处理各种交互‏‏‏‏‏信息。同时，它还能记录日志、发送通‌‌‌‌‌知，并且支持多个客户端同时连接‏‏‏‏‏，保证高效的通信和协作。

和客户端一样，它也؜؜؜؜؜可以通过多种方式进行数据传输，比如⁠⁠⁠⁠⁠ Stdio 标准输入 / 输出、‏‏‏‏‏基于 Servlet / WebF‌‌‌‌‌lux / WebMVC 的 SS‏‏‏‏‏E 传输，满足不同应用场景。

这种设计使؜؜؜؜؜得客户端和服务⁠⁠⁠端⁠完⁠全解耦，任‏‏‏何语‏言开‏发的客‌‌‌户端都‌可以调‌用‏‏‏ MC‏P 服务。‏如图：

MCP 核心概念

很多同学以为 MCP 协议只能提供工具供他人调用，但实际上，MCP 协议的能力远不止于此。

按照官方说明，它共有 6 大核心概念。大家简单了解即可，除 Tools 工具外，其他概念实用性相对较弱，如需深入学习可查阅对应官方文档：

1.Resources 资源：让服务端向客户端提供各类数据（如文本、文件等），客户端可自主决定使用时机，使 AI 能访问最新信息与外部知识，为模型提供更丰富的上下文。

2.Prompts 提示词：服务端可定义可复用的提示词模板与工作流，供客户端和用户直接使用。它能标准化常见 AI 交互模式，以 UI 元素形式呈现，简化用户与 LLM 的交互过程。

3.Tools 工具：MCP 中最实用的特性，服务端可提供可调用函数，使 AI 模型能够执行计算、查询信息或与外部系统交互，极大拓展 AI 的能力边界。

4.Sampling 采样：允许服务端通过客户端向大模型发送生成内容的反向请求，使 MCP 服务可实现复杂智能代理行为，同时保障用户对全过程的控制权与数据隐私。

5.Roots 根目录：MCP 协议的安全机制，定义服务器可访问的文件系统位置，限制访问范围，为 MCP 服务提供安全边界，防止恶意文件访问。

6.Transports 传输：定义客户端与服务器间的通信方式，包括 Stdio（本地进程间通信）和 SSE（网络实时通信），确保不同环境下的可靠信息交换。

如果要开发 MCP 服务，我们主要关注前 3 个概念：

MCP 官方文档中提到，大多数客户端也只支持 Tools 工具调用能力：

所以接下来؜؜؜؜؜我们学习使用⁠⁠和⁠开⁠发⁠ MC‏‏P ‏的过‏程中‏‌‌，只需‌关注 ‌T‏‏oo‌l‏s ‏工具即可。

三使用 MCP

本节我们将实战 3 种使用 MCP 的方式：

云平台使用 MCP
软件客户端使用 MCP
程序中使用 MCP

无论是哪种使用方式，原理都是类似的，而且有 2 种可选的使用模式：本地下载 MCP 服务端代码并运行 （类似引入 SDK），或者 直接使用已部署的 MCP 服务（类似调用 API）。

到哪里去找别人开发的 MCP 服务呢？

MCP 服务大全

目前已经有؜؜؜很多 MCP ⁠服⁠务⁠市场，开发‏者可‏以在‏这些平‌台上找‌到各种‌现‏成的 M‏CP 服‏务：

MCP.so：较为主流，提供丰富的 MCP 服务目录
GitHub Awesome MCP Servers：开源 MCP 服务集合
阿里云百炼 MCP 服务市场
Spring AI Alibaba 的 MCP 服务市场
Glama.ai MCP 服务

其中，绝大多؜؜؜数 MCP 服务市场仅⁠⁠⁠提供本地下载 MCP ‏‏‏服务端代码并运行的使用‌‌‌方式，毕竟部署 MCP‏‏‏ 服务也是需要成本的。

有些云服务平台提؜؜؜供了云端部署的 MCP 服务，比⁠⁠⁠如阿里云百炼平台，在线填写配置后‏‏‏就能用，可以轻松和平台上的 AI ‌应‌‌用集成。但一般局限性也比较大‏‏‏，不太能直接在自己的代码中使用。

下面来学习 3 种使用 MCP 的方式。

云平台使用 MCP

以阿里云百炼为例，参考官方 MCP 文档，我们可以直接使用官方预置的 MCP 服务，或者部署自己的 MCP 服务到阿里云平台上。

如图，官方提供了很多现成的 MCP 服务：

让我们进入一个智؜؜؜能体应用，在左侧可以点击添加 ⁠⁠⁠MCP 服务，然后选择想要使用‏‏‏的 MCP 服务即可，比如使用‌‌‌高德地图 MCP 服务，提供地‏‏‏理信息查询等 12 个工具。

测试一下，؜؜؜输入 Promp⁠⁠t⁠：我的另一半居‏‏住在‏上海静安区，‌‌请帮我‌找到 5 ‏‏公里内合适的‏约会地点。

发现 AI؜؜؜ 自动调用了 ⁠M⁠C⁠P 提供的‏多个‏工具‏，给出‌了不错‌的回答‌：

AI 会根؜؜؜据需要调用不同⁠的⁠工⁠具，比如将‏地点‏转为‏坐标、‌查找某‌坐标附‌近‏的地点：

调用工具完成؜后，؜؜AI 会利用工具的⁠输出结果进一步分⁠⁠析并生成‏回复，流程类似于‏‏工具调用。

软件客户端使用 MCP

不同的客户端软件对 MCP 支持程度不同，可以在官方文档中查看各客户端支持的特性。

下面我们以主流؜؜؜ AI 客户端 Curso⁠⁠⁠r 为例，演示如何使用 M‏‏‏CP 服务。由于没有现成的‌‌‌部署了 MCP 服务的服务‏‏‏器，我们采用本地运行的方式。

1 环境准备

首先安装本地运؜؜؜行 MCP 服务需要用到的工⁠⁠⁠具，具体安装什么工具取决于 ‏‏‏MCP 服务的配置要求。

比如我们到 MCP 市场找到高德地图 MCP，发现 Server Config 中定义了使用 npx 命令行工具来安装和运行服务端代码：

大多数 MCP 服务都支持基于 NPX 工具运行，所以推荐安装 Node.js 和 NPX。

从配置中发现，使用地图 MCP 需 API Key，我们可以到地图开放平台创建应用并添加 API Key：

2 Cursor 接入 MCP

在右上角进؜؜؜入 Cursor ⁠⁠⁠Settings ‏‏‏设置界面，然后选择‌‌‌ MCP，添加全局‏‏‏的 MCP Server：

接下来从 MCP 市场中找到 MCP Server Config，并粘贴到 mcp.json 配置中，注意要将 API Key 更改为自己的：

保存配置，软件会自动识别并启动服务，效果如图：

3 测试使用 MCP

接下来就可以؜؜؜使用 MCP 服务了，还⁠⁠⁠是提供之前的 Promp‏‏‏t：我的另一半居住在上海‌‌‌静安区，请帮我找到 5 ‏‏‏公里内合适的约会地点。

观察效果，发现 AI 可能会多次调用 MCP：

最终生成结果如图，还是不错的：

但是这也让我们意识到使用 MCP 服务的代价 ------ 由于调用次数不稳定，可能产生较高的 AI 和 API 调用费用，所以一般我的建议是 能不用就不用。

如果要使用؜؜؜其他软件客户端，接入⁠⁠⁠ MCP 的方法也是‏‏‏类似的，可以直接看软‌‌‌件官方（MCP ‏‏‏官方）提供的接入文档，比如：

Cherry Studio：查看软件官方文档了解集成方法
Claude Desktop：参考 MCP 官方的用户快速入门指南

程序中使用 MCP

让我们利用 ؜؜؜Spring AI 框架⁠⁠⁠，在程序中使用 MCP ‏‏‏并完成我们的需求，实现一‌‌‌个能够根据另一半的位置推‏‏‏荐约会地点的 AI 助手。

💡 类似的 Java MCP 开发框架还有 Solon AI MCP，但由于我们更多地使用 Spring 生态，所以还是推荐使用 Spring AI 框架。

首先了解 Spring AI MCP 客户端的基本使用方法。建议参考 Spring AI Alibaba 的文档，因为 Spring AI 官方文档更新的太快了，包的路径可能会变动。

1）在 Maven 中央仓库中可以找到正确的依赖，引入到项目中：

XML 复制代码

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-mcp-client-spring-boot-starter</artifactId>
    <version>1.0.0-M6</version>
</dependency>

2）在 resources 目录下新建 mcp-servers.json 配置，定义需要用到的 MCP 服务：

bash 复制代码

{
  "mcpServers": {
    "amap-maps": {
      "command": "npx",
      "args": [
        "-y",
        "@amap/amap-maps-mcp-server"
      ],
      "env": {
        "AMAP_MAPS_API_KEY": "改成你的 API Key"
      }
    }
  }
}

注意：在 Windows 中，命令配置需添加 .cmd 后缀（npx.cmd），否则会报找不到命令的错误。💡

3）修改 Spr؜؜؜ing 配置文件，编写 MCP⁠⁠⁠ 客户端配置。由于是本地运行 ‏‏‏MCP 服务，所以使用 std‌‌‌io 模式，并且要指定 MCP‏‏‏ 服务配置文件的位置。代码如下：

bash 复制代码

spring:
    ai:
      mcp:
        client:
          stdio:
            servers-configuration: classpath:mcp-servers.json

这样，؜؜؜MCP 客户端程⁠⁠序⁠启动时，会额外‏‏启动‏一个子进程来‌‌运行 ‌MCP 服‏‏务，从而能够‏实现调用。

4）修改 LoveApp 的代码，新增一个利用 MCP 完成对话的方法。通过自动注入的 ToolCallbackProvider 获取到配置中定义的 MCP 服务提供的所有工具，并提供给 ChatClient。

java 复制代码

@Resource
private ToolCallbackProvider toolCallbackProvider;

public String doChatWithMcp(String message, String chatId) {
    ChatResponse response = chatClient
            .prompt()
            .user(message)
            .advisors(spec -> spec.param(CHAT_MEMORY_CONVERSATION_ID_KEY, chatId)
                    .param(CHAT_MEMORY_RETRIEVE_SIZE_KEY, 10))
            // 开启日志，便于观察效果
            .advisors(new MyLoggerAdvisor())
            .tools(toolCallbackProvider)
            .call()
            .chatResponse();
    String content = response.getResult().getOutput().getText();
    log.info("content: {}", content);
    return content;
}

从这段代码我们能够看出，MCP 调用的本质就是类似工具调用，并不是让 AI 服务器主动去调用 MCP 服务，而是告诉 AI "MCP 服务提供了哪些工具"，如果 AI 想要使用这些工具完成任务，就会告诉我们的后端程序，后端程序在执行工具后将结果返回给 AI，最后由 AI 总结并回复。

流程图如下：

5）测试运行，编写单元测试代码：

java 复制代码

@Test
void doChatWithMcp() {
    String chatId = UUID.randomUUID().toString();
    // 测试地图 MCP
    String message = "我的另一半居住在上海静安区，请帮我找到 5 公里内合适的约会地点";
    String answer =  loveApp.doChatWithMcp(message, chatId);
}

四 Spring AI MCP 开发模式

Spring AI 在 ؜؜؜MCP 官方 Java SDK 的基础上额外封⁠⁠⁠装了一层，提供了和 Spring Boot 整‏‏‏合的 SDK，支持客户端和服务端的普通调用和响应‌‌‌式调用。下面分别学习如何使用 Spring ‏‏‏AI 开发 MCP 客户端和服务端。

MCP 客户端开发

客户端开发主要基于 Spring AI MCP Client Boot Starter，能够自动完成客户端的初始化、管理多个客户端实例、自动清理资源等。

1 引入依赖

Sprin؜؜؜g AI 提供了 2⁠⁠⁠ 种客户端 SDK，‏‏‏分别支持非响应式和响‌‌‌应式编程，可以根据需‏‏‏要选择对应的依赖包：5vPWD56ll5kkUnG0ja5sSNqkp2tHgsJHiSpPWWLD64g=

spring-ai-starter-mcp-client：核心启动器，提供 STDIO 和基于 HTTP 的 SSE 支持
spring-ai-starter-mcp-client-webflux：基于 WebFlux 响应式的 SSE 传输实现

比如下面的依赖（具体的依赖名称以官方文档为准）：

XML 复制代码

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

2 配置连接

引入依赖后؜؜؜，需要配置与服⁠务⁠器⁠的连接，S‏pr‏in‏g A‌I 支‌持两种‌配‏置方式：

1）直接写؜؜؜入配置文件，这⁠种⁠方⁠式同时支持‏ s‏td‏io ‌和 S‌SE 连‏‌接方式。

bash 复制代码

spring:
  ai:
    mcp:
      client:
        enabled: true
        name: my-mcp-client
        version: 1.0.0
        request-timeout: 30s
        type: SYNC
        sse:
          connections:
            server1:
              url: http://localhost:8080
        stdio:
          connections:
            server1:
              command: /path/to/server
              args:
                - --port=8080
              env:
                API_KEY: your-api-key

2）引用 Claude Desktop 格式的 JSON 文件，目前仅支持 stdio 连接方式。

XML 复制代码

spring:
  ai:
    mcp:
      client:
        stdio:
          servers-configuration: classpath:mcp-servers.json

配置文件格؜؜؜式如下：

bash 复制代码

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/username/Desktop",
        "/Users/username/Downloads"
      ]
    }
  }
}

3 使用服务

启动项目时؜؜؜，Spring⁠ ⁠A⁠I 会自动‏注入‏一些‏ MC‌P 相‌关的 B‏‌ean。

如果你想利用 MCP 服务提供的工具来增强 AI 的能力，可以使用自动注入的 ToolCallbackProvider Bean，从中获取到 ToolCallback 工具对象。

java 复制代码

// 和 Spring AI 的工具进行整合
@Autowired
private SyncMcpToolCallbackProvider toolCallbackProvider;
ToolCallback[] toolCallbacks = toolCallbackProvider.getToolCallbacks();

然后绑定给 ChatClient 对象即可：

java 复制代码

ChatResponse response = chatClient
        .prompt()
        .user(message)
        .tools(toolCallbackProvider)
        .call()
        .chatResponse();

MCP 服务端开发

服务端开发主要基于 Spring AI MCP Server Boot Starter，能够自动配置 MCP 服务端组件，使开发者能够轻松创建 MCP 服务，向 AI 客户端提供工具、资源和提示词模板，从而扩展 AI 模型的能力范围。

1 引入依赖

Spring؜؜؜ AI 提供了 3 种⁠⁠⁠ MCP 服务端 SD‏‏‏K，分别支持非响应式和‌‌‌响应式编程，可以根据需‏‏‏要选择对应的依赖包：

spring-ai-starter-mcp-server：提供 stdio 传输支持，不需要额外的 web 依赖
spring-ai-starter-mcp-server-webmvc：提供基于 Spring MVC 的 SSE 传输和可选的 stdio 传输
spring-ai-starter-mcp-server-webflux：提供基于 Spring WebFlux 的响应式 SSE 传输和可选的 stdio 传输

比如下面的依赖：

XML 复制代码

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

2 配置服务

如果要开发 stdio 服务，配置如下：

bash 复制代码

# 使用 spring-ai-starter-mcp-server
spring:
  ai:
    mcp:
      server:
        name: stdio-mcp-server
        version: 1.0.0
        stdio: true
        type: SYNC # 同步

开发 SSE 服务，配置如下：

bash 复制代码

# 使用 spring-ai-starter-mcp-server-webmvc
spring:
  ai:
    mcp:
      server:
        name: webmvc-mcp-server
        version: 1.0.0
        type: SYNC # 同步
        sse-message-endpoint: /mcp/message  # SSE 消息端点路径
        sse-endpoint: /sse                  # SSE 端点路径

如果要开发响应式（异步）服务，配置如下：

bash 复制代码

# 使用 spring-ai-starter-mcp-server-webflux
spring:
  ai:
    mcp:
      server:
        name: webflux-mcp-server
        version: 1.0.0
        type: ASYNC  # 异步
        sse-message-endpoint: /mcp/messages # SSE 消息端点路径
        sse-endpoint: /sse                  # SSE 端点路径

还有更多可选配置，详细信息可参考官方文档。

3 开发服务

无论采用哪种传输方式，开发 MCP 服务的过程都是类似的，跟开发工具调用一样，直接使用 @Tool 注解标记服务类中的方法。

java 复制代码

@Service
public class WeatherService {
    @Tool(description = "获取指定城市的天气信息")
    public String getWeather(
            @ToolParameter(description = "城市名称，如北京、上海") String cityName) {
        // 实现天气查询逻辑
        return "城市" + cityName + "的天气是晴天，温度22°C";
    }
}

然后在 Spring Boot 项目启动时注册一个 ToolCallbackProvider Bean 即可：

java 复制代码

@SpringBootApplication
public class McpServerApplication {
    @Bean
    public ToolCallbackProvider weatherTools(WeatherService weatherService) {
        return MethodToolCallbackProvider.builder()
                .toolObjects(weatherService)
                .build();
    }
}

恭喜你学习完成！❀

SpringAI：MCP 协议介绍与接入方法

一 需求分析

二 MCP 必知必会

什么是 MCP？

MCP 架构

1 宏观架构

2 SDK 3 层架构

3 MCP 客户端

4 MCP 服务端

MCP 核心概念

三 使用 MCP

MCP 服务大全

云平台使用 MCP

软件客户端使用 MCP

1 环境准备

2 Cursor 接入 MCP

3 测试使用 MCP

程序中使用 MCP

四 Spring AI MCP 开发模式

MCP 客户端开发

1 引入依赖

2 配置连接

3 使用服务

MCP 服务端开发

1 引入依赖

2 配置服务

3 开发服务

一需求分析

三使用 MCP