SpringAI 1.0.0鉴权避坑指南：MCP服务调用时99%人会漏掉的header配置-优快云博客

SpringAI 1.0.0鉴权避坑指南：MCP服务调用时99%人会漏掉的header配置

在微服务架构盛行的今天，SpringAI作为企业级AI能力整合框架，正在成为开发者构建智能应用的首选工具。然而，当我们从传统Spring生态迁移到SpringAI体系时，MCP（Model Context Protocol）服务的鉴权配置往往成为最容易被忽视的"暗礁"。本文将深入剖析WebFlux环境下headers传递的典型陷阱，揭示那些官方文档未曾明示的关键细节。

1. 为什么你的MCP调用总是401？

许多开发者在初次接触SpringAI的MCP服务时，都会遇到一个令人困惑的现象：明明按照文档配置了鉴权参数，服务调用却频繁返回401未授权错误。这背后往往隐藏着三个容易被忽视的真相：

隐式header传递机制：与传统RestTemplate不同，WebFlux的header传递存在异步上下文丢失问题
Nacos集成的特殊要求：当MCP服务注册到Nacos时，header的命名需要遵循特定前缀规则
多层代理的过滤效应：经过API网关转发的请求，其原始headers可能被意外剥离

以下是一个典型的错误配置示例：

# application.yml (问题配置)
spring:
  ai:
    mcp:
      client:
        sse:
          connections:
            server1:
              url: http://service-endpoint
              headers:
                Authorization: Bearer xxxxx  # 这种配置方式在WebFlux下可能失效

2. WebFlux环境下的正确header注入方式

在响应式编程范式中，header的传递需要特别注意上下文保存。以下是经过验证的可靠配置方案：

2.1 基础配置层

// 正确配置示例
@Bean
public WebClient.Builder webClientBuilder() {
    return WebClient.builder()
        .defaultHeader("X-Request-ID", UUID.randomUUID().toString())
        .filter((request, next) -> {
            return Mono.deferContextual(contextView -> {
                if (contextView.hasKey("auth-token")) {
                    request.headers().add(
                        "Authorization", 
                        "Bearer " + contextView.get("auth-token")
                    );
                }
                return next.exchange(request);
            });
        });
}

关键要点：

使用Mono.deferContextual确保异步上下文不丢失
重要鉴权header建议设置双重保障（配置文件和代码动态注入）

2.2 Nacos集成时的特殊处理

当MCP服务注册到Nacos时，headers需要添加命名空间前缀：

spring:
  ai:
    mcp:
      client:
        sse:
          connections:
            server1:
              url: http://service-endpoint
              headers:
                ${nacos.namespace}.Authorization: Bearer xxxxx  # 添加命名空间前缀
                ${nacos.namespace}.X-Trace-Id: ${trace.id}