FastAPI MCP 中实现请求头传递的完整解决方案

在基于 FastAPI 构建的 MCP (Model Context Protocol) 服务中，请求头信息的传递是一个常见但容易被忽视的技术细节。本文将深入探讨如何在 FastAPI MCP 项目中实现请求头的完整传递机制，特别是认证令牌的透传问题。

问题背景

当使用 FastAPI MCP 作为中间层服务时，客户端发送的请求头（如包含认证信息的 Authorization 头）在初始请求中能够正常接收，但在后续 MCP 主机调用工具服务时，这些关键头信息却丢失了。这会导致后端服务无法验证请求的合法性，返回 401 未授权错误。

核心挑战

请求头丢失的根本原因在于 FastAPI MCP 默认不会自动将接收到的请求头转发到下游服务。特别是在以下场景中：

1. 客户端 → MCP 服务的初始请求包含认证头
2. MCP 服务 → 工具服务的内部调用丢失认证头
3. 工具服务因缺少认证信息拒绝请求

解决方案实现

自定义 HTTP 客户端

通过创建自定义的 AuthClient 类继承 httpx.AsyncClient，我们可以确保每个请求都携带认证头：

class AuthClient(httpx.AsyncClient):
    def __init__(self, auth_token: str, *args, **kwargs):
        super().__init__(*args, **kwargs)
        self.headers.update({"Authorization": f"Bearer {auth_token}"})

请求中间件处理

在 FastAPI 中间件中，我们实现了完整的请求头处理流程：

@app.middleware("http")
async def log_requests(request, call_next):
    # 记录请求信息
    logger.debug(f"Incoming request: {request.method} {request.url}")
    logger.debug(f"Headers: {request.headers}")

    # 从请求头提取认证令牌
    auth_header = request.headers.get("authorization")
    if not auth_header:
        raise HTTPException(status_code=401, detail="Missing Authorization header")
    
    try:
        token = auth_header.split(" ")[1]
    except IndexError:
        raise HTTPException(status_code=401, detail="Invalid Authorization header format")

    # 创建带认证头的客户端
    request.state.auth_client = AuthClient(auth_token=token)
    
    # 更新 MCP 的 HTTP 客户端
    mcp._http_client = request.state.auth_client

    # 继续处理请求
    response = await call_next(request)
    logger.debug(f"Response status: {response.status_code}")
    return response

技术要点解析

1. 令牌提取机制：从 Authorization 头中正确提取 Bearer 令牌，处理各种可能的格式错误情况。

2. 客户端生命周期管理：为每个请求创建独立的认证客户端，确保线程安全。

3. MCP 集成：通过修改 mcp._http_client 属性，将认证客户端注入到 MCP 的核心处理流程中。

4. 日志记录：完整的请求/响应日志记录，便于调试和问题追踪。

最佳实践建议

1. 生产环境增强：考虑添加令牌缓存机制，避免为每个请求重复创建客户端。

2. 安全考虑：确保令牌在日志中脱敏处理，防止敏感信息泄露。

3. 性能优化：对于高频调用的场景，可以实现客户端连接池管理。

4. 错误处理：完善各种异常情况的处理逻辑，提供清晰的错误响应。

总结

通过实现自定义 HTTP 客户端和请求中间件，我们成功解决了 FastAPI MCP 中请求头传递的问题。这种方案不仅适用于认证头传递，也可以扩展到其他需要透传的请求头信息。关键在于理解 FastAPI 的请求生命周期和 MCP 的工作机制，从而在适当的环节进行拦截和处理。

对于更复杂的场景，开发者还可以考虑实现动态头注入、基于角色的头信息过滤等高级功能，构建更加灵活和安全的 API 网关层。