Java MCP 鉴权设计与实现指南

一、MCP 鉴权概述

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

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

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

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

<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 通道的服务：

@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) 获取用户身份或鉴权信息：

@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

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

2、自定义 Header 鉴权

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 参数鉴权（比较常见）

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

四、不同通道的鉴权实现

1、HTTP SSE 通道鉴权

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

@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 通道，鉴权通常通过环境变量或启动参数实现：

@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);
    }
}

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

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 互通，共享鉴权逻辑：

@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;
    }
}

六、最佳实践与注意事项

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

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

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

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

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

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

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

服务端实现

// 鉴权配置类
@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;
    }
}

客户端实现

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 服务的安全可靠运行。