MCP Authx

MCP认证工具包

一个Python库，用于向模型上下文协议（MCP）服务器添加OAuth 2.1+PKCE身份验证和细粒度授权。

未准备好生产

特性

• 🔐 OAuth 2.1 + PKCE 版本：支持PKCE的安全授权代码流
• 🎯 细粒度授权：具有可配置策略的工具级权限
• 🔧 可嵌入的：在现有MCP服务器中充当中间件或装饰器
• 🚀 运行时无关：与FastMCP、自定义服务器和框架兼容
• 🛡️ 基于JWT：具有工具范围声明的短期令牌
• 📋 策略引擎：具有正则表达式模式匹配的声明性RBAC

快速开始

安装

使用紫外线（推荐）

# Install the package
uv add mcp-authx

# Or install with FastMCP support
uv add mcp-authx[fastmcp]

# For development
git clone
cd mcp-authx
uv sync --group dev

使用pip

pip install mcp-auth-toolkit
# or with FastMCP support
pip install mcp-auth-toolkit[fastmcp]

基本用法

from src import OAuthProvider, OAuthConfig, PolicyEngine, auth_required

# Configure OAuth provider
config = OAuthConfig(
    client_id="your-client-id",
    client_secret="your-client-secret",
    authorization_endpoint="https://auth.example.com/oauth/authorize",
    token_endpoint="https://auth.example.com/oauth/token",
    scopes=["mcp:tools:read", "mcp:tools:write"]
)

oauth_provider = OAuthProvider(config, "your-jwt-secret")
policy_engine = PolicyEngine()

# Define tool permissions
policy_engine.add_tool_scope_policy("read_.*", ["mcp:tools:read"])
policy_engine.add_tool_scope_policy("write_.*", ["mcp:tools:write"])

# Protect MCP tools with decorators
@auth_required(oauth_provider, policy_engine, "read_files")
async def read_files(auth_context, path: str):
    return {"files": ["file1.txt"], "user": auth_context.user_id}

FastMCP集成

from mcp.server.fastmcp import FastMCP
from src import FastMCPAuthWrapper, create_default_policies

mcp = FastMCP("My Secure Server")

# Add your tools
@mcp.tool()
def my_tool(data: str):
    return {"result": data}

# Wrap with authentication
oauth_provider = OAuthProvider(config, jwt_secret)
policy_engine = create_default_policies()
auth_wrapper = FastMCPAuthWrapper(mcp, oauth_provider, policy_engine)
auth_wrapper.add_auth_endpoints()

建筑

OAuth流

1. 授权：生成启用了PKCE的授权URL
2. 代币交换：JWT访问令牌的交换授权码
3. 工具访问：验证令牌并检查工具权限
4. 内省：验证令牌有效性并提取声明

策略引擎

策略引擎支持：

• 正则表达式模式 用于工具名称匹配
• 基于范围的授权 要求索赔
• 有条件的政策 基于用户属性
• 默认拒绝 具有明确的允许规则

代币结构

JWT代币包括：

• 标准索赔(iss, sub, aud, exp)
• mcp_tool_scopes：允许的工具范围数组
• upstream_token：原始OAuth提供者令牌

配置

环境变量

OAUTH_CLIENT_ID=your-client-id
OAUTH_CLIENT_SECRET=your-client-secret
OAUTH_AUTH_ENDPOINT=https://auth.example.com/oauth/authorize
OAUTH_TOKEN_ENDPOINT=https://auth.example.com/oauth/token
JWT_SECRET=your-jwt-signing-secret

政策实例

# Allow read tools for users with read scope
policy_engine.add_tool_scope_policy("get_.*", ["mcp:tools:read"])

# Require admin scope for delete operations  
policy_engine.add_tool_scope_policy("delete_.*", ["mcp:tools:admin"])

# Wildcard access for superusers
policy_engine.add_tool_scope_policy(".*", ["mcp:tools:*"])

演示服务器

运行附带的演示服务器：

# Using uv
uv run demo_server.py

# Or install with examples and run via script
uv sync --extra examples
uv run mcp-auth-demo

# Using pip
python demo_server.py

可用端点：

• get_weather （要求： mcp:tools:read)
• send_email （要求： mcp:tools:write)
• delete_user （要求： mcp:tools:admin)
• oauth://authorize （OAuth授权）
• oauth_token （代币兑换）
• oauth_introspect （令牌验证）

安全功能

• PKCE：防止授权码被拦截
• 短期代币：默认过期时间为1小时
• 范围验证：工具需要特定的范围
• 令牌自省：实时验证
• 撤销支持：使受损令牌无效

集成模式

1.装饰图案

@auth_required(oauth_provider, policy_engine, "tool_name")
async def my_tool(auth_context, ...):
    pass

2.中间件模式

auth_wrapper = FastMCPAuthWrapper(mcp_server, oauth_provider, policy_engine)

3.手动图案

middleware = MCPAuthMiddleware(oauth_provider, policy_engine)
auth_context = middleware.authenticate_request(auth_header)
authorized, reason = middleware.authorize_tool_call(tool_name, auth_context)

贡献

此工具包遵循MCP身份验证规范，并实现了OAuth 2.1最佳实践。欢迎捐款：

• 其他身份提供者集成
• 策略引擎增强
• 传输层改进
• 文件和示例

许可证

MIT许可证-有关详细信息，请参阅许可证文件。