Spring AI框架中集成MCP的完整指南_Java

1. 引言

随着大模型应用的快速发展，让 ai 模型安全、标准化地访问外部工具和数据源，成为工程化落地的关键难题。model context protocol（mcp）正是 anthropic 提出的开放协议，旨在统一模型与外部系统之间的交互方式——无论模型是调用本地文件、数据库，还是远程 api，都可以通过同一套协议完成。

spring ai 从 1.0.0 版本开始，对 mcp 提供了原生支持。开发者可以用几乎相同的编程模型构建 mcp server（暴露工具）和 mcp client（消费工具），让 spring 生态的大模型应用快速具备「调用外部能力」的标准化能力。

本文将带你从零开始，完整走通 spring ai 集成 mcp 的全流程：理解核心概念、搭建 mcp server、配置 mcp client，最后完成一个可运行的端到端示例。

2. mcp 核心概念速览

在动手之前，先厘清 mcp 中的几个关键角色。

2.1 server 与 client

mcp server：能力的提供方。它暴露若干工具（tools）、资源（resources）或提示模板（prompts），供模型或上游应用调用。
mcp client：能力的消费方。它连接一个或多个 mcp server，发现并调用 server 暴露的能力。

在 spring ai 中，一个应用既可以作为 server 暴露工具，也可以作为 client 调用其他 server；两者甚至可以同时存在于同一个应用中。

2.2 tool 与 function calling

mcp 中最常用的场景是 tool（工具）。一个 tool 本质上就是一个「可被模型调用的函数」：

模型输出一个函数调用请求（包含函数名和参数 json）；
client 将请求转发给对应的 mcp server；
server 执行本地函数逻辑，返回结构化结果；
client 再把结果返回给模型，由模型组织最终回复。

这与 openai 的 function calling 机制高度一致，但通过 mcp，工具定义和调用被抽象为跨应用、跨语言的协议。

2.3 传输方式

spring ai mcp 支持多种传输协议：

stdio：通过标准输入输出通信，适合本地进程间调用；
sse / http：通过 http 长连接传输，适合远程服务；
webflux / webmvc：与 spring web 体系集成，适合微服务架构。

本文将以最简单的 stdio 传输方式为主线，演示完整的工具注册与调用流程。

3. 环境准备

本文示例基于以下环境：

依赖	版本
jdk	17 及以上
maven	3.8+
spring boot	3.3.5
spring ai	1.0.0 ga

在 pom.xml 中引入 bom，统一管理 spring ai 依赖版本：

<dependencymanagement>
    <dependencies>
        <dependency>
            <groupid>org.springframework.ai</groupid>
            <artifactid>spring-ai-bom</artifactid>
            <version>1.0.0</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencymanagement>

由于 spring ai 的部分依赖尚未进入 maven central，还需要在 pom.xml 中补充仓库：

<repositories>
    <repository>
        <id>spring-milestones</id>
        <name>spring milestones</name>
        <url>https://repo.spring.io/milestone</url>
        <snapshots>
            <enabled>false</enabled>
        </snapshots>
    </repository>
    <repository>
        <id>spring-snapshots</id>
        <name>spring snapshots</name>
        <url>https://repo.spring.io/snapshot</url>
        <releases>
            <enabled>false</enabled>
        </releases>
    </repository>
</repositories>

4. 服务端实践：构建 mcp server

本节创建一个独立的 spring boot 应用，作为「天气查询」mcp server。它暴露一个 getweather 工具，接收城市名，返回模拟的天气信息。

4.1 引入依赖

在 pom.xml 中引入 mcp server 相关的 starter：

<dependencies>
    <dependency>
        <groupid>org.springframework.ai</groupid>
        <artifactid>spring-ai-starter-mcp-server</artifactid>
    </dependency>
    <dependency>
        <groupid>org.springframework.boot</groupid>
        <artifactid>spring-boot-starter-web</artifactid>
    </dependency>
</dependencies>

4.2 创建工具定义

通过 @tool 注解，我们可以非常简洁地把一个普通方法暴露为 mcp tool。创建一个天气服务类：

package com.example.mcpserver;

import java.util.map;

import org.springframework.ai.tool.annotation.tool;
import org.springframework.ai.tool.annotation.toolparam;
import org.springframework.stereotype.service;

@service
public class weatherservice {

    @tool(description = "根据城市名称查询当前天气，返回温度与天气状况")
    public string getweather(
            @toolparam(description = "需要查询天气的城市名称，例如北京") string city) {

        // 模拟天气查询逻辑，实际项目中可替换为真实 api 调用
        map<string, string> mockdata = map.of(
                "北京", "晴，25°c",
                "上海", "多云，28°c",
                "深圳", "阵雨，30°c"
        );

        return mockdata.getordefault(city, "暂无该城市的天气数据");
    }
}

4.3 启用 mcp 支持

在启动类上启用 mcp server 能力，并在配置文件中关闭默认 web 路径（stdio 模式下不需要 http 端点）：

package com.example.mcpserver;

import org.springframework.boot.springapplication;
import org.springframework.boot.autoconfigure.springbootapplication;
import org.springframework.context.annotation.bean;
import org.springframework.ai.tool.toolcallbackprovider;
import org.springframework.ai.tool.methodtoolcallbackprovider;

@springbootapplication
public class mcpserverapplication {

    public static void main(string[] args) {
        springapplication.run(mcpserverapplication.class, args);
    }

    @bean
    public toolcallbackprovider weathertools(weatherservice weatherservice) {
        return methodtoolcallbackprovider.builder()
                .toolobjects(weatherservice)
                .build();
    }
}

methodtoolcallbackprovider 会扫描被 @tool 注解的方法，并自动注册为可调用的 mcp tool。

4.4 server 端配置

在 application.properties 中配置 mcp server 的基本信息、协议版本和工具开关：

spring.application.name=mcp-weather-server
# mcp server 配置
spring.ai.mcp.server.name=weather-server
spring.ai.mcp.server.version=1.0.0
spring.ai.mcp.server.type=sync
# 工具变更通知
spring.ai.mcp.server.tool-change-notification=true

这样，一个最小可用的 mcp server 就完成了。它会在启动后通过 stdio 协议等待客户端连接。

5. 客户端实践：集成 mcp client

接下来创建另一个 spring boot 应用，作为 mcp client。它连接上一节的天气 server，并把天气工具注入到一个 chat 客户端中，让大模型可以按需调用。

5.1 引入依赖

在 client 项目的 pom.xml 中引入 mcp client starter 以及模型调用相关依赖：

<dependencies>
    <dependency>
        <groupid>org.springframework.ai</groupid>
        <artifactid>spring-ai-starter-mcp-client</artifactid>
    </dependency>
    <dependency>
        <groupid>org.springframework.ai</groupid>
        <artifactid>spring-ai-openai-spring-boot-starter</artifactid>
    </dependency>
</dependencies>

这里以 openai 兼容模型为例，你也可以替换为其他支持的模型厂商。

5.2 配置 mcp server 连接

在 application.properties 中声明要连接哪些 mcp server，并配置传输参数：

spring.application.name=mcp-client-demo
# 连接一个名为 weather 的 mcp server
spring.ai.mcp.client.connections.weather.transport=stdio
spring.ai.mcp.client.connections.weather.command=java
spring.ai.mcp.client.connections.weather.args=-jar,mcp-weather-server.jar
# 模型配置（openai 兼容接口示例）
spring.ai.openai.api-key=${openai_api_key}
spring.ai.openai.base-url=${openai_base_url}
spring.ai.openai.chat.options.model=gpt-4o-mini

其中 command 和 args 指定了以 stdio 方式启动本地 mcp server 进程的命令。若连接远程 server，可改用 http 传输：

spring.ai.mcp.client.connections.remote.transport=http
spring.ai.mcp.client.connections.remote.url=http://localhost:8080/mcp

5.3 注入工具并调用模型

在客户端代码中，通过 toolcallbackprovider 拿到已连接的 mcp server 工具，并注入到 chatclient：

package com.example.mcpclient;

import org.springframework.ai.chat.client.chatclient;
import org.springframework.ai.tool.toolcallbackprovider;
import org.springframework.web.bind.annotation.getmapping;
import org.springframework.web.bind.annotation.requestparam;
import org.springframework.web.bind.annotation.restcontroller;

@restcontroller
public class chatcontroller {

    private final chatclient chatclient;

    public chatcontroller(chatclient.builder builder,
                          toolcallbackprovider toolcallbackprovider) {
        this.chatclient = builder
                .defaulttools(toolcallbackprovider.gettoolcallbacks())
                .build();
    }

    @getmapping("/chat")
    public string chat(@requestparam string message) {
        return chatclient.prompt()
                .user(message)
                .call()
                .content();
    }
}

5.4 验证调用

启动客户端应用后，可以通过 http 请求验证工具调用是否打通：

curl "http://localhost:8081/chat?message=北京今天天气怎么样？"

预期返回类似：

北京今天天气晴，气温 25°c。

此时，完整的链路是：用户提问 → 大模型识别需要调用 getweather 工具 → mcp client 将调用请求转发给 mcp server → server 执行本地逻辑并返回结果 → 大模型整合结果生成自然语言回复。

6. 全流程工作原理解析

为了加深理解，下面用一张流程图总结上述调用链：

关键点在于：

工具定义与实现解耦：server 只关心「能力」本身，client 只关心「会话编排」，协议负责两者之间的标准化通信。
模型决定调用时机：工具是否被调用、参数如何填充，完全由大模型根据上下文判断，开发者无需编写硬编码的分支逻辑。
可组合性：一个 client 可以同时连接多个 mcp server，例如天气 server、数据库 server、浏览器 server，形成一个能力丰富的智能体。

7. 进阶实践与生产注意事项

7.1 多工具与多服务端编排

当系统需要多个能力来源时，可以在配置文件中声明多个连接，并在代码中聚合它们的工具：

@configuration
public class toolconfiguration {

    @bean
    public toolcallbackprovider alltools(
            list<toolcallbackprovider> providers) {
        list<toolcallback> callbacks = providers.stream()
                .flatmap(p -> list.of(p.gettoolcallbacks()).stream())
                .tolist();
        return toolcallbackprovider.from(callbacks);
    }
}

7.2 错误处理与重试

生产环境中，远程 mcp server 可能因网络等原因暂时不可用。建议在 client 侧做以下处理：

为工具调用设置超时时间；
捕获调用异常时，向模型返回友好的错误信息，让模型能够向用户解释；
对关键工具实现幂等逻辑，避免重复调用产生副作用。

7.3 安全建议

mcp 本质上是让模型获得了「操作外部系统」的权限，因此安全边界非常重要：

最小权限原则：每个 server 只暴露必要工具，避免把危险操作（如删除数据、执行命令）无差别开放；
输入校验：即使模型生成的参数通常是合理的，也必须对入参做严格校验，防止注入或越权访问；
敏感信息隔离：api key、数据库连接串等敏感信息不要出现在工具描述或返回结果中；
审计日志：记录工具调用的入参、结果和调用方，便于问题追踪。

7.4 常见问题排查

现象	可能原因	排查方向
模型不调用工具	工具描述不清晰	优化 `@tool` 的 description，说明适用场景
连接建立失败	命令或传输配置错误	检查 stdio 的 `command`/`args`，或 http 的 `url`
工具返回空结果	参数名不匹配	确认 `@toolparam` 描述与模型传参一致
依赖解析失败	仓库未配置	确认已添加 spring milestones/snapshots 仓库

8. 总结

本文从 mcp 的核心概念出发，带你完整走通了 spring ai 集成 mcp 的实践路径：

使用 @tool 注解和 methodtoolcallbackprovider 构建 mcp server；
通过 spring.ai.mcp.client.connections 配置 mcp client；
将远程工具注入 chatclient，实现大模型驱动的工具调用；
了解了生产环境中的多工具编排、安全与排错要点。

mcp 的价值在于用统一协议连接「模型」与「世界」。结合 spring ai 的深度集成，java 开发者可以用熟悉的 spring 编程模型，快速构建出能够操作真实数据与系统的大模型应用。希望本文能成为你上手 spring ai + mcp 的实用起点。

以上就是spring ai框架中集成mcp的完整指南的详细内容，更多关于spring ai集成mcp的资料请关注代码网其它相关文章！

Spring AI框架中集成MCP的完整指南

2026年09月01日 • Java •我要评论