Enkrypt AI安全MCP网关
enkrypt-secure-mcp-gateway-hld
📖 特色博客文章： 在我们的最新博客中了解安全MCP网关如何防止顶级攻击和漏洞： Enkrypt的安全MCP网关和MCP扫描器如何防止顶级攻击 了解真实世界的攻击场景、安全最佳实践，以及我们的网关如何保护您的AI应用程序。
概述
此安全MCP网关具有身份验证、自动工具发现、缓存和护栏实施功能。
它位于MCP客户端和MCP服务器之间。因此，从本质上讲，它本身也充当MCP服务器和MCP客户端：）
当您的MCP客户端连接到网关时，它充当MCP服务器。当网关连接到实际的MCP服务器时，它充当MCP客户端。
- 另请参见：
- CLI-Commands-Reference.md 查看命令列表及其用法 - API参考.md 获取API终结点及其用法的列表 - MCP网关设置笔记本 了解所有基本命令的完整演练
目录
- 1.特点🚀
- 2.MCP网关工作原理的高级步骤🪜
- 3.先决条件🧩
- 4.网关设置👨💻
- 5.（可选）开放遥测设置📊
- 6.验证安装并检查生成的文件✅
- 7.根据需要编辑网关配置✏️
- 8.CLI快速入门指南🖥️
- 9.1（可选）使用OAuth连接到MCP服务器🔐
- 11.护栏使用建议💡
- 12.其他可用工具🔧
- 13.（可选）沙箱隔离🛡️
- 14.部署模式🪂
- 15.卸载网关🗑️
- 16.故障排除🕵
- 17.正在处理的已知问题🏗️
- 18.已知限制⚠️
- 19.贡献🤝
- 20.测试🧪
- 21.许可证
1.特点
enkrypt-secure-mcp-gateway-features
以下是Enkrypt AI安全MCP网关提供的功能列表：
- 认证：我们使用唯一密钥向网关进行身份验证。如果您想使用Enkrypt Guardrails保护您的MCP，我们也使用Enkrypt API密钥。此外，安全
admin_apikey（256字符随机字符串）是为管理REST API操作自动生成的。
- 易用性：您可以在配置文件中本地配置所有MCP服务器，或者更好的是在Enkrypt中配置 *（即将推出）* 并在网关中使用它们的名称
- 动态工具发现：网关从MCP服务器动态发现工具，并将其提供给MCP客户端
- 限制工具调用：如果您不希望MCP服务器访问所有工具，可以通过在网关配置中明确提及这些工具来限制它们，以便MCP客户端只能访问允许的工具
- 缓存：我们在本地或外部缓存服务器（如KeyDB）中缓存从各种MCP服务器发现的用户网关配置和工具，如果配置为提高性能
- 护栏：您可以在输入侧（在向MCP服务器发送请求之前）和输出侧（在收到MCP服务器的响应之后）为Enkrypt中的每个MCP服务器配置护栏
- 日志记录：我们在本地MCP日志中记录网关的每个请求和响应，并将其转发给Enkrypt *（即将推出）* 用于监控。这使您能够查看帐户中进行的所有调用、使用的服务器、调用的工具、阻止的请求等。
- 沙箱隔离：MCP服务器可以在隔离的沙盒环境（Docker、Podman或microVM）中启动，这样受感染或恶意的服务器就无法访问主机文件系统、网络或其他资源。每个沙箱都是短暂的——每个会话创建一个沙箱，完成后销毁。
1.1护栏
enkrypt-secure-mcp-gateway-guardrails
输入保护： 主题检测、NSFW过滤、毒性检测、注入攻击预防、关键字检测、策略违规检测、偏见检测和PII编辑（即将推出系统提示保护、版权保护等）
输出保护： 所有输入保护，加上依从性检查和相关性验证（即将推出更多功能，如幻觉检测等）。如果响应在输入时被编辑，我们还会自动取消编辑。
1.2概念
- MCP Config是一系列MCP服务器，如
mcp_server_1,mcp_server_2,mcp_server_3等等
- 每个配置都有一个唯一的ID
- 用户是具有唯一电子邮件和ID的网关用户
- 项目是共享MCP配置的用户集合
- 项目有一个名称和唯一的ID - MCP配置可以更新，也可以由管理员指向其他配置 - 用户可以添加到多个项目中
- 为用户和项目组合创建API密钥
- 用户可以为不同的项目使用不同的API密钥 - 此API密钥用于验证用户并识别正确的项目和MCP配置
- *看 6.5生成的配置文件示例 和 7.根据需要编辑网关配置 用于模式参考*
2.MCP网关工作原理的高级步骤
Local Gateway with Remote Guardrails Flow
🪜 Steps
- 您的MCP客户端使用API密钥连接到Secure MCP网关服务器（由处理
src/secure_mcp_gateway/gateway.py).
- 网关服务器从本地获取网关配置
enkrypt_mcp_config.json文件或远程Enkrypt身份验证服务器 *（即将推出）*.
- 它在本地或外部缓存服务器（如KeyDB）中缓存配置（如果配置为提高性能）。
- 如果启用了输入护栏，则在工具调用之前验证请求（由
src/secure_mcp_gateway/guardrail.py).
- 如果请求违反了任何配置的护栏，并且特定的检测器被配置为阻止，则请求将被阻止。
- 请求被转发到网关客户端（由
src/secure_mcp_gateway/client.py).
- 网关客户端将请求转发到相应的MCP服务器（由
src/secure_mcp_gateway/client.py).
- MCP服务器处理请求并将响应返回给网关客户端。
- 如果是发现工具调用，网关客户端会在本地或外部缓存服务器（如KeyDB）中缓存工具（如果已配置）。然后，它将响应转发到网关服务器。
- 网关服务器从网关客户端接收响应，如果启用了输出护栏，它将根据配置的护栏（由处理）验证响应
src/secure_mcp_gateway/guardrail.py).
- 如果响应违反了任何配置的护栏，并且特定的检测器被配置为阻止，则响应将被阻止。
- 如果一切正常，网关服务器会将响应转发回MCP客户端。
3.先决条件
🔗 Dependencies
Git 2.43或更高
Python 3.11或更高版本安装在您的系统上，可以使用以下任一方式从命令行访问python或python3命令
pip 25.0.1您的系统上安装了或更高版本，可以使用以下任一方式从命令行访问pip或python -m pip命令
uv 0.7.9您的系统上安装了或更高版本，可以使用以下任一方式从命令行访问uv或python -m uv命令
🔍 Check versions
- 检查是否安装了Python、pip和uv
- 如果以下任何命令失败，请参阅相应的文档以正确安装它们
# ------------------
# Python
# ------------------
python --version
# Example output
Python 3.13.3
# If not, install python from their website and run the version check again
# ------------------
# pip
# ------------------
pip --version
# Example output
pip 25.0.1 from C:\Users\PC\AppData\Local\Packages\PythonSoftwareFoundation.Python.3.13_qbz5n2kfra8p0\LocalCache\local-packages\Python313\site-packages\pip (python 3.13)
# If not, try the following and run the version check again
python -m ensurepip
# ------------------
# uv
# ------------------
uv --version
# Or run with "python -m" if uv is not found directly
# If this works, use "python -m" before all uv commands from now on
python -m uv --version
# Example output
uv 0.7.9 (13a86a23b 2025-05-30)
# If not, try the following and run the version check again
python -m pip install uv
- 安装 克劳德桌面版 作为MCP客户端 他们的网站 如果您还没有，请登录
- *如果你使用的是Linux，无法运行任何 非官方版本 克劳德桌面，你可以使用 任何支持的MCP客户端 以测试网关。如果它不支持mcp-cli mcp install 命令，然后遍历脚本代码并手动运行支持的命令。*
- 我们希望代理请求的MCP服务器所需的任何其他依赖关系
- 按照相应MCP服务器的说明安装其依赖项
- 喜欢 Node.js, npx, docker等等。
- （可选）安装并运行KeyDB等缓存服务器（如果您想在外部而非本地缓存）
🔒 Optional Protection with Enkrypt Guardrails
如果您想使用Enkrypt护栏保护MCP，您需要执行以下操作：
- 如果您没有新帐户，请创建一个新帐户。它是免费的！ 🆓 无需信用卡💳🚫
- 一
ENKRYPT_API_KEY你可以从那里得到 Enkrypt仪表板设置
- 要使用护栏保护MCP，您可以使用默认的护栏示例
Sample Airline Guardrail开始使用，或者您可以创建自己的自定义护栏
- 要配置自定义护栏，您需要登录Enkrypt AI应用程序或使用API/SDK
- 您还可以使用Enkrypt MCP服务器🤯 创建护栏并在网关中使用
4.网关设置
4.1带管道的本地安装
📦 Pip Installation Steps
4.1.1下载并安装软件包
- 激活虚拟环境
python -m venv .secure-mcp-gateway-venv
# Activate the virtual environment
# On Windows
.secure-mcp-gateway-venv\Scripts\activate
# On Linux/macOS
source .secure-mcp-gateway-venv/bin/activate
# Run the below to exit the virtual environment later if needed
deactivate- 安装软件包。有关更多信息，请参阅 https://pypi.org/project/secure-mcp-gateway/
pip install secure-mcp-gateway4.1.2运行Generate命令
- 这将在以下位置生成配置文件
~/.enkrypt/enkrypt_mcp_config.json在macOS和%USERPROFILE%\.enkrypt\enkrypt_mcp_config.json在Windows上
secure-mcp-gateway generate-config🖨️ Example output
Initializing Enkrypt Secure MCP Gateway
Initializing Enkrypt Secure MCP Gateway Common Utilities Module
Initializing Enkrypt Secure MCP Gateway Module
--------------------------------
SYSTEM INFO:
Using Python interpreter: C:\Users\PC\Documents\GitHub\EnkryptAI\secure-mcp-gateway\.secure-mcp-gateway-venv\Scripts\python.exe
Python version: 3.13.3 (tags/v3.13.3:6280bb5, Apr 8 2025, 14:47:33) [MSC v.1943 64 bit (AMD64)]
Current working directory: C:\Users\PC\Documents\GitHub\EnkryptAI\secure-mcp-gateway
PYTHONPATH: Not set
--------------------------------
Installing dependencies...
All dependencies installed successfully.
Initializing Enkrypt Secure MCP Gateway Client Module
Initializing Enkrypt Secure MCP Gateway Guardrail Module
Error: Gateway key is required. Please update your mcp client config and try again.
Getting Enkrypt Common Configuration
config_path: C:\Users\PC\.enkrypt\enkrypt_mcp_config.json
example_config_path: C:\Users\PC\Documents\GitHub\EnkryptAI\secure-mcp-gateway\.secure-mcp-gateway-venv\Lib\site-packages\secure_mcp_gateway\example_enkrypt_mcp_config.json
No enkrypt_mcp_config.json file found. Defaulting to example_enkrypt_mcp_config.json
--------------------------------
ENKRYPT_GATEWAY_KEY: ****NULL
enkrypt_log_level: info
is_debug_log_level: False
enkrypt_base_url: https://api.enkryptai.com
enkrypt_use_remote_mcp_config: False
enkrypt_api_key: ****_KEY
enkrypt_tool_cache_expiration: 4
enkrypt_gateway_cache_expiration: 24
enkrypt_mcp_use_external_cache: False
enkrypt_async_input_guardrails_enabled: False
--------------------------------
External Cache is not enabled. Using local cache only.
Initializing Enkrypt Secure MCP Gateway CLI Module
Generated default config at C:\Users\PC\.enkrypt\enkrypt_mcp_config.json
4.1.3生成的配置文件示例
🍎 Example file in macOS
- 这是macOS上CLI生成的默认配置文件的示例：
{
"common_mcp_gateway_config": {
"enkrypt_log_level": "INFO",
"enkrypt_base_url": "https://api.enkryptai.com",
"enkrypt_api_key": "YOUR_ENKRYPT_API_KEY",
"enkrypt_use_remote_mcp_config": false,
"enkrypt_remote_mcp_gateway_name": "enkrypt-secure-mcp-gateway-1",
"enkrypt_remote_mcp_gateway_version": "v1",
"enkrypt_mcp_use_external_cache": false,
"enkrypt_cache_host": "localhost",
"enkrypt_cache_port": 6379,
"enkrypt_cache_db": 0,
"enkrypt_cache_password": null,
"enkrypt_tool_cache_expiration": 4,
"enkrypt_gateway_cache_expiration": 24,
"enkrypt_async_input_guardrails_enabled": false,
"enkrypt_async_output_guardrails_enabled": false,
"enkrypt_telemetry": {
"enabled": true,
"insecure": true,
"endpoint": "http://localhost:4317"
}
},
"mcp_configs": {
"fcbd4508-1432-4f13-abb9-c495c946f638": {
"mcp_config_name": "default_config",
"mcp_config": [
{
"server_name": "echo_server",
"description": "Simple Echo Server",
"config": {
"command": "python",
"args": [
"/Users/user/enkryptai/secure-mcp-gateway/venv/lib/python3.13/site-packages/secure_mcp_gateway/bad_mcps/echo_mcp.py"
]
},
"tools": {},
"input_guardrails_config": {
"enabled": false,
"guardrail_name": "Sample Airline Guardrail",
"additional_config": {
"pii_redaction": false
},
"block": [
"policy_violation"
]
},
"output_guardrails_config": {
"enabled": false,
"guardrail_name": "Sample Airline Guardrail",
"additional_config": {
"relevancy": false,
"hallucination": false,
"adherence": false
},
"block": [
"policy_violation"
]
}
}
]
}
},
"projects": {
"3c09f06c-1f0d-4153-9ac5-366397937641": {
"project_name": "default_project",
"mcp_config_id": "fcbd4508-1432-4f13-abb9-c495c946f638",
"users": [
"6469a670-1d64-4da5-b2b3-790de21ac726"
],
"created_at": "2025-07-16T17:02:00.406877"
}
},
"users": {
"6469a670-1d64-4da5-b2b3-790de21ac726": {
"email": "default@example.com",
"created_at": "2025-07-16T17:02:00.406902"
}
},
"apikeys": {
"2W8UupCkazk4SsOcSu_1hAbiOgPdv0g-nN9NtfZyg-rvYGat": {
"project_id": "3c09f06c-1f0d-4153-9ac5-366397937641",
"user_id": "6469a670-1d64-4da5-b2b3-790de21ac726",
"created_at": "2025-07-16T17:02:00.406905"
}
}
}
🪟 Example file in Windows
- 这是Windows上CLI生成的默认配置文件的示例：
{
"common_mcp_gateway_config": {
"enkrypt_log_level": "INFO",
"enkrypt_base_url": "https://api.enkryptai.com",
"enkrypt_api_key": "YOUR_ENKRYPT_API_KEY",
"enkrypt_use_remote_mcp_config": false,
"enkrypt_remote_mcp_gateway_name": "enkrypt-secure-mcp-gateway-1",
"enkrypt_remote_mcp_gateway_version": "v1",
"enkrypt_mcp_use_external_cache": false,
"enkrypt_cache_host": "localhost",
"enkrypt_cache_port": 6379,
"enkrypt_cache_db": 0,
"enkrypt_cache_password": null,
"enkrypt_tool_cache_expiration": 4,
"enkrypt_gateway_cache_expiration": 24,
"enkrypt_async_input_guardrails_enabled": false,
"enkrypt_async_output_guardrails_enabled": false,
"enkrypt_telemetry": {
"enabled": true,
"insecure": true,
"endpoint": "http://localhost:4317"
}
},
"mcp_configs": {
"fcbd4508-1432-4f13-abb9-c495c946f638": {
"mcp_config_name": "default_config",
"mcp_config": [
{
"server_name": "echo_server",
"description": "Simple Echo Server",
"config": {
"command": "python",
"args": [
"C:\\Users\\\\Documents\\GitHub\\EnkryptAI\\secure-mcp-gateway\\.secure-mcp-gateway-venv\\Lib\\site-packages\\secure_mcp_gateway\\bad_mcps\\echo_mcp.py"
]
},
"tools": {},
"input_guardrails_config": {
"enabled": false,
"guardrail_name": "Sample Airline Guardrail",
"additional_config": {
"pii_redaction": false
},
"block": [
"policy_violation"
]
},
"output_guardrails_config": {
"enabled": false,
"guardrail_name": "Sample Airline Guardrail",
"additional_config": {
"relevancy": false,
"hallucination": false,
"adherence": false
},
"block": [
"policy_violation"
]
}
}
]
}
},
"projects": {
"3c09f06c-1f0d-4153-9ac5-366397937641": {
"project_name": "default_project",
"mcp_config_id": "fcbd4508-1432-4f13-abb9-c495c946f638",
"users": [
"6469a670-1d64-4da5-b2b3-790de21ac726"
],
"created_at": "2025-07-16T17:02:00.406877"
}
},
"users": {
"6469a670-1d64-4da5-b2b3-790de21ac726": {
"email": "default@example.com",
"created_at": "2025-07-16T17:02:00.406902"
}
},
"apikeys": {
"2W8UupCkazk4SsOcSu_1hAbiOgPdv0g-nN9NtfZyg-rvYGat": {
"project_id": "3c09f06c-1f0d-4153-9ac5-366397937641",
"user_id": "6469a670-1d64-4da5-b2b3-790de21ac726",
"created_at": "2025-07-16T17:02:00.406905"
}
}
}
4.1.4安装克劳德桌面网关
- 运行以下命令为Claude安装网关：
secure-mcp-gateway install --client claude-desktop- 这将在Claude Desktop上注册Enkrypt安全MCP网关。
- 注意：请在安装后重新启动Claude Desktop
🖨️ Example output
Initializing Enkrypt Secure MCP Gateway
Initializing Enkrypt Secure MCP Gateway Common Utilities Module
Initializing Enkrypt Secure MCP Gateway Module
--------------------------------
SYSTEM INFO:
Using Python interpreter: C:\Users\PC\Documents\GitHub\EnkryptAI\secure-mcp-gateway\.secure-mcp-gateway-venv\Scripts\python.exe
Python version: 3.13.3 (tags/v3.13.3:6280bb5, Apr 8 2025, 14:47:33) [MSC v.1943 64 bit (AMD64)]
Current working directory: C:\Users\PC\Documents\GitHub\EnkryptAI\secure-mcp-gateway
PYTHONPATH: Not set
--------------------------------
Installing dependencies...
All dependencies installed successfully.
Initializing Enkrypt Secure MCP Gateway Client Module
Initializing Enkrypt Secure MCP Gateway Guardrail Module
Error: Gateway key is required. Please update your mcp client config and try again.
Getting Enkrypt Common Configuration
config_path: C:\Users\PC\.enkrypt\enkrypt_mcp_config.json
example_config_path: C:\Users\PC\Documents\GitHub\EnkryptAI\secure-mcp-gateway\.secure-mcp-gateway-venv\Lib\site-packages\secure_mcp_gateway\example_enkrypt_mcp_config.json
Loading enkrypt_mcp_config.json file...
--------------------------------
ENKRYPT_GATEWAY_KEY: ****NULL
enkrypt_log_level: info
is_debug_log_level: False
enkrypt_base_url: https://api.enkryptai.com
enkrypt_use_remote_mcp_config: False
enkrypt_api_key: ****_KEY
enkrypt_tool_cache_expiration: 4
enkrypt_gateway_cache_expiration: 24
enkrypt_mcp_use_external_cache: False
enkrypt_async_input_guardrails_enabled: False
--------------------------------
External Cache is not enabled. Using local cache only.
Initializing Enkrypt Secure MCP Gateway CLI Module
CONFIG_PATH: C:\Users\PC\.enkrypt\enkrypt_mcp_config.json
GATEWAY_PY_PATH: C:\Users\PC\Documents\GitHub\EnkryptAI\secure-mcp-gateway\.secure-mcp-gateway-venv\Lib\site-packages\secure_mcp_gateway\gateway.py
client name from args: claude-desktop
Successfully installed gateway for claude-desktop
Path to gateway is incorrect. Modifying the path to gateway in claude_desktop_config.json file...
Path to gateway modified in claude_desktop_config.json file
Please restart Claude Desktop to use the gateway.
4.1.5安装后的Claude桌面配置示例
🍎 Example file in macOS
~/Library/Application Support/Claude/claude_desktop_config.json
{
"mcpServers": {
"Enkrypt Secure MCP Gateway": {
"command": "mcp",
"args": [
"run",
"/Users/user/enkryptai/secure-mcp-gateway/venv/lib/python3.13/site-packages/secure_mcp_gateway/gateway.py"
],
"env": {
"ENKRYPT_GATEWAY_KEY": "2W8UupCkazk4SsOcSu_1hAbiOgPdv0g-nN9NtfZyg-rvYGat",
"ENKRYPT_PROJECT_ID": "3c09f06c-1f0d-4153-9ac5-366397937641",
"ENKRYPT_USER_ID": "6469a670-1d64-4da5-b2b3-790de21ac726"
}
}
}
}🪟 Example file in Windows
%USERPROFILE%\AppData\Roaming\Claude\claude_desktop_config.json
{
"mcpServers": {
"Enkrypt Secure MCP Gateway": {
"command": "mcp",
"args": [
"run",
"C:\\Users\\\\Documents\\GitHub\\EnkryptAI\\secure-mcp-gateway\\.secure-mcp-gateway-venv\\Lib\\site-packages\\secure_mcp_gateway\\gateway.py"
],
"env": {
"ENKRYPT_GATEWAY_KEY": "2W8UupCkazk4SsOcSu_1hAbiOgPdv0g-nN9NtfZyg-rvYGat",
"ENKRYPT_PROJECT_ID": "3c09f06c-1f0d-4153-9ac5-366397937641",
"ENKRYPT_USER_ID": "6469a670-1d64-4da5-b2b3-790de21ac726"
}
}
}
}4.1.6安装游标网关
- 运行Cursor的CLI安装命令
secure-mcp-gateway install --client cursor- 这将自动用正确的条目更新您的~/.cursor/mcp.json（在Windows上，它位于：%USERPROFILE%.cursor\\mcp.json）。
- *虽然通常不需要重新启动，但如果您看到它长时间处于加载状态，请重新启动Cursor*
🍎 Example file in macOS
~/.cursor/mcp.json
{
"mcpServers": {
"Enkrypt Secure MCP Gateway": {
"command": "mcp",
"args": [
"run",
"/Users/user/enkryptai/secure-mcp-gateway/venv/lib/python3.13/site-packages/secure_mcp_gateway/gateway.py"
],
"env": {
"ENKRYPT_GATEWAY_KEY": "2W8UupCkazk4SsOcSu_1hAbiOgPdv0g-nN9NtfZyg-rvYGat",
"ENKRYPT_PROJECT_ID": "3c09f06c-1f0d-4153-9ac5-366397937641",
"ENKRYPT_USER_ID": "6469a670-1d64-4da5-b2b3-790de21ac726"
}
}
}
}🪟 Example file in Windows
%USERPROFILE%\.cursor\mcp.json
{
"mcpServers": {
"Enkrypt Secure MCP Gateway": {
"command": "uv",
"args": [
"run",
"--with",
"mcp[cli]",
"mcp",
"run",
"C:\\Users\\\\Documents\\GitHub\\EnkryptAI\\secure-mcp-gateway\\.secure-mcp-gateway-venv\\Lib\\site-packages\\secure_mcp_gateway\\gateway.py"
],
"env": {
"ENKRYPT_GATEWAY_KEY": "2W8UupCkazk4SsOcSu_1hAbiOgPdv0g-nN9NtfZyg-rvYGat",
"ENKRYPT_PROJECT_ID": "3c09f06c-1f0d-4153-9ac5-366397937641",
"ENKRYPT_USER_ID": "6469a670-1d64-4da5-b2b3-790de21ac726"
}
}
}
}4.1.7安装克劳德代码网关
克劳德代码 是Anthropic基于CLI的编码代理。它使用 claude mcp add 配置MCP服务器的命令。与使用JSON配置文件的Claude Desktop和Cursor不同，Claude Code通过自己的CLI管理MCP服务器。
先决条件： 这 claude CLI必须安装在您的系统上。看 Claude代码文档 用于安装。步骤1：安装网关
secure-mcp-gateway install --client claude-code这会自动：
- 从生成的配置中读取网关密钥、项目ID和用户ID
- 跑
claude mcp add具有正确的凭据和网关路径 - 向注册服务器
--scope user（适用于所有Claude Code项目）
步骤2：验证服务器是否已添加
claude mcp list你应该看看 Enkrypt-Secure-MCP-Gateway 在列表中。
步骤3：使用Claude Code中的网关
启动Claude Code并尝试：
list all servers, get all tools availableManual alternative (if you prefer to run claude mcp add directly)
从生成的中获取您的凭据 enkrypt_mcp_config.json 以及网关路径：
python -c "import secure_mcp_gateway.gateway; print(secure_mcp_gateway.gateway.__file__)"然后手动添加网关：
claude mcp add --transport stdio --env ENKRYPT_GATEWAY_KEY=YOUR_GATEWAY_KEY --env ENKRYPT_PROJECT_ID=YOUR_PROJECT_ID --env ENKRYPT_USER_ID=YOUR_USER_ID --scope user Enkrypt-Secure-MCP-Gateway -- mcp run /path/to/secure_mcp_gateway/gateway.py注： 服务器名称必须使用连字符或下划线——Claude Code不允许名称中有空格。
4.2使用git clone进行本地安装
🗂️ Git Clone Installation Steps
4.2.1克隆仓库，设置虚拟环境并安装依赖项
- 克隆存储库：
git clone https://github.com/enkryptai/secure-mcp-gateway
cd secure-mcp-gateway
⚡ Activate a virtual environment
# ------------------
# Create a virtual environment
# ------------------
uv venv
# Example output
Using CPython 3.13.3 interpreter at: C:\Users\PC\AppData\Local\Microsoft\WindowsApps\PythonSoftwareFoundation.Python.3.13_qbz5n2kfra8p0\python.exe
Creating virtual environment at: .venv
Activate with: .venv\Scripts\activate
# ------------------
# Activate the virtual environment
# ------------------
# For 🍎 Linux/macOS, run the following
source ./.venv/Scripts/activate
# For 🪟 Windows, run the following
.\.venv\Scripts\activate
# After activating, you should see (enkrypt-secure-mcp-gateway) before the file path in the terminal
# Example:
# (enkrypt-secure-mcp-gateway) %USERPROFILE%\Documents\GitHub\EnkryptAI\secure-mcp-gateway>
# ------------------
# Install pip in the virtual environment
# ------------------
python -m ensurepip
# ------------------
# Install uv in the virtual environment
# ------------------
python -m pip install uv
- 安装Python依赖项：
uv pip install -r requirements.txt
- 验证mcp-cli是否已成功安装：
mcp version
# Example output
MCP version 1.9.2
4.2.2运行安装脚本
- 此脚本在以下位置创建配置文件
~/.enkrypt/enkrypt_mcp_config.json在macOS和%USERPROFILE%\.enkrypt\enkrypt_mcp_config.json基于Windowssrc/secure_mcp_gateway/example_enkrypt_mcp_config.json文件
- 它取代了
UNIQUE_GATEWAY_KEY以及其他UUIDs具有自动生成的值，并替换DUMMY_MCP_FILE_PATH带有测试MCP文件的实际路径bad_mcps/echo_mcp.py
- 它还将MCP客户端安装在Claude Desktop中
- *注意：请在运行安装脚本后重新启动Claude Desktop，以查看网关在Claude Desktop中的运行情况*
# On 🍎 Linux/macOS run the below
cd scripts
chmod +x *.sh
./setup.sh
# On 🪟 Windows run the below
cd scripts
setup.bat
# Now restart Claude Desktop to see the Gateway running
🖨️ Example output
-------------------------------
Setting up Enkrypt Secure MCP Gateway enkrypt_mcp_config.json config file
-------------------------------
1 file(s) copied.
Generated unique gateway key: WTZOpoU1mXJz8b_ZJQ42DuSXlQCSCtWOn3FX0jG8sO_FKYNJetjYEgSluvhtBN8_
Generated unique uuid: 7920749a-228e-47fe-a6a9-cd2d64a2283b
DUMMY_MCP_FILE_PATH: C:\Users\PC\Documents\GitHub\EnkryptAI\secure-mcp-gateway\src\secure_mcp_gateway\bad_mcps\echo_mcp.py
-------------------------------
Setup complete. Please check the enkrypt_mcp_config.json file in the ~\.enkrypt directory and update with your MCP server configs as needed.
-------------------------------
-------------------------------
Installing Enkrypt Secure MCP Gateway with gateway key and dependencies
-------------------------------
mcp is installed. Proceeding with installation...
ENKRYPT_GATEWAY_KEY: WTZOpoU1mXJz8b_ZJQ42DuSXlQCSCtWOn3FX0jG8sO_FKYNJetjYEgSluvhtBN8_
The system cannot find the path specified.
Package names only:
Dependencies string for the cli install command:
Running the cli install command: mcp install gateway.py --env-var ENKRYPT_GATEWAY_KEY=WTZOpoU1mXJz8b_ZJQ42DuSXlQCSCtWOn3FX0jG8sO_FKYNJetjYEgSluvhtBN8_
Initializing Enkrypt Secure MCP Gateway
Initializing Enkrypt Secure MCP Gateway Common Utilities Module
Initializing Enkrypt Secure MCP Gateway Module
--------------------------------
SYSTEM INFO:
Using Python interpreter: C:\Users\PC\Documents\GitHub\EnkryptAI\secure-mcp-gateway\.secure-mcp-gateway-venv\Scripts\python.exe
Python version: 3.13.3 (tags/v3.13.3:6280bb5, Apr 8 2025, 14:47:33) [MSC v.1943 64 bit (AMD64)]
Current working directory: C:\Users\PC\Documents\GitHub\EnkryptAI\secure-mcp-gateway\src\secure_mcp_gateway
PYTHONPATH: Not set
--------------------------------
Installing dependencies...
All dependencies installed successfully.
Initializing Enkrypt Secure MCP Gateway Client Module
Initializing Enkrypt Secure MCP Gateway Guardrail Module
Getting Enkrypt Common Configuration
config_path: C:\Users\PC\.enkrypt\enkrypt_mcp_config.json
example_config_path: C:\Users\PC\Documents\GitHub\EnkryptAI\secure-mcp-gateway\.secure-mcp-gateway-venv\Lib\site-packages\secure_mcp_gateway\example_enkrypt_mcp_config.json
Loading enkrypt_mcp_config.json file...
--------------------------------
ENKRYPT_GATEWAY_KEY: ****BN8_
enkrypt_log_level: info
is_debug_log_level: False
enkrypt_base_url: https://api.enkryptai.com
enkrypt_use_remote_mcp_config: False
enkrypt_api_key: ****_KEY
enkrypt_tool_cache_expiration: 4
enkrypt_gateway_cache_expiration: 24
enkrypt_mcp_use_external_cache: False
enkrypt_async_input_guardrails_enabled: False
--------------------------------
External Cache is not enabled. Using local cache only.
Initializing Enkrypt Secure MCP Gateway Module
--------------------------------
SYSTEM INFO:
Using Python interpreter: C:\Users\PC\Documents\GitHub\EnkryptAI\secure-mcp-gateway\.secure-mcp-gateway-venv\Scripts\python.exe
Python version: 3.13.3 (tags/v3.13.3:6280bb5, Apr 8 2025, 14:47:33) [MSC v.1943 64 bit (AMD64)]
Current working directory: C:\Users\PC\Documents\GitHub\EnkryptAI\secure-mcp-gateway\src\secure_mcp_gateway
PYTHONPATH: Not set
--------------------------------
Installing dependencies...
All dependencies installed successfully.
Getting Enkrypt Common Configuration
config_path: C:\Users\PC\.enkrypt\enkrypt_mcp_config.json
example_config_path: C:\Users\PC\Documents\GitHub\EnkryptAI\secure-mcp-gateway\.secure-mcp-gateway-venv\Lib\site-packages\secure_mcp_gateway\example_enkrypt_mcp_config.json
Loading enkrypt_mcp_config.json file...
--------------------------------
ENKRYPT_GATEWAY_KEY: ****BN8_
enkrypt_log_level: info
is_debug_log_level: False
enkrypt_base_url: https://api.enkryptai.com
enkrypt_use_remote_mcp_config: False
enkrypt_api_key: ****_KEY
enkrypt_tool_cache_expiration: 4
enkrypt_gateway_cache_expiration: 24
enkrypt_mcp_use_external_cache: False
enkrypt_async_input_guardrails_enabled: False
--------------------------------
External Cache is not enabled. Using local cache only.
[06/15/25 13:14:10] INFO Added server 'Enkrypt Secure MCP Gateway' to Claude config claude.py:137
INFO Successfully installed Enkrypt Secure MCP Gateway in Claude app cli.py:486
-------------------------------
Installation complete. Check the claude_desktop_config.json file as per the readme instructions and restart Claude Desktop.
-------------------------------
4.2.3设置其他MCP客户端
⬡ Cursor
- 您可以导航到光标的 全球MCP 文件在
~/.cursor/mcp.json在Linux/macOS或%USERPROFILE%\.cursor\mcp.json在Windows上
- 如果你想在a 项目级别 把它放在你的项目中。有关详细信息，请参阅 Cursor的文档
- 您还可以通过单击光标的UI导航到文件
settings右上角的齿轮图标
- 点击
MCP然后单击Add new global MCP server这会带你去mcp.json文件
- 示例
mcp.json在编辑器中打开的文件
- 在全局或项目级别打开文件后，您可以复制粘贴我们在中使用的相同配置
Claude Desktop。作为参考，您可以参考 安装-6.2生成的MCP配置文件示例📄
- *请确保使用您自己的文件，该文件由 setup 脚本在 安装-4.2.2运行安装脚本📥。请不要复制粘贴此仓库中的示例配置文件。*
- 看 验证光标 验证MCP服务器是否在Cursor中运行的部分
⬡ Claude Code
- 克劳德代码 使用自己的CLI来管理MCP服务器，而不是JSON配置文件
- 从生成的中获取您的凭据
enkrypt_mcp_config.json（网关密钥、项目ID、用户ID）
- 查找gateway.py路径：
python -c "import secure_mcp_gateway.gateway; print(secure_mcp_gateway.gateway.__file__)"- 将网关添加到Claude Code：
claude mcp add --transport stdio --env ENKRYPT_GATEWAY_KEY=YOUR_GATEWAY_KEY --env ENKRYPT_PROJECT_ID=YOUR_PROJECT_ID --env ENKRYPT_USER_ID=YOUR_USER_ID --scope user Enkrypt-Secure-MCP-Gateway -- mcp run /path/to/secure_mcp_gateway/gateway.py- 验证：
claude mcp list
- 有关详细设置，请参阅 4.1.7安装克劳德代码网关
4.3 Docker安装
🐳 Docker Installation Steps
4.3.1构建Docker镜像
docker build -t secure-mcp-gateway .
🖨️ Example output
[+] Building 72.9s (20/20) FINISHED docker:default
=> [internal] load build definition from Dockerfile 0.1s
=> => transferring dockerfile: 724B 0.1s
=> [internal] load metadata for docker.io/library/python:3.11-alpine 1.0s
=> [internal] load .dockerignore 0.1s
=> => transferring context: 456B 0.1s
=> [ 1/15] FROM docker.io/library/python:3.11-alpine@sha256:8068890a42d68ece5b62455ef327253249b5f094dcdee57f492635a40217f6a3 0.0s
=> => resolve docker.io/library/python:3.11-alpine@sha256:8068890a42d68ece5b62455ef327253249b5f094dcdee57f492635a40217f6a3 0.0s
=> [internal] load build context 1.5s
=> => transferring context: 82.25kB 1.4s
=> CACHED [ 2/15] WORKDIR /app 0.0s
=> CACHED [ 3/15] COPY requirements.txt . 0.0s
=> [ 4/15] COPY requirements-dev.txt . 0.0s
=> [ 5/15] RUN pip install --upgrade pip && pip install -r requirements.txt && pip install -r requirements-dev.txt 38.7s
=> [ 6/15] COPY src src 0.2s
=> [ 7/15] COPY setup.py setup.py 0.1s
=> [ 8/15] COPY MANIFEST.in MANIFEST.in 0.1s
=> [ 9/15] COPY pyproject.toml pyproject.toml 0.1s
=> [10/15] COPY CHANGELOG.md CHANGELOG.md 0.1s
=> [11/15] COPY LICENSE.txt LICENSE.txt 0.1s
=> [12/15] COPY README.md README.md 0.1s
=> [13/15] COPY README_PYPI.md README_PYPI.md 0.1s
=> [14/15] RUN python -m build 8.5s
=> [15/15] RUN pip install . 5.5s
=> exporting to image 16.6s
=> => exporting layers 11.8s
=> => exporting manifest sha256:47bd860c903fdefeda59364f577c487f96e1482b0e8eadef8292df86922641dc 0.0s
=> => exporting config sha256:9d211386091dfc08fcfe80f1efb399d4a1ab80484f850476c328614ecaaefbae 0.1s
=> => exporting attestation manifest sha256:bc85b5aaf4035e6f449d9b94567135a28a61c594fa2a507ca7fea889efbf2952 0.0s
=> => exporting manifest list sha256:7cd30cbf456ba3105d4bef7c28ea8402ec5476e4da3cd8c16b752f3214f8b3b1 0.0s
=> => naming to docker.io/library/secure-mcp-gateway:latest 0.0s
=> => unpacking to docker.io/library/secure-mcp-gateway:latest
4.3.2生成配置文件
- 这将在中创建一个配置文件
~/.enkrypt/docker/enkrypt_mcp_config.jsonmacOS/Linux上的文件%USERPROFILE%\.enkrypt\docker\enkrypt_mcp_config.jsonWindows上的文件。
快速速记 --如果您通过pip在本地安装了CLI，则可以使用--docker标记任何命令并跳过冗长的Docker语法： ``bash secure-mcp-gateway --docker generate-config``
Verbose Docker run commands (if CLI is not installed locally)
# On 🍎 Linux/macOS run the below
docker run --rm -e HOST_OS=macos -e HOST_ENKRYPT_HOME=$HOME/.enkrypt -v ~/.enkrypt/docker:/app/.enkrypt/docker --entrypoint python secure-mcp-gateway -m secure_mcp_gateway.cli generate-config
# On 🪟 Windows (CMD) run the below
docker run --rm -e HOST_OS=windows -e HOST_ENKRYPT_HOME=%USERPROFILE%\.enkrypt -v %USERPROFILE%\.enkrypt\docker:/app/.enkrypt/docker --entrypoint python secure-mcp-gateway -m secure_mcp_gateway.cli generate-config
# On 🪟 Windows (📟 PowerShell) run the below
docker run --rm -e HOST_OS=windows -e "HOST_ENKRYPT_HOME=$env:USERPROFILE\.enkrypt" -v "$env:USERPROFILE\.enkrypt\docker:/app/.enkrypt/docker" --entrypoint python secure-mcp-gateway -m secure_mcp_gateway.cli generate-config
🐳 Example Docker config file
{
"common_mcp_gateway_config": {
"enkrypt_log_level": "INFO",
"enkrypt_base_url": "https://api.enkryptai.com",
"enkrypt_api_key": "YOUR_ENKRYPT_API_KEY",
"enkrypt_use_remote_mcp_config": false,
"enkrypt_remote_mcp_gateway_name": "enkrypt-secure-mcp-gateway-1",
"enkrypt_remote_mcp_gateway_version": "v1",
"enkrypt_mcp_use_external_cache": false,
"enkrypt_cache_host": "localhost",
"enkrypt_cache_port": 6379,
"enkrypt_cache_db": 0,
"enkrypt_cache_password": null,
"enkrypt_tool_cache_expiration": 4,
"enkrypt_gateway_cache_expiration": 24,
"enkrypt_async_input_guardrails_enabled": false,
"enkrypt_async_output_guardrails_enabled": false,
"enkrypt_telemetry": {
"enabled": true,
"insecure": true,
"endpoint": "http://localhost:4317"
}
},
"mcp_configs": {
"fcbd4508-1432-4f13-abb9-c495c946f638": {
"mcp_config_name": "default_config",
"mcp_config": [
{
"server_name": "echo_server",
"description": "Simple Echo Server",
"config": {
"command": "python",
"args": [
"/usr/local/lib/python3.11/site-packages/secure_mcp_gateway/bad_mcps/echo_mcp.py"
]
},
"tools": {},
"input_guardrails_config": {
"enabled": false,
"guardrail_name": "Sample Airline Guardrail",
"additional_config": {
"pii_redaction": false
},
"block": [
"policy_violation"
]
},
"output_guardrails_config": {
"enabled": false,
"guardrail_name": "Sample Airline Guardrail",
"additional_config": {
"relevancy": false,
"hallucination": false,
"adherence": false
},
"block": [
"policy_violation"
]
}
}
]
}
},
"projects": {
"3c09f06c-1f0d-4153-9ac5-366397937641": {
"project_name": "default_project",
"mcp_config_id": "fcbd4508-1432-4f13-abb9-c495c946f638",
"users": [
"6469a670-1d64-4da5-b2b3-790de21ac726"
],
"created_at": "2025-07-16T17:02:00.406877"
}
},
"users": {
"6469a670-1d64-4da5-b2b3-790de21ac726": {
"email": "default@example.com",
"created_at": "2025-07-16T17:02:00.406902"
}
},
"apikeys": {
"2W8UupCkazk4SsOcSu_1hAbiOgPdv0g-nN9NtfZyg-rvYGat": {
"project_id": "3c09f06c-1f0d-4153-9ac5-366397937641",
"user_id": "6469a670-1d64-4da5-b2b3-790de21ac726",
"created_at": "2025-07-16T17:02:00.406905"
}
}
}
4.3.3在Claude Desktop中安装网关
- 您可以在系统中的以下位置找到Claude配置位置。 有关参考，请参阅Claude文档。
- macOS： ~/Library/Application Support/Claude - 窗户： %APPDATA%\Claude
注： 生成的配置包括 MCP_TRANSPORT=stdio 用于与Claude Desktop进行stdio模式通信。
# On 🍎 Linux/macOS run the below
docker run --rm -i -e HOST_OS=macos -e HOST_ENKRYPT_HOME=$HOME/.enkrypt -v ~/.enkrypt/docker:/app/.enkrypt/docker -v ~/Library/Application\ Support/Claude:/app/.claude --entrypoint python secure-mcp-gateway -m secure_mcp_gateway.cli install --client claude-desktop
# On 🪟 Windows (CMD) run the below
docker run --rm -i -e HOST_OS=windows -e HOST_ENKRYPT_HOME=%USERPROFILE%\.enkrypt -v %USERPROFILE%\.enkrypt\docker:/app/.enkrypt/docker -v %APPDATA%\Claude:/app/.claude --entrypoint python secure-mcp-gateway -m secure_mcp_gateway.cli install --client claude-desktop
# On 🪟 Windows (📟 PowerShell) run the below
docker run --rm -i -e HOST_OS=windows -e "HOST_ENKRYPT_HOME=$env:USERPROFILE\.enkrypt" -v "$env:USERPROFILE\.enkrypt\docker:/app/.enkrypt/docker" -v "$env:APPDATA\Claude:/app/.claude" --entrypoint python secure-mcp-gateway -m secure_mcp_gateway.cli install --client claude-desktop
4.3.4 Claude桌面配置文件示例
🪟 Example Windows claude_desktop_config.json
{
"mcpServers": {
"Enkrypt Secure MCP Gateway": {
"command": "docker",
"args": [
"run",
"--rm",
"-i",
"-e",
"MCP_TRANSPORT=stdio",
"-v",
"C:\\Users\\\\.enkrypt\\docker:/app/.enkrypt/docker",
"secure-mcp-gateway"
],
"env": {
"ENKRYPT_GATEWAY_KEY": "2W8UupCkazk4SsOcSu_1hAbiOgPdv0g-nN9NtfZyg-rvYGat",
"ENKRYPT_PROJECT_ID": "3c09f06c-1f0d-4153-9ac5-366397937641",
"ENKRYPT_USER_ID": "6469a670-1d64-4da5-b2b3-790de21ac726"
}
}
}
}
4.3.5在游标中安装网关
- 您可以在以下位置找到Cursor配置位置。 有关参考信息，请参阅Cursor文档。
- macOS： ~/.cursor - 窗户： %USERPROFILE%\.cursor
注： 生成的配置包括 MCP_TRANSPORT=stdio 用于与Cursor进行stdio模式通信。
# On 🍎 Linux/macOS run the below
docker run --rm -i -e HOST_OS=macos -e HOST_ENKRYPT_HOME=$HOME/.enkrypt -v ~/.enkrypt/docker:/app/.enkrypt/docker -v ~/.cursor:/app/.cursor --entrypoint python secure-mcp-gateway -m secure_mcp_gateway.cli install --client cursor
# On 🪟 Windows (CMD) run the below
docker run --rm -i -e HOST_OS=windows -e HOST_ENKRYPT_HOME=%USERPROFILE%\.enkrypt -v %USERPROFILE%\.enkrypt\docker:/app/.enkrypt/docker -v %USERPROFILE%\.cursor:/app/.cursor --entrypoint python secure-mcp-gateway -m secure_mcp_gateway.cli install --client cursor
# On 🪟 Windows (📟 PowerShell) run the below
docker run --rm -i -e HOST_OS=windows -e "HOST_ENKRYPT_HOME=$env:USERPROFILE\.enkrypt" -v "$env:USERPROFILE\.enkrypt\docker:/app/.enkrypt/docker" -v "$env:USERPROFILE\.cursor:/app/.cursor" --entrypoint python secure-mcp-gateway -m secure_mcp_gateway.cli install --client cursor
4.3.6在Claude代码中安装网关
Claude Code使用自己的CLI(claude mcp add)管理MCP服务器。在Docker中运行网关时，Claude Code通过以下方式连接 npx mcp-remote 连接到网关的Streamable HTTP端点。
先决条件： Node.js和npm必须安装在您的计算机上(node -v和npm -v验证）。
步骤1：运行网关容器
将网关作为后台Docker容器启动，并暴露Streamable HTTP端点：
# On 🍎 Linux/macOS
docker run -d --name enkrypt-gateway -p 8000:8000 -v ~/.enkrypt/docker:/app/.enkrypt/docker secure-mcp-gateway
# On 🪟 Windows (PowerShell)
docker run -d --name enkrypt-gateway -p 8000:8000 -v "$env:USERPROFILE\.enkrypt\docker:/app/.enkrypt/docker" secure-mcp-gateway步骤2：将网关添加到Claude Code
claude mcp add --transport http --header "apikey:YOUR_GATEWAY_KEY" --header "project_id:YOUR_PROJECT_ID" --header "user_id:YOUR_USER_ID" --scope user Enkrypt-Secure-MCP-Gateway http://localhost:8000/mcp/替换 YOUR_GATEWAY_KEY, YOUR_PROJECT_ID，以及 YOUR_USER_ID 用你的价值观 enkrypt_mcp_config.json.
Alternative: stdio mode via Docker
如果你喜欢stdio模式（没有持久容器），你可以直接使用JSON添加Claude Code的MCP配置。创建或编辑 ~/.claude.json 并在下面添加服务器 mcpServers:
{
"mcpServers": {
"Enkrypt Secure MCP Gateway": {
"command": "docker",
"args": [
"run",
"--rm",
"-i",
"-e",
"MCP_TRANSPORT=stdio",
"-v",
"/Users//.enkrypt/docker:/app/.enkrypt/docker",
"secure-mcp-gateway"
],
"env": {
"ENKRYPT_GATEWAY_KEY": "YOUR_GATEWAY_KEY",
"ENKRYPT_PROJECT_ID": "YOUR_PROJECT_ID",
"ENKRYPT_USER_ID": "YOUR_USER_ID"
}
}
}
}或者使用Claude Code CLI：
claude mcp add-json Enkrypt-Secure-MCP-Gateway '{
"type": "stdio",
"command": "docker",
"args": ["run", "--rm", "-i", "-e", "MCP_TRANSPORT=stdio", "-v", "/Users//.enkrypt/docker:/app/.enkrypt/docker", "secure-mcp-gateway"],
"env": {
"ENKRYPT_GATEWAY_KEY": "YOUR_GATEWAY_KEY",
"ENKRYPT_PROJECT_ID": "YOUR_PROJECT_ID",
"ENKRYPT_USER_ID": "YOUR_USER_ID"
}
}'关于Windows（PowerShell）的说明： 替换/Users//.enkrypt/docker使用您的Windows路径（例如。，C:\Users\\.enkrypt\docker)并相应地调整音量挂载语法。
步骤3：验证
claude mcp list步骤4：在Claude代码中使用
启动Claude Code并尝试以下提示 list all servers, get all tools available.
4.3.7使用Docker Run运行网关（高级）
对于高级Docker部署，您可以使用自定义配置直接运行网关容器：
# Basic Docker run command
docker run -d --name enkrypt-gateway -p 8000:8000 -v ~/.enkrypt/docker:/app/.enkrypt/docker -e ENKRYPT_GATEWAY_KEY="your-gateway-key" -e ENKRYPT_PROJECT_ID="your-project-id" -e ENKRYPT_USER_ID="your-user-id" secure-mcp-gateway:latestWindows PowerShell：
docker run -d `
--name enkrypt-gateway `
-p 8000:8000 `
-v "$env:USERPROFILE\.enkrypt\docker:/app/.enkrypt/docker" `
-e ENKRYPT_GATEWAY_KEY="your-gateway-key" `
-e ENKRYPT_PROJECT_ID="your-project-id" `
-e ENKRYPT_USER_ID="your-user-id" `
secure-mcp-gateway:latest环境变量
| 变量 | 描述 | 默认值 | 必填 |
|---|---|---|---|
ENKRYPT_GATEWAY_KEY | 用于身份验证的API密钥 | - | 是 |
ENKRYPT_PROJECT_ID | 配置中的项目ID | - | 是 |
ENKRYPT_USER_ID | 配置中的用户ID | - | 是 |
MCP_TRANSPORT | 运输方式： streamable-http 或 stdio | streamable-http | 没有 |
SKIP_DEPENDENCY_INSTALL | 跳过运行时依赖项安装 | true （Docker）， false （其他） | 否 |
HOST | 网关绑定地址 | 0.0.0.0 | 没有 |
FASTAPI_HOST | FastAPI服务器绑定地址 | 0.0.0.0 | 没有 |
MCP运输
这 MCP_TRANSPORT 环境变量控制网关的传输模式。
运输方式：
streamable-http（默认）：端口8000上的HTTP服务器模式。与...一起使用-p 8000:8000用于端口映射。stdio：通过stdin/stdout通信的MCP客户端的标准输入/输出模式。与...一起使用-i旗帜。
stdio模式示例（克劳德桌面、光标）：
docker run --rm -i -e MCP_TRANSPORT=stdio -v ~/.enkrypt/docker:/app/.enkrypt/docker -e ENKRYPT_GATEWAY_KEY="your-gateway-key" secure-mcp-gatewaySKIP_redependency_INSTALL
这 SKIP_DEPENDENCY_INSTALL 环境变量控制网关是否在运行时重新安装Python依赖项。
默认行为：
- Docker环境：默认为
true（自动检测）。依赖关系已预先安装在Docker映像中，因此会自动跳过运行时安装。 - 非Docker环境：默认为
false。启动时安装依赖项以确保兼容性。
何时显式设置 SKIP_DEPENDENCY_INSTALL=false 在Docker中：
- 测试新依赖关系的开发环境
- 为实时开发装载源代码卷时
- 如果您不确定是否正确安装了所有依赖项
何时显式设置 SKIP_DEPENDENCY_INSTALL=true Docker之外：
- 预安装依赖项的生产部署
- 缩短启动时间（更快的冷启动）
- 在您已经运行过的环境中
pip install
docker compose集成示例：
# Connect to observability stack network
# Note: SKIP_DEPENDENCY_INSTALL defaults to true in Docker, so it's optional
docker run -d --name enkrypt-gateway --network secure-mcp-gateway-infra_default -p 8000:8000 -p 8080:8080 -v ~/.enkrypt/docker:/app/.enkrypt/docker -e ENKRYPT_GATEWAY_KEY="your-gateway-key" -e ENKRYPT_PROJECT_ID="your-project-id" -e ENKRYPT_USER_ID="your-user-id" secure-mcp-gateway:latestWindows PowerShell：
# Note: SKIP_DEPENDENCY_INSTALL defaults to true in Docker, so it's optional
docker run -d `
--name enkrypt-gateway `
--network secure-mcp-gateway-infra_default `
-p 8000:8000 `
-p 8080:8080 `
-v "$env:USERPROFILE\.enkrypt\docker:/app/.enkrypt/docker" `
-e ENKRYPT_GATEWAY_KEY="your-gateway-key" `
-e ENKRYPT_PROJECT_ID="your-project-id" `
-e ENKRYPT_USER_ID="your-user-id" `
secure-mcp-gateway:latest注： 这 --network 如果您正在运行第5节中的监控服务，则标志将网关连接到可观察性堆栈（Grafana、Prometheus、Loki、Jaeger）。
端口映射
8000：网关MCP服务器（必需）8080：OAuth回调服务器（可选，仅授权码流需要）8001：REST API服务器（可选，如果要公开管理API）
卷装载
~/.enkrypt/docker:/app/.enkrypt/docker-配置文件位置（必填）- 如果您的MCP服务器需要访问本地文件，可能需要额外的挂载
⚠️ 重要提示： MCP客户端（Claude Desktop、Cursor、Claude Code）无需shell即可直接生成Docker，因此~（波浪号）将 不 扩大。总是使用 绝对路径 在MCP客户端配置JSON文件中（例如。/Users/yourname/.enkrypt/docker:/app/.enkrypt/docker在macOS/Linux或C:\\Users\\yourname\\.enkrypt\\docker:/app/.enkrypt/docker在Windows上）。
⚠️ 重要提示：网关在Docker中运行时配置MCP服务器
在Docker中运行Enkrypt网关时， 不要将MCP服务器配置为也在Docker模式下运行。这会导致Docker中的Docker问题、网络问题和卷挂载复杂性。
❌ 避免（基于Docker的MCP服务器）：
{
"server_name": "github_server",
"config": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"-e",
"GITHUB_PERSONAL_ACCESS_TOKEN",
"ghcr.io/github/github-mcp-server"
],
"env": {
"GITHUB_PERSONAL_ACCESS_TOKEN": "your-token"
}
}
}✅ 请改用（基于npx/npm/Python的服务器）：
{
"server_name": "github_server",
"config": {
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-github"
],
"env": {
"GITHUB_PERSONAL_ACCESS_TOKEN": "your-token"
}
}
}为什么？
- Docker中的Docker需要特权模式和特殊的套接字挂载
- 网络隔离会阻止容器正常通信
- 跨容器边界的卷装载无法按预期工作
- 性能开销和安全问题
- 增加了复杂性和调试难度
Gateway在Docker中时推荐的MCP服务器格式：
- ✅ 基于npx的服务器:
npx -y @modelcontextprotocol/server-* - ✅ 基于npm的服务器:
npm exec -y server-name - ✅ 基于Python的服务器:
python /path/to/server.py或uv run server.py - ✅ 基于Node.js的服务器:
node /path/to/server.js - ✅ 远程MCP服务器:
npx mcp-remote https://api.example.com/mcp/
例外情况：
如果您必须使用基于Docker的MCP服务器，请考虑：
- 在Docker之外运行网关（本地安装），或者
- 通过以下方式设置适当的Docker网络
--network host或定制网桥网络，或 - 在Docker中使用Docker并进行适当的配置（需要
--privileged旗和/var/run/docker.sock挂载- 不建议用于生产)
4.4远程安装
🌐 Remote Installation Steps
4.4.1在远程服务器中运行网关
python gateway.py
- 或者使用我们的docker镜像在k8s中运行
enkryptai/secure-mcp-gateway:vx.x.x
- 例子：
enkryptai/secure-mcp-gateway:v2.1.2
- 使用Docker Hub的最新版本：
- 您可以在本地挂载配置文件，也可以从远程位置下载json文件，例如
S3使用ainitContainer并安装卷
- 看
docs/secure-mcp-gateway-manifest-example.yaml获取完整的清单文件参考
4.4.2修改MCP客户端配置以使用网关
- 您可以在系统中的以下位置找到Claude Desktop配置位置。 有关参考，请参阅Claude文档。
- macOS： ~/Library/Application Support/Claude - 窗户： %APPDATA%\Claude
- 您可以在以下位置找到Cursor配置位置。 有关参考信息，请参阅Cursor文档。
- macOS： ~/.cursor - 窗户： %USERPROFILE%\.cursor
- 替换
ENKRYPT_GATEWAY_KEY用你从enkrypt_mcp_config.json文件
- 替换
http://0.0.0.0:8000/mcp/随着 `http(s)://:
/mcp/`
- 如果您在本地运行此程序，则可以使用
http://0.0.0.0:8000/mcp/
- 您可以设置入口，通过以下方式将流量路由到MCP网关
https
- 例子：
https://mcp.enkryptai.com/mcp/
- 注意：请确保客户端计算机上安装了node和npm
- 要验证，请运行 node -v 和 npm -v
- 注意：确保使用尾随斜线
/在MCP URL中，类似/mcp/
适用于Claude桌面和光标 --将以下内容添加到您的 claude_desktop_config.json 或 mcp.json:
{
"mcpServers": {
"Enkrypt Secure MCP Gateway": {
"command": "npx",
"args": [
"mcp-remote",
"http://0.0.0.0:8000/mcp/",
"--allow-http",
"--header",
"apikey:${ENKRYPT_GATEWAY_KEY}",
"--header",
"project_id:${ENKRYPT_PROJECT_ID}",
"--header",
"user_id:${ENKRYPT_USER_ID}"
],
"env": {
"ENKRYPT_GATEWAY_KEY": "2W8UupCkazk4SsOcSu_1hAbiOgPdv0g-nN9NtfZyg-rvYGat",
"ENKRYPT_PROJECT_ID": "3c09f06c-1f0d-4153-9ac5-366397937641",
"ENKRYPT_USER_ID": "6469a670-1d64-4da5-b2b3-790de21ac726"
}
}
}
}
克劳德代码 --使用 claude mcp add 命令：
# Connect Claude Code to the remote gateway via HTTP transport
claude mcp add --transport http --header "apikey:YOUR_GATEWAY_KEY" --header "project_id:YOUR_PROJECT_ID" --header "user_id:YOUR_USER_ID" --scope user Enkrypt-Secure-MCP-Gateway https://mcp.your-domain.com/mcp/注： 对于使用HTTP（不是HTTPS）的本地测试，请添加--allow-http如果需要，或使用http://0.0.0.0:8000/mcp/作为URL。
5.（可选）开放遥测设置
📊 OpenTelemetry Setup and Usage
本节解释了如何使用Enkrypt Secure MCP网关设置和使用开放遥测（OTEL）以实现可观察性。
5.1架构
可观测性堆栈包括：
- OpenTetry Collector：收集遥测数据（跟踪、指标、日志）
- Jaeger：分布式跟踪可视化
- Loki：日志聚合和查询
- Prometheus：度量聚合
- Grafana：指标和日志的统一可视化
- 由于某种原因，Grafana中看不到痕迹。请使用Jaeger进行追踪。
5.2先决条件
- 已安装Docker和Docker Compose
- 网关已安装并正在运行（请遵循 第4节)
5.3设置步骤
- 启动可观测性堆栈
cd infra
docker-compose up -d- 停止Observability堆栈
# When we want to stop the Observability Stack, run the below command
docker-compose down5.4配置
- 编辑
enkrypt_mcp_config.json启用遥测的文件
{
"common_mcp_gateway_config": {
...
"enkrypt_telemetry": {
"enabled": true,
"insecure": true,
"endpoint": "http://localhost:4317"
}
},
...
}5.5验证步骤
- 验证服务是否正在运行
# On Windows
docker ps | findstr "loki grafana jaeger otel prometheus"
# On Linux/macOS
docker ps | grep -E "loki|grafana|jaeger|otel|prometheus"- 访问服务UI
- 图表 ： （默认凭据：admin/admin）
- 耶格尔：
- 普罗米修斯：
- 洛基：通过格拉法纳进入
1. 打开Grafana() 1. 前往探索（左侧边栏） 1. 从数据源下拉列表中选择“Loki”
- 验证网关遥测
- 通过网关发出测试请求，如 List all servers and tools 和 echo test
- 检查Jaeger中的痕迹：
- 添加可选标签，如 enkrypt_email=default@example.com 或 enkrypt_project_name=default_project 或 enkrypt_mcp_config_id=fcbd4508-1432-4f13-abb9-c495c946f638 查看特定用户、项目或MCP配置等的跟踪。
- 我们还可以通过用空格分隔标签来组合标签，例如 enkrypt_email=default@example.com enkrypt_project_name=default_project
- 寻找 enkrypt_discover_all_tools 跨度
- 检查缓存、工具发现等的子跨度。
- 查看Grafana中的指标：
- 导航到 Drilldown -> metrics
- 我们可以过滤各种标签，比如 email, user_id, mcp_config_id, project_id, project_name 等等
- 检查Grafana的日志
- 导航到 Drilldown -> Logs
- 选择标签为 service_name=secure-mcp-gateway 然后单击 Show logs
- 现在我们可以通过各种标签进行过滤，比如 attributes_project_name, attributes_project_id, attributes_email, attributes_user_id, attributes_mcp_config_id, attributes_tool_name 等等
- 通过导航到以下位置查看Grafana中的仪表板 Dashboards -> OpenTelemetry Gateway Metrics
- 由于Grafana中的问题，您可能需要编辑每个互动程序并单击 Run queries 查看数据
5.6可用遥测技术（并非详尽无遗）
- 痕迹
- 请求处理管道 - 具有持续时间跟踪功能的工具调用 - 缓存操作（命中/未命中） - 护栏检查 - 错误跟踪和状态监控 - 调试的详细属性
- 指标
- enkrypt_list_all_servers_calls：API端点使用情况 - mcp_cache_misses_total：缓存效率跟踪 - enkrypt_servers_discovered：服务器发现监视 - mcp_tool_calls_total：工具调用跟踪 - mcp_tool_call_duration_seconds：性能监控（直方图）
- 日志
- 结构化JSON格式，便于查询 - 具有上下文的网关操作 - 堆栈跟踪的错误情况 - 安全事件和护栏检查 - 带有计时信息的性能数据
6.验证安装并检查生成的文件
✅ Verification steps and files generated
6.1验证克劳德桌面
- 要验证Claude的安装，请导航到
claude_desktop_config.json文件由 遵循以下说明
- macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
- 窗户： %APPDATA%\Claude\claude_desktop_config.json
6.2生成的MCP配置文件示例
🍎 Example file in macOS
~/Library/Application Support/Claude/claude_desktop_config.json
{
"mcpServers": {
"Enkrypt Secure MCP Gateway": {
"command": "mcp",
"args": [
"run",
"/Users/user/enkryptai/secure-mcp-gateway/src/secure_mcp_gateway/gateway.py"
],
"env": {
"ENKRYPT_GATEWAY_KEY": "2W8UupCkazk4SsOcSu_1hAbiOgPdv0g-nN9NtfZyg-rvYGat",
"ENKRYPT_PROJECT_ID": "3c09f06c-1f0d-4153-9ac5-366397937641",
"ENKRYPT_USER_ID": "6469a670-1d64-4da5-b2b3-790de21ac726"
}
}
}
}🪟 Example file in Windows
%USERPROFILE%\AppData\Roaming\Claude\claude_desktop_config.json
{
"mcpServers": {
"Enkrypt Secure MCP Gateway": {
"command": "mcp",
"args": [
"run",
"C:\\Users\\\\Documents\\GitHub\\EnkryptAI\\secure-mcp-gateway\\src\\secure_mcp_gateway\\gateway.py"
],
"env": {
"ENKRYPT_GATEWAY_KEY": "2W8UupCkazk4SsOcSu_1hAbiOgPdv0g-nN9NtfZyg-rvYGat",
"ENKRYPT_PROJECT_ID": "3c09f06c-1f0d-4153-9ac5-366397937641",
"ENKRYPT_USER_ID": "6469a670-1d64-4da5-b2b3-790de21ac726"
}
}
}
}6.3重新启动Claude Desktop以运行网关
- 重新启动后，导航到Claude Desktop
Settings
- 点击
Developer->Enkrypt Secure MCP Gateway
Claude Desktop MCP Gateway Running
🧰 Check tools and logs
- 您还可以单击搜索栏下方的设置图标，查看可用的网关
Claude Desktop Gateway in Search
- 点击
Enkrypt Secure MCP Gateway查看可用工具列表
Claude Desktop MCP Gateway Tools
- 您可以检查Claude日志，同时要求Claude做一些事情来查看Gateway的运行情况
- 示例🍎 Linux/macOS日志路径： ~/Library/Application Support/Claude/logs/mcp-server-Enkrypt Secure MCP Gateway.log
- 示例🪟 Windows日志路径： %USERPROFILE%\AppData\Roaming\Claude\logs\mcp-server-Enkrypt Secure MCP Gateway.log
6.4示例提示
list all servers, get all tools available and echo test
- 这使用测试MCP服务器 echo_server 即在 bad_mcps/echo_mcp.py
💡 Other examples
- 我们还可以将多个提示组合成一个，一次触发多个工具调用
- 例子：
echo test and also echo best
- 例子：
echo "hello; ls -la; whoami"
- 这可能是一个恶意提示，但由于没有启用护栏，它不会被阻止
claude-mcp-chat-echo-not-blocked
6.5生成的配置文件示例
- 示例
enkrypt_mcp_config.json由setup脚本在~/.enkrypt/enkrypt_mcp_config.json在macOS和%USERPROFILE%\.enkrypt\enkrypt_mcp_config.json在Windows上
- *如果你运行docker命令来安装Gateway，配置文件将位于
~/.enkrypt/docker/enkrypt_mcp_config.json在macOS和%USERPROFILE%\.enkrypt\docker\enkrypt_mcp_config.json在Windows上*
{
"admin_apikey": "AUTO_GENERATED_256_CHAR_ADMIN_API_KEY_FOR_ADMINISTRATIVE_OPERATIONS",
"common_mcp_gateway_config": {
"enkrypt_log_level": "INFO",
"enkrypt_base_url": "https://api.enkryptai.com",
"enkrypt_api_key": "YOUR_ENKRYPT_API_KEY",
"enkrypt_use_remote_mcp_config": false,
"enkrypt_remote_mcp_gateway_name": "enkrypt-secure-mcp-gateway-1",
"enkrypt_remote_mcp_gateway_version": "v1",
"enkrypt_mcp_use_external_cache": false,
"enkrypt_cache_host": "localhost",
"enkrypt_cache_port": 6379,
"enkrypt_cache_db": 0,
"enkrypt_cache_password": null,
"enkrypt_tool_cache_expiration": 4,
"enkrypt_gateway_cache_expiration": 24,
"enkrypt_async_input_guardrails_enabled": false,
"enkrypt_async_output_guardrails_enabled": false,
"enkrypt_telemetry": {
"enabled": true,
"insecure": true,
"endpoint": "http://localhost:4317"
}
},
"mcp_configs": {
"fcbd4508-1432-4f13-abb9-c495c946f638": {
"mcp_config_name": "default_config",
"mcp_config": [
{
"server_name": "echo_server",
"description": "Simple Echo Server",
"config": {
"command": "python",
"args": [
"C:\\Users\\\\Documents\\GitHub\\EnkryptAI\\secure-mcp-gateway\\src\\secure_mcp_gateway\\bad_mcps\\echo_mcp.py"
]
},
"tools": {},
"input_guardrails_config": {
"enabled": false,
"guardrail_name": "Sample Airline Guardrail",
"additional_config": {
"pii_redaction": false
},
"block": [
"policy_violation"
]
},
"output_guardrails_config": {
"enabled": false,
"guardrail_name": "Sample Airline Guardrail",
"additional_config": {
"relevancy": false,
"hallucination": false,
"adherence": false
},
"block": [
"policy_violation"
]
}
}
]
}
},
"projects": {
"3c09f06c-1f0d-4153-9ac5-366397937641": {
"project_name": "default_project",
"mcp_config_id": "fcbd4508-1432-4f13-abb9-c495c946f638",
"users": [
"6469a670-1d64-4da5-b2b3-790de21ac726"
],
"created_at": "2025-07-16T17:02:00.406877"
}
},
"users": {
"6469a670-1d64-4da5-b2b3-790de21ac726": {
"email": "default@example.com",
"created_at": "2025-07-16T17:02:00.406902"
}
},
"apikeys": {
"2W8UupCkazk4SsOcSu_1hAbiOgPdv0g-nN9NtfZyg-rvYGat": {
"project_id": "3c09f06c-1f0d-4153-9ac5-366397937641",
"user_id": "6469a670-1d64-4da5-b2b3-790de21ac726",
"created_at": "2025-07-16T17:02:00.406905"
}
}
}6.6验证光标
- 通过导航到以下位置，您可以在Cursor中的MCP服务器列表中看到MCP服务器
~/.cursor/mcp.json点击右上角的设置图标，然后点击Tools & Integrations或在MCP标签
- *通常不需要重新启动，但如果它长时间处于加载状态，请重新启动Cursor*
- 现在，您可以与MCP服务器聊天。
- 示例提示：
- *（点击 Run Tool 当Cursor要求您这样做时）*
- list all servers, get all tools available and echo test
- 这使用测试MCP服务器 echo_server 即在 bad_mcps/echo_mcp.py
6.7验证克劳德代码
- 跑
claude mcp list在已配置的MCP服务器列表中查看网关
- 启动Claude Code并运行
/mcp检查服务器状态
- 尝试
list all servers, get all tools available and echo test作为验证网关是否正常工作的提示
7.根据需要编辑网关配置
✂️ Edit Gateway Config
- 重要提示：
- 编辑配置文件后，我们需要重新启动Claude Desktop - 要使所有新工具可访问，请使用提示“list all servers, get all tools available“以便MCP客户端发现所有新工具。在此之后，MCP客户端应该能够使用网关配置文件中配置的服务器的所有工具
- 您可以在内部添加许多MCP服务器
mcp_config此网关配置的数组
- 你可以 看看这里的服务器示例
- 你也可以试试 Enkrypt MCP服务器
- 例子：
{
"common_mcp_gateway_config": {...},
"mcp_configs": {
"UNIQUE_MCP_CONFIG_ID": {
"mcp_config_name": "default_config",
"mcp_config": [
{
"server_name": "MCP_SERVER_NAME_1",
"description": "MCP_SERVER_DESCRIPTION_1",
"config": {
"command": "python/npx/etc.",
"args": [
"arg1", "arg2", ...
],
"env": { "key": "value" }
},
// Set explicit tools to restrict access to only the allowed tools
// Example: "tools": { "tool_name": "tool_description" }
// Example: "tools": { "echo": "Echo a message" }
// Or leave the tools empty {} to discover all tools dynamically
"tools": {},
"enable_server_info_validation": false,
"enable_tool_guardrails": false,
"input_guardrails_config": {...},
"output_guardrails_config": {...}
},
{
"server_name": "MCP_SERVER_NAME_2",
"description": "MCP_SERVER_DESCRIPTION_2",
"config": {...},
"tools": {},
"enable_server_info_validation": false,
"enable_tool_guardrails": false,
"input_guardrails_config": {...},
"output_guardrails_config": {...}
}
]
},
"UNIQUE_MCP_CONFIG_ID_2": {...}
},
"projects": {
"UNIQUE_PROJECT_ID": {
"project_name": "default_project",
"mcp_config_id": "UNIQUE_MCP_CONFIG_ID",
"users": [
"UNIQUE_USER_ID"
],
"created_at": "2025-01-01T00:00:00.000000"
},
"UNIQUE_PROJECT_ID_2": {...}
},
"users": {
"UNIQUE_USER_ID": {
"email": "default@example.com",
"created_at": "2025-01-01T00:00:00.000000"
},
"UNIQUE_USER_ID_2": {...}
},
"apikeys": {
"UNIQUE_GATEWAY_KEY": {
"project_id": "UNIQUE_PROJECT_ID",
"user_id": "UNIQUE_USER_ID",
"created_at": "2025-01-01T00:00:00.000000"
},
"UNIQUE_GATEWAY_KEY_2": {...}
}
}⛩️ Gateway Config Schema
admin_apikey（根级别）：一个256字符的随机字符串，用于验证REST API管理操作（用户管理、项目管理、配置管理、API密钥管理）。这是在您运行时自动生成的secure-mcp-gateway generate-config.
- 重要：保管好这把钥匙！它提供对网关的完全管理访问。 - 与一起使用 Authorization: Bearer REST API调用的头。 - 不同于MCP客户端用于连接到网关的常规API密钥。 - 看 第12节：用于管理操作的REST API 了解详情。
- 如果你想为单独的客户端/用户添加一组不同的MCP服务器，你可以添加一个新的
mcp_config配置文件的一部分。此外，您还可以运行cli命令。看 CLI-Commands-Reference.md 部分2. CONFIGURATION MANAGEMENT详情
- 集
enkrypt_log_level到DEBUG获取更详细的日志common_mcp_gateway_config配置文件的一部分
- 这默认为 INFO
- 现在，里面
mcp_configs对于每个单独的MCP配置，您可以设置以下内容：
- server_name：我们连接到的MCP服务器的名称
- description （可选）：MCP服务器的描述
- config：MCP服务器文档中指示的MCP服务器配置
- 通常，配置中有以下键：
- command：运行MCP服务器的命令
- args：传递给命令的参数
- env：为命令设置的环境变量
- tools：MCP服务器公开的工具
- 设置显式工具以仅限制对允许的工具的访问，或者 留为空白 tools": {} 让网关动态发现所有工具
- 需要为工具命名和描述，如 "tools": { "dummy_echo": "Echo a message" }
🔒 Optional Guardrails Schema
- 得到你的
enkrypt_api_key从 Enkrypt仪表板 并将其添加到common_mcp_gateway_config配置文件的一部分
enkrypt_use_remote_mcp_config用于远程从Enkrypt服务器获取MCP服务器配置 *（即将推出）*
- 请使用 false 目前
- 这使您能够在Enkrypt Dashboard中集中配置和管理MCP网关配置 *（即将推出）*
- 如果您有任何外部缓存服务器（如KeyDB）正在运行，您可以设置
enkrypt_mcp_use_external_cache到true在你的common_mcp_gateway_config
- 设置与缓存相关的其他相关密钥 common_mcp_gateway_config
enkrypt_tool_cache_expiration（以小时为单位）决定从MCP服务器发现的工具在本地或外部缓存服务器中缓存的时间
enkrypt_gateway_cache_expiration（以小时为单位）决定网关配置在本地或外部缓存服务器中缓存的时间。当我们将其与Enkrypt Auth服务器集成时，这很有用 *（即将推出）*
enkrypt_async_input_guardrails_enabled
- false 默认情况下
- 异步模式不建议用于执行无法撤消操作的工具
- 由于工具调用与护栏调用并行进行，因此如果检测到输入护栏违规，则无法阻止它
- 适用于只返回信息而不执行操作的服务器，即只返回读取操作
enkrypt_async_output_guardrails_enabled*（即将推出）*
- 这使得输出侧护栏异步调用以节省时间
- 即，在收到MCP服务器的响应后，并行进行护栏检测呼叫、相关性检查、遵守性检查、PII未编辑等
- 在每个MCP服务器配置中，您可以设置以下内容：
- input_guardrails_config：如果我们计划在输入侧使用Enkrypt护栏，请使用此选项
- guardrail_name：您在Enkrypt应用程序中或使用API/SDK创建的护栏策略的名称
- enabled：是否在输入侧启用护栏。这是 false 在示例配置文件中
- additional_config：护栏策略的附加配置
- pii_redaction：是否在发送到MCP服务器的请求中编辑PII
- 如果 true，这也会自动取消对MCP服务器响应中的PII的编辑
- block：要封锁的护栏列表
- 数组中可能的值有：
- topic_detector, nsfw, toxicity, pii, injection_attack, keyword_detector, policy_violation, bias, sponge_attack
- system_prompt_protection, copyright_protection *（即将推出）*
- 这类似于我们的AI代理部署配置。 请参阅我们的文档
output_guardrails_config：如果我们计划在输出侧使用Enkrypt护栏，请使用此选项
- guardrail_name：您在Enkrypt应用程序中或使用API/SDK创建的护栏策略的名称
- enabled：是否在输出侧启用护栏。这是 false 在示例配置文件中
- additional_config：护栏策略的附加配置
- relevancy：是否检查MCP服务器响应的相关性
- adherence：是否检查MCP服务器响应的遵守情况
- hallucination：是否检查MCP服务器响应中的幻觉 *（即将推出）*
- block：要封锁的护栏列表
- 数组中可能的值有：
- 输入块数组+中的所有可能值 adherence, relevancy
- system_prompt_protection, copyright_protection, hallucination *（即将推出）*
- 这类似于我们的AI代理部署配置。 请参阅我们的文档
8.CLI快速入门指南
🖥️ CLI Quick Start Guide
本节将引导您完全通过CLI管理网关，从首次设置到添加服务器、管理项目和日常操作。
提示： 以下所有命令均显示 本地（pip） 版本。对于Docker，只需添加 --docker 对于任何命令，请参阅 在本节的底部。 有关完整的CLI参考，请参阅 CLI-Commands-Reference.md.______________________________________________________________________
步骤1：生成配置
如果还没有，请生成默认配置文件。这创建了您开始使用所需的一切-一个带有示例echo服务器、默认项目、用户和API键的配置。
secure-mcp-gateway generate-config
# To overwrite an existing config and start fresh
secure-mcp-gateway generate-config --overwrite这会产生什么：
| 项目 | 详细信息 |
|---|---|
| 配置文件 | ~/.enkrypt/enkrypt_mcp_config.json （macOS/Linux）或 %USERPROFILE%\.enkrypt\enkrypt_mcp_config.json （Windows） |
| 默认配置 | default_config 一起 echo_server |
| 默认项目 | default_project 链接到该配置 |
| 默认用户 | default@example.com |
| 网关API密钥 | 用于身份验证的自动生成密钥 |
现在您的配置已经准备就绪，下一步是告诉您的MCP客户端（Claude Desktop、Cursor或Claude Code）有关网关的信息。这是一次性设置——install命令将连接详细信息写入客户端的配置中，以便它知道如何与网关通信。
______________________________________________________________________
步骤2：为MCP客户端安装网关
选择您使用的客户端并运行匹配命令：
# For Claude Desktop
secure-mcp-gateway install --client claude-desktop
# For Cursor
secure-mcp-gateway install --client cursor
# For Claude Code (requires the `claude` CLI — see https://docs.anthropic.com/en/docs/claude-code)
secure-mcp-gateway install --client claude-code幕后操作：install命令从生成的配置中读取网关密钥、项目ID和用户ID，并将其写入MCP客户端的配置文件。
对于 光标 和 克劳德桌面版，您将看到如下输出：
INFO: Updated 'Enkrypt Secure MCP Gateway' in C:\Users\\.cursor\mcp.json
INFO: Successfully configured Cursor.以及客户的配置文件（例如。 ~/.cursor/mcp.json 或 ~/Library/Application Support/Claude/claude_desktop_config.json)现在将包含：
{
"mcpServers": {
"Enkrypt Secure MCP Gateway": {
"command": "mcp",
"args": [
"run",
"
/secure_mcp_gateway/gateway.py"
],
"env": {
"ENKRYPT_GATEWAY_KEY": "",
"ENKRYPT_PROJECT_ID": "",
"ENKRYPT_USER_ID": ""
}
}
}
}对于 克劳德代码，install命令运行 claude mcp add 在幕后，你会看到：
INFO: Successfully installed gateway for Claude Code
INFO: Server name: Enkrypt-Secure-MCP-Gateway
INFO: Scope: user (available across all Claude Code projects)
INFO: Verify with: claude mcp list一旦安装完成， 重新启动MCP客户端 因此，它采用了新的配置。重启后，网关将显示为已连接的MCP服务器，您可以开始了。
此时，您的设置如下：
default_project
└── default_config
└── echo_server (a simple test server that echoes back your input)
default@example.com ← default user
oQrnCFS43o-...rDjX ← auto-generated gateway API key你有一个 项目 (default_project)这指向一个 配置 (default_config)，该配置有一个 服务器 (echo_server).还创建了一个默认的用户和网关API密钥，这样一切都可以开箱即用。
______________________________________________________________________
第三步：检查你有什么
您可以随时验证此设置：
# List all configs
secure-mcp-gateway config list
# List servers in a config
secure-mcp-gateway config list-servers --config-name "default_config"
# List projects linked to a config
secure-mcp-gateway config list-projects --config-name "default_config"______________________________________________________________________
从这里你能做什么？
根据你的需要，你有三条路。选择一个合适的，并按照下面的步骤进行操作。
经验法则： 如果您只在当前配置中添加或删除服务器，只需重新启动MCP客户端即可。如果切换到其他配置或创建新项目，则需要重新安装。
______________________________________________________________________
Path A — Add a server to your existing config (simplest, no reinstall needed)
这是最常见的路径。你已经有了 default_config --只需向其中添加更多服务器即可。
default_project
└── default_config
├── echo_server (already there)
└── github_server ← you are adding this1.添加服务器：
secure-mcp-gateway config add-server --config-name "default_config" --server-name "github_server" --server-command "npx" --args="-y,@modelcontextprotocol/server-github" --env '{"GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_YOUR_TOKEN"}' --description "GitHub MCP Server"2.验证是否已添加：
secure-mcp-gateway config list-servers --config-name "default_config"您应该看到：
Servers in config "default_config":
1. echo_server - Simple Echo Server
2. github_server - GitHub MCP Server3.重新启动MCP客户端 --无需重新安装，只需重新启动：
| 客户端 | 如何重新启动 |
|---|---|
| 光标 | Ctrl+Shift+P （或 Cmd+Shift+P)然后“开发人员：重新加载窗口” |
| 克劳德桌面版 | 完全退出应用程序，然后重新打开它 |
| 克劳德代码 | 退出并重新启动 claude |
4.稍后更新或删除服务器：
# Update a server's description or settings
secure-mcp-gateway config update-server --config-name "default_config" --server-name "github_server" --description "Updated GitHub Server"
# Remove a server you no longer need
secure-mcp-gateway config remove-server --config-name "default_config" --server-name "github_server"Path B — Create a new config under the existing project
当您希望在同一项目下为不同环境（例如开发环境与生产环境）进行单独配置时，这很有用。
default_project
├── default_config (original, untouched)
│ └── echo_server
└── production_config ← new config you are creating
└── github_server1.创建新配置 --从以下两个选项中选择一个：
# Option A: Create an empty config and add servers manually (Step 2 below)
secure-mcp-gateway config add --config-name "production_config"
# Option B: Copy an existing config (including all its servers) — skip Step 2
secure-mcp-gateway config copy --source-config "default_config" --target-config "production_config"你不能两者都做--config copy为您创建目标配置。如果你已经跑了config add，使用选项A并在步骤2中添加服务器。
2.向其中添加服务器 （如果您使用了上述选项B，请跳过此步骤）：
secure-mcp-gateway config add-server --config-name "production_config" --server-name "github_server" --server-command "npx" --args="-y,@modelcontextprotocol/server-github" --env '{"GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_YOUR_TOKEN"}' --description "GitHub MCP Server"3.将项目指向新配置：
secure-mcp-gateway project assign-config --project-name "default_project" --config-name "production_config"4.为您的MCP客户端重新安装网关 --这是必需的，因为项目现在指向不同的配置：
secure-mcp-gateway install --client cursor
# or: secure-mcp-gateway install --client claude-desktop
# or: secure-mcp-gateway install --client claude-code5.重新启动MCP客户端 以适应变化。
其他配置管理命令：
# Rename a config
secure-mcp-gateway config rename --config-name "production_config" --new-name "staging_config"
# Get full details of a config
secure-mcp-gateway config get --config-name "production_config"
# Delete a config you no longer need
secure-mcp-gateway config remove --config-name "production_config"Path C — Create an entirely new project with its own config
创建一个全新的项目。由于新项目获得自己的API密钥，因此必须更新MCP客户端才能使用它。
default_project (original, untouched)
└── default_config
└── echo_server
my_new_project ← new project you are creating
└── my_new_config ← new config
└── github_server1.创建新配置：
secure-mcp-gateway config add --config-name "my_new_config"2.向其中添加服务器：
secure-mcp-gateway config add-server --config-name "my_new_config" --server-name "github_server" --server-command "npx" --args="-y,@modelcontextprotocol/server-github" --env '{"GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_YOUR_TOKEN"}' --description "GitHub MCP Server"3.创建新项目并将其链接到配置：
# Create the project
secure-mcp-gateway project create --project-name "my_new_project"
# Link the config to the project
secure-mcp-gateway project assign-config --project-name "my_new_project" --config-name "my_new_config"4.将用户添加到项目中 （或使用现有的默认用户）：
# Use existing user
secure-mcp-gateway project add-user --project-name "my_new_project" --email "default@example.com"
# Or create a new user first, then add them
secure-mcp-gateway user create --email "alice@company.com"
secure-mcp-gateway project add-user --project-name "my_new_project" --email "alice@company.com"5.为该项目中的用户生成一个API密钥：
secure-mcp-gateway user generate-api-key --project-name "my_new_project" --email "alice@company.com"6.为您的MCP客户端重新安装网关 --这是 必需的 因为新项目具有不同的API密钥。如果不重新安装，您的客户端仍将使用旧项目的密钥，并且看不到新项目的服务器：
secure-mcp-gateway install --client cursor
# or: secure-mcp-gateway install --client claude-desktop
# or: secure-mcp-gateway install --client claude-code7.重新启动MCP客户端 以获取新配置。
______________________________________________________________________
步骤4：设置您的Enkrypt API密钥（用于护栏）
如果您想要使用Enkrypt AI护栏（输入/输出保护、PII编辑、毒性过滤等），您需要设置您的Enkryptneneneba API密钥。你可以从 Enkrypt AI仪表板.
# Set the Enkrypt API key
secure-mcp-gateway config set-enkrypt-api-key --api-key "YOUR_ENKRYPT_API_KEY"
# Verify it was set
secure-mcp-gateway config get-enkrypt-api-key没有这个键，护栏功能将无法工作，但网关本身仍将正常路由工具。
______________________________________________________________________
步骤5：打开或关闭遥测
该网关附带了用于日志记录、跟踪和指标的OpenTetry支持。默认情况下，它处于启用状态，但如果无法访问收集器端点，它将自动跳过。您可以显式启用或禁用它：
# Disable telemetry
secure-mcp-gateway config configure-telemetry --enabled false
# Enable telemetry with a custom collector URL
secure-mcp-gateway config configure-telemetry --enabled true --url "http://localhost:4317"
# Allow insecure (non-TLS) connections to the collector
secure-mcp-gateway config configure-telemetry --insecure true启动遥测堆栈： 网关将遥测数据发送到OpenTetry收集器——它本身不运行收集器。回购包括一个现成的堆栈（收集器、普罗米修斯、格拉法纳、耶格尔、洛基） infra/ 目录：
cd infra
docker compose up -d| 服务 | URL |
|---|---|
| Grafana仪表板 | http://localhost:3000 |
| Jaeger跟踪查看器 | http://localhost:16686 |
| 普罗米修斯指标 | http://localhost:9090 |
| OTLP gRPC端点 | http://localhost:4317 |
堆栈运行后，网关将自动开始向收集器发送跟踪、日志和指标。
______________________________________________________________________
步骤6：系统操作
# Check gateway health
secure-mcp-gateway system health-check
# Backup your entire config
secure-mcp-gateway system backup
# Restore from a backup
secure-mcp-gateway system restore --file
# Reset to defaults (⚠️ destructive)
secure-mcp-gateway system reset______________________________________________________________________
Docker命令模式
添加 --docker 到 任何 CLI命令在Docker容器中自动运行它。 该标志自动检测您的操作系统，设置 HOST_OS 和 HOST_ENKRYPT_HOME，并安装 ~/.enkrypt/docker 音量--不久 docker run 需要咒语。
# Quick (recommended) — works on macOS, Linux, and Windows (all shells)
secure-mcp-gateway --docker
# Use a custom Docker image
secure-mcp-gateway --docker --docker-image my-registry/secure-mcp-gateway:v2.1.2 示例：
# List configs
secure-mcp-gateway --docker config list
# Add a server
secure-mcp-gateway --docker config add-server --config-name "default_config" --server-name "my_server" --server-command "npx" --args="-y,@example/mcp-server" --description "My Server"
# Generate config
secure-mcp-gateway --docker generate-config
# Health check
secure-mcp-gateway --docker system health-check______________________________________________________________________
🔧 Troubleshooting — Server not showing up?
┌──────────────────────────────────────────────────────────────────┐
│ ❓ DIAGNOSTIC FLOWCHART │
├──────────────────────────────────────────────────────────────────┤
│ │
│ Server not showing up after restart? │
│ │ │
│ ▼ │
│ Did you verify with "config list-servers"? │
│ │ │
│ ├── NO → Run it. Is server listed? │
│ │ │ │
│ │ ├── NO → Wrong --config-name. Go to Step 3. │
│ │ │ │
│ │ └── YES → Continue below ▼ │
│ │ │
│ └── YES, server IS in list-servers │
│ │ │
│ ▼ │
│ Did you restart the MCP client? │
│ │ │
│ ├── NO → Restart it (Step 5) │
│ │ │
│ └── YES, I restarted │
│ │ │
│ ▼ │
│ Check: does your ENKRYPT_PROJECT_ID in the │
│ MCP client config match a project that uses │
│ this config name? │
│ │ │
│ ├── NO → Your gateway key points to a │
│ │ different config. Either: │
│ │ a) Add server to the correct config, OR │
│ │ b) Change the project's config assignment │
│ │ │
│ └── YES → Check if the server's command is │
│ available in the gateway environment │
│ (e.g., npx requires Node.js) │
│ │
└──────────────────────────────────────────────────────────────────┘9.（可选）将GitHub MCP服务器添加到网关
👨🏻💻 Configure GitHub
⚠️ Docker用户注意事项： 如果你在Docker中运行Enkrypt网关， 使用npx版本 GitHub MCP服务器，而不是下面显示的Docker版本。看 基于npx的配置示例 在本节末尾。 有关原因的详细信息，请参阅 .
GitHub MCP Server可以运行docker或npxDocker版本要求在您的机器上安装并运行Docker。
- 你可以 。如果您还没有，请安装并运行它
- 创建一个只能访问公共存储库的令牌，并将初始到期时间设置得非常低，以便进行测试
- 将下面的GitHub服务器块添加到 enkrypt_mcp_config.json 里面 "mcp_config": [] 阵列。它应该已经具有echo服务器配置。
- *注意：别忘了加逗号 , 在echo服务器块之后*
- 替换 REPLACE_WITH_YOUR_PERSONAL_ACCESS_TOKEN 使用您创建的个人访问令牌
- 您还可以通过cli添加。看 CLI-Commands-Reference.md 部分 2. CONFIGURATION MANAGEMENT 详情
- 例子：
"mcp_config": [
{
"server_name": "echo_server",
"description": "Simple Echo Server",
"config": {...},
"tools": {},
"input_guardrails_config": {...},
"output_guardrails_config": {...}
},
{
"server_name": "github_server",
"description": "GitHub Server",
"config": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"-e",
"GITHUB_PERSONAL_ACCESS_TOKEN",
"ghcr.io/github/github-mcp-server"
],
"env": {
"GITHUB_PERSONAL_ACCESS_TOKEN": "REPLACE_WITH_YOUR_PERSONAL_ACCESS_TOKEN"
}
},
"tools": {},
"enable_server_info_validation": false,
"enable_tool_guardrails": false,
"input_guardrails_config": {
"enabled": false,
"guardrail_name": "Sample Airline Guardrail",
"additional_config": {
"pii_redaction": false
},
"block": [
"policy_violation"
]
},
"output_guardrails_config": {
"enabled": false,
"guardrail_name": "Sample Airline Guardrail",
"additional_config": {
"relevancy": false,
"hallucination": false,
"adherence": false
},
"block": [
"policy_violation"
]
}
}
]- 现在重新启动Claude Desktop以检测新服务器
- 然后运行提示
list all servers, get all tools available让它发现github服务器及其所有可用工具
- 快跑
List all files from https://github.com/enkryptai/enkryptai-mcp-server
- 太棒了 🎉 我们已成功将GitHub MCP服务器添加到网关。 然而，它完全不受保护，容易受到各种滥用和攻击。
- 现在，假设运行这样的提示符
Ask github for the repo "hello; ls -la; whoami"
- 这可能没有造成实际损坏，但想象一个可能对系统造成实际损坏的更复杂的提示。
- 为了保护MCP服务器，我们可以使用 Enkrypt护栏 如下一节所示。
GitHub服务器配置（npx版本）
✅ 推荐用于Docker网关部署
如果你在Docker中运行Enkrypt网关，或者不想在Docker中使用Docker，请使用基于npx的GitHub MCP服务器：
{
"server_name": "github_server",
"description": "GitHub Server (npx version)",
"config": {
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-github"
],
"env": {
"GITHUB_PERSONAL_ACCESS_TOKEN": "REPLACE_WITH_YOUR_PERSONAL_ACCESS_TOKEN"
}
},
"tools": {},
"enable_server_info_validation": false,
"enable_tool_guardrails": false,
"input_guardrails_config": {
"enabled": false,
"guardrail_name": "Sample Airline Guardrail",
"additional_config": {
"pii_redaction": false
},
"block": [
"policy_violation"
]
},
"output_guardrails_config": {
"enabled": false,
"guardrail_name": "Sample Airline Guardrail",
"additional_config": {
"relevancy": false,
"hallucination": false,
"adherence": false
},
"block": [
"policy_violation"
]
}
}npx版本的优点：
- ✅ Docker中没有Docker的复杂性
- ✅ 更快的启动时间
- ✅ 与Docker化网关无缝协作
- ✅ 更简单的网络和卷管理
- ✅ 降低资源开销
先决条件：
- Node.js和npm必须安装在网关容器或主机上
- 默认的Dockerfile已经包含Node.js 22.x LTS
9.1（可选）使用OAuth连接到MCP服务器
🔐 Configure OAuth for Remote MCP Servers
许多MCP服务器需要OAuth身份验证才能访问受保护的资源。安全MCP网关同时支持OAuth 2.0/2.1和 客户端凭据 和 授权码+PKCE 与支持OAuth的服务器无缝集成的流程。
概述
Gateway处理OAuth令牌获取、缓存和自动刷新，因此您不必手动管理令牌。当连接到远程MCP服务器时，令牌会自动注入请求中。
支持的资助类型：
- 客户端凭据 -用于服务器到服务器身份验证（机器到机器）
- 授权码+PKCE -用于具有增强安全性的用户授权流
主要特点：
- 授权码流的自动浏览器授权
- 本地和远程回调URL支持
- 到期前自动刷新令牌
- 安全令牌缓存
- 用于增强安全性的PKCE（S256）
- CSRF保护状态参数
OAuth配置示例
客户端凭据流（服务器到服务器）
对于机器对机器身份验证，请使用客户端凭据流：
{
"server_name": "oauth-enabled-server",
"description": "Remote MCP Server with OAuth",
"config": {
"command": "npx",
"args": ["-y", "mcp-remote", "https://api.example.com/mcp", "--allow-http"]
},
"oauth_config": {
"enabled": true,
"is_remote": true,
"OAUTH_VERSION": "2.1",
"OAUTH_GRANT_TYPE": "client_credentials",
"OAUTH_CLIENT_ID": "your-client-id",
"OAUTH_CLIENT_SECRET": "your-client-secret",
"OAUTH_TOKEN_URL": "https://auth.example.com/oauth/token",
"OAUTH_AUDIENCE": "https://api.example.com"
},
"tools": {},
"enable_server_info_validation": false,
"enable_tool_guardrails": false,
"input_guardrails_config": {
"enabled": false
},
"output_guardrails_config": {
"enabled": false
}
}OAuth关键字段
核心配置
| 字段 | 必填 | 默认 | 描述 |
|---|---|---|---|
enabled | 是的 | false | 为此服务器启用OAuth |
is_remote | 推荐 | 自动检测 | 设置为 true 对于远程服务器， false 对于本地服务器 |
OAUTH_VERSION | 没有 | "2.1" | OAuth版本： "2.0" 或 "2.1" |
OAUTH_GRANT_TYPE | 没有 | "client_credentials" | 资助类型： "client_credentials" 或 "authorization_code" |
OAUTH_CLIENT_ID | 是 | - | 您的OAuth客户端ID |
OAUTH_CLIENT_SECRET | 是 | - | 您的OAuth客户端密钥 |
OAUTH_TOKEN_URL | 是 | - | 令牌端点URL（对于OAuth 2.1必须是HTTPS） |
OAUTH_AUTHORIZATION_URL | 有条件的 | - | 授权端点（必需 authorization_code 赠款） |
OAUTH_REDIRECT_URI | 条件 | - | 回调URL（必填 authorization_code 赠款） |
可选OAuth参数
| 字段 | 必填 | 默认 | 描述 |
|---|---|---|---|
OAUTH_AUDIENCE | 没有 | null | 代币的预期受众（aud声称） |
OAUTH_ORGANIZATION | 没有 | null | 组织ID（适用于多租户OAuth提供商） |
OAUTH_SCOPE | 没有 | null | 空格分隔的作用域（例如“读写”） |
OAUTH_RESOURCE | 没有 | null | 资源指示符（RFC 8707） |
OAUTH_TOKEN_EXPIRY_BUFFER | 没有 | 300 | 令牌到期前触发刷新的秒数（默认值：5分钟） |
OAUTH_USE_PKCE | 没有 | false | 为授权码流启用PKCE（推荐） |
OAUTH_CODE_CHALLENGE_METHOD | 没有 | "S256" | PKCE挑战方法： "S256" （推荐）或 "plain" |
OAUTH_ADDITIONAL_PARAMS | 没有 | {} | 令牌请求中要包含的其他参数（JSON对象） |
OAUTH_CUSTOM_HEADERS | 没有 | {} | 令牌请求的自定义HTTP标头（JSON对象） |
安全和身份验证设置
| 字段 | 必填 | 默认 | 描述 |
|---|---|---|---|
OAUTH_USE_BASIC_AUTH | 没有 | true | 对客户端凭据使用HTTP基本身份验证（RFC 6749§2.3.1） |
OAUTH_ENFORCE_HTTPS | 没有 | true | 强制HTTPS以符合OAuth 2.1（设置 false 仅用于本地测试） |
OAUTH_TOKEN_IN_HEADER_ONLY | 没有 | true | 仅在授权标头中发送令牌（推荐） |
OAUTH_VALIDATE_SCOPES | 没有 | true | 验证返回的令牌是否包含请求的作用域 |
双向TLS（mTLS）配置
| 字段 | 必填 | 默认 | 描述 |
|---|---|---|---|
OAUTH_USE_MTLS | 没有 | false | 启用双向TLS（RFC 8705）以增强安全性 |
OAUTH_CLIENT_CERT_PATH | 有条件的 | null | 客户端证书文件的路径（如果启用了mTLS，则需要） |
OAUTH_CLIENT_KEY_PATH | 有条件的 | null | 客户端私钥文件的路径（如果启用了mTLS，则需要） |
OAUTH_CA_BUNDLE_PATH | 没有 | null | 用于服务器证书验证的CA包路径 |
令牌撤销
| 字段 | 必填 | 默认 | 描述 |
|---|---|---|---|
OAUTH_REVOCATION_URL | 没有 | null | 令牌吊销端点URL（RFC 7009） |
授权码+PKCE流程
对于具有增强安全性的用户授权，请使用PKCE的授权码流：
{
"server_name": "user-auth-server",
"description": "MCP Server requiring user authorization",
"config": {
"command": "npx",
"args": ["-y", "mcp-remote", "https://api.example.com/mcp"]
},
"oauth_config": {
"enabled": true,
"is_remote": true,
"OAUTH_VERSION": "2.1",
"OAUTH_GRANT_TYPE": "authorization_code",
"OAUTH_CLIENT_ID": "your-client-id",
"OAUTH_CLIENT_SECRET": "your-client-secret",
"OAUTH_AUTHORIZATION_URL": "https://auth.example.com/authorize",
"OAUTH_TOKEN_URL": "https://auth.example.com/oauth/token",
"OAUTH_REDIRECT_URI": "http://localhost:8080/callback",
"OAUTH_SCOPE": "openid profile email",
"OAUTH_USE_PKCE": true,
"OAUTH_CODE_CHALLENGE_METHOD": "S256"
},
"tools": {},
"enable_server_info_validation": false,
"enable_tool_guardrails": true
}自动浏览器授权
使用授权码流时，网关会自动：
- 打开浏览器以访问授权URL
- 处理回调（本地主机或远程）
- 将授权码替换为令牌
- 缓存令牌以备将来使用
流量选项：
本地主机回拨（自动）：
"OAUTH_REDIRECT_URI": "http://localhost:8080/callback"- 网关在端口8080上启动本地服务器
- 自动捕获授权码
- 无需人工干预
远程回拨（手动输入代码）：
"OAUTH_REDIRECT_URI": "https://oauth.yourdomain.com/callback"- Gateway打开浏览器进行授权
- 用户在远程页面上完成授权
- 用户从回调页面复制代码
- 用户将代码粘贴到终端
- 网关交换令牌代码
设置远程回拨
如果你想使用远程回叫URL（专业、品牌体验）：
- 托管回调页面：
# Quick start with Python
python host_oauth_callback.py
# Or with Docker
docker-compose -f docker-compose.oauth-callback.yml up -d
# Or deploy oauth_callback.html to any static hosting
# (GitHub Pages, Vercel, Netlify, AWS S3, etc.)- 更新您的配置：
"OAUTH_REDIRECT_URI": "https://your-domain.com/callback"- 向OAuth提供商注册：
- 将回调URL添加到OAuth应用程序设置中 - Auth0:“允许的回调URL” - Okta：“登录重定向URI” - Azure AD：“重定向URI” - 谷歌：“授权重定向URI”
使用Echo OAuth服务器进行测试
Gateway包括一个测试回声服务器，用于演示OAuth标头注入。您可以使用它来验证OAuth是否正常工作。
步骤1：启动Echo OAuth服务器
echo OAuth服务器需要在HTTP模式下运行才能接受远程连接：
macOS/Linux：
# Export the environment variable
export MCP_HTTP_MODE=true
# Start the server
python src/secure_mcp_gateway/bad_mcps/echo_oauth_mcp.pyWindows（PowerShell）：
# Set the environment variable
$env:MCP_HTTP_MODE = "true"
# Start the server
python src/secure_mcp_gateway/bad_mcps/echo_oauth_mcp.pyWindows（命令提示符）：
# Set the environment variable
set MCP_HTTP_MODE=true
# Start the server
python src/secure_mcp_gateway/bad_mcps/echo_oauth_mcp.py服务器将于启动 http://localhost:8001/mcp/ 并在调用工具时打印与OAuth相关的标头。
步骤2：将Echo OAuth服务器添加到网关配置中
将此配置添加到您的 enkrypt_mcp_config.json 在 mcp_config 数组：
{
"server_name": "echo_oauth_server",
"description": "Echo Server with OAuth Testing",
"config": {
"command": "npx",
"args": [
"-y",
"mcp-remote",
"http://localhost:8001/mcp/",
"--allow-http"
]
},
"oauth_config": {
"enabled": true,
"is_remote": true,
"OAUTH_VERSION": "2.0",
"OAUTH_GRANT_TYPE": "client_credentials",
"OAUTH_CLIENT_ID": "test-client-id",
"OAUTH_CLIENT_SECRET": "test-client-secret",
"OAUTH_TOKEN_URL": "https://auth.example.com/oauth/token",
"OAUTH_ENFORCE_HTTPS": false
},
"tools": {},
"enable_server_info_validation": false,
"enable_tool_guardrails": false,
"input_guardrails_config": {
"enabled": false
},
"output_guardrails_config": {
"enabled": false
}
}注： OAUTH_ENFORCE_HTTPS: false 仅设置为本地测试。在生产环境中始终使用HTTPS！
步骤3：测试OAuth令牌注入
- 重新启动Claude Desktop（或您的MCP客户端）以获取新的服务器配置
- 使用提示：
list all servers and discover tools from echo_oauth_server
- 调用回声工具：
call the echo tool from echo_oauth_server with message "test oauth"
- 检查echo服务器终端输出-您应该看到正在打印OAuth标头：
================================================================================
🔐 OAuth HTTP Headers Check (Remote Mode)
================================================================================
✅ AUTHORIZATION: Bearer ...
❌ X-OAUTH-TOKEN: Not set
❌ X-ACCESS-TOKEN: Not set
📋 All Request Headers:
authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
content-type: application/json
user-agent: python-requests/2.31.0
================================================================================这确认了OAuth令牌正在被自动获取并注入到Authorization标头中。
OAuth令牌流
客户端凭据流
- 首次请求：Gateway从OAuth提供程序获取令牌
- 缓存：令牌缓存有过期跟踪
- 代币注入:
- 远程服务器：令牌添加为 Authorization: Bearer 头球 - 本地服务器：环境变量中可用的令牌
- 自动刷新：令牌在到期前5分钟刷新（可配置）
授权码+PKCE流程
- 初始设置：Gateway生成PKCE代码验证器和质询
- 浏览器授权:
- 网关打开浏览器以访问授权URL - 用户登录并授权应用程序
- 回拨处理:
- 本地主机：Gateway自动从回调中捕获代码 - 远程：用户复制代码并粘贴到终端
- 代币交换：网关交换令牌的授权码
- 缓存和刷新：令牌缓存并在到期前自动刷新
高级功能
- 授权码+PKCE：具有增强安全性的用户授权（S256）
- 自动浏览器流：打开浏览器并自动处理回调
- 远程回拨支持：您域上的主机回调页面
- 双向TLS（mTLS）：通过客户端证书增强安全性（RFC 8705）
- 令牌撤销：程序化撤销令牌（RFC 7009）
- 范围验证：验证返回的令牌是否具有请求的作用域
- 自定义头：向令牌请求添加自定义HTTP标头
- 状态参数：授权码流的CSRF保护
- 指标：跟踪令牌获取成功/失败，缓存命中率
故障排除
OAuth令牌请求失败：
- 验证CLIENT_ID和CLIENT_SECRET是否正确
- 检查TOKEN_URL是否可访问
- 确保使用（或设置）HTTPS
OAUTH_ENFORCE_HTTPS: false用于测试）
令牌未出现在请求中：
- 确认
is_remote: true用于远程服务器 - 检查服务器日志中的OAuth获取消息
- 启用调试日志记录：
"enkrypt_log_level": "DEBUG"
授权码流问题：
- 验证AUTHORIZATION_URL和REDIRECT_URI是否正确
- 确保回调URL已向OAuth提供程序注册
- 检查浏览器是否自动打开（或使用手动URL）
- 对于远程回调，验证回调页面是否可访问
回拨不起作用：
- 本地主机：如果使用8080，网关会自动尝试下一个可用端口（最多10个端口）
- 远程：验证回调URL是否可访问并与OAuth提供程序设置匹配
- 检查防火墙是否阻止回调
Echo服务器未接收到标头：
- 确保
MCP_HTTP_MODE=true环境变量已设置 - 验证服务器是否正在运行http://localhost:8001/mcp/
10.（可选）保护GitHub MCP服务器并测试Echo服务器
🎁 Protect with Enkrypt Guardrails for FREE
10.1 🌐 Create a Guardrail in Enkrypt App
- 您可以使用提示生成规则或生成PDF文件，然后在应用程序中创建策略时粘贴或上传
10.1.1 🔍 Rules to copy
1. MCP-Specific Security Policies
Scan all tool descriptions for hidden instructions/malicious patterns.
Authenticate MCP servers with cryptographic verification.
Lock and pin tool versions to prevent rug-pull attacks.
Enforce isolation between MCP servers to avoid interference.
Restrict GitHub MCP access to specific repositories and users.
2. Code Filtering and Prohibited Patterns
Block known malicious code patterns (e.g., buffer overflows, SQL injection).
Detect malware signatures (e.g., keylogger, trojan).
Prevent crypto mining code.
Identify network attack patterns (e.g., DDoS, botnet).
Block privilege escalation code (e.g., root exploits).
3. Repository Access Control
Enforce role-based read access for private repositories.
Enable strict content filtering for all access types.
Mandate audit logging for private repositories.
Quarantine access to sensitive repositories.
4. AI-Specific Guardrails
Detect tool poisoning via hidden tags and file access commands.
Monitor behavior for file access and network activity.
Require explicit UI approval for suspicious tools.
Protect against prompt injection in GitHub issues.
Block PRs that expose private repo data.
Quarantine suspicious GitHub issues.
5. RADE (Retrieval-Agent Deception) Mitigation
Scan retrieved content for embedded commands.
Validate document integrity and modification timestamps.
Sandbox retrieved content to prevent auto-execution.
6. Input Validation
Limit prompt length (max 4096 tokens).
Block forbidden keywords (e.g., "ignore previous instructions").
Detect encoded/injection patterns (base64, hex, unicode).
7. Model Behavior Constraints
Limit code generation by complexity and size.
Restrict certain languages (e.g., shell scripts, assembly).
Monitor API/system calls and network activity.
Enforce strict context boundaries across repositories.
10.1.2 💡 Prompt used to generate the rules
Give numbered list of security rules in plain text for configuring AI guardrails for a GitHub server on the rules and policies it needs to follow to prevent malicious use of the GitHub services
- 那么说
Research latest GitHub MCP hacks and abuses people are trying and update the rules to prevent those. Keep research to the most severe topics
- 那么说
Only keep essential security rules to reduce size. Remove unwanted sections like post incident, compliance, audit, etc which cannot be used while prevention
- 然后，您可以在创建策略时复制粘贴规则
- 首选 Enkcrypt应用程序 并使用OTP或谷歌或微软帐户登录
- 点击
Policies
- 点击
Add new policy
- 命名它
GitHub Safe Policy粘贴策略规则并单击Save
- 这是应用规则后保存的策略的外观
Policy violation护栏
- 现在导航回主页或将鼠标悬停在左侧边栏上并单击
Guardrails
- 点击
Add New Guardrail右上角的按钮
enkrypt-app-add-guardrail-button
- 命名它
GitHub Guardrail，切换Injection Attack关闭
enkrypt-app-add-guardrail-add-1
- 向下滚动
Configure Guardrails侧面板和开关Policy ViolationON，选择新创建的策略并勾选Need Explanation如有需要
enkrypt-app-add-guardrail-add-2
- 现在，点击
Save右下角的按钮，用于保存护栏
enkrypt-app-add-guardrail-add-3
- 我们可以在护栏列表中看到新增的护栏
enkrypt-app-add-guardrail-add-4
10.2 🔑 Get Enkrypt API Key
- 现在，我们需要从Enkrypt应用程序获得免费的API密钥。将鼠标悬停在左侧边栏上，使其展开并单击
Settings
- 您还可以直接导航到 https://app.enkryptai.com/settings
- 现在点击
Copy图标旁边的模糊API密钥，将密钥复制到您的剪贴板，如下面屏幕截图中突出显示的那样
10.3 🔑 Add API Key and the Guardrail to Config File
- 现在我们从应用程序中获得了所需的一切。让我们将API密钥添加到
enkrypt_mcp_config.json文件
- 打开
enkrypt_mcp_config.json文件来自~/.enkrypt/enkrypt_mcp_config.json在macOS或%USERPROFILE%\.enkrypt\enkrypt_mcp_config.json在Windows上
- *如果你运行docker命令来安装Gateway，配置文件将位于 ~/.enkrypt/docker/enkrypt_mcp_config.json 在macOS和 %USERPROFILE%\.enkrypt\docker\enkrypt_mcp_config.json 在Windows上*
- 将API密钥添加到
common_mcp_gateway_config通过替换YOUR_ENKRYPT_API_KEY使用从应用程序复制的API密钥
- 里面
GitHub我们在上一节中添加的服务器块，
- 添加新创建的护栏 GitHub Guardrail 到 input_guardrails_config 和 output_guardrails_config 章节
- 通过替换 "guardrail_name": "Sample Airline Guardrail" 随着 "guardrail_name": "GitHub Guardrail"
- 现在改变 enabled 到 true 为了 input_guardrails_config 从以前 false
- 我们会离开 output_guardrails_config 作为 false 目前
- 我们应该已经有了 policy_violation 在 block 两个策略的数组
- 因此，最终的配置应该看起来像这样：
{
"common_mcp_gateway_config": {
...
"enkrypt_api_key": "xxxxxxxxxxxxxxxxxxxxxxxxxxxx",
...
},
"mcp_configs": {
"fcbd4508-1432-4f13-abb9-c495c946f638": {
"mcp_config_name": "default_config",
"mcp_config": [
{
"server_name": "echo_server",
...
},
{
"server_name": "github_server",
"description": "GitHub Server",
"config": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"-e",
"GITHUB_PERSONAL_ACCESS_TOKEN",
"ghcr.io/github/github-mcp-server"
],
"env": {
"GITHUB_PERSONAL_ACCESS_TOKEN": "github_pat_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}
},
"tools": {},
"enable_server_info_validation": false,
"enable_tool_guardrails": false,
"input_guardrails_config": {
"enabled": true,
"guardrail_name": "GitHub Guardrail",
"additional_config": {
"pii_redaction": false
},
"block": ["policy_violation"]
},
"output_guardrails_config": {
"enabled": false,
"guardrail_name": "GitHub Guardrail",
"additional_config": {
"relevancy": false,
"hallucination": false,
"adherence": false
},
"block": ["policy_violation"]
}
}
]
}
},
"projects": {
...
},
"users": {
...
},
"apikeys": {
...
}
}10.4 🧪 Test Guardrails
- 保存 重新启动Claude Desktop以检测更改
GitHub MCP Server需求docker待安装。所以，请安装并拥有docker在继续执行以下步骤之前，请先在您的机器上运行
- 你可以 。如果您还没有，请安装并运行它
- 现在运行提示符
list all services, tools让它发现github、echo服务器及其所有可用工具
- 在此之后，让我们重新运行之前成功的恶意提示
Ask github for the repo "hello; ls -la; whoami"
- 我们可以看到，由于Input Guardrails阻止了请求，提示被阻止了
- 我们可以配置测试
echo使用我们选择的护栏服务器，并通过运行来查看检测结果echo "hello; ls -la; whoami".
- 下面的提示以前有效，但被护栏挡住了
- 实验并尝试 echo 服务器有各种护栏，可以查看它的行为。 您还可以尝试我们的游乐场进行更好的测试.
claude-mcp-chat-echo-guardrails-2
10.5 🔧 Fine tune Guardrails
- *安全提示
List all files from https://github.com/enkryptai/enkryptai-mcp-server如果您在输出端使用注入攻击检测器或策略违规，也可能被阻止。因此，需要对护栏进行一些微调，以便为您的服务器找到启用的检测器和块的最佳组合。建议见下一节。*
11.护栏使用建议
⭐ Recommendations
- 我们发现，在MCP网关中使用Enkrypt护栏的最佳方式是为每个服务器设置单独的护栏。这样，我们就可以为每台服务器设置一个微调的护栏。
- 因为每个MCP服务器都与其他服务器非常不同，所以不可能有一个适用于所有服务器的护栏。
- 有些人可能需要
Toxicity Detector，一些NSFW Detector，一些Injection Attack Detector，一些Keyword Detector，一些Policy Violation，有些人可能需要Relevancy探测器，有些可能需要Adherence检测器等。
- 有些可能需要这些检测器的组合来共同阻止恶意请求。
- 有些可能需要在输入端安装护栏，有些需要在输出端安装，有些可能需要两者都安装。
- 有关详细信息，请参阅我们的文档 多种探测器可供选择。
- 因此，为每个服务器设置单独的护栏，并为每个服务器尝试检测器和块的最佳组合，以阻止恶意请求，但允许合法请求通过。
- 试试我们的
Policy Violation检测器具有您自己的自定义策略，详细说明允许和不允许的内容。这可能是您用例的最佳方式。
🚨 Try Policy Violation
- 您可以导航到 Enkcrypt应用程序主页，登录并单击
Policies创建自己的自定义策略。
- 这接受文本和PDF文件作为输入，因此创建一个包含您要应用于MCP服务器的所有规则的文件并上传
- 创建后，您可以在配置护栏时使用它，就像我们说的那样 GitHub Guardrail 在上一节中
11.1每台服务器护栏配置
您可以使用配置中的每台服务器标志单独控制每台服务器的护栏行为。
注： 虽然这两个字段默认为 false，为了清晰和可维护性，建议在服务器配置中明确包含它们。
enable_server_info_validation （布尔值，默认值： false)
控制在发现/注册有害内容（注入攻击、违反策略等）期间是否验证服务器描述。
何时禁用：
- 具有已知安全服务器的测试/开发环境
- 内容完全可信的内部服务器
- 当服务器元数据包含触发误报的技术术语时
例子：
{
"server_name": "test_server",
"description": "Development test server",
"config": {
"command": "python",
"args": ["test_server.py"]
},
"enable_server_info_validation": false,
"enable_tool_guardrails": false,
"input_guardrails_config": {
"enabled": false
},
"output_guardrails_config": {
"enabled": false
}
}enable_tool_guardrails （布尔值，默认值： false)
控制在发现过程中是否验证单个工具描述和模式。
护栏等级：
大门有三层不同的护栏：
- 服务器注册验证 (
enable_server_info_validation)
- 当：在服务器发现期间，在加载任何工具之前 - 什么：验证服务器名称和有害内容的描述 - 积木：具有恶意元数据的服务器
- 工具注册验证 (
enable_tool_guardrails)
- 当：在工具发现期间 - 什么：验证工具描述和模式 - 积木：含有有害内容的个人工具
- 运行时护栏 (
input_guardrails_config/output_guardrails_config)
- 当：工具执行期间（前输入，后输出） - 什么：验证工具参数和响应 - 积木：违反政策的请求/响应
注： 所有三个级别都是独立的，可以为每台服务器单独配置。
12.其他可用工具
🔧 REST API for Administrative Operations
网关提供了一个REST API服务器，用于管理用户、项目、配置和API密钥等管理操作。
启动REST API服务器
secure-mcp-gateway system start-api --host 0.0.0.0 --port 8001- API文档：可在
http://localhost:8001/docs（Swagger用户界面） - 健康检查:
http://localhost:8001/health - OpenAPI架构：从加载
openapi.json在项目根中
管理员API密钥验证
重要：行政业务需要特别 admin_apikey 其与常规用户API密钥分离。这为管理操作提供了增强的安全性。
获取管理员API密钥
这 admin_apikey 运行时自动生成 secure-mcp-gateway generate-config。在配置文件中找到它：
- 视窗:
%USERPROFILE%\.enkrypt\enkrypt_mcp_config.json - macOS/Linux:
~/.enkrypt/enkrypt_mcp_config.json
{
"admin_apikey": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6...",
"apikeys": {
"regular_user_key_1": { ... },
"regular_user_key_2": { ... }
},
...
}关键区别
admin_apikey（根级别）：用于所有管理操作（用户管理、项目管理等）
- 256个字符的随机字符串，以实现最高安全性 - 生成于 secure-mcp-gateway generate-config - REST API终结点必需
apikeys（在apikeyssection）：用于用户访问网关
- MCP客户端用于连接到网关 - 与特定用户和项目相关联 - 不用于行政操作
使用管理员API密钥
包括 admin_apikey 在所有管理API调用的授权头中：
curl -X GET "http://localhost:8001/api/v1/users" -H "Authorization: Bearer YOUR_ADMIN_API_KEY_HERE"安全说明:
- 确保您的管理员API密钥安全，永远不要将其提交到版本控制
- 仅与授权管理员共享管理员API密钥
- 普通用户不应该有权访问管理员API密钥
可用的管理操作
REST API为以下各项提供端点：
- 用户管理：创建、列出、更新和删除用户
- 项目管理：创建项目、分配配置、管理用户
- API密钥管理：生成、旋转、禁用/启用和删除API密钥
- 配置管理：创建、更新和管理MCP配置和服务器
有关完整的API文档和示例，请参阅：
- API参考.md
- API交互式文档，网址：
http://localhost:8001/docs
💾 Cache Management
12.1 📊 Get Cache Status
- 网关可以通过查看本地/外部缓存服务器来提供其缓存状态的摘要
- 这对于调试问题很有用，例如，如果服务器远程更新了一个工具，但网关还没有意识到这一点
claude-mcp-chat-get-cache-status
12.2 🧹 Clear Cache
- 网关可以从本地/外部缓存服务器中清除其缓存
- 这对于清除缓存很有用，例如，如果服务器远程更新了一个工具，但网关还没有意识到这一点
- 您可以通过提供以下命令清除所有缓存或特定缓存
server_name
- 例子： clear cache for echo_server
- 您还可以清除所有缓存，或者仅清除网关缓存，或者只清除服务器缓存
- 例子： clear all cache, clear just gateway cache, clear server cache for echo_server, Clear all server cache
13.（可选）沙箱隔离
沙盒隔离允许您在隔离的容器或微虚拟机中运行每个MCP服务器，从而在服务器受到攻击或恶意攻击时减少爆炸半径。启用后，每次MCP服务器启动都会被透明地包装——不需要对MCP客户端或服务器进行更改。
沙盒保护什么？
| 威胁 | 无沙盒 | 有沙盒 |
|---|---|---|
| 文件系统访问 | 完整主机文件系统 | 只读 /app 仅限安装 |
| 网络访问 | 完全网络 | 已阻止(--network=none) |
| 资源耗尽（分叉炸弹、OOM） | 可能导致主机崩溃 | 容器限制上限 |
| 环境变量盗窃 | 所有环境变量可见 | 只有分配的变量通过 |
| 跨调用的持久性 | 进程可以持久 | 短暂性-在每次会话后被销毁 |
快速启用
# 1. Enable sandbox in global config
secure-mcp-gateway config update-sandbox --enabled --runtime docker
# 2. Build a Docker image with MCP dependencies
docker build -t sandbox-test-mcp -f tests/Dockerfile.sandbox-test .
# 3. Enable for a specific server with a custom image
secure-mcp-gateway config update-server-sandbox \
--config-name default_config \
--server-name echo_server \
--enabled \
--image sandbox-test-mcp每台服务器配置
每个服务器都可以覆盖全局沙盒默认值：
{
"server_name": "untrusted_server",
"config": { "command": "python", "args": ["server.py"] },
"sandbox": {
"enabled": true,
"runtime": "docker",
"image": "my-mcp-image:latest",
"memory_limit": "256m",
"cpu_limit": "0.5",
"network": "none",
"allowed_env": ["GITHUB_TOKEN"]
}
}支持的运行时
| 运行时 | 隔离 | 平台 | 状态 |
|---|---|---|---|
| Docker | 命名空间+cgroup | Linux、macOS、Windows | 生产就绪 |
| Podman | 命名空间+c组（无根） | Linux、macOS | 生产就绪 |
| Microsandbox | 硬件微虚拟机（libkrun） | Linux、macOS | SDK待定 |
| NovaVM | 硬件微虚拟机（KVM） | Linux | CLI待定 |
有关完整的设置指南、配置参考、测试说明和故障排除，请参阅 沙盒隔离演练.
14.部署模式
🪂 Deployment Patterns
14.1本地网关、本地护栏和本地MCP服务器
Local Gateway with Local Guardrails Flow
14.2本地网关、带远程护栏的本地MCP服务器
Local Gateway with Remote Guardrails Flow
14.3带远程MCP服务器和远程护栏的本地网关
Local Gateway with Remote Guardrails and Remote MCP Server Flow
14.4远程网关、远程MCP服务器和远程护栏
Remote Gateway with Remote Guardrails and Remote MCP Server Flow
15.卸载网关
🗑️ Uninstall the Gateway
- 要从任何MCP客户端中删除网关，只需删除MCP服务器块
"Enkrypt Secure MCP Gateway": {...}从客户端的配置文件中。对于Claude Code，运行claude mcp remove Enkrypt-Secure-MCP-Gateway.
- 重新启动MCP客户端，为某些客户端（如Claude Desktop）应用更改。游标不需要重新启动。
- 要卸载pip包，请运行以下命令：
pip uninstall secure-mcp-gateway16.故障排除
🕵 Troubleshooting
- 如果客户端中的任何调用失败，请查看相应客户端的mcp日志
- 示例🍎 Linux/macOS日志路径： ~/Library/Logs/Claude/mcp-server-Enkrypt Secure MCP Gateway.log - 示例🪟 Windows日志路径： %USERPROFILE%\AppData\Roaming\Claude\logs\mcp-server-Enkrypt Secure MCP Gateway.log
- 如果您看到以下错误
Exception: unhandled errors in a TaskGroup (1 sub-exception)那么网关试图使用的MCP服务器可能没有运行。
- 因此，请确保它试图访问的文件可用 - 满足MCP服务器运行的任何先决条件，如 docker 跑步等。
- 如果我们需要更详细的日志，请设置
enkrypt_log_level到debug在enkrypt_mcp_config.json文件并重新启动MCP客户端。
16.1开放遥测故障排除
- SSL握手错误
如果您看到SSL错误，例如：
SSL_ERROR_SSL: error:100000f7:SSL routines:OPENSSL_internal:WRONG_VERSION_NUMBER解决方案：添加 insecure=True 到中的OTLP导出器配置 telemetry.py
- 洛基没有日志
- 验证OTLP收集器是否正在运行：
docker logs secure-mcp-gateway-otel-collector-1- 检查收集器配置 otel_collector/otel-collector-config.yaml
- 验证Loki是否正在接收数据：
curl -G -s "http://localhost:3100/loki/api/v1/query" --data-urlencode 'query={job="enkrypt"}'- 缺少指标
- 检查OTLP收集器度量管道：
curl http://localhost:8888/metrics- 验证收集器日志中的指标：
docker logs secure-mcp-gateway-otel-collector-1 | grep "metrics"- Docker问题
# Restart the stack
docker-compose down
docker-compose up -d
# Check individual service logs
docker logs 17.正在处理的已知问题
- 输出护栏未应用于非文本工具结果。对图像、音频等其他媒体类型的支持即将推出。
18.已知限制
- 网关不支持远程部署网关但本地部署MCP服务器（不暴露于互联网）的情况。这是因为网关需要知道MCP服务器的地址才能向其转发请求。
19.贡献
我们欢迎捐款。请阅读 贡献.md 关于如何提交更改以及我们的 贡献者许可协议（CLA），您通过提交pull请求来同意。
- 看
TODO当前正在进行的工作和尚未实现的功能的文件
- 在本地安装网关以测试您的更改
- 通过遵循 Git克隆步骤 - 或使用 python -m build，激活venv并使用安装 pip install .
- 报告或修复您遇到的任何错误😊
20.测试
🧪 Running Tests
该网关包括一个全面的测试套件，用于验证所有核心功能，包括服务器发现、工具执行、护栏、缓存、遥测等。
先决条件
- 本地安装网关（如下 本地安装)
- 虚拟环境已激活
- Echo OAuth MCP服务器正在运行（用于测试远程服务器场景）
运行测试套件
步骤1：设置环境变量
Windows PowerShell：
$env:MCP_HTTP_MODE="true"Windows命令提示符：
set MCP_HTTP_MODE=truemacOS/Linux：
export MCP_HTTP_MODE="true"此环境变量使echo OAuth服务器能够在HTTP模式下运行以进行测试。
步骤2：启动Echo OAuth服务器
导航到echo服务器目录并启动它：
Windows PowerShell：
cd src\secure_mcp_gateway\bad_mcps
python .\echo_oauth_mcp.pymacOS/Linux：
cd src/secure_mcp_gateway/bad_mcps
python echo_oauth_mcp.py服务器将于启动 http://localhost:8001/mcp/ 并保持运行。保持这个终端打开。
步骤3：运行测试套件
打开一个新终端，激活您的虚拟环境，然后运行测试：
Windows PowerShell：
# Activate virtual environment
.\.venv\Scripts\activate
# Navigate to tests directory
cd tests
# Run tests
python .\test_gateway.pymacOS/Linux：
# Activate virtual environment
source ./.venv/bin/activate
# Navigate to tests directory
cd tests
# Run tests
python test_gateway.py测试覆盖率
测试套件包括：
- 服务器发现测试：列出服务器、获取服务器信息、发现工具
- 工具执行测试：调用工具、多个工具调用、错误处理
- 缓存测试：缓存状态、缓存清除、缓存过期
- 护栏测试：输入/输出防护栏、异步防护栏、PII编辑
- 遥测测试：OpenTetry集成、指标、跟踪、日志
- 配置测试：超时设置、日志级别、外部缓存
- 集成测试：完整的工作流程、错误恢复、性能
预期输出
测试运行器将显示：
- 每次测试的进度
- 成功/失败状态
- 执行持续时间
- 最终总结，包括通过/失败计数
输出示例：
=== Gateway Tools Test Runner ===
Setting up test environment...
Setup complete.
Running Tests...
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✅ test_list_all_servers_basic (0.45s)
✅ test_discover_all_tools_all_servers (1.23s)
✅ test_secure_call_tools_basic (0.89s)
...
=== Test Summary ===
Total Tests: 45
Passed: 45
Failed: 0
Success Rate: 100.0%
Total Duration: 45.67s故障排除测试
Echo服务器连接错误：
- 验证echo OAuth服务器是否在端口8001上运行
- 检查一下
MCP_HTTP_MODE环境变量已设置 - 确保没有其他服务正在使用端口8001
网关配置错误：
- 验证
enkrypt_mcp_config.json存在于~/.enkrypt/目录 - 检查配置文件是否具有有效的网关密钥和服务器配置
- 确保虚拟环境已安装所有依赖项
测试失败：
- 通过设置启用调试日志记录
enkrypt_log_level: "DEBUG"在配置中 - 检查MCP客户端日志以获取详细的错误消息
- 验证是否安装了所有先决条件（Python 3.11+、pip、uv）
21.许可证
21.1 Enkrypt AI MCP网关核心
该项目的核心功能根据Apache许可证2.0版获得许可。
有关完整的许可证文本，请参阅 LICENSE 此存储库中的文件。
21.2 Enkrypt AI护栏、徽标和品牌
©2025 Enkrypt AI。保留所有权利。
Enkrypt AI软件是在专有许可下提供的。严禁未经授权使用、复制或分发本软件或其任何部分。
使用条款： https://www.enkryptai.com/terms-and-conditions
隐私政策： https://app.enkryptai.com/privacy-policy
EnkryptAI和EnkryptAI标志是Enkrypt AI，股份有限公司的商标。