大模型开发 - SpringAI之MCP Client开发：让Agent动态调用远程工具服务

1. 从一次“工具找不到”的报错说起如果你正在用 SpringAI 写 Agent大概率遇到过这种场景本地Tool方法写得挺顺可一旦想把工具能力拆到另一个进程、让多个 Agent 共享代码就开始重复版本还对不齐。我试过把天气查询、配置读取、搜索这些能力分别塞进不同 Agent结果每加一个工具就要改三处代码维护成本直线上升。MCPModel Context Protocol解决的正是这个问题。它把工具从 Agent 进程里“搬出去”变成独立的远程服务Agent 通过标准协议动态发现并调用。SpringAI 从 1.1.0 开始原生支持 MCP Client你只需要几行配置就能让 Agent 拿到远程 Server 暴露的全部工具像调用本地方法一样自然。这篇面向 Java 大模型开发者聚焦 SpringAI 中 MCP Client 的配置骨架与远程工具服务接入流程。我会给出可复制的 MCP Client 配置片段含 TaoToken 统一 Key/API 通道接入点并带你跑通一次完整的远程工具调用链路。适合已经写过基础 Tool Calling、想往多 Agent / 微服务方向走的同学。读完后你能独立搭起 Client-Server 两端并知道报错时先查哪里。2. 前置准备TaoToken 统一 Key 与依赖骨架在动手写 MCP 之前先把模型通道和依赖理清楚。MCP Client 本身只负责“发现和调用远程工具”真正和大模型对话的那一步仍然需要一个模型服务。这里我用 TaoToken 作为统一入口一个 Key 就能覆盖对话模型和后续的 coding 场景省得在多个平台之间来回切换。TaoToken 的定位是统一的大模型 API 通道官网在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 入口是 https://taotoken.net/api 。你需要在控制台创建一个 API Key后面会写进 SpringAI 的配置里。创建入口在 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite Key 管理页在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。依赖方面MCP Client 和模型 starter 要一起引入。下面是我实际用的pom.xml片段SpringAI 版本用 1.1.0 及以上dependencies !-- 模型对话能力走 TaoToken 统一通道 -- dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-starter-model-openai/artifactId /dependency !-- MCP Client动态发现并调用远程工具 -- dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-starter-mcp-client/artifactId /dependency /dependencies这里有个容易踩的点spring-ai-starter-mcp-client默认带的是 stdio 传输如果你要连 HTTP 方式的远程 Server需要确认版本里包含 streamable-http 连接器。1.1.0 之后是内置的不用额外加包。依赖拉不下来时先检查仓库镜像和版本号别急着怀疑代码。3. 可复制配置Client 端 application.yml 全量骨架配置是 MCP Client 的核心写对了基本就成功一半。下面这份application.yml是我调通后的完整骨架模型部分指向 TaoTokenMCP 部分连一个本地 8082 的远程工具服务server: port: 8081 spring: ai: openai: # TaoToken 统一 API 通道 base-url: https://taotoken.net/api api-key: ${TAOTOKEN_API_KEY} chat: options: model: gpt-4o-mini mcp: client: name: spring-ai-mcp-client-demo # 使用 HTTP 方式连接远程 MCP Server streamable-http: connections: weather-server: url: http://localhost:8082 timeout: 10s几个参数值得单独说清楚。name是当前应用在 MCP 协议里的标识Server 端日志会打印它方便排查是谁连上来了。connections下面可以挂多个 Server每个 key 是连接名url指向 Server 的 HTTP 入口。timeout建议显式设置默认值偏长Server 挂掉时会让请求卡很久。多 Server 的场景直接并列写就行Client 启动时会逐个发现工具spring: ai: mcp: client: streamable-http: connections: weather-server: url: http://localhost:8082 config-server: url: http://localhost:8083 search-server: url: http://localhost:8084API Key 不要硬编码在 yml 里用环境变量TAOTOKEN_API_KEY注入。启动前在终端export TAOTOKEN_API_KEY你的Key或者用 IDE 的运行配置填。这一步做不好后面报 401 会浪费你半小时。4. Server 端用注解暴露远程工具远程工具服务这一端SpringAI 用注解把普通 Bean 的方法暴露成 MCP 能力。核心就三个注解McpTool是可执行函数McpResource是只读数据McpPrompt是预设提示模板。先看工具部分Service public class WeatherService { McpTool(description 获取指定城市的天气) public String getWeather(String cityName) { if (上海.equals(cityName)) { return 天晴; } else if (北京.equals(cityName)) { return 下雨; } return 未知城市; } }McpTool的description会直接进入工具 schema大模型靠它判断什么时候调用。参数名cityName会被自动映射成 JSON Schema 的properties类型是 string并且是必填。你不需要手写 schemaSpringAI 会扫描方法签名生成。资源类能力适合共享配置McpResource(uri config://{key}, name configuration) public String getConfig(String key) { return environment.getProperty(key, default); }URI 模板里的{key}是参数占位Client 读取config://spring.datasource.url时会把key解析成spring.datasource.url。提示词模板则用McpPrompt适合放系统级的欢迎语或固定指令。Server 端的application.yml要声明协议和端口server: port: 8082 spring: ai: mcp: server: name: weather-mcp-server protocol: streamableprotocol: streamable表示走 HTTP 流式传输和 Client 端的streamable-http对应。启动类不需要任何额外配置SpringAI 会自动扫描注解并注册SpringBootApplication public class McpServerApplication { public static void main(String[] args) { SpringApplication.run(McpServerApplication.class, args); } }5. 验证请求跑通一次完整远程调用两端都起来后写一个 Controller 作为调用入口。关键是把ToolCallbackProvider注入进来它会在启动时自动从远程 Server 拉取工具列表RestController public class McpController { private final ChatClient chatClient; private final ToolCallbackProvider toolCallbackProvider; public McpController(ChatClient.Builder builder, ToolCallbackProvider toolCallbackProvider) { this.chatClient builder.build(); this.toolCallbackProvider toolCallbackProvider; } GetMapping(/mcp) public String mcp(String message) { return chatClient.prompt() .user(message) .toolCallbacks(toolCallbackProvider.getToolCallbacks()) .call() .content(); } }启动顺序很重要先起 Server8082再起 Client8081。Client 启动日志里应该能看到类似Connected to MCP Server和工具列表被加载的记录。如果没看到说明连接没建立先别急着发请求。验证命令curl http://localhost:8081/mcp?message上海天气怎样预期返回类似“根据天气工具反馈上海天晴”。这条链路背后发生了这些事Client 把用户问题和远程工具列表一起提交给模型模型决定调用getWeatherToolCallbackProvider通过 HTTP 把tools/call请求发到 8082Server 执行后返回“天晴”模型再据此生成自然语言回复。想单独验证模型通道是否正常可以先用模型对话页发一条消息https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite 。如果那边通、这边不通问题就锁定在 MCP 配置上。接入细节和参数说明可以对照文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。6. 本篇常见错排查Tool not found最常见。先curl http://localhost:8082/health确认 Server 活着再看 Client 启动日志里工具列表是否加载成功。如果列表为空多半是 Server 端注解没被扫描到检查启动类包路径是否覆盖了WeatherService。还有一种情况是工具名大小写不一致模型请求的名字和 Server 定义必须完全匹配。连接超时 / 请求卡住Client 的timeout没设或设太长Server 无响应时请求会一直挂着。把timeout调到 10s 以内并给 Server 加健康检查。生产环境建议配重试但重试次数别超过 3 次否则会放大延迟。401 / 模型调用失败MCP 链路本身没问题是模型通道的 Key 不对。检查TAOTOKEN_API_KEY环境变量是否真的注入到了进程里base-url是否写成了https://taotoken.net/api。注意 API 入口不带路径后缀写错成/v1之类会 404。工具调用结果为空Server 方法返回了 null或者异常被吞掉了。在McpTool方法里加 try-catch把错误信息作为字符串返回模型能收到并据此调整。直接抛异常的话Client 侧可能只看到超时。多 Server 时部分工具缺失某个 Server 没起来Client 不会崩溃但那个 Server 的工具不会出现在列表里。逐个curl各 Server 的健康端点确认都在线。日志里会有连接失败的 warn别忽略。7. 下一步从单次调用到长期编码跑通一次远程工具调用只是起点。如果你打算把 MCP 用在日常编码或 Agent 长任务里建议把模型通道固定下来避免每次换环境都重新配 Key。TaoToken 的 Coding Plan 适合这种长期场景https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 。Claude Code 相关的接入方式在 https://taotoken.net/claude-code-anthropic?utm_sourcetaotoken_aicg_blog_endutm_contentclaudecodeutm_campaignrewrite 需要的话可以对照配置。回到 MCP 本身接下来值得做的两件事一是把工具服务容器化用 Docker Compose 把 Server 和 Client 编排起来验证跨容器调用二是给ToolCallbackProvider加缓存避免每次请求都重新拉工具列表。这两步做完你的 Agent 就从“能跑”进入“能扛”的阶段了。