MCP 协议入门

27.1 为什么需要 MCP

先回顾第 24 章的工具调用。@Tool 注解能把 Java 方法变成模型可调用的工具，但工具和模型都在同一个应用里。现实情况往往更复杂：AI 要查数据库、读文件、搜网页，这些能力散落在不同的服务中。

每个服务都自己做一套接入方式，AI 应用就得写一堆适配代码。服务多了，维护成本直线上升。MCP（Model Context Protocol，模型上下文协议）就是为了解决这个问题：它把”AI 应用如何连接外部工具和资源”这件事标准化了。

Anthropic 官方宣传的说法很形象：MCP 是 AI 世界的”USB-C 接口”。以前每个设备都要自己的充电线，现在统一成一个标准。有了 MCP，数据库、文件系统、API 服务都能以同一种方式接入 AI 应用。官方 MCP Java SDK 由 MCP 官方团队维护；Spring 团队深度参与了 MCP 生态建设，Spring AI 的 MCP 集成就是他们做的。

拿实际场景感受一下。没有 MCP 时，接一个搜索服务要写一个 HTTP 客户端，接一个数据库要写一套查询封装，每个接入都是重复劳动。有了 MCP，别人写好的搜索服务器、文件系统服务器直接连，你只写配置，不写适配代码。这也是 MCP 生态快速壮大的原因。

27.2 三个核心角色

MCP 的架构围绕三个角色展开。

Client（客户端）是 AI 应用这一侧。它负责连接服务器、发现工具、发起调用。具体活不少：协议版本协商、能力协商、JSON-RPC 消息收发、工具发现与执行、资源访问、提示词交互。Spring AI 应用里的 MCP Client 就是干这些的，第 28 章写的就是它。

Server（服务器）是能力提供方。它把工具、资源、提示词暴露给客户端。比如一个天气服务器，暴露一个”查温度”的工具，第 29 章写的就是它。

Transport（传输层）负责消息怎么在两端之间传递。JSON-RPC 消息的序列化、反序列化都在这一层。STDIO、SSE、Streamable-HTTP 都是传输方式，第 30 章详细对比。

MCP Java SDK 把这三层拆得很清楚。最上层是 Client/Server 层，对应 McpClient 和 McpServer 两个类，处理协议操作。中间是 Session 层，对应 McpSession，管理连接状态。最底层是 Transport 层，也就是 McpTransport，处理消息的序列化和反序列化。层与层职责分离，换传输方式不影响上层逻辑。

日常开发不用直接碰这三层，Boot Starter 的自动配置全包了。但了解分层有助于排错：连接不上先查传输层配置，工具列表为空先查会话层协商，功能异常再查上层逻辑。

27.3 服务器能提供什么

MCP Server 能暴露三类东西。

Tools（工具）：模型可以直接调用的函数，比如查天气、发邮件。这是最常用的一类，也是本教程的重点。工具自带参数 Schema，模型根据描述和 Schema 决定怎么调。

Resources（资源）：以 URI 访问的数据，比如 config://{key} 配置项、文件内容。资源给模型提供上下文，类似知识库的素材。和工具的区别是：资源是”读数据”，工具是”做事情”。

Prompts（提示词）：服务器预置的提示词模板。客户端可以直接引用，省去自己拼提示词的麻烦，适合把领域专家的提示词沉淀在服务端。

客户端和服务器建立连接时，会先协商各自支持哪些能力，再决定用什么功能。服务器端可以按需开关这些能力，比如只开工具、关掉资源。

27.4 与工具调用是什么关系

第 24 章讲的 @Tool 和 MCP 不冲突，而是互补。

@Tool 解决的是”本应用内的工具”。方法写在哪、工具就用在哪，模型和工具同属一个进程，调用直接走 Java 方法。

MCP 解决的是”跨应用的工具”。工具实现在远程服务器上，AI 应用通过协议发现并调用它，两端可以完全独立部署。

Spring AI 2.0 里两者打通了。服务器端 @Tool 方法能自动转成 MCP 工具，被远程客户端发现；客户端拿到远程 MCP 工具后，会包装成 ToolCallback，和本地工具一样交给 ChatClient 使用。对模型来说，本地工具和远程工具没有区别，调用方式完全一致。

一次典型的调用长这样：客户端连上服务器，握手初始化，然后列出工具清单，把工具定义交给模型。模型觉得需要时发起调用，客户端把参数转发给服务器，服务器执行方法，结果原路返回，模型基于结果生成最终回答。整个过程就是三次交互：initialize、tools/list、tools/call。

27.5 Spring AI 怎么支持 MCP

Spring AI 对 MCP 的支持分三块。

第一块是 Boot Starter。客户端有 spring-ai-starter-mcp-client 和 spring-ai-starter-mcp-client-webflux；服务器端有 spring-ai-starter-mcp-server（STDIO）、spring-ai-starter-mcp-server-webmvc、spring-ai-starter-mcp-server-webflux。加依赖、写配置就能跑起来，自动配置负责连接、发现、注册这些脏活。

第二块是注解。@McpTool、@McpResource 这类注解把方法声明成 MCP 能力，框架自动生成 JSON Schema 并注册，不用手写规范对象。第 31 章细讲。

第三块是传输。STDIO、SSE、Streamable-HTTP（含 Stateless 变体）都支持，用配置项切换。选哪种取决于部署环境：本地工具选 STDIO，独立服务选 Streamable-HTTP，无状态扩容选 Stateless。第 30 章给出完整对比。

另外还有注解模块和工具回调的自动转换：spring-ai-mcp-annotations 随 Starter 自动引入，@Tool 方法、ToolCallback Bean 会被自动注册成 MCP 工具。声明式开发是 2.0 的主推姿势。

27.6 2.0 升级要点

如果你从 1.x 升级到 2.0，有几处要留意。

2.0.0 GA 要求 MCP Java SDK 2.0.0（早期里程碑曾要求 1.0.x）。BOM 会统一管理版本，一般不用手改。

mcp-spring-webflux 和 mcp-spring-webmvc 两个构件从 io.modelcontextprotocol.sdk 组迁移到了 org.springframework.ai 组。相关类也搬了家，比如 WebFluxSseServerTransportProvider 的新包名是 org.springframework.ai.mcp.server.webflux.transport。

如果你只用 Boot Starter 的自动配置，Java 代码一行不用改，只需更新 pom.xml 里的依赖坐标。

27.7 小结

MCP 是 AI 应用连接外部世界的标准化协议。Client 发起连接，Server 提供能力，Transport 负责传输。它和 @Tool 互补：本地工具用注解声明，远程工具走 MCP 发现。服务器能暴露工具、资源、提示词三类能力。下一章从客户端接入开始动手。