1. 为什么 MCP Server 鉴权要放在过滤器层SpringAI 进入 GA 之后MCP Server 的接入方式基本稳定下来了spring-ai-starter-mcp-server-webflux一引application.yml里把sse-message-endpoint、capabilities配好工具类上打Tool注解一个能对外提供时间查询、文件读取、数据库查询的 MCP Server 就跑起来了。问题也随之而来——工具一多鉴权逻辑就开始散。我见过最常见的写法是每个Tool方法开头先来一段if (token null) return unauthorized或者干脆在 Service 层塞一个checkAuth()。工具从 3 个涨到 30 个这段代码就复制了 30 遍。更麻烦的是 MCP Client 侧每个工具调用都要单独带 KeyKey 一换客户端要改 N 个地方。这其实就是「Key 分散 鉴权逻辑重复」的典型症状。MCP Server 本质是一个基于 SSE 的 HTTP 服务请求先到 WebFlux 的过滤器链再到具体的工具方法。既然请求头在过滤器层就能拿到那鉴权完全可以前置到WebFilter里做一次工具方法只关心业务。这就是「过滤器版」鉴权的核心思路在 MCP Server 入口统一校验请求头通过则放行到工具链不通过直接返回 401。这篇要解决的就是三件事过滤器骨架怎么写、config.toml怎么配、以及怎么用 TaoToken 把多个 MCP Client 的 Key 收敛成一条统一通道。适合已经在用 SpringAI GA 写 MCP Server、但被多工具鉴权搞烦的开发者。下面所有代码都可以直接复制到你的工程里跑。2. TaoToken 统一 Key 通道的前置准备在写过滤器之前先把 Key 通道这件事理清楚。MCP Server 的鉴权过滤器校验的是「请求头里的 token 对不对」但 token 从哪来、怎么统一管理是另一回事。如果每个 MCP Client 各自持有一个 Key过滤器里就得维护一张 Key 白名单表Key 一多配置和轮换都是负担。TaoToken 在这里的角色是「统一 Key/API 通道」MCP Client 侧不再直接持有各个模型的 Key而是统一走 TaoToken 的 API 通道请求头里带的是同一套凭证。这样 MCP Server 的过滤器只需要校验一个来源的 token逻辑就收敛了。官网入口在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 基址是 https://taotoken.net/api 这个不加 UTM直接用于配置。你需要先拿到两样东西一个 API Key以及确认模型通道可用。API Key 在控制台的 API Keys 页面创建地址是 https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 。创建时建议按用途命名比如mcp-server-prod方便后面在过滤器里做来源区分。拿到 Key 之后先别急着写代码用模型对话页面确认通道是通的https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 。这一步的意义是排除「Key 本身无效」这种低级问题免得后面过滤器报 401 时你分不清是过滤器逻辑错了还是 Key 错了。如果你后面要做长期编码或 Agent 场景可以了解下 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 配置参数以文档为准。注意过滤器里校验的 token 是你自己定义的请求头值TaoToken 的 API Key 是 MCP Client 调用模型通道时用的凭证两者是不同层的东西。别把 API Key 直接当过滤器 token 用容易混。3. 可复制的过滤器骨架与 config.toml 配置3.1 依赖与 application.yml先确认pom.xml里引的是 WebFlux 版的 MCP Server starter因为WebFilter是响应式栈的接口用 Servlet 栈的 starter 会对不上dependencies dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-starter-mcp-server-webflux/artifactId /dependency /dependenciesapplication.yml里把 MCP Server 的基础信息配好端口用 19000SSE 消息端点走/mcp/messagesserver: port: 19000 spring: application: name: mcp-auth-mcp-server ai: mcp: server: name: mcp-auth-mcp-server version: 1.0.0 type: ASYNC instructions: This reactive server provides time information tools and resources sse-message-endpoint: /mcp/messages capabilities: tool: true resource: true prompt: true completion: true logging: level: io: modelcontextprotocol: client: DEBUG spec: DEBUG server: DEBUGtype: ASYNC是响应式应用的推荐值配合 WebFlux 使用。capabilities里把 tool、resource、prompt、completion 都打开方便后面验证过滤器对不同类型请求都生效。3.2 过滤器骨架核心过滤器实现WebFilter接口从请求头取 token比对通过就chain.filter(exchange)不通过就设 401 并setComplete()package com.spring.ai.tutorial.mcp.server.filter; import org.slf4j.Logger; import org.slf4j.LoggerFactory; import org.springframework.stereotype.Component; import org.springframework.web.server.ServerWebExchange; import org.springframework.web.server.WebFilter; import org.springframework.web.server.WebFilterChain; import reactor.core.publisher.Mono; Component public class McpServerFilter implements WebFilter { private static final String TOKEN_HEADER token-yingzi-1; private static final String TOKEN_VALUE yingzi; private static final Logger logger LoggerFactory.getLogger(McpServerFilter.class); Override public MonoVoid filter(ServerWebExchange exchange, WebFilterChain chain) { String token exchange.getRequest().getHeaders().getFirst(TOKEN_HEADER); if (TOKEN_VALUE.equals(token)) { logger.info(preHandle: URL: {}, exchange.getRequest().getURI()); logger.info(preHandle: TOKEN: {}, token); return chain.filter(exchange); } else { logger.warn(Token auth failed: URL: {}, TOKEN: {}, exchange.getRequest().getURI(), token); exchange.getResponse().setStatusCode(org.springframework.http.HttpStatus.UNAUTHORIZED); return exchange.getResponse().setComplete(); } } }这里TOKEN_HEADER和TOKEN_VALUE是硬编码的示例值实际项目里应该从配置中心或环境变量读。过滤器的关键点是它在工具方法之前执行所以不管你有多少个Tool鉴权只做一次。3.3 工具类与启动类工具类保持干净只写业务逻辑不掺鉴权package com.spring.ai.tutorial.mcp.server.service; import org.slf4j.Logger; import org.slf4j.LoggerFactory; import org.springframework.ai.tool.annotation.Tool; import org.springframework.ai.tool.annotation.ToolParam; import org.springframework.stereotype.Service; import java.time.ZoneId; import java.time.ZonedDateTime; import java.time.format.DateTimeFormatter; Service public class TimeService { private static final Logger logger LoggerFactory.getLogger(TimeService.class); Tool(description Get the time of a specified city.) public String getCityTimeMethod(ToolParam(description Time zone id, such as Asia/Shanghai) String timeZoneId) { logger.info(The current time zone is {}, timeZoneId); return String.format(The current time zone is %s and the current time is %s, timeZoneId, getTimeByZoneId(timeZoneId)); } private String getTimeByZoneId(String zoneId) { ZoneId zid ZoneId.of(zoneId); ZonedDateTime zonedDateTime ZonedDateTime.now(zid); DateTimeFormatter formatter DateTimeFormatter.ofPattern(yyyy-MM-dd HH:mm:ss z); return zonedDateTime.format(formatter); } }启动类把工具注册成ToolCallbackProviderpackage com.spring.ai.tutorial.mcp.server; import com.spring.ai.tutorial.mcp.server.service.TimeService; import org.springframework.ai.tool.ToolCallbackProvider; import org.springframework.ai.tool.method.MethodToolCallbackProvider; import org.springframework.boot.SpringApplication; import org.springframework.boot.autoconfigure.SpringBootApplication; import org.springframework.context.annotation.Bean; SpringBootApplication public class AuthWebServerApplication { public static void main(String[] args) { SpringApplication.run(AuthWebServerApplication.class, args); } Bean public ToolCallbackProvider timeTools(TimeService timeService) { return MethodToolCallbackProvider.builder().toolObjects(timeService).build(); } }3.4 config.toml 配置MCP Client 侧如果用支持config.toml的客户端把统一 Key 通道配进去。下面是一个可复制的骨架url指向你的 MCP Serverheaders里带过滤器要校验的 token[[mcp_servers]] name mcp-auth-web-server url http://localhost:19000/mcp/messages transport sse [mcp_servers.headers] token-yingzi-1 yingzi如果你走 TaoToken 统一通道模型侧的配置单独放在 provider 段API 基址用https://taotoken.net/apiKey 从环境变量注入不要写死在文件里[[providers]] name taotoken base_url https://taotoken.net/api api_key_env TAOTOKEN_API_KEY这样 MCP Server 的过滤器只管校验token-yingzi-1模型调用走 TaoToken 通道两件事解耦。Key 轮换时只改环境变量不用动过滤器代码。4. 验证鉴权拦截与放行配置写完启动 MCP Server 模块然后用 curl 验证两种路径不带 token 应该被拦带正确 token 应该放行。先测拦截。不带任何请求头直接请求 SSE 端点curl -i -N http://localhost:19000/mcp/messages预期返回 401HTTP/1.1 401 Unauthorized服务端日志会打出Token auth failed说明过滤器生效了。这一步很关键很多人写完过滤器不测拦截结果上线发现鉴权根本没起作用。再测放行。带上正确的请求头curl -i -N -H token-yingzi-1: yingzi http://localhost:19000/mcp/messages预期返回 200并且开始推送 SSE 事件流。服务端日志会打出preHandle: URL和preHandle: TOKEN说明请求已经穿过过滤器进入工具链。最后测工具调用。启动带请求头的 MCP Client让它调用getCityTimeMethod传入Asia/Shanghai。如果过滤器放行工具会返回类似The current time zone is Asia/Shanghai and the current time is 2025-09-17 15:30:00 CST如果过滤器拦截MCP Client 侧会报 401 鉴权失败。我试过把TOKEN_VALUE从yingzi改成yingzi-1服务端立刻放行客户端正常拿到时间改回yingzi再跑客户端又报 401。这个来回切换能帮你确认过滤器和客户端配置是对齐的。提示验证时把logging.level开到 DEBUGMCP 协议层的握手和消息都能看到排障效率高很多。5. 本篇常见错排查401 一直不消失但 token 明明带了。先确认请求头名字大小写。HTTP 头在 WebFlux 里是大小写不敏感的但如果你在客户端配置里写成了Token-Yingzi-1某些客户端会原样发送过滤器用getFirst(token-yingzi-1)取不到。统一用小写。过滤器写了但没生效。检查是不是引了 Servlet 栈的 starter。WebFilter只在 WebFlux 环境里被自动装配如果你用的是spring-ai-starter-mcp-server-webmvc过滤器不会进链。确认依赖是spring-ai-starter-mcp-server-webflux。SSE 连接建立后工具调用才报 401。这说明过滤器只拦了初始握手没拦后续消息。检查sse-message-endpoint配置是否和过滤器匹配/mcp/messages这个路径要能被过滤器覆盖到。如果端点配错消息请求走了另一个路径过滤器就漏了。config.toml 里 headers 不生效。不同客户端对config.toml的 headers 段支持程度不一样有的要求放在[mcp_servers.headers]子表下有的要求内联。以你所用客户端的文档为准别照搬。如果客户端不支持自定义头考虑在客户端侧加一层转发。TaoToken 通道报鉴权失败。先确认 API Key 是从控制台创建的、且没有过期地址 https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 。再确认base_url是https://taotoken.net/api不要多加路径。如果还不行去模型对话页面单独测一下 Key 是否可用https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 。多个 MCP Server 共用一套过滤器。如果每个 Server 的 token 不同别把TOKEN_VALUE写死。改成从配置读一个 Map按请求路径或 Server 名匹配对应 token。过滤器骨架不变只是比对逻辑从单值变成查表。6. 接入与排障的下一步过滤器骨架跑通之后接下来要做的通常是把 Key 管理从硬编码挪到配置中心以及把 MCP Client 侧的请求头注入做成统一拦截器避免每个调用点都手写 header。这两步做完多工具场景下的鉴权就基本收敛了。如果你在接入过程中遇到 401 排查不清、或者不确定请求头有没有正确传递优先去 API Keys 页面确认凭证状态再对照接入文档检查参数https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。文档里对 base_url、鉴权头格式、常见错误码都有说明比在代码里猜快得多。长期做编码或 Agent 场景的话Coding Plan 那条通道可以单独了解https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 。它和 MCP Server 过滤器是两层东西一个管模型调用通道一个管服务入口鉴权别混在一起配。