Auth MCP Gateway

AuthMCP网关

模型上下文协议（MCP）服务器的安全身份验证代理

AuthMCP网关是 全MCP协议代理 通过集中式身份验证、授权和监控。它透明地代理所有MCP功能——工具、资源、提示和完成——从多个后端服务器通过单个经过身份验证的端点。

OAuth+DCR就绪： 网关支持OAuth 2.0授权码流和动态客户端注册（DCR），因此像Codex这样的MCP客户端可以自行注册和验证，而无需手动配置客户端。

📋 目录

• ✨ 特性
• 📸 截图
• 🚀 快速开始
• ⚙️ 配置
• 💡 用法
• 🏗️ 建筑
• 🔌 API终点
• 🔐 安全
• 🛠️ 发展
• 📊 监控
• 🔧 故障排除

______________________________________________________________________

✨ 特性

🔗 完整MCP协议代理 （v1.2.0）

• 工具 - tools/list, tools/call 具有智能路由（前缀、映射、自动发现）
• 资源 - resources/list, resources/read, resources/templates/list
• 提示 - prompts/list, prompts/get
• 补全 - completion/complete 基于ref的路由
• 动态能力 -查询后端位于 initialize 只宣传他们支持的东西
• 多服务器聚合 -list方法合并来自所有后端的结果；读取/获取/调用正确的路由
• 协议版本 -MCP 2025-03-26

🔐 身份验证和授权

• OAuth 2.0+JWT -行业标准身份验证流程
• 动态客户端注册（DCR） -MCP客户端可以自行注册OAuth
• 用户管理 -基于角色的访问的多用户支持
• 后端令牌管理 -MCP服务器凭据的安全存储和自动刷新
• 速率限制 -具有可配置限制的按用户请求限制

📊 实时监控

• 实时MCP活动监测器 -具有自动刷新功能的实时请求提要
• 性能指标 -响应时间、成功率、请求/分钟
• 安全事件日志记录 -未经授权的访问尝试、速率限制、可疑活动
• 健康检查 -对所有连接的MCP服务器进行自动健康检查

🎛️ 管理员仪表板

• 用户管理 -创建、编辑和管理用户
• MCP服务器配置 -添加和配置后端MCP服务器
• 许可证管理 -监控令牌运行状况和手动刷新
• 安全事件 -查看和筛选安全事件
• 安全审计 -MCP漏洞扫描

🛡️ 安全

• 基于JWT令牌的刷新令牌身份验证
• 支持加密数据库的安全凭据存储
• CORS保护和请求验证
• 安全事件记录和监控
• 基于文件的日志记录 -JSON日志，用于旋转认证和MCP请求；安全事件保留在SQLite中以供审计/查询

📸 截图

🖥️ Dashboard - Real-time Overview

*实时统计数据、服务器运行状况监控、顶级工具使用情况和最近的活动提要*

🔧 MCP Servers - Connection Management

*通过状态监控和健康检查管理后端MCP服务器连接*

📊 MCP Activity Monitor - Real-time Request Tracking

*使用详细指标、顶级工具排名和请求提要监控实时MCP请求*

🛡️ Security Events - Threat Detection

*跟踪安全事件、速率限制、可疑有效载荷和未经授权的访问尝试*

🔒 MCP Security Audit - Vulnerability Scanner

*通过全面的自动检查测试任何MCP服务器的安全漏洞*

______________________________________________________________________

🚀 快速开始

选项1:PyPI包（推荐）

1.安装：

pip install authmcp-gateway

2.首轮：

authmcp-gateway start
# ✓ Auto-creates .env with JWT_SECRET_KEY
# ✓ Auto-creates data/ directory
# ✓ Initializes database

3.访问设置向导： 打开 http://localhost:8000/ 在浏览器中创建管理员用户。

4.可选-自定义配置：

# Edit auto-generated .env or download full example
curl -o .env https://raw.githubusercontent.com/loglux/authmcp-gateway/main/.env.example.pypi

# Common settings to customize in .env:
# PORT=9000                          # Change server port
# PASSWORD_REQUIRE_SPECIAL=false     # Relax password requirements
# LOG_LEVEL=DEBUG                    # More detailed logs

# Restart to apply changes
authmcp-gateway start

可用命令：

authmcp-gateway start                    # Start server (default: 0.0.0.0:8000)
authmcp-gateway start --port 9000        # Start on custom port
authmcp-gateway start --host 127.0.0.1   # Bind to localhost only
authmcp-gateway start --env-file custom.env  # Use custom config file

authmcp-gateway init-db                  # Initialize database
authmcp-gateway create-admin             # Create admin user via CLI
authmcp-gateway version                  # Show version
authmcp-gateway --help                   # Show all options

选项2：Docker编写

1. 克隆和配置：

   git clone https://github.com/loglux/authmcp-gateway.git
   cd authmcp-gateway
   cp .env.example .env
   # Edit .env with your settings

1. 启动网关：

   docker-compose up -d

1. 访问管理面板：

- 打开http://localhost:9105/ - 完成设置向导以创建管理员用户 - 添加您的MCP服务器

⚙️ 配置

环境变量

# Gateway Settings
GATEWAY_PORT=9105              # Host port mapping for Docker (container listens on 8000)
JWT_SECRET_KEY=your-secret-key # JWT signing key (auto-generated if not set)
AUTH_REQUIRED=true             # Enable authentication (default: true)

# Admin Settings
ADMIN_USERNAME=admin           # Initial admin username
ADMIN_PASSWORD=secure-password # Initial admin password

添加MCP服务器

通过管理面板：

1. 导航至 MCP服务器 → 添加服务器
2. 输入服务器详细信息：

- 名称（例如，“GitHub MCP”） - URL（例如，“http://github-mcp:8000/mcp") - 后端令牌（如果需要）

通过API：

curl -X POST http://localhost:9105/admin/api/mcp-servers \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "GitHub MCP",
    "url": "http://github-mcp:8000/mcp",
    "backend_token": "optional-token"
  }'

💡 用法

面向最终用户

1. 登录以获取访问令牌：

   curl -X POST http://localhost:9105/auth/login \
     -H "Content-Type: application/json" \
     -d '{"username":"your-username","password":"your-password"}'

1. 使用令牌访问MCP端点：

   # List tools from all backends
   curl -X POST http://localhost:9105/mcp \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

   # List resources
   curl -X POST http://localhost:9105/mcp \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"jsonrpc":"2.0","id":2,"method":"resources/list"}'

   # List prompts
   curl -X POST http://localhost:9105/mcp \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"jsonrpc":"2.0","id":3,"method":"prompts/list"}'

   # Ping
   curl -X POST http://localhost:9105/mcp \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"jsonrpc":"2.0","id":4,"method":"ping"}'

对于管理员

管理面板功能：

• 仪表板 -用户、服务器和活动概述
• MCP活动 -实时监控所有MCP请求
• 安全事件 -查看未经授权的访问尝试和可疑活动
• 用户管理 -创建和管理用户帐户
• 许可证管理 -监控和刷新后端令牌

🏗️ 建筑

┌──────────────────────────────────────────┐
│      MCP Clients (Claude, Codex, etc.)   │
│      OAuth 2.0 / JWT Authentication      │
└────────────────────┬─────────────────────┘
                     │
┌────────────────────▼─────────────────────┐
│               AuthMCP Gateway            │
│             MCP 2025-03-26 Proxy         │
│                                          │
│  • Full MCP Protocol Proxy               │
│  • Tools / Resources / Prompts           │
│  • OAuth 2.0 + DCR                       │
│  • JWT Auth (HS256/RS256+JWKS)           │
│  • Rate Limiting                         │
│  • Security Logging                      │
│  • Multi-Server Aggregation              │
│  • Health Monitoring                     │
│  • Admin Dashboard                       │
└────────────────────┬─────────────────────┘
                     │
    ┌──────────┬──────────┬──────────┐
    ▼          ▼          ▼          ▼
┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐
│  RAG   │ │WhatsApp│ │ Docs   │ │Custom  │
│  MCP   │ │  MCP   │ │  MCP   │ │  MCP   │
└────────┘ └────────┘ └────────┘ └────────┘

🔌 API终点

公共端点

• POST /auth/login -用户登录
• POST /auth/register -用户注册（如果启用）
• POST /auth/refresh -刷新访问令牌
• POST /oauth/register -OAuth动态客户端注册（如果启用）
• GET /.well-known/oauth-authorization-server -OAuth发现

受保护的端点

• POST /mcp -聚合MCP端点（所有服务器）
• POST /mcp/{server_name} -特定MCP服务器端点
• GET /mcp -可流式MCP端点（SSE/流客户端）
• GET /auth/me -当前用户信息
• POST /auth/logout -注销

支持的MCP方法

工具注释和安全检索

对于 tools/call，网关更喜欢标准MCP工具 annotations 决定工具是否为只读时 或者可以安全地重试：

• annotations.readOnlyHint
• annotations.idempotentHint
• annotations.destructiveHint

行为：

• 只读工具可以使用安全的自动重试。
• 突变工具是 不 盲目重试。
• 如果一个变异工具被标记为幂等，则网关会保留或生成

arguments.idempotency_key 并在重试时重用相同的密钥。

• 如果元数据缺失或不清楚，网关将恢复到保守行为并禁用

自动重试 tools/call.

这使网关与标准MCP注释保持一致，同时允许后端MCP服务器 在需要的地方实现更强的幂等性语义。

🤖 Codex OAuth（DCR）登录（手动回调）

Codex使用OAuth授权码+PKCE和动态客户端注册（DCR）。在终端中运行时 如果没有自动启动的浏览器，您必须手动打开授权URL，然后 调用本地主机 自己回调URL 完成登录。

步骤：

1. 在Codex中添加MCP服务器：

codex mcp add rag --url https://your-domain.com/mcp/your-backend

1. Codex打印 授权URL。在浏览器中打开它。
2. 完成登录（管理员/用户凭据）。
3. 成功登录后，您将被重定向到 `http://127.0.0.1:

/callback?...` URL。 复制该完整URL并从另一个终端调用它：

curl "http://127.0.0.1:
/callback?code=...&state=..."

您应该看到： Authentication complete. You may close this window.

一旦完成，Codex将显示MCP服务器已登录。

无头令牌存储（重要）

在无头服务器（无桌面环境）上，Codex无法访问操作系统密钥环来存储OAuth令牌。 即使在成功登录后，也会导致“需要身份验证”错误。要解决此问题，请切换到基于文件的令牌存储：

# ~/.codex/config.toml
mcp_oauth_credentials_store = "file"

参考： Codex配置参考

如果没有此参数，Codex将无法刷新令牌，因为它会查找密钥环安全服务，并且 失败。这迫使您按照上述手动程序一次又一次地重新登录。 更新配置后，重新启动Codex。

发现兼容性

一些MCP客户端在成功交换令牌后使用非标准路径探测OpenID发现。在 除标准外 /.well-known/openid-configuration，网关也提供相同的发现 文件在 /oauth/token/.well-known/openid-configuration 作为兼容性别名。

如果您已被锁定并看到此警告：

⚠ The rag MCP server is not logged in. Run `codex mcp login rag`.
⚠ MCP startup incomplete (failed: rag)

您可以使用辅助脚本刷新令牌，而无需再次进行手动身份验证过程：

python3 scripts/codex_refresh_mcp.py rag https://your-domain.com/oauth/token

Codex多机注释

如果Codex在多台机器上运行，每台机器都会存储自己的本地令牌。在这种情况下，从一个 当发生以下情况时，机器可以使另一台机器上的令牌无效 强制执行单次会话 启用（每个用户一个活动令牌）。 禁用 强制执行单次会话 在管理设置中，以避免在多机设置中强制注销。

🔐 安全

安全功能

• ✅ 基于JWT的刷新令牌身份验证
• ✅ 每个用户的速率限制
• ✅ 安全事件日志记录
• ✅ MCP请求跟踪与可疑活动检测
• ✅ 后端服务器的运行状况监控
• ✅ CORS保护
• ✅ 安全的凭证存储

🛠️ 发展

发布流程：见 docs/RELEASE.md.

本地开发

# Clone repository
git clone https://github.com/loglux/authmcp-gateway.git
cd authmcp-gateway

# Create virtual environment
python3 -m venv venv
source venv/bin/activate  # or `venv\Scripts\activate` on Windows

# Install dependencies
pip install -e .

# Run gateway
authmcp-gateway

运行测试

该套件分为快速单元测试和较慢的集成测试 （后者使用真正的SQLite夹具，每次测试约4.5秒设置）：

make test        # tests/unit only — ~3 min, run before every release
make test-slow   # tests/integration only
make test-all    # both (full suite)
make test-cov    # full suite + HTML coverage report

项目结构

authmcp-gateway/
├── src/authmcp_gateway/
│   ├── admin/           # Admin panel routes and logic
│   ├── auth/            # Authentication & authorization
│   ├── mcp/             # MCP proxy and handlers
│   ├── security/        # Security logging and monitoring
│   ├── middleware.py    # Request middleware
│   └── app.py           # Main application
│   ├── templates/       # Jinja2 templates (admin UI)
├── docs/                # Documentation
├── tests/               # Test suite
└── docker-compose.yml   # Docker deployment

📊 监控

实时仪表板

访问 /admin/mcp-activity 用于：

• 实时请求源（每3秒更新一次）
• 每分钟请求数
• 平均响应时间
• 成功率
• 顶级工具使用
• 每台服务器统计信息

日志

实时查看日志：

docker logs -f authmcp-gateway

🔧 故障排除

无法访问管理面板：

• 确保您已在完成安装向导 /setup
• 检查Cookie是否已启用
• 验证JWT_SECRET_KEY是否设置正确

MCP服务器显示为脱机：

• 检查服务器URL是否正确且可访问
• 如果需要，请验证后端令牌
• 在MCP服务器页面中查看错误详细信息

401未经授权的错误：

• 令牌可能已过期-请使用刷新令牌
• 验证授权标头格式： Bearer YOUR_TOKEN
• 检查用户是否有MCP服务器的权限

有关更多帮助，请参阅上面的故障排除和使用部分。

许可证

MIT许可证-请参阅 许可证 文件以获取详细信息。