Java MCP 鉴权设计与实现指南

一、MCP 鉴权概述

MCP (Model Context Protocol) 旨在为大语言模型（LLM）与外部数据源、工具和服务提供标准化、安全的集成方式（相当于一种专用的 RPC 协议）。广泛应用于 AI 开发中的工具服务(Tool)、提示语服务(Prompt)和资源服务(Resource)。在实际应用中，确保 MCP 服务的安全性至关重要，因此需要合理的鉴权机制。

根据提供的资料，MCP 鉴权主要涉及以下几个方面：

服务端鉴权设计
客户端鉴权配置
不同通讯通道(stdio/SSE)的鉴权实现
与 Web API 互通的鉴权处理

本案基于 Solon AI MCP 进行鉴权方面的探讨：

xml 复制代码

<dependency>
    <groupId>org.noear</groupId>
    <artifactId>solon-ai-mcp</artifactId>
    <version>最新版本</version>
</dependency>

可支持 java8, java11, java17, java21, java24 。可支持 solon，springboot，vert.x，jFinal 等框架集成。

二、MCP 服务端鉴权设计

1、基于过滤器的鉴权方案

MCP 服务端可以通过过滤器或路由拦截器实现鉴权，特别是对于 HTTP SSE 通道的服务：

java 复制代码

@Component
public class McpFilter implements Filter {
    @Override
    public void doFilter(Context ctx, FilterChain chain) throws Throwable {
        //message 端点，不需要鉴权
        if (ctx.pathNew().startsWith("/mcp/") && ctx.pathNew().endsWith("/message") == false) { 
            String authStr = ctx.header("Authorization");
            if (Utils.isEmpty(authStr)) {
                ctx.status(401);
                return;
            }
            // 业务检测逻辑
            if (!checkAuth(authStr)) {
                ctx.status(403);
                return;
            }
        }
        
        chain.doFilter(ctx);
    }
    
    private boolean checkAuth(String authStr) {
        // 实现具体的鉴权逻辑
        return true;
    }
}

2、基于注解的端点级鉴权

对于使用 @McpServerEndpoint 注解的服务端点，可以通过 @Header 注解或者上下文对象(Context) 获取用户身份或鉴权信息：

java 复制代码

@McpServerEndpoint(sseEndpoint = "/mcp/sse")
public class McpAuthService {
    
    @ToolMapping(description = "需要鉴权的天气预报查询")
    public String getWeather(@Param(description = "城市位置") String location, @Header("user") user, Context ctx) {
        // 根据用户隔离数据: user
        
        // 从上下文中获取鉴权或身份信息: ctx
        
        return "晴,14度";
    }
}

在方法里鉴权时不能输出状态码，要改为异常抛出。

三、MCP 客户端鉴权配置

1、Basic Authentication

java 复制代码

McpClientProvider toolProvider = McpClientProvider.builder()
    .apiUrl("https://localhost:8080/mcp/sse")
    .apiKey("sk-xxxxx") // 自动转换为Authorization头
    .build();

java 复制代码

McpClientProvider toolProvider = McpClientProvider.builder()
    .apiUrl("https://localhost:8080/mcp/sse")
    .header("X-API-KEY", "your-api-key")
    .header("X-API-SECRET", "your-api-secret")
    .header("X-USER", "your-user")
    .build();

3、QueryString 参数鉴权（比较常见）

java 复制代码

McpClientProvider toolProvider = McpClientProvider.builder()
    .apiUrl("https://localhost:8080/mcp/sse?token=xxxx")
    .build();

四、不同通道的鉴权实现

1、HTTP SSE 通道鉴权

HTTP SSE 通道的鉴权可以利用 HTTP 协议本身的特性：

java 复制代码

@Configuration
public class McpSseAuthConfig {
    
    @Bean
    public McpClientProvider sseClient() {
        return McpClientProvider.builder()
            .apiUrl("http://localhost:8080/mcp/sse")
            .header("X-Auth-Token", "your-token")
            .httpTimeout(HttpTimeout.builder()
                .connectTimeout(Duration.ofSeconds(10))
                .readTimeout(Duration.ofSeconds(60))
                .build())
            .build();
    }
}

2、2. STDIO 通道鉴权

对于 STDIO 通道，鉴权通常通过环境变量或启动参数实现：

java 复制代码

@McpServerEndpoint(channel = McpChannel.STDIO)
public class StdioAuthService {
    
    @ToolMapping(description = "STDIO通道的鉴权服务")
    public String secureOperation(@Param String input) {
        String authToken = System.getenv("INTERNAL_AUTH_TOKEN");
        if(!validateInternalToken(authToken)) {
            throw new SecurityException("Invalid internal token");
        }
        
        return processInput(input);
    }
}

客户端调用时配置环境变量：

java 复制代码

McpClientProvider stdioClient = McpClientProvider.builder()
    .channel(McpChannel.STDIO)
    .serverParameters(ServerParameters.builder("java")
        .args("-jar", "secure-service.jar")
        .addEnvVar("INTERNAL_AUTH_TOKEN", "secure-token-value")
        .build())
    .build();

五、与 Web API 互通的鉴权

MCP 服务可以与 Web API 互通，共享鉴权逻辑：

java 复制代码

@Mapping("/api/secure")
@Controller
@McpServerEndpoint(sseEndpoint = "/mcp/secure/sse")
public class HybridAuthService {
    
    @ToolMapping(description = "混合鉴权服务")
    @Mapping("operation")
    public String hybridOperation(
        @Param(description = "输入参数") String input,
        @Header("Authorization") String authHeader) {
        
        if(!validateAuthHeader(authHeader)) {
            throw new SecurityException("Unauthorized");
        }
        
        return "Processed: " + input;
    }
}

六、最佳实践与注意事项

多因素认证：对于高安全性要求的场景，可以结合多种鉴权方式

java 复制代码

McpClientProvider highSecClient = McpClientProvider.builder()
    .apiUrl("https://secure.example.com/mcp/sse")
    .apiKey("primary-key")
    .header("X-Second-Factor", "totp-code")
    .build();

敏感信息保护：避免在日志中输出鉴权信息

java 复制代码

// 开发 stdio 服务时特别重要
@McpServerEndpoint(channel = McpChannel.STDIO)
public class SecureStdioService {
    // 确保不打印敏感信息到控制台
}

性能考虑：对于高频调用的服务，采用高效的鉴权方案

java 复制代码

// 使用高效的JWT验证
public class JwtAuthFilter implements Filter {
    // 实现快速的JWT验证逻辑
}

七、完整示例：带鉴权的 MCP 服务

服务端实现

java 复制代码

// 鉴权配置类
@Configuration
public class McpAuthConfig {
    
    @Bean
    public Filter mcpAuthFilter() {
        return new McpAuthFilter();
    }
}

// 鉴权过滤器
public class McpAuthFilter implements Filter {
    @Override
    public void doFilter(Context ctx, FilterChain chain) throws Throwable {
        if (ctx.pathNew().startsWith("/mcp/") && ctx.pathNew().endsWith("/message") == false) {
            String token = ctx.header("X-Auth-Token");
            if (!"valid-token".equals(token)) {
                ctx.status(401).output("Unauthorized");
                return;
            }
        }
        chain.doFilter(ctx);
    }
}

// MCP服务端点
@McpServerEndpoint(sseEndpoint = "/mcp/secure/sse")
public class SecureMcpService {
    
    @ToolMapping(description = "安全操作")
    public String secureOp(@Param(description = "输入") String input) {
        return "Secure result for: " + input;
    }
}

客户端实现

java 复制代码

public class SecureMcpClient {
    
    private final McpClientProvider client;
    
    public SecureMcpClient() {
        this.client = McpClientProvider.builder()
            .apiUrl("http://localhost:8080/mcp/secure/sse")
            .header("X-Auth-Token", "valid-token")
            .requestTimeout(Duration.ofSeconds(20))
            .build();
    }
    
    public String callSecureOp(String input) {
        return client.callToolAsText("secureOp", Map.of("input", input));
    }
}

总结

MCP 鉴权是保障服务安全性的重要环节，通过本文介绍的服务端过滤器、客户端配置、不同通道实现等方式，可以构建灵活安全的鉴权体系。在实际应用中，应根据具体场景选择适合的鉴权方案，并遵循安全最佳实践，确保 MCP 服务的安全可靠运行。

Java MCP 鉴权设计与实现指南

一、MCP 鉴权概述

二、MCP 服务端鉴权设计

1、基于过滤器的鉴权方案

2、基于注解的端点级鉴权

三、MCP 客户端鉴权配置

1、Basic Authentication

2、自定义 Header 鉴权

3、QueryString 参数鉴权（比较常见）

四、不同通道的鉴权实现

1、HTTP SSE 通道鉴权

2、2. STDIO 通道鉴权

五、与 Web API 互通的鉴权

六、最佳实践与注意事项

七、完整示例：带鉴权的 MCP 服务

服务端实现

客户端实现

总结