Spring-AI-Alibaba 初体验：用 Streamable-http 接入 MCP Server 的配置骨架

1. 为什么我要在 Spring Boot 里接一个 Streamable-http 的 MCP Server如果你最近在折腾 Spring Boot 和 AI 结合的项目大概率会碰到一个词MCP Server。MCP 全称 Model Context Protocol是 Anthropic 提出的一套让模型和外部工具对话的协议。你可以把它理解成「给大模型装了一双手」——模型本身只会生成文字但通过 MCP它可以去执行 shell 命令、截网页图、查数据库、调内部接口。而 Streamable-http 是 MCP 的一种传输方式相比 stdio 只能本地进程通信、SSE 长连接容易断Streamable-http 更适合部署在远端服务器上用普通的 HTTP 请求就能调用天然适配云环境和容器。Spring-AI-Alibaba 是阿里开源的一套 Spring 生态 AI 集成框架它把 OpenAiClient、ChatClient、MCP 客户端这些能力都封装成了 Spring 的 Bean用注解和 yml 就能配起来。这篇要解决的问题很具体一个 Spring Boot 项目怎么通过 Spring-AI-Alibaba 的 OpenAiClient 去调用一个跑在远端的 Streamable-http 协议 MCP Server把依赖、application.yml、MCP 客户端配置骨架搭起来最后跑通一次本地调用验证。适合已经会写 Spring Boot、但对 MCP 接入还没跑通链路的同学。我会把每一步的配置和踩坑点都写清楚你照着改改就能用。2. 前置准备TaoToken 的 Key 和 MCP Server 地址在写代码之前有两样东西要先拿到手一个是模型调用的凭证一个是 MCP Server 的访问地址。模型这块我用的是 TaoToken 提供的 OpenAI 兼容接口。它的好处是接口格式和 OpenAI 一致Spring-AI-Alibaba 里的 OpenAiClient 可以直接对接不用改底层协议。你需要先去控制台创建一个 API Key这个 Key 后面会填到 application.yml 里。具体操作路径是打开 https://taotoken.net/api-keys 登录后新建一个 Key复制出来保存好。注意 Key 只在创建时完整显示一次关掉页面就看不到了建议先贴到本地临时文件里。MCP Server 这边我假设你已经有一个用 FastMCP 写好的服务以 Streamable-http 方式启动监听在某个端口上比如http://your-host:8000/mcp。如果你还没有可以先用 Python 起一个最小服务核心就是mcp.run(transportstreamable-http)这一行FastMCP 会自动暴露一个/mcp的端点。这个端点就是我们 Spring Boot 要连的目标。注意MCP Server 的地址一定要带上协议和端口Streamable-http 模式下路径通常是/mcp不要写成/sse那是另一种传输方式。3. 依赖引入与 application.yml 配置骨架先看 pom.xml。Spring-AI-Alibaba 的 MCP 支持依赖 spring-ai-alibaba-core 和 spring-ai-alibaba-mcp 两个包版本我用的 1.0.0.1。同时要引入 OpenAI 的自动配置和 chat-client 自动配置因为 OpenAiClient 的 Bean 是由它们提供的。dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-autoconfigure-model-openai/artifactId /dependency dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-autoconfigure-model-chat-client/artifactId /dependency dependency groupIdcom.alibaba.cloud.ai/groupId artifactIdspring-ai-alibaba-core/artifactId version1.0.0.1/version /dependency dependency groupIdcom.alibaba.cloud.ai/groupId artifactIdspring-ai-alibaba-mcp/artifactId version1.0.0.1/version /dependency依赖拉下来之后配 application.yml。这里分两块一块是 OpenAI 兼容的模型配置指向 TaoToken 的接口另一块是 MCP 客户端的配置声明要连的 Server 地址和传输方式。spring: ai: openai: api-key: ${TAOTOKEN_API_KEY} base-url: https://taotoken.net/api chat: options: model: gpt-4o-mini temperature: 0.7 mcp: client: enabled: true name: spring-ai-alibaba-mcp-client version: 1.0.0 type: SYNC request-timeout: 30s streamable-http: connections: host-info-server: url: http://your-host:8000/mcp endpoint: /mcp几个参数说明一下。type: SYNC表示用同步客户端 McpSyncClient适合大多数请求-响应式的工具调用如果你要处理流式返回可以改成 ASYNC。request-timeout建议设 30 秒以上因为有些工具比如网页截图、执行命令会比较慢超时太短会直接报错。connections下面可以配多个 Server每个给个名字后面注入的时候按名字区分。提示api-key 不要硬编码在 yml 里用环境变量${TAOTOKEN_API_KEY}注入本地跑的时候在 IDE 的运行配置里加上就行。4. MCP 客户端与 OpenAiClient 的配置骨架yml 配好之后Spring 会自动创建 MCP 客户端的 Bean。但为了在业务代码里方便注入和调用我习惯再写一个配置类把 McpSyncClient 显式暴露出来顺便把工具回调也注册进去。Configuration public class McpClientConfig { Bean public McpSyncClient mcpSyncClient(McpClientProperties properties) { return new McpSyncClient(properties); } Bean public OpenAiClient openAiClient(OpenAiApi openAiApi) { return new OpenAiClient(openAiApi); } }这里有个点要注意McpSyncClient 的构造依赖 McpClientProperties这个 Properties 是 spring-ai-alibaba-mcp 根据 yml 自动装配的你不需要自己 new直接方法参数注入即可。OpenAiClient 同理OpenAiApi 也是自动配置好的base-url 和 api-key 都从 yml 读。接下来是调用工具的服务类。MCP 的工具调用本质上是发一个 ToolExecutionRequest里面带上工具名和参数然后拿回 ToolExecutionResponse。Service public class McpCallerService { private final McpSyncClient mcpSyncClient; public McpCallerService(McpSyncClient mcpSyncClient) { this.mcpSyncClient mcpSyncClient; } public String callTool(String toolName, MapString, Object args) { ToolExecutionRequest request ToolExecutionRequest.builder() .toolName(toolName) .arguments(args) .build(); ToolExecutionResponse response mcpSyncClient.call(request); return response.getResult().toString(); } }参数用 Map 传比较灵活因为不同工具的参数结构不一样。比如run_cmd只要一个command字段webpage_capture只要一个url字段。如果你想要类型安全可以给每个工具定义一个 POJO用Data加字段然后 arguments 传对象效果一样。最后加一个 Controller 方便用 curl 验证RestController RequestMapping(/mcp) public class McpController { private final McpCallerService callerService; public McpController(McpCallerService callerService) { this.callerService callerService; } PostMapping(/call) public ResponseEntityString callMcpTool(RequestBody MapString, Object payload) { String toolName (String) payload.get(tool); MapString, Object args (MapString, Object) payload.get(args); String result callerService.callTool(toolName, args); return ResponseEntity.ok(result); } }5. 一次可复现的本地调用验证配置写完启动 Spring Boot 应用。控制台如果看到 MCP 客户端初始化成功的日志说明连接建立没问题。然后开一个终端用 curl 发一个请求调用 MCP Server 上的system_info工具。curl -X POST http://localhost:8080/mcp/call \ -H Content-Type: application/json \ -d { tool: system_info, args: {} }如果链路通了你会看到返回一段 JSON里面包含 system、node、release、machine 这些字段就是 MCP Server 所在机器的系统信息。这一步能跑通说明 Spring Boot 到 MCP Server 的 Streamable-http 通道是活的。再试一个带参数的工具比如run_cmdcurl -X POST http://localhost:8080/mcp/call \ -H Content-Type: application/json \ -d { tool: run_cmd, args: {command: ls -lrt . | wc -l} }返回的应该是当前目录下的文件数量。如果返回的是Error: ...那多半是 MCP Server 那边的命令执行环境有问题不是 Spring 这边的事去 Server 日志里看具体报错。我实测下来第一次跑最容易卡在连接建立阶段。如果启动时报Connection refused先确认 MCP Server 是不是真的在跑用curl http://your-host:8000/mcp直接访问一下正常应该返回一个 405 或者协议相关的响应而不是连不上。6. 本篇常见错误排查报错一No qualifying bean of type McpSyncClient这个通常是 yml 里spring.ai.mcp.client.enabled没设成 true或者依赖没拉全。检查 pom 里 spring-ai-alibaba-mcp 的版本和 core 是否一致版本不一致会导致自动配置类加载失败。报错二Tool not found: xxx工具名写错了。MCP Server 上注册的工具名要和请求里的toolName完全一致大小写敏感。你可以在 MCP Server 启动日志里看到它注册了哪些工具或者用 MCP 的 list tools 接口查一下。报错三请求超时Read timed out把request-timeout调大比如 60s。另外确认 MCP Server 那边的工具执行是不是真的卡住了比如webpage_capture依赖 puppeteer如果浏览器没装好会一直挂起。报错四401 Unauthorized或模型调用失败这是 TaoToken 的 Key 没配对。检查环境变量TAOTOKEN_API_KEY是否生效base-url 是不是https://taotoken.net/api。如果 Key 没问题但还是 401去 https://taotoken.net/api-keys 确认 Key 的状态是不是启用中。报错五Streamable-http 返回 404路径写错了。Streamable-http 的端点是/mcp不是/sse也不是根路径。在 yml 里url和endpoint两个字段都要对有的版本只需要 url 带全路径有的需要分开写按你用的版本调整。如果你在接入过程中想先验证模型本身能不能通可以打开 https://taotoken.net/model-chat 直接对话测试确认 Key 和模型没问题之后再回来排查 MCP 链路。长期做编码和 Agent 类项目的同学可以看看 https://taotoken.net/coding-plan 里面有更完整的工程化配置参考。接入文档在 https://taotoken.net/doc MCP 相关的参数说明都在里面。