【MCP】用 SpringBoot + Streamable-HTTP 搭一个 MCP-Server:TaoToken 统一 Key 接入配置骨架
发布时间:2026/11/16 9:59:22来源:尧图网络
1. 为什么我要把 MCP-Server 从 SSE 迁到 Streamable-HTTPMCP 全称 Model Context Protocol简单说就是让大模型能调用你本地或远端工具的一套标准协议。你可以把它理解成「AI 世界的 USB 接口」模型是主机你的 SpringBoot 服务是外设插上就能用。适合谁适合手里已经有一堆内部接口、想让 Claude Code、Cursor 这类客户端直接调用的后端同学。我最早用 SSE 版本跑通了一个 MCP-Server本地测试没问题一放到内网网关后面就开始抽风长连接被中间设备掐断、断线后 session 恢复不了、并发一上来线程池直接打满。后来翻 MCP 的 PR #206 才发现官方推了 Streamable-HTTP 传输层核心变化是把「一条长连接」拆成「普通 POST 可选流式响应」请求之间靠Mcp-Session-Id关联状态。这意味着它既能走标准 HTTP 语义又保留了流式推送能力对网关和负载均衡友好得多。这篇就按我实际落地的顺序来先给可复制的 pom 依赖再写工具类和自动配置然后配application.yml打开 Streamable 协议最后用 curl 把 initialize、tools/list、tools/call 三个动作跑一遍。同时我会把自建 MCP-Server 接入 TaoToken 统一 Key 通道的配置骨架一起给出这样你本地跑通之后客户端侧不用再为每个服务单独配 Key。2. TaoToken 前置统一 Key 与通道准备在动手写代码之前先把「通道」这件事说清楚。自建 MCP-Server 本身只负责暴露工具真正去调模型、跑 Agent 的是客户端比如 Claude Code、Cline、各种 IDE 插件。如果每个客户端、每个服务都单独配一套 Key 和地址维护成本会爆炸。TaoToken 在这里扮演的是统一入口一个 Key 走通模型对话、编码 Agent、API 调用几条线客户端侧只需要改一个 base 地址。你需要提前准备的东西不多第一一个可用的 API Key。登录官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 进控制台 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 创建然后在 API Keys 页面 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 复制出来。这个 Key 后面会写进客户端的settings.json或config.toml。第二确认你的调用地址。API 基址是 https://taotoken.net/api 注意这个地址不带任何查询参数直接作为 base_url 用。模型对话入口在 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 排障的时候这两个页面比搜索引擎好使。第三想清楚你的 MCP-Server 是本地跑还是部署到内网。本地跑的话客户端直接连http://localhost:9090/mcp部署到内网就要保证客户端能访问到那个地址同时把 TaoToken 的 Key 配在客户端侧而不是服务端侧——服务端只暴露工具不持有模型凭证这样权限边界更干净。注意MCP-Server 本身不需要 TaoToken 的 Key 就能启动和自测Key 是给「调用方」用的。别把 Key 硬编码进服务端代码里这是很多人第一次接会踩的坑。3. 可复制配置pom、工具类、自动配置与 application.yml3.1 pom 核心依赖我用的版本组合是 Spring Boot 4.0.1 spring-ai-bom 2.0.0-M1。先导入 BOM再引 starter。这里有个关键选择spring-ai-starter-mcp-server-webflux和spring-ai-starter-mcp-server-webmvc二选一前者是响应式后者是阻塞式。因为 Streamable-HTTP 的流式响应在响应式栈下更自然我选 webflux。dependencyManagement dependencies dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-bom/artifactId version${spring-ai.version}/version typepom/type scopeimport/scope /dependency /dependencies /dependencyManagement dependencies dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-starter-mcp-server-webflux/artifactId /dependency /dependencies如果你团队更熟悉 Servlet 栈把上面那个 starter 换成spring-ai-starter-mcp-server-webmvc也能跑但工具方法返回值类型要跟着spring.ai.mcp.server.type的配置走这点后面会讲。3.2 MCP 工具类工具类就是普通 POJO方法上打McpTool注解参数上打McpToolParam描述。我写了两个方法一个查天气一个算八字纯粹为了演示多工具注册。package com.wen3.demo.ai.mcp.server.tools; import lombok.extern.slf4j.Slf4j; import org.springaicommunity.mcp.annotation.McpTool; import org.springaicommunity.mcp.annotation.McpToolParam; import reactor.core.publisher.Mono; import java.util.Map; Slf4j public class DemoTool { McpTool(name hello, description 根据城市名称获取天气预报) public MonoString hello( McpToolParam(description 城市名称比如广州) String city) { log.info(city: {}, city); MapString, String mockData Map.of( 西安, 晴天, 北京, 小雨, 上海, 大雨 ); return Mono.just(mockData.getOrDefault(city, 抱歉未查询到对应城市)); } McpTool(description 根据名字算八字) public MonoString helloWithName( McpToolParam(description 姓名) String name) { log.info(name: {}, name); return Mono.just(五行缺火!); } }注意返回值是MonoString这是配合type: ASYNC用的。如果你配成SYNC返回值就得是String、Integer这类普通类型或者CallToolResult这种 MCP 原生类型。3.3 自动配置类用Configuration把工具类注册成 Bean加ConditionalOnMissingBean是为了让使用方可以覆盖。package com.wen3.demo.ai.mcp.server.autoconfigure; import com.wen3.demo.ai.mcp.server.tools.DemoTool; import org.springframework.boot.autoconfigure.condition.ConditionalOnMissingBean; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; Configuration class McpServerAutoConfiguration { ConditionalOnMissingBean Bean DemoTool demoTool() { return new DemoTool(); } }这里有个容易踩的坑spring.ai.mcp.server.annotation-scanner.enabled默认就是true框架会自动扫描McpTool并注册。如果你再手动写一个ToolCallbackProvider去注册工具会被注册两次tools/list里出现重复项。我一开始就多写了一段后来注释掉才干净。3.4 application.yml 骨架server: port: 9090 spring: ai: mcp: server: name: demo-mcp-server version: 1.0.0 type: ASYNC protocol: STREAMABLE streamable-http: mcp-endpoint: /mcp keep-alive-interval: 30s必须配的一项就是spring.ai.mcp.server.protocolSTREAMABLE不配它默认还是走 SSE端点行为完全不一样。type: ASYNC对应响应式返回值mcp-endpoint默认就是/mcp写出来是为了后面 curl 时心里有数。keep-alive-interval是流式连接的心跳间隔内网网关如果 60 秒断空闲连接这个值设 30s 比较稳。配置项对应的类分别是McpServerProperties前缀spring.ai.mcp.server、McpServerAnnotationScannerProperties前缀spring.ai.mcp.server.annotation-scanner、McpServerStreamableHttpProperties前缀spring.ai.mcp.server.streamable-http出问题的时候直接翻这三个类最快。4. 验证请求curl 跑通 initialize / tools/list / tools/call服务起来之后别急着接客户端先用 curl 把协议动作走一遍确认服务端行为正确。4.1 initialize 拿 Session-IdStreamable-HTTP 的第一个请求必须是 initialize而且Accept头要同时包含application/json和text/event-stream少一个都会被WebFluxStreamableServerTransportProvider#handlePost拦下来。curl -ik -H Accept: application/json \ -H Accept: text/event-stream \ -XPOST --url http://localhost:9090/mcp \ -d {id:stream-1,method:initialize,params:{capabilities:{},clientInfo:{},protocolVersion:}}响应里重点看两处响应头里的Mcp-Session-Id以及 body 里的protocolVersion。我实测拿到的 session id 形如d6d67425-2d58-4758-9bbd-9b2c7521e033协议版本返回2025-06-18。这个 session id 后面每个请求都要带上。HTTP/1.1 200 OK Content-Type: application/json Mcp-Session-Id: d6d67425-2d58-4758-9bbd-9b2c7521e033 {jsonrpc:2.0,id:stream-1,result:{protocolVersion:2025-06-18,capabilities:{tools:{listChanged:true}},serverInfo:{name:demo-mcp-server,version:1.0.0}}}4.2 tools/list 看工具注册带上 session id 发 tools/list响应是text/event-stream数据在data:行里。curl -ik -H Mcp-Session-Id: d6d67425-2d58-4758-9bbd-9b2c7521e033 \ -H Accept: application/json \ -H Accept: text/event-stream \ -XPOST --url http://localhost:9090/mcp \ -d {id:stream-1,method:tools/list,params:{}}正常应该看到hello和helloWithName两个工具每个都带inputSchema。如果这里出现重复工具回去检查是不是手动注册了ToolCallbackProvider。4.3 tools/call 实际调用调用hello工具参数传北京curl -ik -H Mcp-Session-Id: d6d67425-2d58-4758-9bbd-9b2c7521e033 \ -H Content-Type: application/json;charsetGBK \ -H Accept: application/json \ -H Accept: text/event-stream \ -XPOST --url http://localhost:9090/mcp \ -d {id:stream-1,method:tools/call,params:{name:hello,arguments:{city:北京}}}返回的data里content[0].text应该是「小雨」。这里Content-Type带charsetGBK是因为我测试环境终端编码是 GBK参数里有中文时不加会乱码你如果是 UTF-8 环境去掉 charset 或者改成 UTF-8 都行。4.4 客户端侧接入 TaoToken 统一 Key服务端跑通后客户端配置才是真正让它「能用」的一步。以 Claude Code 这类支持 MCP 的客户端为例settings.json里大致是这样{ mcpServers: { demo-mcp-server: { url: http://localhost:9090/mcp, transport: streamable-http } }, env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: 你的TaoToken Key } }如果你用的是走config.toml的客户端等价写法是[mcp_servers.demo-mcp-server] url http://localhost:9090/mcp transport streamable-http [env] ANTHROPIC_BASE_URL https://taotoken.net/api ANTHROPIC_API_KEY 你的TaoToken Key这样客户端调模型走 TaoToken 统一通道调工具走你自建的 MCP-Server两边解耦。长期跑编码 Agent 的话用 Coding Plan 更划算入口在 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 只是想先验证模型通不通用模型对话页面 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 更快。5. 本篇常见错排查报 406 或请求直接被打回。九成是Accept头没同时带application/json和text/event-stream。Streamable 的 POST 处理逻辑对这两个头是硬校验缺一个就不往下走。initialize 返回里protocolVersion是 null。检查请求体里protocolVersion字段有没有传。这个字段不能是 null但可以是空字符串框架会自己协商。tools/list 里工具重复。前面提过annotation-scanner默认开启别再手动注册ToolCallbackProvider。工具调用返回类型报错。看spring.ai.mcp.server.type配ASYNC就必须返回MonoT、FluxT、PublisherT配SYNC就返回普通类型或 MCP 原生类型。两者混用会直接抛异常。中文参数乱码。请求头Content-Type的 charset 要和实际编码一致。GBK 终端传中文就写charsetGBKUTF-8 环境写charsetUTF-8或不写。客户端连不上本地服务。确认客户端和服务端在同一网络命名空间容器里跑的话localhost指向容器自身要用宿主 IP 或服务名。流式连接一段时间后断。调小keep-alive-interval或者检查中间网关的空闲超时设置两者对齐。6. 接入通道与后续动作把上面几步串起来你手上就有了一个能跑 Streamable-HTTP 的 SpringBoot MCP-Server以及一套客户端侧的统一 Key 配置骨架。接下来按你的目标分流如果你卡在接入或排障阶段先去 API Keys 页面 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 确认 Key 状态再对照接入文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 检查 base 地址和请求头这两个地方覆盖了大部分连接类问题。如果你只是想验证模型通道是否正常直接用模型对话 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 发一条消息比写代码快。如果你是要长期跑编码 Agent、把 MCP-Server 挂到日常开发流里Coding Plan https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 的额度模型更适合持续调用配合 Claude Code 的接入方式在文档里有专门章节。最后留一个我踩过的坑MCP-Server 的 session 是有状态的重启服务后旧 session id 全部失效客户端如果缓存了 session 会报错。生产环境要么做 session 持久化要么让客户端在失败后重新 initialize别指望它自己恢复。
网站建设高端定制企业官网