
Enkrypt AI Secure MCP Gateway
β 55from enkryptai
A secure MCP gateway that acts as a proxy, providing authentication, tool discovery, caching, and guardrail enforcement.
Enkrypt AI Secure MCP Gateway

π Featured Blog Post: Learn how the Secure MCP Gateway prevents top attacks and vulnerabilities in our latest blog:
How Enkrypt's Secure MCP Gateway and MCP Scanner Prevent Top Attacks
Discover real-world attack scenarios, security best practices, and how our gateway protects your AI applications.
Overview
This Secure MCP Gateway is built with authentication, automatic tool discovery, caching, and guardrail enforcement.
It sits between your MCP client and MCP servers. So, by it's nature it itself also acts as an MCP server as well as an MCP client :)
When your MCP client connects to the Gateway, it acts as an MCP server. When the Gateway connects to the actual MCP server, it acts as an MCP client.
-
Also see:
- CLI-Commands-Reference.md for the list of commands and their usage
- API-Reference.md for the list of API endpoints and their usage
- MCP Gateway Setup Notebook for a complete walkthrough of all the essential commands
Table of Contents
- 1. Features π
- 2. High level steps of how the MCP Gateway works πͺ
- 3. Prerequisites π§©
- 4. Gateway Setup π¨βπ»
- 5. (Optional) OpenTelemetry Setup π
- 6. Verify Installation and check the files generated β
- 7. Edit the Gateway config as needed βοΈ
- 8. CLI Quick Start Guide π₯οΈ
- 9. (Optional) Add GitHub MCP Server to the Gateway π€
- 9.1 (Optional) Connect to MCP Servers with OAuth π
- 10. (Optional) Protect GitHub MCP Server and Test Echo Server π
- 11. Recommendations for using Guardrails π‘
- 12. Other tools available π§
- 13. (Optional) Sandbox Isolation π‘οΈ
- 14. Deployment Patterns πͺ
- 15. Uninstall the Gateway ποΈ
- 16. Troubleshooting π΅
- 17. Known Issues being worked on ποΈ
- 18. Known Limitations β οΈ
- 19. Contribute π€
- 20. Testing π§ͺ
- 21. License
1. Features

Below are the list of features Enkrypt AI Secure MCP Gateway provides:
-
Authentication: We use Unique Key to authenticate with the Gateway. We also use Enkrypt API Key if you want to protect your MCPs with Enkrypt Guardrails. Additionally, a secure
admin_apikey(256-character random string) is automatically generated for administrative REST API operations. -
Ease of use: You can configure all your MCP servers locally in the config file or better yet in Enkrypt (Coming soon) and use them in the Gateway by using their name
-
Dynamic Tool Discovery: The Gateway discovers tools from the MCP servers dynamically and makes them available to the MCP client
-
Restrict Tool Invocation: If you don't want all tools to be accessible of a an MCP server, you can restrict them by explicitly mentioning the tools in the Gateway config so that only the allowed tools are accessible to the MCP client
-
Caching: We cache the user gateway config and tools discovered from various MCP servers locally or in an external cache server like KeyDB if configured to improve performance
-
Guardrails: You can configure guardrails for each MCP server in Enkrypt both on input side (before sending the request to the MCP server) and output side (after receiving the response from the MCP server)
-
Logging: We log every request and response from the Gateway locally in your MCP logs and also forward them to Enkrypt (Coming soon) for monitoring. This enables you to see all the calls made in your account, servers used, tools invoked, requests blocked, etc.
-
Sandbox Isolation: MCP servers can be launched inside isolated sandbox environments (Docker, Podman, or microVMs) so that a compromised or malicious server cannot access the host filesystem, network, or other resources. Each sandbox is ephemeral β created per session and destroyed when done.
1.1 Guardrails

Input Protection: Topic detection, NSFW filtering, toxicity detection, injection attack prevention, keyword detection, policy violation detection, bias detection, and PII redaction (More coming soon like system prompt protection, copyright protection, etc.)
Output Protection: All input protections plus adherence checking and relevancy validation (More coming soon like hallucination detection, etc.) We also auto unredact the response if it was redacted on input.
1.2 Concepts
-
MCP Config is an array of MCP servers like
mcp_server_1,mcp_server_2,mcp_server_3etc.- Each config has a unique ID
-
User is a user of the gateway with unique email and ID
-
A project is a collection of users that share an MCP Config
- Project has a name and unique ID
- The MCP Config can be updated or can be pointed to a different config by the Admin
- Users can be added to multiple projects
-
An API Key is created for a user and project combination
- A user can have different API Keys for different projects
- This API Key is used to authenticate the user and identify the right project and MCP Config
-
See 6.5 Example config file generated and 7. Edit the Gateway config as needed for schema reference
2. High level steps of how the MCP Gateway works

-
Your MCP client connects to the Secure MCP Gateway server with API Key (handled by
src/secure_mcp_gateway/gateway.py). -
Gateway server fetches gateway config from local
enkrypt_mcp_config.jsonfile or remote Enkrypt Auth server (Coming soon).- It caches the config locally or in an external cache server like KeyDB if configured to improve performance.
-
If input guardrails are enabled, request is validated before the tool call (handled by
src/secure_mcp_gateway/guardrail.py).- Request is blocked if it violates any of the configured guardrails and the specific detector is configured to block.
-
Requests are forwarded to the Gateway Client (handled by
src/secure_mcp_gateway/client.py). -
The Gateway client forwards the request to the appropriate MCP server (handled by
src/secure_mcp_gateway/client.py). -
The MCP server processes the request and returns the response to the Gateway client.
-
If it was a discover tools call, the Gateway client caches the tools locally or in an external cache server like KeyDB if configured. It then forwards the response to the Gateway server.
-
The Gateway server receives the response from the Gateway client and if output guardrails are enabled, it validates the response against the configured guardrails (handled by
src/secure_mcp_gateway/guardrail.py).- Response is blocked if it violates any of the configured guardrails and the specific detector is configured to block.
-
The Gateway server forwards the response back to the MCP client if everything is fine.
7. Edit the Gateway config as needed
<details> <summary><strong>βοΈ Edit Gateway Config </strong></summary>-
Important:
- We need to restart Claude Desktop after editing the config file
- To make all new tools accessible, please use prompt "
list all servers, get all tools available" for the MCP Client to discover all new tools. After this the MCP Client should be able to use all tools of the servers configured in the Gateway config file
-
You can add many MCP servers inside the
mcp_configarray of this gateway config-
You can look here for example servers
-
You can also try the Enkrypt MCP Server
-
Example:
{ "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.000
-
# ------------------
# 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 uvBefore it works, you'll need: ENKRYPT_GATEWAY_KEYENKRYPT_PROJECT_IDENKRYPT_USER_ID
3. Prerequisites
<details> <summary><strong>π Dependencies </strong></summary>-
Git 2.43or higher -
Python 3.11or higher installed on your system and is accessible from the command line using eitherpythonorpython3command -
pip 25.0.1or higher is installed on your system and is accessible from the command line using eitherpiporpython -m pipcommand -
uv 0.7.9or higher is installed on your system and is accessible from the command line using eitheruvorpython -m uvcommand
-
Check if Python, pip and uv are installed
-
If any of the below commands fail, please refer the respective documentation to install them properly
# ------------------
# 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
-
Install Claude Desktop as the MCP Client from their website if you haven't already and login to it
- If you are using Linux and cannot run any unofficial version of Claude Desktop, you can use any supported MCP Client to test the Gateway. If it does not support mcp cli
mcp installcommand, then go through the scripts code and run the commands supported manually.
- If you are using Linux and cannot run any unofficial version of Claude Desktop, you can use any supported MCP Client to test the Gateway. If it does not support mcp cli
-
Any other dependencies required for the MCP servers we want to proxy requests to
-
Follow the instructions of the respective MCP server to install its dependencies
-
Like
Node.js,npx,docker, etc.
-
-
(Optional) A cache server like KeyDB installed and running (If you want to cache externally and not locally)
If you want to protect your MCPs with Enkrypt Guardrails, you need to do the following:
-
Create a new account if you don't have one. It's free! π No credit card required π³π«
-
An
ENKRYPT_API_KEYwhich you can get from Enkrypt Dashboard Settings -
To protect your MCPs with Guardrails, you can use the default sample Guardrail
Sample Airline Guardrailto get started or you can create your own custom Guardrail -
To configure custom Guardrails, you need to either login to Enkrypt AI App or use the APIs/SDK
4. Gateway Setup
4.1 Local Installation with pip
<details> <summary><strong>π¦ Pip Installation Steps </strong></summary>4.1.1 Download and Install the Package
-
Activate a virtual environment
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 -
Install the package. For more info see https://pypi.org/project/secure-mcp-gateway/
pip install secure-mcp-gateway
4.1.2 Run the Generate Command
-
This generates the config file at
~/.enkrypt/enkrypt_mcp_config.jsonon macOS and%USERPROFILE%\.enkrypt\enkrypt_mcp_config.jsonon Windowssecure-mcp-gateway generate-config
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 of the generated config file
<details> <summary><strong>π Example file in macOS</strong></summary> <br>- This is an example of the default configuration file generated by the CLI on macOS:
{
"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"
}
}
}
- This is an example of the default configuration file generated by the CLI on Windows:
{
"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\\<User>\\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 Install the Gateway for Claude Desktop
-
Run the following command to install the gateway for Claude:
secure-mcp-gateway install --client claude-desktop -
This will register Enkrypt Secure MCP Gateway with Claude Desktop.
-
NOTE: Please restart Claude Desktop after installation
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 Example of the Claude Desktop Config after installation
<details> <summary><strong>π Example file in macOS</strong></summary> <br>-
~/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" } } } }
-
%USERPROFILE%\AppData\Roaming\Claude\claude_desktop_config.json{ "mcpServers": { "Enkrypt Secure MCP Gateway": { "command": "mcp", "args": [ "run", "C:\\Users\\<User>\\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 Install the Gateway for Cursor
-
Run the CLI Install Command for Cursor
secure-mcp-gateway install --client cursor -
This automatically updates your ~/.cursor/mcp.json (on Windows it is at: %USERPROFILE%.cursor\mcp.json) with the correct entry.
-
Although it is not usually required to restart, if you see it in loading state for a long time, please restart Cursor
-
~/.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" } } } }
-
%USERPROFILE%\.cursor\mcp.json{ "mcpServers": { "Enkrypt Secure MCP Gateway": { "command": "uv", "args": [ "run", "--with", "mcp[cli]", "mcp", "run", "C:\\Users\\<User>\\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 Install the Gateway for Claude Code
Claude Code is Anthropic's CLI-based coding agent. It uses claude mcp add commands to configure MCP servers. Unlike Claude Desktop and Cursor which use JSON config files, Claude Code manages MCP servers through its own CLI.
Prerequisite: The
claudeCLI must be installed on your system. See Claude Code docs for installation.
Step 1: Install the gateway
secure-mcp-gateway install --client claude-codeThis automatically:
- Reads your gateway key, project ID, and user ID from the generated config
- Runs
claude mcp addwith the correct credentials and gateway path - Registers the server with
--scope user(available across all Claude Code projects)
Step 2: Verify the server was added
claude mcp listYou should see Enkrypt-Secure-MCP-Gateway in the list.
Step 3: Use the gateway in Claude Code
Launch Claude Code and try:
list all servers, get all tools availableGet your credentials from the generated enkrypt_mcp_config.json and the gateway path:
python -c "import secure_mcp_gateway.gateway; print(secure_mcp_gateway.gateway.__file__)"Then add the gateway manually:
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</details> </details>Note: The server name must use hyphens or underscores β Claude Code does not allow spaces in names.
4.2 Local Installation with git clone
<details> <summary><strong>ποΈ Git Clone Installation Steps </strong></summary>4.2.1 Clone the repo, setup virtual environment and install dependencies
- Clone the repository:
git clone https://github.com/enkryptai/secure-mcp-gateway
cd secure-mcp-gateway
# ------------------
# 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
- Install Python dependencies:
uv pip install -r requirements.txt
- Verify mcp cli got installed successfully:
mcp version
# Example output
MCP version 1.9.2
4.2.2 Run the setup script
<!-- - The `setup` script checks versions of Python, pip, uv and makes sure they are installed and accessible --> <!-- - It then installs the dependencies -->-
This script creates the config file at
~/.enkrypt/enkrypt_mcp_config.jsonon macOS and%USERPROFILE%\.enkrypt\enkrypt_mcp_config.jsonon Windows based onsrc/secure_mcp_gateway/example_enkrypt_mcp_config.jsonfile -
It replaces
UNIQUE_GATEWAY_KEYand otherUUIDswith auto generated values and also replacesDUMMY_MCP_FILE_PATHwith the actual path to the test MCP filebad_mcps/echo_mcp.py -
It also installs the MCP client in Claude Desktop
-
NOTE: Please restart Claude Desktop after running the setup script to see the Gateway running in 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
-------------------------------
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 Setup Other MCP Clients
<details> <summary><strong>⬑ Cursor </strong></summary> <br>-
You can navigate to cursor's Global MCP file at
~/.cursor/mcp.jsonon Linux/macOS or%USERPROFILE%\.cursor\mcp.jsonon Windows- If you would like to use at a Project level place it inside your project. For details see Cursor's docs
-
You can also navigate to the file Via cursor's UI by clicking on
settingsgear icon on the top right
-
Click on
MCPand then click onAdd new global MCP serverwhich takes you to themcp.jsonfile
-
Example
mcp.jsonfile opened in the editor
-
Once the file is opened at Global or Project level, you can copy paste the same config we used in
Claude Desktop. For reference, you can refer to Installation - 6.2 Example MCP config file generated π- Be sure to use your own file that was generated by the
setupscript in Installation - 4.2.2 Run the setup script π₯. Please do not copy paste the example config file in this repo.
- Be sure to use your own file that was generated by the
-
See Verify Cursor section to verify the MCP server is running in Cursor
-
Claude Code uses its own CLI to manage MCP servers instead of JSON config files
-
Get your credentials from the generated
enkrypt_mcp_config.json(gateway key, project ID, user ID) -
Find the gateway.py path:
python -c "import secure_mcp_gateway.gateway; print(secure_mcp_gateway.gateway.__file__)" -
Add the gateway to 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 -
Verify:
claude mcp list -
For detailed setup, see 4.1.7 Install the Gateway for Claude Code
4.3 Docker Installation
<details> <summary><strong>π³ Docker Installation Steps </strong></summary>4.3.1 Build the Docker Image
docker build -t secure-mcp-gateway .
[+] 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 Generate the config file
- This creates a config file in the
~/.enkrypt/docker/enkrypt_mcp_config.jsonfile on macOS/Linux and%USERPROFILE%\.enkrypt\docker\enkrypt_mcp_config.jsonfile on Windows.
<details> <summary><strong>Verbose Docker run commands (if CLI is not installed locally)</strong></summary>Quick shorthand β If you have the CLI installed locally via pip, you can use the
--dockerflag on any command and skip the verbose Docker syntax:secure-mcp-gateway --docker generate-config
# 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
{
"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 Install the Gateway in Claude Desktop
- You can find the Claude config location at the below locations in your system. For reference see Claude docs.
- macOS:
~/Library/Application Support/Claude - Windows:
%APPDATA%\Claude
- macOS:
Note: The generated config includes
MCP_TRANSPORT=stdiofor stdio mode communication with Claude Desktop.
# 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 Example Claude Desktop config file
<details> <summary><strong>πͺ Example Windows claude_desktop_config.json</strong></summary> <br>{
"mcpServers": {
"Enkrypt Secure MCP Gateway": {
"command": "docker",
"args": [
"run",
"--rm",
"-i",
"-e",
"MCP_TRANSPORT=stdio",
"-v",
"C:\\Users\\<user>\\.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 Install the Gateway in Cursor
- You can find the Cursor config location at the below locations. For reference see Cursor docs.
- macOS:
~/.cursor - Windows:
%USERPROFILE%\.cursor
- macOS:
Note: The generated config includes
MCP_TRANSPORT=stdiofor stdio mode communication with Cursor.
# 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 Install the Gateway in Claude Code
Claude Code uses its own CLI (claude mcp add) to manage MCP servers. When running the gateway in Docker, Claude Code connects via npx mcp-remote to the gateway's Streamable HTTP endpoint.
Prerequisites: Node.js and npm must be installed on your machine (
node -vandnpm -vto verify).
Step 1: Run the gateway container
Start the gateway as a background Docker container with the Streamable HTTP endpoint exposed:
# 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-gatewayStep 2: Add the gateway to 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/Replace YOUR_GATEWAY_KEY, YOUR_PROJECT_ID, and YOUR_USER_ID with the values from your enkrypt_mcp_config.json.
If you prefer stdio mode (no persistent container), you can add Claude Code's MCP config using JSON directly. Create or edit ~/.claude.json and add the server under mcpServers:
{
"mcpServers": {
"Enkrypt Secure MCP Gateway": {
"command": "docker",
"args": [
"run",
"--rm",
"-i",
"-e",
"MCP_TRANSPORT=stdio",
"-v",
"/Users/<user>/.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"
}
}
}
}Or use the 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/<user>/.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"
}
}'</details>Note on Windows (PowerShell): Replace
/Users/<user>/.enkrypt/dockerwith your Windows path (e.g.,C:\Users\<user>\.enkrypt\docker) and adjust the volume mount syntax accordingly.
Step 3: Verify
claude mcp listStep 4: Use in Claude Code
Launch Claude Code and try prompts like list all servers, get all tools available.
4.3.7 Running Gateway with Docker Run (Advanced)
For advanced Docker deployments, you can run the gateway container directly with custom configurations:
# 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:latestEnvironment Variables
| Variable | Description | Default | Required |
|---|---|---|---|
ENKRYPT_GATEWAY_KEY | API key for authentication | - | Yes |
ENKRYPT_PROJECT_ID | Project ID from config | - | Yes |
ENKRYPT_USER_ID | User ID from config | - | Yes |
MCP_TRANSPORT | Transport mode: streamable-http or stdio | streamable-http | No |
SKIP_DEPENDENCY_INSTALL | Skip runtime dependency installation | true (Docker), false (other) | No |
HOST | Gateway bind address | 0.0.0.0 | No |
FASTAPI_HOST | FastAPI server bind address | 0.0.0.0 | No |
MCP_TRANSPORT
The MCP_TRANSPORT environment variable controls the transport mode for the gateway.
Transport modes:
streamable-http(default): HTTP server mode on port 8000. Use with-p 8000:8000for port mapping.stdio: Standard input/output mode for MCP clients that communicate via stdin/stdout. Use with-iflag.
Example for stdio mode (Claude Desktop, Cursor):
docker run --rm -i -e MCP_TRANSPORT=stdio -v ~/.enkrypt/docker:/app/.enkrypt/docker -e ENKRYPT_GATEWAY_KEY="your-gateway-key" secure-mcp-gatewaySKIP_DEPENDENCY_INSTALL
The SKIP_DEPENDENCY_INSTALL environment variable controls whether the gateway reinstalls Python dependencies at runtime.
Default behavior:
- Docker environments: Defaults to
true(auto-detected). Dependencies are pre-installed in the Docker image, so runtime installation is skipped automatically. - Non-Docker environments: Defaults to
false. Dependencies are installed at startup to ensure compatibility.
When to explicitly set SKIP_DEPENDENCY_INSTALL=false in Docker:
- Development environments where you're testing new dependencies
- When mounting source code volumes for live development
- If you're unsure whether all dependencies are properly installed
When to explicitly set SKIP_DEPENDENCY_INSTALL=true outside Docker:
- Production deployments where dependencies are pre-installed
- To reduce startup time (faster cold starts)
- In environments where you've already run
pip install
Example with docker-compose integration:
# 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:latestNote: The --network flag connects the gateway to the observability stack (Grafana, Prometheus, Loki, Jaeger) if you're running the monitoring services from section 5.
Port Mapping
8000: Gateway MCP server (required)8080: OAuth callback server (optional, only needed for Authorization Code flow)8001: REST API server (optional, if you want to expose the management API)
Volume Mounts
~/.enkrypt/docker:/app/.enkrypt/docker- Config file location (required)- Additional mounts may be needed if your MCP servers require access to local files
β οΈ Important: MCP clients (Claude Desktop, Cursor, Claude Code) spawn Docker directly without a shell, so
~(tilde) will not be expanded. Always use absolute paths in your MCP client config JSON files (e.g./Users/yourname/.enkrypt/docker:/app/.enkrypt/dockeron macOS/Linux orC:\\Users\\yourname\\.enkrypt\\docker:/app/.enkrypt/dockeron Windows).
β οΈ Important: Configuring MCP Servers When Gateway Runs in Docker
When running the Enkrypt Gateway in Docker, DO NOT configure your MCP servers to also run in Docker mode. This causes Docker-in-Docker issues, networking problems, and volume mount complications.
β Avoid (Docker-based MCP servers):
{
"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"
}
}
}β Use instead (npx/npm/Python-based servers):
{
"server_name": "github_server",
"config": {
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-github"
],
"env": {
"GITHUB_PERSONAL_ACCESS_TOKEN": "your-token"
}
}
}Why?
- Docker-in-Docker requires privileged mode and special socket mounting
- Network isolation prevents containers from communicating properly
- Volume mounts don't work as expected across container boundaries
- Performance overhead and security concerns
- Increased complexity and debugging difficulty
Recommended MCP Server Formats When Gateway is in Docker:
- β
npx-based servers:
npx -y @modelcontextprotocol/server-* - β
npm-based servers:
npm exec -y server-name - β
Python-based servers:
python /path/to/server.pyoruv run server.py - β
Node.js-based servers:
node /path/to/server.js - β
Remote MCP servers:
npx mcp-remote https://api.example.com/mcp/
Exception:
If you absolutely must use Docker-based MCP servers, consider:
- Running the gateway outside of Docker (local installation), OR
- Setting up proper Docker networking with
--network hostor custom bridge networks, OR - Using Docker-in-Docker with proper configuration (requires
--privilegedflag and/var/run/docker.sockmount - not recommended for production)
4.4 Remote Installation
<details> <summary><strong>π Remote Installation Steps </strong></summary>4.4.1 Run the Gateway in a remote server
python gateway.py
-
Or run in k8s using our docker image
enkryptai/secure-mcp-gateway:vx.x.x -
Example:
enkryptai/secure-mcp-gateway:v2.1.2 -
Use the latest version from Docker Hub: https://hub.docker.com/r/enkryptai/secure-mcp-gateway/tags
-
You can either mount the config file locally or download the json file from a remote place like
S3using aninitContainerand mount the volume -
See
docs/secure-mcp-gateway-manifest-example.yamlfor the complete manifest file reference
4.4.2 Modify your MCP Client config to use the Gateway
-
You can find the Claude Desktop config location at the below locations in your system. For reference see Claude docs.
- macOS:
~/Library/Application Support/Claude - Windows:
%APPDATA%\Claude
- macOS:
-
You can find the Cursor config location at the below locations. For reference see Cursor docs.
- macOS:
~/.cursor - Windows:
%USERPROFILE%\.cursor
- macOS:
-
Replace the
ENKRYPT_GATEWAY_KEYwith the key you got from theenkrypt_mcp_config.jsonfile -
Replace the
http://0.0.0.0:8000/mcp/with thehttp(s)://<remote_server_ip>:<port>/mcp/ -
If you are running this locally, you can use
http://0.0.0.0:8000/mcp/ -
You can setup ingress to route the traffic to the MCP Gateway over
https -
Example:
https://mcp.enkryptai.com/mcp/ -
NOTE: Please make sure node and npm are installed on the client machine
- To verify, run
node -vandnpm -v
- To verify, run
-
NOTE: Make sure to use the trailing slash
/in the MCP URL like/mcp/
For Claude Desktop and Cursor β add the following to your claude_desktop_config.json or 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"
}
}
}
}
For Claude Code β use the claude mcp add command:
# 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/</details>Note: For local testing with HTTP (not HTTPS), add
--allow-httpif required, or usehttp://0.0.0.0:8000/mcp/as the URL.
5. (Optional) OpenTelemetry Setup
<details> <summary><strong>π OpenTelemetry Setup and Usage </strong></summary> <br>This section explains how to set up and use OpenTelemetry (OTEL) with the Enkrypt Secure MCP Gateway for observability.
5.1 Architecture
The observability stack includes:
-
OpenTelemetry Collector: Collects telemetry data (traces, metrics, logs)
-
Jaeger: Distributed tracing visualization
-
Loki: Log aggregation and querying
-
Prometheus: Metrics aggregation
-
Grafana: Unified visualization for metrics and logs
- Traces are not visible in Grafana for some reason. Please use Jaeger for traces.
5.2 Prerequisites
-
Docker and Docker Compose installed
-
Gateway installed and running (follow section 4)
5.3 Setup Steps
-
Start the Observability Stack
cd infra docker-compose up -d -
To stop the Observability Stack
# When we want to stop the Observability Stack, run the below command docker-compose down
5.4 Configuration
-
Edit the
enkrypt_mcp_config.jsonfile to enable telemetry{ "common_mcp_gateway_config": { ... "enkrypt_telemetry": { "enabled": true, "insecure": true, "endpoint": "http://localhost:4317" } }, ... }
5.5 Verification Steps
-
Verify Services are Running
# On Windows docker ps | findstr "loki grafana jaeger otel prometheus" # On Linux/macOS docker ps | grep -E "loki|grafana|jaeger|otel|prometheus" -
Access Service UIs
-
Grafana: http://localhost:3000 (default credentials: admin/admin)
-
Jaeger: http://localhost:16686
-
Prometheus: http://localhost:9090
-
Loki: Access through Grafana
- Open Grafana (http://localhost:3000)
- Go to Explore (left sidebar)
- Select "Loki" from the data source dropdown
-
-
Verify Gateway Telemetry
-
Make test requests through the Gateway like
List all servers and toolsandecho test -
Check traces in Jaeger:
-
Add optional tags like
enkrypt_email=default@example.comorenkrypt_project_name=default_projectorenkrypt_mcp_config_id=fcbd4508-1432-4f13-abb9-c495c946f638to see the traces for a specific user, project or MCP config etc. -
We can also combine tags by separating them with spaces like
enkrypt_email=default@example.com enkrypt_project_name=default_project -
Look for
enkrypt_discover_all_toolsspans -
Examine child spans for cache, tool discovery, etc.

-
-
Check metrics in Grafana:
-
Navigate to
Drilldown->metrics -
We can filter on various labels like
email,user_id,mcp_config_id,project_id,project_nameetc.
-
-
Check logs in Grafana
-
Navigate to
Drilldown->Logs -
Select label as
service_name=secure-mcp-gatewayand clickShow logs -
Now we can filter by various labels like
attributes_project_name,attributes_project_id,attributes_email,attributes_user_id,attributes_mcp_config_id,attributes_tool_nameetc.
-
-
Check Dashboards in Grafana by navigating to
Dashboards->OpenTelemetry Gateway Metrics- Due to issues in Grafana, you may need to edit each tile and click
Run queriesto see the data
- Due to issues in Grafana, you may need to edit each tile and click
-
5.6 Available Telemetry (Not exhaustive)
-
Traces
- Request processing pipeline
- Tool invocations with duration tracking
- Cache operations (hits/misses)
- Guardrail checks
- Error tracking and status monitoring
- Detailed attributes for debugging
-
Metrics
enkrypt_list_all_servers_calls: API endpoint usagemcp_cache_misses_total: Cache efficiency trackingenkrypt_servers_discovered: Server discovery monitoringmcp_tool_calls_total: Tool invocation trackingmcp_tool_call_duration_seconds: Performance monitoring (histogram)
-
Logs
- Structured JSON format for better querying
- Gateway operations with context
- Error conditions with stack traces
- Security events and guardrail checks
- Performance data with timing information
6. Verify Installation and check the files generated
<details> <summary><strong>β Verification steps and files generated</strong></summary>6.1 Verify Claude Desktop
-
To verify Claude installation, navigate to
claude_desktop_config.jsonfile by following these instructions-
macOS:
~/Library/Application Support/Claude/claude_desktop_config.json -
Windows:
%APPDATA%\Claude\claude_desktop_config.json
-
6.2 Example MCP config file generated
<details> <summary><strong>π Example file in macOS</strong></summary> <br>-
~/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" } } } }
-
%USERPROFILE%\AppData\Roaming\Claude\claude_desktop_config.json{ "mcpServers": { "Enkrypt Secure MCP Gateway": { "command": "mcp", "args": [ "run", "C:\\Users\\<User>\\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 Restart Claude Desktop to run the Gateway
-
After restarting, navigate to Claude Desktop
Settings
-
Click on
Developer->Enkrypt Secure MCP Gateway
-
You can also click on the settings icon below the search bar to see the Gateway in available

-
Click on
Enkrypt Secure MCP Gatewayto see the list of tools available
-
You can check Claude logs while asking Claude to do something to see the Gateway in action
-
Example π Linux/macOS log path:
~/Library/Application Support/Claude/logs/mcp-server-Enkrypt Secure MCP Gateway.log -
Example πͺ Windows log path:
%USERPROFILE%\AppData\Roaming\Claude\logs\mcp-server-Enkrypt Secure MCP Gateway.log
-
6.4 Example prompts
list all servers, get all tools available and echo test- This uses a test MCP server
echo_serverwhich is inbad_mcps/echo_mcp.py
- This uses a test MCP server

-
We can also combine multiple prompts into one that trigger multiple tool calls at once
-
Example:
echo test and also echo best

-
Example:
echo "hello; ls -la; whoami" -
This could be a malicious prompt but because no guardrails are enabled, it will not be blocked

6.5 Example config file generated
-
Example
enkrypt_mcp_config.jsongenerated by thesetupscript in~/.enkrypt/enkrypt_mcp_config.jsonon macOS and%USERPROFILE%\.enkrypt\enkrypt_mcp_config.jsonon Windows -
If you ran docker command to install the Gateway, the config file will be in
~/.enkrypt/docker/enkrypt_mcp_config.jsonon macOS and%USERPROFILE%\.enkrypt\docker\enkrypt_mcp_config.jsonon 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\\<User>\\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 Verify Cursor
-
You can see the MCP server in the list of MCP servers in Cursor by navigating to
~/.cursor/mcp.jsonand also by clicking on the settings icon on the top right and then clicking onTools & Integrationsor on theMCPtab -
Generally restarting is not needed but if it is in loading state for a long time, please restart Cursor

-
Now you can chat with the MCP server.
-
Example prompts:
-
(Click
Run Toolwhen Cursor asks you to) -
list all servers, get all tools available and echo test- This uses a test MCP server
echo_serverwhich is inbad_mcps/echo_mcp.py
- This uses a test MCP server

-
-
6.7 Verify Claude Code
-
Run
claude mcp listto see the gateway in the list of configured MCP servers -
Launch Claude Code and run
/mcpto check server status -
Try
list all servers, get all tools available and echo testas a prompt to verify the gateway is working
No common issues documented yet. If you hit a problem, the repository's GitHub Issues page is the best place to look.