MCP Auth Middleware

mcp身份验证中间件

用于HTTP MCP服务器的JWE身份验证中间件。对用户数据进行端到端加密，以便只有您的MCP服务器可以读取它。

它做什么

mcp-auth-middleware 为您的MCP服务器提供两件事：

1. 一种中间件，用于解密JWE承载令牌，强制执行配置的JWT作用域，并通过以下方式公开经过身份验证的用户的声明 get_user().
2. CLI(mcp-auth-middleware)生成JWKS格式的RSA密钥对，输出Kubernetes Secret YAML，并在完成后安全地删除本地密钥。

中间件还发布：

• /.well-known/jwks.json 用于公钥发现
• /.well-known/openid-configuration 用于OpenID发现

安装

pip install mcp-auth-middleware

测试

python -m pip install -r requirements.txt
python -m pip install -e .
pytest --cov=mcp_auth_middleware --cov-report=term-missing --cov-fail-under=80

快速开始

1.生成密钥

mcp-auth-middleware generate

文中写道：

.keys/mcp-private.json
.keys/mcp-public.json

2.配置私钥

MCP_KEY_FILE_PATH=.keys/mcp-private.json

3.添加中间件

import uvicorn
from fastmcp import FastMCP

from mcp_auth_middleware import JWKSAuthMiddleware, get_user

mcp = FastMCP("My Server")

required_scopes = [
    {"scope": "name"},
    {"scope": "email"},
]

@mcp.tool()
def whoami() -> str:
    user = get_user()
    return f"Hello, {user.name}!"

app = mcp.http_app()
app.add_middleware(JWKSAuthMiddleware, scopes=required_scopes)

if __name__ == "__main__":
    uvicorn.run(app, host="0.0.0.0", port=8000)

4.OpenID发现

GET /.well-known/openid-configuration 返回颁发者、JWKS URI和配置的作用域：

{
  "issuer": "http://localhost:8000",
  "jwks_uri": "http://localhost:8000/.well-known/jwks.json",
  "scopes_supported": ["name", "email"]
}

端点是公共的，包含许可的CORS标头。

5.缺少范围响应

如果经过验证的令牌缺少一个或多个配置的字段，中间件将拒绝该请求 403 Forbidden:

{
  "error": "missing_scopes",
  "missing": [{ "scope": "email" }]
}

API 参考

JWKSAuthMiddleware

将其连接到任何基于Starlette的MCP服务器应用程序：

app.add_middleware(
    JWKSAuthMiddleware,
    scopes=[
        {"scope": "name"},
    ],
    verifier=None,
    jwks_path="/.well-known/jwks.json",
    openid_configuration_path="/.well-known/openid-configuration",
    issuer=None,
)

规则：

• scopes 是必需的，并且必须至少包含一个作用域。
• 每个配置的作用域都是强制性的。
• 作用域名称必须与JWT字段名称匹配。

get_user() -> AuthUser

返回经过身份验证的用户对当前请求的声明。

user = get_user()
user.email
user["email"]

ScopeDefinition

类型化配置的可选辅助数据类：

from mcp_auth_middleware import ScopeDefinition

scope = ScopeDefinition(
    scope="email",
)

JWETokenVerifier

如果您需要在中间件之外进行令牌验证，请使用较低级别的验证器：

from mcp_auth_middleware import JWETokenVerifier

verifier = JWETokenVerifier()
claims = await verifier.verify_token(token_string)
public_jwks = verifier.get_jwks()

verify_token() 回报 None 当令牌解密失败或解密的有效载荷不是JSON对象时。

浏览器访问

/.well-known/openid-configuration 已经包含CORS标头。

如果浏览器客户端也需要 /.well-known/jwks.json，之后添加CORS中间件 JWKSAuthMiddleware:

from starlette.middleware.cors import CORSMiddleware

app.add_middleware(JWKSAuthMiddleware, scopes=required_scopes)
app.add_middleware(CORSMiddleware, allow_origins=["*"])

Kubernetes部署

生成机密清单：

mcp-auth-middleware k8s | kubectl apply -f -

清理当地关键材料：

mcp-auth-middleware clean

挂载生成的私钥并设置：

MCP_KEY_FILE_PATH=/etc/mcp/secrets/key.json

部署+服务的完整示例在 examples/k8s-deployment.yaml.

环境变量

许可证

麻省理工学院