1. 为什么要在写业务代码前先打通 MCP 通道Spring AI 里接 MCP Client最容易翻车的不是业务逻辑而是配置阶段。我见过太多项目ChatClient 代码写得漂漂亮亮一启动就报No tool callbacks registered或者 SSE 连接超时、STDIO 子进程握手失败最后排查半天发现是application.yml里少写了一行enabledtrue或者npx路径在 Windows 上没带.cmd。这篇是「上篇」只干一件事在 Spring AI 项目里把 TaoToken 的统一 Key 和 API 通道地址写进配置文件同时声明 STDIO 和 SSE 两种传输方式的 MCP Server 连接参数然后用两组最小验证动作确认通道可用。业务代码一行不写先把地基打牢。适合谁看正在用 Spring AI 1.0.x 做 MCP Client 接入、手里已经有 MCP Server本地进程或远程端点、但还没跑通连通性的 Java 开发者。读完你能拿到可直接复制的application.yml、config.toml骨架、Maven 依赖坐标以及 STDIO 握手和 SSE 连通两组验证命令。核心检索词先摆出来Spring AI MCP Client 配置、STDIO 传输、SSE 传输、TaoToken 统一 Key、MCP Server 连通验证。这几个词贯穿全文后面每一步都围绕它们展开。2. TaoToken 前置统一 Key 与 API 通道地址怎么拿在写配置之前先把「模型侧」的通道准备好。Spring AI 的 MCP Client 本身不负责调用大模型它负责连接 MCP Server但你的 ChatClient 需要一个模型端点这里用 TaoToken 做统一入口好处是一个 Key 走通所有模型调用配置里只维护一份base-url和api-key。2.1 获取 API Key打开 TaoToken 控制台进入 API Keys 页面创建一个新 Key。建议按项目命名比如spring-ai-mcp-dev方便后面区分环境。创建后立刻复制保存页面刷新后就不再完整显示。注意Key 不要硬编码进代码仓库后面配置里用环境变量占位本地开发用.env或 IDE 的运行配置注入。2.2 确认 API 通道地址TaoToken 的 API 通道地址是https://taotoken.net/api这个地址直接写进 Spring AI 的base-url。它兼容 OpenAI 的接口规范所以 Spring AI 的spring-ai-starter-model-openai可以直接对接不需要额外写适配层。如果你用的是config.toml风格的配置比如某些 CLI 工具或 Agent 框架通道地址同样填这个Key 填上一步拿到的值。两种配置形态后面都会给骨架。2.3 为什么先配模型通道再配 MCP顺序很重要。MCP Client 启动时会先初始化模型客户端如果模型通道不通日志里会先报模型连接错误把 MCP 的问题掩盖掉。先把模型通道验证通过再叠加 MCP Server 配置排障时能快速定位是哪一层出问题。3. 可复制配置依赖坐标 application.yml config.toml这一节是全文的核心交付物。按「依赖 → 主配置 → STDIO 子配置 → SSE 子配置」的顺序给每段都能直接复制。3.1 Maven 依赖坐标父工程用spring-ai-bom统一版本子模块引入 MCP Client starter 和 OpenAI 模型 starter。dependencyManagement dependencies dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-bom/artifactId version1.0.0/version typepom/type scopeimport/scope /dependency /dependencies /dependencyManagement dependencies dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-starter-model-openai/artifactId /dependency dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-starter-mcp-client/artifactId /dependency /dependenciesspring-ai-starter-mcp-client这个坐标是关键它同时支持 STDIO 和 SSE 两种传输不需要再单独引传输层依赖。版本跟着 BOM 走别自己指定否则容易出现McpClientSession类找不到的兼容问题。3.2 application.yml 主配置把模型通道和 MCP Client 开关写在一起注意base-url指向 TaoToken 的 API 通道。server: port: 8082 spring: ai: openai: api-key: ${TAOTOKEN_API_KEY} base-url: https://taotoken.net/api chat: options: model: gpt-4o-mini mcp: client: enabled: true name: spring-ai-mcp-client version: 1.0.0 request-timeout: 30s type: SYNC sse: connections: remote-server: url: http://localhost:8085 sse-endpoint: /sse stdio: servers-configuration: classpath:mcp-servers-config.json logging: level: org.springframework.ai.model.tool: DEBUG io.modelcontextprotocol: DEBUG逐项说明几个容易写错的点enabled: true必须显式写Spring AI 1.0.0 里 MCP Client 默认不启用漏了这行启动日志里连 MCP 相关 bean 都不会出现。type: SYNC表示同步客户端适合先做连通性验证后面要流式再换ASYNC。sse.connections下面每个 key 是连接名remote-server这个名字会出现在工具名前缀里比如spring_ai_mcp_client_remote-server_xxx命名时别用中文和特殊字符。stdio.servers-configuration指向 classpath 下的 JSON 文件这个文件定义要拉起哪些本地 MCP 进程。3.3 STDIO 子配置 mcp-servers-config.json放在src/main/resources下文件名和上面servers-configuration的值对应。{ mcpServers: { filesystem: { command: npx, args: [ -y, modelcontextprotocol/server-filesystem, /Users/yourname/mcp-workspace ] }, echo-demo: { command: node, args: [ ./mcp-servers/echo-server.js ], env: { DEMO_TOKEN: ${TAOTOKEN_API_KEY} } } } }Windows 用户注意command要写npx.cmd的完整路径比如D:\\Program Files\\nodejs\\npx.cmd直接写npx会报CreateProcess error2。macOS/Linux 写npx即可前提是which npx能找到。args里-y表示自动确认安装第一次运行会下载 npm 包网络慢的话启动日志会卡在Initializing STDIO client十几秒属正常。3.4 config.toml 骨架CLI/Agent 场景如果你除了 Spring Boot 项目还在用支持config.toml的 CLI 工具做联调可以复用同一份 Key 和通道地址。[model] provider openai-compatible base_url https://taotoken.net/api api_key ${TAOTOKEN_API_KEY} model gpt-4o-mini [mcp.servers.filesystem] transport stdio command npx args [-y, modelcontextprotocol/server-filesystem, /Users/yourname/mcp-workspace] [mcp.servers.remote-server] transport sse url http://localhost:8085/sse两种配置形态的字段名不同但语义一致base_url对应base-urltransport对应sse/stdio分支。联调时保持 Key 和地址一致避免「Spring 里通了、CLI 里不通」的错觉。4. 验证请求STDIO 握手 SSE 连通两组动作配置写完不算完必须跑两组验证。一组验证本地 STDIO 子进程能拉起并完成握手一组验证远程 SSE 端点能建立连接并列出工具。4.1 STDIO 本地进程握手验证先单独验证 STDIO不掺 SSE。把application.yml里的sse.connections整段注释掉只留stdio启动应用。观察启动日志成功的标志是出现类似这样的行INFO o.s.a.m.c.s.StdioMcpClientTransport : Initializing STDIO client for server: filesystem INFO i.m.spec.McpClientSession : Sending initialize request INFO i.m.spec.McpClientSession : Received initialize response from filesystem INFO o.s.a.m.c.McpClientAutoConfiguration : Registered tool callbacks: [read_file, write_file, list_directory]关键检查点有三个Initializing STDIO client说明进程拉起命令执行了Received initialize response说明 JSON-RPC 握手成功Registered tool callbacks说明工具列表已经注册进 Spring 容器。如果卡在Initializing不动八成是command路径不对或 npm 包下载超时。手动在终端跑一遍npx -y modelcontextprotocol/server-filesystem /tmp能起来说明配置问题起不来说明环境问题。4.2 SSE 远程端点连通验证恢复sse.connections配置确保远程 MCP Server 已经在localhost:8085监听。启动应用后日志里应该出现INFO o.s.a.m.c.s.HttpClientSseClientTransport : Connecting to SSE endpoint: http://localhost:8085/sse INFO i.m.spec.McpClientSession : SSE connection established INFO o.s.a.m.c.McpClientAutoConfiguration : Registered tool callbacks: [getBookCategories, queryBook]SSE connection established是连通的核心标志。如果这里报Connection refused先确认远程服务端口如果报404检查sse-endpoint路径是否和 Server 端暴露的一致有些实现是/sse有些是/mcp/sse。4.3 用一次最小请求确认工具可调用两组通道都通后写一个最简单的 Controller 触发一次工具调用确认端到端链路。RestController public class PingController { private final ChatClient chatClient; public PingController(ChatClient.Builder builder, ToolCallbackProvider toolCallbackProvider) { this.chatClient builder .defaultToolCallbacks(toolCallbackProvider) .build(); } GetMapping(/ping-mcp) public String ping(RequestParam String q) { return chatClient.prompt().user(q).call().content(); } }请求GET /ping-mcp?q列出当前可用的文件如果日志里出现Executing tool call: spring_ai_mcp_client_filesystem_list_directory并且返回内容里包含目录列表说明 STDIO 链路完整。换成q查询图书分类日志出现spring_ai_mcp_client_remote-server_getBookCategories说明 SSE 链路完整。5. 本篇常见错排查配置阶段的报错集中在四类按出现频率排。第一类No tool callbacks registered。九成是spring.ai.mcp.client.enabled没写或写成false。检查application.yml缩进enabled必须在client下面不能和client平级。第二类CreateProcess error2, 系统找不到指定的文件。Windows 下command写npx而不是npx.cmd的完整路径。用where npx确认路径注意 JSON 里反斜杠要转义成\\。第三类SSE 连接超时但端口能 telnet 通。检查sse-endpoint路径。有些 MCP Server 实现把 SSE 挂在/sse有些挂在根路径用curl -N http://localhost:8085/sse看是否持续输出事件流能输出说明路径对。第四类工具名冲突。两个 MCP Server 暴露了同名工具Spring AI 注册时会覆盖。日志里搜Duplicate tool name给连接名加前缀区分比如fs-server和db-server。提示排障时把logging.level.io.modelcontextprotocol设为TRACE能看到完整的 JSON-RPC 请求和响应报文比DEBUG多出消息体内容定位协议层问题非常快。6. 通道打通后下一步往哪走上篇到这里结束你手里应该有两样东西一份能启动的application.ymlmcp-servers-config.json以及两组验证通过的日志证据。下篇会在这个基础上写 ChatClient 的工具回调、多轮上下文和流式响应。在进入下篇之前建议先把 Key 和通道地址固化到环境变量里别留在配置文件明文。如果你还没创建 Key去 TaoToken 控制台的 API Keys 页面建一个顺手把接入文档过一遍里面有针对 Spring AI 的base-url填写说明。想先验证模型通道本身是否通可以用模型对话页面发一条消息试试确认 Key 有效再回来跑 MCP 配置能省掉一轮「到底是 Key 错还是 MCP 错」的纠结。长期要做编码类 Agent 的话Coding Plan 那条线也值得提前看一眼后面 MCP 工具链和模型调用会共用同一套通道配置早点统一省得来回改。
