Enkrypt AI Secure MCP Gateway

1. Tu cliente MCP se conecta al servidor Secure MCP Gateway con la Clave API (manejado por src/secure_mcp_gateway/gateway.py).

2. El servidor del Gateway obtiene la configuración del gateway ya sea del archivo local enkrypt_mcp_config.json (plugins.auth.provider = "local_apikey") o de la nube remota de Enkrypt en https://api.enkryptai.com/mcp-gateway/get-gateway-config (plugins.auth.provider = "enkrypt"). Consulta §14.5 Esquema de configuración del Gateway para ambas formas.

   • Almacena en caché la configuración localmente o en un servidor de caché externo como KeyDB si está configurado para mejorar el rendimiento.

3. Si los guardarraíles de entrada están habilitados, la solicitud se valida antes de la llamada a la herramienta (manejado por src/secure_mcp_gateway/guardrail.py).

   • La solicitud se bloquea si viola cualquiera de los guardarraíles configurados y el detector específico está configurado para bloquear.

4. Las solicitudes se reenvían al Cliente del Gateway (manejado por src/secure_mcp_gateway/client.py).

5. El cliente del Gateway reenvía la solicitud al servidor MCP apropiado (manejado por src/secure_mcp_gateway/client.py).

6. El servidor MCP procesa la solicitud y devuelve la respuesta al cliente del Gateway.

7. Si fue una llamada de descubrimiento de herramientas, el cliente del Gateway almacena en caché las herramientas localmente o en un servidor de caché externo como KeyDB si está configurado. Luego reenvía la respuesta al servidor del Gateway.

8. El servidor del Gateway recibe la respuesta del cliente del Gateway y si los guardarraíles de salida están habilitados, valida la respuesta contra los guardarraíles configurados (manejado por src/secure_mcp_gateway/guardrail.py).

   • La respuesta se bloquea si viola cualquiera de los guardarraíles configurados y el detector específico está configurado para bloquear.

9. El servidor del Gateway reenvía la respuesta de vuelta al cliente MCP si todo está bien.

• Git 2.43 o superior

• Python 3.11 o superior instalado en tu sistema y accesible desde la línea de comandos usando el comando python o python3

• pip 25.0.1 o superior instalado en tu sistema y accesible desde la línea de comandos usando el comando pip o python -m pip

• uv 0.7.9 o superior instalado en tu sistema y accesible desde la línea de comandos usando el comando uv o python -m 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

Si deseas proteger tus MCPs con los Guardarraíles de Enkrypt, necesitas hacer lo siguiente:

• Crea una nueva cuenta si no tienes una. ¡Es gratis! 🆓 No se requiere tarjeta de crédito 💳🚫

• Una ENKRYPT_API_KEY que puedes obtener desde Configuración del Panel de Enkrypt

• Para proteger tus MCPs con Guardarraíles, puedes usar el Guardarraíl de muestra predeterminado Sample Airline Guardrail para comenzar o puedes crear tu propio Guardarraíl personalizado

• Para configurar Guardarraíles personalizados, necesitas iniciar sesión en la aplicación Enkrypt AI o usar las APIs/SDK

  • Crear Guardarraíles en el Panel de la aplicación Enkrypt AI ✅

  • Crear Guardarraíles usando APIs

  • Crear Guardarraíles usando SDK

  • También puedes usar el Servidor MCP de Enkrypt 🤯 para crear Guardarraíles y usarlos en el Gateway

4.1.1 Descargar e instalar el paquete

• Activa un entorno virtual

  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
  

• Instala el paquete. Para más información consulta https://pypi.org/project/secure-mcp-gateway/

  pip install secure-mcp-gateway
  

4.1.2 Ejecutar el comando de generación

• Esto genera el archivo de configuración en ~/.enkrypt/enkrypt_mcp_config.json en macOS y %USERPROFILE%\.enkrypt\enkrypt_mcp_config.json en Windows

  secure-mcp-gateway generate-config
  

⚠️ ¿Re-ejecutando sobre una configuración existente? generate-config se niega a sobrescribir un archivo existente por defecto — sale con INFO: Config file already exists at <path>. ... use --overwrite flag. Añade --overwrite para regenerar (se escribe una copia de seguridad .bkp.<YYYYMMDD_HHMMSS> con marca de tiempo junto al original primero). La bandera también funciona con --provider enkrypt a continuación.

secure-mcp-gateway generate-config --overwrite

Elegir un proveedor de autenticación en el momento de la generación

El comando predeterminado emite el esquema completo de local-apikey — un servidor echo de muestra, un proyecto predeterminado, un usuario y una clave API de gateway generada automáticamente — todo lo que necesitas para arrancar sin conexión. Si en su lugar deseas que el gateway obtenga sus servidores/proyectos/usuarios de Enkrypt cloud, genera la configuración mínima respaldada por la nube:

secure-mcp-gateway generate-config --provider enkrypt

Esto escribe un archivo mucho más corto que contiene solo:

• enkrypt_config.api_key y base_url (tú completas la apikey)
• plugins.auth.provider = "enkrypt" con un marcador de posición gateway_name
• plugins.guardrails.provider = "enkrypt"
• plugins.telemetry.provider = "opentelemetry" (OTLP gRPC a localhost:4317, coincidiendo con el valor predeterminado de local-apikey y la pila incluida de Prometheus/Grafana/Jaeger/Loki — establece config.enabled: false si no tienes un collector en ejecución)
• Dos entradas comúnmente ajustadas bajo common_mcp_gateway_config (enkrypt_log_level, enkrypt_gateway_cache_expiration_minutes)

Sin bloques locales de mcp_configs / projects / users / apikeys — la nube es dueña de esos. Después de la generación, edita el archivo y establece:

1. enkrypt_config.api_key → tu apikey de Enkrypt cloud
2. plugins.auth.config.gateway_name → el saved_name del gateway que creaste en la consola de Enkrypt

gateway_name es el único valor que también puede llegar por solicitud, como el encabezado X-Enkrypt-MCP-Gateway del cliente MCP, de modo que un solo proceso de gateway pueda servir varios gateways en la nube. Cuando se establece en la configuración, la configuración gana. Referencia completa de claves de configuración y encabezados: §7.1 Proveedor de autenticación de Enkrypt cloud y encabezados de gateway.

El archivo de referencia incluido es src/secure_mcp_gateway/example_enkrypt_cloud_config.json — con la misma forma que genera la CLI. Úsalo como plantilla para configuraciones escritas a mano.

Valores de flag admitidos:

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_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

INFO: Initializing Enkrypt Secure MCP Gateway CLI Module v2.2.0
INFO: HOME_DIR: C:\Users\PC
INFO: GATEWAY_PY_PATH:  C:\Users\PC\Documents\GitHub\EnkryptAI\secure-mcp-gateway\.secure-mcp-gateway-venv\Lib\site-packages\secure_mcp_gateway\gateway.py
INFO: ECHO_SERVER_PATH:  C:\Users\PC\Documents\GitHub\EnkryptAI\secure-mcp-gateway\.secure-mcp-gateway-venv\Lib\site-packages\secure_mcp_gateway\bad_mcps\echo_oauth_mcp.py
INFO: PICKED_CONFIG_PATH:  C:\Users\PC\.enkrypt\enkrypt_mcp_config.json
INFO: Generating minimal Enkrypt-cloud configuration (plugins.auth.provider=enkrypt)...
SUCCESS: Generated config at C:\Users\PC\.enkrypt\enkrypt_mcp_config.json
INFO: Before starting the gateway, edit the file and set:
  * enkrypt_config.api_key            (replace 'YOUR_ENKRYPT_API_KEY' with your Enkrypt cloud apikey)
  * plugins.auth.config.gateway_name  (replace 'your-gateway-saved-name' with the saved_name of the gateway you created in Enkrypt cloud)

4.1.3 Ejemplo del archivo de configuración generado

Nota: Los ejemplos a continuación muestran el esquema completo emitido por secure-mcp-gateway generate-config (--provider local_apikey predeterminado). Cada campo está incluido para que puedas comparar tu archivo generado 1:1. El bloque oauth_config se envía deshabilitado ("enabled": false) — sus claves son marcadores de posición que solo necesitas completar si un servidor usa OAuth. El bloque timeout_settings contiene los tiempos de espera por operación que el gateway usa internamente; los valores predeterminados son sensatos y rara vez necesitan edición.

{
  "admin_apikey": "AUTO_GENERATED_256_CHAR_KEY",
  "enkrypt_config": {
    "api_key": "YOUR_ENKRYPT_API_KEY",
    "base_url": "https://api.enkryptai.com"
  },
  "common_mcp_gateway_config": {
    "enkrypt_log_level": "INFO",
    "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_gateway_cache_expiration_minutes": 5,
    "enkrypt_config_watcher_poll_seconds": 2.0,
    "enkrypt_async_input_guardrails_enabled": false,
    "enkrypt_async_output_guardrails_enabled": false,
    "timeout_settings": {
      "default_timeout": 90,
      "guardrail_timeout": 390,
      "auth_timeout": 30,
      "tool_execution_timeout": 360,
      "discovery_timeout": 540,
      "cache_timeout": 15,
      "connectivity_timeout": 6,
      "escalation_policies": {
        "warn_threshold": 0.8,
        "timeout_threshold": 1.0,
        "fail_threshold": 1.2
      }
    }
  },
  "plugins": {
    "auth": { "provider": "local_apikey", "config": {} },
    "guardrails": { "provider": "enkrypt", "config": {} },
    "telemetry": {
      "provider": "opentelemetry",
      "config": {
        "enabled": true,
        "url": "http://localhost:4317",
        "insecure": true
      }
    }
  },
  "mcp_configs": {
    "fcbd4508-1432-4f13-abb9-c495c946f638": {
      "mcp_config_name": "default_config",
      "common_overrides": {
        "server_tools_guardrails_config": {
          "enabled": false,
          "guardrail_name": "Sample Airline Guardrail",
          "block": [
            "policy_violation",
            "injection_attack",
            "topic_detector",
            "nsfw",
            "toxicity",
            "pii",
            "keyword_detector",
            "bias",
            "sponge_attack"
          ]
        }
      },
      "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"
            ]
          },
          "oauth_config": {
            "enabled": false,
            "is_remote": false,
            "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",
            "OAUTH_ORGANIZATION": "your-org-id",
            "OAUTH_SCOPE": "read write",
            "OAUTH_RESOURCE": "https://resource.example.com",
            "OAUTH_TOKEN_EXPIRY_BUFFER": 300,
            "OAUTH_USE_BASIC_AUTH": true,
            "OAUTH_ENFORCE_HTTPS": true,
            "OAUTH_TOKEN_IN_HEADER_ONLY": true,
            "OAUTH_VALIDATE_SCOPES": true,
            "OAUTH_USE_MTLS": false,
            "OAUTH_CLIENT_CERT_PATH": null,
            "OAUTH_CLIENT_KEY_PATH": null,
            "OAUTH_CA_BUNDLE_PATH": null,
            "OAUTH_REVOCATION_URL": null,
            "OAUTH_ADDITIONAL_PARAMS": {},
            "OAUTH_CUSTOM_HEADERS": {}
          },
          "tools": {},
          "denied_tools": [],
          "input_guardrails_config": {
            "enabled": false,
            "guardrail_name": "Sample Airline Guardrail",
            "additional_config": {
              "pii_redaction": false
            },
            "block": [
              "policy_violation",
              "injection_attack",
              "topic_detector",
              "nsfw",
              "toxicity",
              "pii",
              "keyword_detector",
              "bias",
              "sponge_attack"
            ]
          },
          "output_guardrails_config": {
            "enabled": false,
            "guardrail_name": "Sample Airline Guardrail",
            "additional_config": {
              "relevancy": false,
              "hallucination": false,
              "adherence": false
            },
            "block": [
              "policy_violation",
              "injection_attack",
              "topic_detector",
              "nsfw",
              "toxicity",
              "pii",
              "keyword_detector",
              "bias",
              "sponge_attack"
            ]
          }
        }
      ]
    }
  },
  "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"
    }
  }
}

{
  "admin_apikey": "AUTO_GENERATED_256_CHAR_KEY",
  "enkrypt_config": {
    "api_key": "YOUR_ENKRYPT_API_KEY",
    "base_url": "https://api.enkryptai.com"
  },
  "common_mcp_gateway_config": {
    "enkrypt_log_level": "INFO",
    "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_gateway_cache_expiration_minutes": 5,
    "enkrypt_config_watcher_poll_seconds": 2.0,
    "enkrypt_async_input_guardrails_enabled": false,
    "enkrypt_async_output_guardrails_enabled": false,
    "timeout_settings": {
      "default_timeout": 90,
      "guardrail_timeout": 390,
      "auth_timeout": 30,
      "tool_execution_timeout": 360,
      "discovery_timeout": 540,
      "cache_timeout": 15,
      "connectivity_timeout": 6,
      "escalation_policies": {
        "warn_threshold": 0.8,
        "timeout_threshold": 1.0,
        "fail_threshold": 1.2
      }
    }
  },
  "plugins": {
    "auth": { "provider": "local_apikey", "config": {} },
    "guardrails": { "provider": "enkrypt", "config": {} },
    "telemetry": {
      "provider": "opentelemetry",
      "config": {
        "enabled": true,
        "url": "http://localhost:4317",
        "insecure": true
      }
    }
  },
  "mcp_configs": {
    "fcbd4508-1432-4f13-abb9-c495c946f638": {
      "mcp_config_name": "default_config",
      "common_overrides": {
        "server_tools_guardrails_config": {
          "enabled": false,
          "guardrail_name": "Sample Airline Guardrail",
          "block": [
            "policy_violation",
            "injection_attack",
            "topic_detector",
            "nsfw",
            "toxicity",
            "pii",
            "keyword_detector",
            "bias",
            "sponge_attack"
          ]
        }
      },
      "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"
            ]
          },
          "oauth_config": {
            "enabled": false,
            "is_remote": false,
            "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",
            "OAUTH_ORGANIZATION": "your-org-id",
            "OAUTH_SCOPE": "read write",
            "OAUTH_RESOURCE": "https://resource.example.com",
            "OAUTH_TOKEN_EXPIRY_BUFFER": 300,
            "OAUTH_USE_BASIC_AUTH": true,
            "OAUTH_ENFORCE_HTTPS": true,
            "OAUTH_TOKEN_IN_HEADER_ONLY": true,
            "OAUTH_VALIDATE_SCOPES": true,
            "OAUTH_USE_MTLS": false,
            "OAUTH_CLIENT_CERT_PATH": null,
            "OAUTH_CLIENT_KEY_PATH": null,
            "OAUTH_CA_BUNDLE_PATH": null,
            "OAUTH_REVOCATION_URL": null,
            "OAUTH_ADDITIONAL_PARAMS": {},
            "OAUTH_CUSTOM_HEADERS": {}
          },
          "tools": {},
          "denied_tools": [],
          "input_guardrails_config": {
            "enabled": false,
            "guardrail_name": "Sample Airline Guardrail",
            "additional_config": {
              "pii_redaction": false
            },
            "block": [
              "policy_violation",
              "injection_attack",
              "topic_detector",
              "nsfw",
              "toxicity",
              "pii",
              "keyword_detector",
              "bias",
              "sponge_attack"
            ]
          },
          "output_guardrails_config": {
            "enabled": false,
            "guardrail_name": "Sample Airline Guardrail",
            "additional_config": {
              "relevancy": false,
              "hallucination": false,
              "adherence": false
            },
            "block": [
              "policy_violation",
              "injection_attack",
              "topic_detector",
              "nsfw",
              "toxicity",
              "pii",
              "keyword_detector",
              "bias",
              "sponge_attack"
            ]
          }
        }
      ]
    }
  },
  "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"
    }
  }
}

{
  "enkrypt_config": {
    "api_key": "YOUR_ENKRYPT_API_KEY",
    "base_url": "https://api.enkryptai.com",
    "org_id": "YOUR_ENKRYPT_ORG_ID"
  },
  "plugins": {
    "auth": {
      "provider": "enkrypt",
      "config": {
        "gateway_name": "your-gateway-saved-name",
        "gateway_version": "v1",
        "cache_ttl_seconds": 300
      }
    },
    "guardrails": {
      "provider": "enkrypt",
      "config": {}
    },
    "telemetry": {
      "provider": "opentelemetry",
      "config": {
        "enabled": true,
        "url": "http://localhost:4317",
        "insecure": true
      }
    }
  },
  "common_mcp_gateway_config": {
    "enkrypt_log_level": "INFO",
    "enkrypt_gateway_cache_expiration_minutes": 5
  }
}

4.1.4 Instalar el Gateway para Claude Desktop

• Ejecuta el siguiente comando para instalar el gateway para Claude:

  secure-mcp-gateway install --client claude-desktop
  

• Esto registrará Enkrypt Secure MCP Gateway con Claude Desktop.

• NOTA: Por favor reinicia Claude Desktop después de la instalación

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_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 Ejemplo de la Configuración de Claude Desktop después de la instalación

La forma de las variables de entorno depende del plugins.auth.provider de tu gateway. Misma dicotomía que en la sección de Cursor a continuación:

• Proveedor local_apikey (predeterminado) → tres variables de entorno: ENKRYPT_GATEWAY_KEY + ENKRYPT_PROJECT_ID + ENKRYPT_USER_ID
• Proveedor de nube enkrypt → una sola variable de entorno: ENKRYPT_APIKEY

4.1.6 Instalar el Gateway para Cursor

• Ejecuta el Comando de Instalación de CLI para Cursor

  secure-mcp-gateway install --client cursor
  

• Esto actualiza automáticamente tu ~/.cursor/mcp.json (en Windows está en: %USERPROFILE%.cursor\mcp.json) con la entrada correcta.

• Aunque generalmente no se requiere reiniciar, si lo ves en estado de carga durante mucho tiempo, por favor reinicia Cursor

La forma de las variables de entorno depende del plugins.auth.provider de tu gateway. El comando de instalación escribe la forma que coincida:

Proveedor	Variables de entorno escritas	Usado para
local_apikey (predeterminado)	ENKRYPT_GATEWAY_KEY + ENKRYPT_PROJECT_ID + ENKRYPT_USER_ID	Buscar la apikey local + proyecto + usuario en tu configuración local
enkrypt (nube)	ENKRYPT_APIKEY	Una sola apikey de nube; proyecto/usuario provienen de Enkrypt cloud

Ambas formas de mcp.json a continuación son válidas — elige la que coincida con cómo generaste tu configuración. Ver Sección 4.1.2 para el flag --provider enkrypt.

4.1.7 Instalar el Gateway para Claude Code

Claude Code es el agente de codificación basado en CLI de Anthropic. Usa comandos claude mcp add para configurar servidores MCP. A diferencia de Claude Desktop y Cursor, que usan archivos de configuración JSON, Claude Code gestiona servidores MCP a través de su propia CLI.

Requisito previo: La CLI claude debe estar instalada en tu sistema. Ver documentación de Claude Code para la instalación.

Paso 1: Instalar el gateway

secure-mcp-gateway install --client claude-code

Esto automáticamente:

• Lee las credenciales del gateway de tu configuración generada (consciente del proveedor):
  • Proveedor local_apikey (predeterminado) → emite tres flags --env: ENKRYPT_GATEWAY_KEY, ENKRYPT_PROJECT_ID, ENKRYPT_USER_ID
  • Proveedor de nube enkrypt → emite un solo flag --env: ENKRYPT_APIKEY (obtenido de enkrypt_config.api_key, o --apikey <key> si lo pasas en la CLI)
• Ejecuta claude mcp add con --transport stdio y las credenciales correctas y la ruta del gateway
• Registra el servidor como Enkrypt-Secure-MCP-Gateway con --scope user (disponible en todos los proyectos de Claude Code)

Paso 2: Verificar que el servidor se agregó

claude mcp list

Deberías ver Enkrypt-Secure-MCP-Gateway en la lista.

Paso 3: Usar el gateway en Claude Code

Inicia Claude Code y prueba:

list all servers, get all tools available

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 mcp add --transport stdio --env ENKRYPT_APIKEY=YOUR_ENKRYPT_CLOUD_APIKEY --scope user Enkrypt-Secure-MCP-Gateway -- mcp run /path/to/secure_mcp_gateway/gateway.py

4.2.1 Clonar el repositorio, configurar el entorno virtual e instalar dependencias

• Clona el repositorio:

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

uv pip install -r requirements.txt

mcp version

# Example output
MCP version 1.9.2

4.2.2 Ejecutar el script de configuración

• Este script crea el archivo de configuración en ~/.enkrypt/enkrypt_mcp_config.json en macOS y %USERPROFILE%\.enkrypt\enkrypt_mcp_config.json en Windows basado en el archivo src/secure_mcp_gateway/example_enkrypt_mcp_config.json

• Reemplaza UNIQUE_GATEWAY_KEY y otros UUIDs con valores generados automáticamente y también reemplaza DUMMY_MCP_FILE_PATH con la ruta real al archivo MCP de prueba bad_mcps/echo_mcp.py

• También instala el cliente MCP en Claude Desktop

• NOTA: Por favor reinicia Claude Desktop después de ejecutar el script de configuración para ver el Gateway ejecutándose en 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_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_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 Configurar otros clientes MCP

4.3.1 Construir la imagen Docker

docker build -t secure-mcp-gateway .

Etiqueta tu compilación para que el wrapper --docker la encuentre. A partir de v2.2.0, el wrapper secure-mcp-gateway --docker ... extrae enkryptai/secure-mcp-gateway:<your-host-CLI-version> por defecto (por ejemplo, enkryptai/secure-mcp-gateway:2.2.0). Hasta que esa etiqueta exacta se publique en Docker Hub, cada comando --docker fallará con Unable to find image ... not found. Soluciona esto una vez etiquetando tu compilación local para que coincida (encuentra tu versión con secure-mcp-gateway --version):

# Replace 2.2.0 with the output of `secure-mcp-gateway --version`
docker tag secure-mcp-gateway:latest enkryptai/secure-mcp-gateway:2.2.0

Después de este único comando, todos los secure-mcp-gateway --docker generate-config, --docker install --client X, --docker config list, etc. en el resto de §4.3 funcionan sin necesidad de anulaciones --docker-image.

[+] 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


Verify the image landed:

```bash
docker images secure-mcp-gateway

# REPOSITORY            TAG       IMAGE ID       CREATED          SIZE
# secure-mcp-gateway    latest    92d8c6b5714d   2 seconds ago    1.81GB

4.3.2 Generar el archivo de configuración

• Esto crea un archivo de configuración en el archivo ~/.enkrypt/docker/enkrypt_mcp_config.json en macOS/Linux y en el archivo %USERPROFILE%\.enkrypt\docker\enkrypt_mcp_config.json en Windows.

Atajo rápido — Si tienes el CLI instalado localmente vía pip, puedes usar la bandera --docker en cualquier comando y omitir la sintaxis verbosa de Docker:

secure-mcp-gateway --docker generate-config

Elegir un proveedor de autenticación al momento de la generación

Idéntico a la instalación local — consulta §4.1.2 → "Elegir un proveedor de autenticación al momento de la generación" para la explicación completa. En resumen:

• Predeterminado (omitir --provider) → esquema completo local_apikey con un servidor echo de muestra, proyecto, usuario, clave API de gateway y admin_apikey a nivel raíz. Arranca sin conexión, sin dependencia de la nube.
• --provider enkrypt → esquema mínimo respaldado por la nube. Después de generar, edita el archivo y establece enkrypt_config.api_key (tu apikey de la nube Enkrypt) y plugins.auth.config.gateway_name (el nombre guardado del gateway que creaste en la consola de Enkrypt). La nube posee servidores/proyectos/usuarios/apikeys, por lo que esos bloques están ausentes.

Comandos de copiar y pegar (todos los sistemas operativos, usando el atajo --docker — funciona en bash, zsh, CMD y PowerShell, ya que el wrapper maneja las comillas por sistema operativo internamente):

# 1. Default — local_apikey (offline, no cloud dependency)
secure-mcp-gateway --docker generate-config

# 2. Cloud-backed — enkrypt provider (requires container CLI >= v2.2.0; see warning below)
secure-mcp-gateway --docker generate-config --provider enkrypt

# 3. Re-generate over an existing file (adds timestamped .bkp.YYYYMMDD_HHMMSS next to the original)
secure-mcp-gateway --docker generate-config --overwrite
secure-mcp-gateway --docker generate-config --provider enkrypt --overwrite

# 4. If the default image tag isn't on Docker Hub yet, point at a locally-built image:
#    docker build -t secure-mcp-gateway .   # one-time, from this repo root
secure-mcp-gateway --docker --docker-image secure-mcp-gateway generate-config --provider enkrypt --overwrite

Después de que el comando tenga éxito, el archivo se coloca en:

• macOS/Linux: ~/.enkrypt/docker/enkrypt_mcp_config.json
• Windows: %USERPROFILE%\.enkrypt\docker\enkrypt_mcp_config.json

Si no tienes el CLI instalado localmente vía pip, las invocaciones equivalentes en bruto de docker run ... para cada shell del sistema operativo están en el bloque de detalles "Comandos verbosos de ejecución de Docker" a continuación.

⚠️ ¿Re-ejecutando sobre una configuración existente? generate-config se niega a sobrescribir un archivo existente por defecto — sale con INFO: Config file already exists at <path>. ... use --overwrite flag. Añade --overwrite al final del comando para regenerar (se escribe una copia de seguridad .bkp.<YYYYMMDD_HHMMSS> con marca de tiempo junto al original primero). La bandera funciona igual para --provider enkrypt y el atajo --docker.

⚠️ ¿"unrecognized arguments: --provider enkrypt" al usar --docker? Esto significa que el CLI dentro del contenedor es más antiguo que el CLI de tu host (--provider se añadió en v2.2.0). El wrapper --docker ahora usa por defecto enkryptai/secure-mcp-gateway:<host-version>, pero si esa etiqueta aún no está en Docker Hub verás Unable to find image ... not found. Construye la imagen desde el código fuente: docker build -t secure-mcp-gateway . && secure-mcp-gateway --docker --docker-image secure-mcp-gateway generate-config --provider enkrypt --overwrite. Consulta Patrón de comando Docker → La etiqueta de imagen está fijada a la versión de tu CLI host para la tabla completa de soluciones.

# 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

# On 🍎 Linux/macOS
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 --provider enkrypt

# On 🪟 Windows (CMD)
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 --provider enkrypt

# On 🪟 Windows (📟 PowerShell)
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 --provider enkrypt

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 --overwrite

{
  "admin_apikey": "AUTO_GENERATED_256_CHAR_KEY",
  "enkrypt_config": {
    "api_key": "YOUR_ENKRYPT_API_KEY",
    "base_url": "https://api.enkryptai.com"
  },
  "common_mcp_gateway_config": {
    "enkrypt_log_level": "INFO",
    "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_gateway_cache_expiration_minutes": 5,
    "enkrypt_config_watcher_poll_seconds": 2.0,
    "enkrypt_async_input_guardrails_enabled": false,
    "enkrypt_async_output_guardrails_enabled": false,
    "timeout_settings": {
      "default_timeout": 90,
      "guardrail_timeout": 390,
      "auth_timeout": 30,
      "tool_execution_timeout": 360,
      "discovery_timeout": 540,
      "cache_timeout": 15,
      "connectivity_timeout": 6,
      "escalation_policies": {
        "warn_threshold": 0.8,
        "timeout_threshold": 1.0,
        "fail_threshold": 1.2
      }
    }
  },
  "plugins": {
    "auth": { "provider": "local_apikey", "config": {} },
    "guardrails": { "provider": "enkrypt", "config": {} },
    "telemetry": {
      "provider": "opentelemetry",
      "config": {
        "enabled": true,
        "url": "http://localhost:4317",
        "insecure": true
      }
    }
  },
  "mcp_configs": {
    "31491c1c-7258-4617-93aa-0bd81800d318": {
      "mcp_config_name": "default_config",
      "common_overrides": {
        "server_tools_guardrails_config": {
          "enabled": false,
          "guardrail_name": "Sample Airline Guardrail",
          "block": [
            "policy_violation",
            "injection_attack",
            "topic_detector",
            "nsfw",
            "toxicity",
            "pii",
            "keyword_detector",
            "bias",
            "sponge_attack"
          ]
        }
      },
      "mcp_config": [
        {
          "server_name": "echo_server",
          "description": "Simple Echo Server",
          "config": {
            "command": "python",
            "args": [
              "/usr/local/lib/python3.12/dist-packages/secure_mcp_gateway/bad_mcps/echo_oauth_mcp.py"
            ]
          },
          "oauth_config": {
            "enabled": false,
            "is_remote": false,
            "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",
            "OAUTH_ORGANIZATION": "your-org-id",
            "OAUTH_SCOPE": "read write",
            "OAUTH_RESOURCE": "https://resource.example.com",
            "OAUTH_TOKEN_EXPIRY_BUFFER": 300,
            "OAUTH_USE_BASIC_AUTH": true,
            "OAUTH_ENFORCE_HTTPS": true,
            "OAUTH_TOKEN_IN_HEADER_ONLY": true,
            "OAUTH_VALIDATE_SCOPES": true,
            "OAUTH_USE_MTLS": false,
            "OAUTH_CLIENT_CERT_PATH": null,
            "OAUTH_CLIENT_KEY_PATH": null,
            "OAUTH_CA_BUNDLE_PATH": null,
            "OAUTH_REVOCATION_URL": null,
            "OAUTH_ADDITIONAL_PARAMS": {},
            "OAUTH_CUSTOM_HEADERS": {}
          },
          "tools": {},
          "denied_tools": [],
          "input_guardrails_config": {
            "enabled": false,
            "guardrail_name": "Sample Airline Guardrail",
            "additional_config": {
              "pii_redaction": false
            },
            "block": [
              "policy_violation",
              "injection_attack",
              "topic_detector",
              "nsfw",
              "toxicity",
              "pii",
              "keyword_detector",
              "bias",
              "sponge_attack"
            ]
          },
          "output_guardrails_config": {
            "enabled": false,
            "guardrail_name": "Sample Airline Guardrail",
            "additional_config": {
              "relevancy": false,
              "hallucination": false,
              "adherence": false
            },
            "block": [
              "policy_violation",
              "injection_attack",
              "topic_detector",
              "nsfw",
              "toxicity",
              "pii",
              "keyword_detector",
              "bias",
              "sponge_attack"
            ]
          }
        }
      ]
    }
  },
  "projects": {
    "48a1e676-5b4b-41a9-8c50-ef04be4c9173": {
      "project_name": "default_project",
      "mcp_config_id": "31491c1c-7258-4617-93aa-0bd81800d318",
      "users": [
        "dbaf0d74-a312-4469-bb92-ba4f8af7eb18"
      ],
      "created_at": "2026-01-01T00:00:00.000000"
    }
  },
  "users": {
    "dbaf0d74-a312-4469-bb92-ba4f8af7eb18": {
      "email": "default@example.com",
      "created_at": "2026-01-01T00:00:00.000000"
    }
  },
  "apikeys": {
    "Xy2RXGMu_2ZmLP9d7heVb5cj4WYeosldWvDd6hi9opW7ekRL": {
      "project_id": "48a1e676-5b4b-41a9-8c50-ef04be4c9173",
      "user_id": "dbaf0d74-a312-4469-bb92-ba4f8af7eb18",
      "created_at": "2026-01-01T00:00:00.000000"
    }
  }
}

{
  "enkrypt_config": {
    "api_key": "YOUR_ENKRYPT_API_KEY",
    "base_url": "https://api.enkryptai.com",
    "org_id": "YOUR_ENKRYPT_ORG_ID"
  },
  "plugins": {
    "auth": {
      "provider": "enkrypt",
      "config": {
        "gateway_name": "your-gateway-saved-name",
        "gateway_version": "v1",
        "cache_ttl_seconds": 300
      }
    },
    "guardrails": {
      "provider": "enkrypt",
      "config": {}
    },
    "telemetry": {
      "provider": "opentelemetry",
      "config": {
        "enabled": true,
        "url": "http://localhost:4317",
        "insecure": true
      }
    }
  },
  "common_mcp_gateway_config": {
    "enkrypt_log_level": "INFO",
    "enkrypt_gateway_cache_expiration_minutes": 5
  }
}

4.3.3 Instalar el Gateway en Claude Desktop

• Puedes encontrar la ubicación de configuración de Claude en las siguientes ubicaciones de tu sistema. Para referencia, consulta la documentación de Claude.
  • macOS: ~/Library/Application Support/Claude
  • Windows: %APPDATA%\Claude

Nota: La configuración generada incluye MCP_TRANSPORT=stdio para la comunicación en modo stdio con Claude Desktop. El comando es consciente del proveedor — lee plugins.auth.provider de tu configuración de gateway y emite la forma correcta de env/-e (ENKRYPT_GATEWAY_KEY/ENKRYPT_PROJECT_ID/ENKRYPT_USER_ID para local_apikey, un solo ENKRYPT_APIKEY para enkrypt).

Comando de copiar y pegar (todos los sistemas operativos — el wrapper --docker monta automáticamente tu directorio de configuración de Claude):

secure-mcp-gateway --docker install --client claude-desktop

¿Te aparece Unable to find image 'enkryptai/secure-mcp-gateway:<version>' ... not found? Omitiste el paso único docker tag al final de §4.3.1. Ejecútalo una vez y vuelve a intentarlo.

Después de que se ejecute, reinicia Claude Desktop para que tome la nueva configuración.

# 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 Ejemplo de archivo de configuración de Claude Desktop

El bloque env depende del plugins.auth.provider de tu gateway (consulta §4.1.2). Ambas formas se muestran a continuación.

{
  "mcpServers": {
    "Enkrypt Secure MCP Gateway": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "MCP_TRANSPORT=stdio",
        "-v",
        "C:\\Users\\<user>\\.enkrypt\\docker:/app/.enkrypt/docker",
        "-e",
        "ENKRYPT_GATEWAY_KEY",
        "-e",
        "ENKRYPT_PROJECT_ID",
        "-e",
        "ENKRYPT_USER_ID",
        "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"
      }
    }
  }
}

{
  "mcpServers": {
    "Enkrypt Secure MCP Gateway": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "MCP_TRANSPORT=stdio",
        "-v",
        "C:\\Users\\<user>\\.enkrypt\\docker:/app/.enkrypt/docker",
        "-e",
        "ENKRYPT_APIKEY",
        "secure-mcp-gateway"
      ],
      "env": {
        "ENKRYPT_APIKEY": "your-enkrypt-cloud-apikey"
      }
    }
  }
}

4.3.5 Instalar el Gateway en Cursor

• Puedes encontrar la ubicación de la configuración de Cursor en las siguientes ubicaciones. Para referencia, consulta la documentación de Cursor.
  • macOS: ~/.cursor
  • Windows: %USERPROFILE%\.cursor

Nota: La configuración generada incluye MCP_TRANSPORT=stdio para la comunicación en modo stdio con Cursor. El comando es consciente del proveedor — lee plugins.auth.provider de tu configuración de gateway y emite la forma correcta de env/-e (ENKRYPT_GATEWAY_KEY/ENKRYPT_PROJECT_ID/ENKRYPT_USER_ID para local_apikey, un único ENKRYPT_APIKEY para enkrypt).

Comando de copiar y pegar (todos los sistemas operativos — el envoltorio --docker monta automáticamente ~/.cursor para que el install dentro del contenedor pueda escribir de vuelta en él):

secure-mcp-gateway --docker install --client cursor

¿Obtuviste Unable to find image 'enkryptai/secure-mcp-gateway:<version>' ... not found? Te saltaste el paso único de docker tag al final de §4.3.1. Ejecútalo una vez y vuelve a intentarlo.

Después de que se ejecute, reinicia Cursor para que detecte el nuevo servidor. La entrada se guarda en ~/.cursor/mcp.json en macOS/Linux o %USERPROFILE%\.cursor\mcp.json en Windows.

# 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 Instalar el Gateway en Claude Code

Claude Code utiliza su propia CLI (claude mcp add) para gestionar los servidores MCP. Cuando el gateway se ejecuta en Docker, Claude Code se conecta a través de npx mcp-remote al endpoint HTTP Streamable del gateway.

Requisitos previos: Node.js y npm deben estar instalados en tu máquina (node -v y npm -v para verificar).

Paso 1: Ejecutar el contenedor del gateway

Inicia el gateway como un contenedor Docker en segundo plano con el endpoint HTTP Streamable expuesto:

# 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

Paso 2: Añadir el gateway a Claude Code

Los encabezados HTTP varían según el proveedor de autenticación:

# For local_apikey provider (default)
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/

# For enkrypt cloud provider (generated with --provider enkrypt)
claude mcp add --transport http --header "apikey:YOUR_ENKRYPT_CLOUD_APIKEY" --scope user Enkrypt-Secure-MCP-Gateway http://localhost:8000/mcp/

Reemplaza los marcadores de posición con los valores de tu enkrypt_mcp_config.json (apikeys.<key> y los IDs de proyecto/usuario correspondientes para local_apikey, o enkrypt_config.api_key para enkrypt cloud).

secure-mcp-gateway --docker install --client claude-code

{
  "mcpServers": {
    "Enkrypt Secure MCP Gateway": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "MCP_TRANSPORT=stdio",
        "-v",
        "/Users/<user>/.enkrypt/docker:/app/.enkrypt/docker",
        "-e",
        "ENKRYPT_GATEWAY_KEY",
        "-e",
        "ENKRYPT_PROJECT_ID",
        "-e",
        "ENKRYPT_USER_ID",
        "secure-mcp-gateway"
      ],
      "env": {
        "ENKRYPT_GATEWAY_KEY": "YOUR_GATEWAY_KEY",
        "ENKRYPT_PROJECT_ID": "YOUR_PROJECT_ID",
        "ENKRYPT_USER_ID": "YOUR_USER_ID"
      }
    }
  }
}

{
  "mcpServers": {
    "Enkrypt Secure MCP Gateway": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "MCP_TRANSPORT=stdio",
        "-v",
        "/Users/<user>/.enkrypt/docker:/app/.enkrypt/docker",
        "-e",
        "ENKRYPT_APIKEY",
        "secure-mcp-gateway"
      ],
      "env": {
        "ENKRYPT_APIKEY": "YOUR_ENKRYPT_CLOUD_APIKEY"
      }
    }
  }
}

# For local_apikey provider (default)
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", "-e", "ENKRYPT_GATEWAY_KEY", "-e", "ENKRYPT_PROJECT_ID", "-e", "ENKRYPT_USER_ID", "secure-mcp-gateway"],
  "env": {
    "ENKRYPT_GATEWAY_KEY": "YOUR_GATEWAY_KEY",
    "ENKRYPT_PROJECT_ID": "YOUR_PROJECT_ID",
    "ENKRYPT_USER_ID": "YOUR_USER_ID"
  }
}'

# For enkrypt cloud provider (generated with --provider enkrypt)
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", "-e", "ENKRYPT_APIKEY", "secure-mcp-gateway"],
  "env": {
    "ENKRYPT_APIKEY": "YOUR_ENKRYPT_CLOUD_APIKEY"
  }
}'

Paso 3: Verificar

claude mcp list

Paso 4: Usar en Claude Code

Inicia Claude Code y prueba indicaciones como list all servers, get all tools available.

4.3.7 Ejecutar el Gateway con Docker Run (Avanzado)

Para implementaciones avanzadas de Docker, puedes ejecutar el contenedor del gateway directamente con configuraciones personalizadas. Las variables de entorno de autenticación dependen del plugins.auth.provider de tu gateway (consulta §4.1.2):

# Basic Docker run command — local_apikey provider (default)
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:latest

# Basic Docker run command — enkrypt cloud provider (generated with --provider enkrypt)
docker run -d --name enkrypt-gateway -p 8000:8000 -v ~/.enkrypt/docker:/app/.enkrypt/docker -e ENKRYPT_APIKEY="your-enkrypt-cloud-apikey" secure-mcp-gateway:latest

Windows PowerShell:

# local_apikey provider (default)
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 cloud provider
docker run -d `
  --name enkrypt-gateway `
  -p 8000:8000 `
  -v "$env:USERPROFILE\.enkrypt\docker:/app/.enkrypt/docker" `
  -e ENKRYPT_APIKEY="your-enkrypt-cloud-apikey" `
  secure-mcp-gateway:latest

Variables de Entorno

Las variables de entorno de autenticación son dependientes del proveedor — se requiere exactamente una de las dos formas siguientes:

MCP_TRANSPORT

La variable de entorno MCP_TRANSPORT controla el modo de transporte del gateway.

Modos de transporte:

• streamable-http (predeterminado): modo servidor HTTP en el puerto 8000. Úsalo con -p 8000:8000 para el mapeo de puertos.
• stdio: modo de entrada/salida estándar para clientes MCP que se comunican a través de stdin/stdout. Úsalo con la bandera -i.

Ejemplo para modo stdio (Claude Desktop, Cursor):

# local_apikey provider (default) — pass all 3 env vars
docker run --rm -i -e MCP_TRANSPORT=stdio -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

# enkrypt cloud provider — pass a single env var
docker run --rm -i -e MCP_TRANSPORT=stdio -v ~/.enkrypt/docker:/app/.enkrypt/docker -e ENKRYPT_APIKEY="your-enkrypt-cloud-apikey" secure-mcp-gateway

SKIP_DEPENDENCY_INSTALL

La variable de entorno SKIP_DEPENDENCY_INSTALL controla si el gateway reinstala las dependencias de Python en tiempo de ejecución.

Comportamiento predeterminado:

• Entornos Docker: el valor predeterminado es true (detección automática). Las dependencias están preinstaladas en la imagen de Docker, por lo que la instalación en tiempo de ejecución se omite automáticamente.
• Entornos que no son Docker: el valor predeterminado es false. Las dependencias se instalan al inicio para garantizar la compatibilidad.

Cuándo establecer explícitamente SKIP_DEPENDENCY_INSTALL=false en Docker:

• Entornos de desarrollo donde estás probando nuevas dependencias
• Cuando montas volúmenes de código fuente para desarrollo en vivo
• Si no estás seguro de que todas las dependencias estén instaladas correctamente

Cuándo establecer explícitamente SKIP_DEPENDENCY_INSTALL=true fuera de Docker:

• Implementaciones de producción donde las dependencias están preinstaladas
• Para reducir el tiempo de inicio (arranques en frío más rápidos)
• En entornos donde ya has ejecutado pip install

Ejemplo con integración de docker-compose:

# Connect to observability stack network — local_apikey provider (default)
# Note: SKIP_DEPENDENCY_INSTALL defaults to true in Docker, so it's optional
docker run -d --name enkrypt-gateway --network secure-mcp-gateway-observability_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:latest

# Same, but for the enkrypt cloud provider
docker run -d --name enkrypt-gateway --network secure-mcp-gateway-observability_default -p 8000:8000 -p 8080:8080 -v ~/.enkrypt/docker:/app/.enkrypt/docker -e ENKRYPT_APIKEY="your-enkrypt-cloud-apikey" secure-mcp-gateway:latest

Windows PowerShell:

# Note: SKIP_DEPENDENCY_INSTALL defaults to true in Docker, so it's optional
# local_apikey provider (default)
docker run -d `
  --name enkrypt-gateway `
  --network secure-mcp-gateway-observability_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

# enkrypt cloud provider
docker run -d `
  --name enkrypt-gateway `
  --network secure-mcp-gateway-observability_default `
  -p 8000:8000 `
  -p 8080:8080 `
  -v "$env:USERPROFILE\.enkrypt\docker:/app/.enkrypt/docker" `
  -e ENKRYPT_APIKEY="your-enkrypt-cloud-apikey" `
  secure-mcp-gateway:latest

Nota: La bandera --network conecta el gateway con la pila de observabilidad (Grafana, Prometheus, Loki, Jaeger, más las 9 reglas de alerta de Slack) si estás ejecutando los servicios de monitoreo de la sección 5. El nombre de la red (secure-mcp-gateway-observability_default) se deriva del nombre del proyecto compose definido al inicio de observability/docker-compose.grafana.yml (el campo name: no cambia con el cambio de nombre del archivo, por lo que el nombre de la red es estable).

Mapeo de Puertos

• 8000: servidor MCP del gateway (requerido) — vinculado por el ENTRYPOINT ["python3", "src/secure_mcp_gateway/gateway.py"] predeterminado.
• 8080: servidor de devolución de llamada OAuth (opcional, solo necesario para el flujo de Código de Autorización). También vinculado por el punto de entrada del gateway cuando OAuth está configurado.
• 8001: servidor de API REST de administración. No se inicia con el punto de entrada predeterminado. Mapear -p 8001:8001 solo no hace nada — no hay un listener en el puerto 8001 dentro del contenedor a menos que también inicies python -m secure_mcp_gateway.api_server (por ejemplo, a través de un sidecar docker exec, un --entrypoint personalizado, o tu propia imagen que ejecute ambos procesos). Las rutas integradas de vaciado de caché y última recarga también se exponen directamente en el gateway (puerto 8000) en POST /api/v1/cache/flush-gateway-config y GET /api/v1/cache/last-reload, por lo que la mayoría de los operadores no necesitan exponer el puerto 8001 en absoluto.

Montajes de Volúmenes

• ~/.enkrypt/docker:/app/.enkrypt/docker - Ubicación del archivo de configuración (requerido)
• Pueden ser necesarios montajes adicionales si tus servidores MCP requieren acceso a archivos locales

⚠️ Importante: Los clientes MCP (Claude Desktop, Cursor, Claude Code) inician Docker directamente sin un shell, por lo que ~ (tilde) no se expandirá. Usa siempre rutas absolutas en tus archivos JSON de configuración del cliente MCP (por ejemplo, /Users/yourname/.enkrypt/docker:/app/.enkrypt/docker en macOS/Linux o C:\\Users\\yourname\\.enkrypt\\docker:/app/.enkrypt/docker en Windows).

⚠️ Importante: Configurar Servidores MCP Cuando el Gateway se Ejecuta en Docker

Cuando ejecutes el Enkrypt Gateway en Docker, NO configures tus servidores MCP para que también se ejecuten en modo Docker. Esto causa problemas de Docker-in-Docker, problemas de red y complicaciones con los montajes de volúmenes.

❌ Evita (servidores MCP basados en Docker):

{
  "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"
    }
  }
}

✅ Usa en su lugar (servidores basados en npx/npm/Python):

{
  "server_name": "github_server",
  "config": {
    "command": "npx",
    "args": [
      "-y",
      "@modelcontextprotocol/server-github"
    ],
    "env": {
      "GITHUB_PERSONAL_ACCESS_TOKEN": "your-token"
    }
  }
}

¿Por qué?

• Docker-in-Docker requiere modo privilegiado y montaje especial de sockets
• El aislamiento de red impide que los contenedores se comuniquen correctamente
• Los montajes de volúmenes no funcionan como se espera a través de los límites de los contenedores
• Sobrecarga de rendimiento y problemas de seguridad
• Mayor complejidad y dificultad de depuración

Formatos de Servidor MCP Recomendados Cuando el Gateway está en Docker:

• ✅ Servidores basados en npx: npx -y @modelcontextprotocol/server-*
• ✅ Servidores basados en npm: npm exec -y server-name
• ✅ Servidores basados en Python: python /path/to/server.py o uv run server.py
• ✅ Servidores basados en Node.js: node /path/to/server.js
• ✅ Servidores MCP remotos: npx mcp-remote https://api.example.com/mcp/

Excepción:

Si absolutamente debes usar servidores MCP basados en Docker, considera:

1. Ejecutar el gateway fuera de Docker (instalación local), O
2. Configurar una red Docker adecuada con --network host o redes bridge personalizadas, O
3. Usar Docker-in-Docker con la configuración adecuada (requiere la bandera --privileged y el montaje /var/run/docker.sock - no recomendado para producción)

4.4.1 Ejecutar el Gateway en un servidor remoto

python gateway.py

• O ejecútalo en k8s usando nuestra imagen de Docker enkryptai/secure-mcp-gateway:vx.x.x

• Ejemplo: enkryptai/secure-mcp-gateway:v2.1.2

• Usa la versión más reciente de Docker Hub: https://hub.docker.com/r/enkryptai/secure-mcp-gateway/tags

• Puedes montar el archivo de configuración localmente o descargar el archivo JSON desde una ubicación remota como S3 usando un initContainer y montar el volumen

• Consulta docs/secure-mcp-gateway-manifest-example.yaml para la referencia completa del archivo de manifiesto

4.4.2 Modificar la configuración de tu Cliente MCP para usar el Gateway

• Puedes encontrar la ubicación de la configuración de Claude Desktop en las siguientes ubicaciones de tu sistema. Para referencia, consulta la documentación de Claude.

  • macOS: ~/Library/Application Support/Claude
  • Windows: %APPDATA%\Claude

• Puedes encontrar la ubicación de la configuración de Cursor en las siguientes ubicaciones. Para referencia, consulta la documentación de Cursor.

  • macOS: ~/.cursor
  • Windows: %USERPROFILE%\.cursor

• Reemplaza las credenciales con los valores de tu enkrypt_mcp_config.json. La forma de las credenciales depende del plugins.auth.provider de tu gateway:

  • local_apikey (predeterminado) — encabezados apikey + project_id + user_id, obtenidos de apikeys.<key> y los IDs de proyecto/usuario correspondientes
  • enkrypt cloud — un único encabezado apikey, obtenido de enkrypt_config.api_key. Añade un encabezado X-Enkrypt-MCP-Gateway solo si la configuración del gateway deja plugins.auth.config.gateway_name sin definir — consulta §7.1

• Reemplaza el http://0.0.0.0:8000/mcp/ con el http(s)://<remote_server_ip>:<port>/mcp/

• Si estás ejecutando esto localmente, puedes usar http://0.0.0.0:8000/mcp/

• Puedes configurar ingress para enrutar el tráfico al MCP Gateway a través de https

• Ejemplo: https://mcp.enkryptai.com/mcp/

• NOTA: Asegúrate de que node y npm estén instalados en la máquina cliente

  • Para verificar, ejecuta node -v y npm -v

• NOTA: Asegúrate de usar la barra diagonal final / en la URL de MCP como /mcp/

Para Claude Desktop y Cursor — agrega lo siguiente a tu claude_desktop_config.json o mcp.json.

Proveedor local_apikey (predeterminado) — tres encabezados:

{
  "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"
      }
    }
  }
}

Proveedor de nube enkrypt (generado con --provider enkrypt) — un solo encabezado:

{
  "mcpServers": {
    "Enkrypt Secure MCP Gateway": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://0.0.0.0:8000/mcp/",
        "--allow-http",
        "--header",
        "apikey:${ENKRYPT_APIKEY}"
      ],
      "env": {
        "ENKRYPT_APIKEY": "your-enkrypt-cloud-apikey"
      }
    }
  }
}

Opcional: enrutar un proceso de gateway a varios gateways en la nube. Si el gateway se ejecuta sin plugins.auth.config.gateway_name, cada cliente también debe enviar X-Enkrypt-MCP-Gateway nombrando el saved_name del gateway en la nube; el gateway lo reenvía a la nube de Enkrypt para elegir la configuración. Cuando gateway_name está configurado en la configuración del gateway, ese valor tiene prioridad y este encabezado se ignora — consulta §7.1.

{
  "mcpServers": {
    "Enkrypt Secure MCP Gateway": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://0.0.0.0:8000/mcp/",
        "--allow-http",
        "--header",
        "apikey:${ENKRYPT_APIKEY}",
        "--header",
        "X-Enkrypt-MCP-Gateway:${ENKRYPT_MCP_GATEWAY}"
      ],
      "env": {
        "ENKRYPT_APIKEY": "your-enkrypt-cloud-apikey",
        "ENKRYPT_MCP_GATEWAY": "your-gateway-saved-name"
      }
    }
  }
}

Los nombres de las variables de entorno aquí son arbitrarios — mcp-remote simplemente los sustituye en los valores de los encabezados. El gateway en sí no lee ninguna variable de entorno para el nombre del gateway, por lo que este enrutamiento funciona solo en el transporte streamable-HTTP.

Para Claude Code — usa el comando claude mcp add:

# local_apikey provider (default)
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/

# enkrypt cloud provider (generated with --provider enkrypt)
claude mcp add --transport http --header "apikey:YOUR_ENKRYPT_CLOUD_APIKEY" --scope user Enkrypt-Secure-MCP-Gateway https://mcp.your-domain.com/mcp/

# enkrypt cloud provider, gateway chosen per-request (only when the gateway config leaves plugins.auth.config.gateway_name unset)
claude mcp add --transport http --header "apikey:YOUR_ENKRYPT_CLOUD_APIKEY" --header "X-Enkrypt-MCP-Gateway:your-gateway-saved-name" --scope user Enkrypt-Secure-MCP-Gateway https://mcp.your-domain.com/mcp/

Nota: Para pruebas locales con HTTP (no HTTPS), agrega --allow-http si es necesario, o usa http://0.0.0.0:8000/mcp/ como URL.

Esta sección explica cómo configurar y usar el stack de observabilidad incluido con Enkrypt Secure MCP Gateway. Todo está plantillado como código en observability/: clona, copia .env.grafana.example, ejecuta un docker compose -f docker-compose.grafana.yml, obtén un panel de control funcional con alertas de Slack.

Dos backends, elige uno. El repositorio incluye dos stacks de observabilidad paralelos: el stack de OpenSearch (principal; puertos OTel predeterminados 4317/4318) y este stack Grafana heredado (4327/4328). Cada uno tiene su propio compose y archivos env (docker-compose.grafana.yml + .env.grafana vs docker-compose.opensearch.yml + .env.opensearch) y debe invocarse con banderas explícitas -f/--env-file. Consulta observability/README.opensearch.md para la ruta de OpenSearch; el resto de esta sección cubre el stack de Grafana.

Para el análisis profundo — cada regla de alerta, panel y punto de personalización — consulta observability/README.md. Esta sección es la guía de inicio rápido.

5.1 Arquitectura

┌─────────────────────┐   logs (OTLP)         ┌────────────┐    LogQL    ┌─────────┐
│ secure-mcp-gateway  │──────────────────────▶│            │────────────▶│         │
│ (host process       │   metrics (OTLP)      │   OTel     │             │ Grafana │
│  on :8000)          │──────────────────────▶│ Collector  │   PromQL    │ (:3001) │
│                     │   traces  (OTLP)      │ (:4317)    │────────────▶│         │
└─────────────────────┘                       └────────────┘             └─────────┘
                                              │     │     │                  ▲
                                              ▼     ▼     ▼                  │
                                          ┌──────┐ ┌────┐ ┌────────┐         │
                                          │ Loki │ │Prom│ │ Jaeger │─────────┘
                                          └──────┘ └────┘ └────────┘   dashboards
                                                          (:16686)      & alerts

Componentes incluidos en observability/docker-compose.grafana.yml:

Nota sobre el puerto de Grafana: el archivo compose publica Grafana en el puerto del host 3001 por predeterminado (el contenedor aún escucha en 3000) para evitar conflictos con un servicio Grafana nativo o el relay Docker WSL que a menudo ocupa el 3000 en Windows. Configura GRAFANA_HOST_PORT=3030 (o cualquier puerto libre) en observability/.env.grafana para anular.

5.2 Requisitos previos

• Docker Desktop (Windows/macOS) o Docker Engine + plugin compose (Linux)

• Gateway instalado y ejecutándose (sigue la sección 4)

• (Opcional) Una URL de webhook entrante de Slack si deseas que las reglas de alerta incluidas publiquen en Slack

5.3 Pasos de configuración

1. Copia la plantilla de env

   cd observability
   cp .env.grafana.example .env.grafana
   # edit observability/.env.grafana and replace SLACK_WEBHOOK_URL with your
   # real https://hooks.slack.com/services/... URL (leave the placeholder if
   # you don't want Slack — Grafana provisioning will still succeed, the
   # Slack POST will just silently fail).
   

2. Inicia el Stack de Observabilidad

   docker compose -f docker-compose.grafana.yml --env-file .env.grafana up -d
   

   Esto levanta el OTel Collector, Prometheus, Loki, Jaeger, Promtail y Grafana — con todos los paneles, reglas de alerta y el punto de contacto de Slack preaprovisionados. La autenticación de administrador anónimo está habilitada por predeterminado (sin pantalla de inicio de sesión). Consulta observability/README.md → Personalización para establecer una contraseña de administrador real.

3. Para detener el Stack de Observabilidad

   docker compose down
   

5.4 Configuración

• Edita el archivo enkrypt_mcp_config.json para habilitar la telemetría. La forma actual usa el bloque de plugin plugins.telemetry (proveedor opentelemetry, el predeterminado emitido por secure-mcp-gateway generate-config):

  {
    "plugins": {
      "telemetry": {
        "provider": "opentelemetry",
        "config": {
          "enabled": true,
          "url": "http://localhost:4317",
          "insecure": true
        }
      }
    }
  }
  

5.5 Pasos de verificación

1. Verifica que los servicios estén ejecutándose

   # On Windows
   docker ps | findstr "loki grafana jaeger otel prometheus"
   
   # On Linux/macOS
   docker ps | grep -E "loki|grafana|jaeger|otel|prometheus"
   

2. Accede a las interfaces de los servicios

   • Grafana: http://localhost:3001 (administrador anónimo habilitado por predeterminado — sin pantalla de inicio de sesión; anula el puerto del host vía GRAFANA_HOST_PORT en observability/.env.grafana)

   • Jaeger: http://localhost:16686

   • Prometheus: http://localhost:9090

   • Loki: Accede a través de Grafana

     1. Abre Grafana (http://localhost:3001)
     2. Ve a Explorar (barra lateral izquierda)
     3. Selecciona "Loki" en el menú desplegable de fuentes de datos

3. Verifica la telemetría del gateway

   • Haz solicitudes de prueba a través del gateway como List all servers and tools y echo test

   • Revisa las trazas en Jaeger:

     • Agrega etiquetas opcionales como enkrypt_email=default@example.com o enkrypt_project_name=default_project o enkrypt_mcp_config_id=fcbd4508-1432-4f13-abb9-c495c946f638 para ver las trazas de un usuario, proyecto o configuración MCP específicos, etc.

     • También podemos combinar etiquetas separándolas con espacios como enkrypt_email=default@example.com enkrypt_project_name=default_project

     • Busca tramos enkrypt_discover_all_tools

     • Examina los tramos secundarios para caché, descubrimiento de herramientas, etc.

       

   • Revisa las métricas en Grafana:

     • Navega a Drilldown -> metrics

     • Podemos filtrar por varias etiquetas como email, user_id, mcp_config_id, project_id, project_name, etc.

       

   • Revisa los registros en Grafana

     • Navega a Drilldown -> Logs

     • Selecciona la etiqueta como service_name=secure-mcp-gateway y haz clic en Show logs

     • Ahora podemos filtrar por varias etiquetas como attributes_project_name, attributes_project_id, attributes_email, attributes_user_id, attributes_mcp_config_id, attributes_tool_name, etc.

       

   • Revisa los paneles en Grafana navegando a Dashboards -> OpenTelemetry Gateway Metrics

     • Debido a problemas en Grafana, es posible que debas editar cada mosaico y hacer clic en Run queries para ver los datos

5.6 Telemetría disponible (no exhaustiva)

1. Trazas

   • Pipeline de procesamiento de solicitudes
   • Invocaciones de herramientas con seguimiento de duración
   • Operaciones de caché (aciertos/fallos)
   • Verificaciones de guardarraíles
   • Seguimiento de errores y monitoreo de estado
   • Atributos detallados para depuración

2. Métricas

   • enkrypt_list_all_servers_calls: Uso de endpoints de API
   • mcp_cache_misses_total: Seguimiento de eficiencia de caché
   • enkrypt_servers_discovered: Monitoreo de descubrimiento de servidores
   • mcp_tool_calls_total: Seguimiento de invocaciones de herramientas
   • mcp_tool_call_duration_seconds: Monitoreo de rendimiento (histograma)

3. Registros

   • Formato JSON estructurado para mejores consultas
   • Operaciones del gateway con contexto
   • Condiciones de error con trazas de pila
   • Eventos de seguridad y verificaciones de guardarraíles
   • Datos de rendimiento con información de tiempos

El mapeo completo de métrica → serie de Prometheus → regla de alerta está en docs/metric_reference.md, y las constantes de nombres de métricas/tramos/atributos están en src/secure_mcp_gateway/plugins/telemetry/conventions.py.

5.7 Reglas de alerta preaprovisionadas (Slack)

El stack incluye 9 reglas de alerta de Grafana conectadas a un punto de contacto de Slack — coloca tu URL de webhook en observability/.env.grafana (SLACK_WEBHOOK_URL=...) y comenzarás a recibir alertas de guardarraíles/seguridad/salud inmediatamente.

Las reglas de ráfaga usan sum by (server_name, tool_name) (o user_id, failure_reason) para que cada infractor distinto produzca un mensaje de Slack separado en lugar de una alerta agregada. Para ajustar los umbrales, edita observability/grafana/provisioning/alerting/rules.yaml y docker compose restart grafana — las reglas se recargan desde el disco en cada inicio. Consulta observability/README.md → Personalización para agregar nuevas reglas o cambiar Slack por PagerDuty / Opsgenie / webhook genérico / correo electrónico.

6.1 Verifica Claude Desktop

• Para verificar la instalación de Claude, navega al archivo claude_desktop_config.json siguiendo estas instrucciones

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

  • Windows: %APPDATA%\Claude\claude_desktop_config.json

6.2 Ejemplo de archivo de configuración MCP generado

Los ejemplos a continuación usan la forma del proveedor local_apikey (predeterminado). Si generaste con --provider enkrypt, el bloque env tiene una sola entrada ENKRYPT_APIKEY en su lugar — consulta §4.1.5 para la variante de enkrypt cloud.

6.3 Reinicia Claude Desktop para ejecutar el Gateway

• Después de reiniciar, navega a Settings de Claude Desktop

  

• Haz clic en Developer -> Enkrypt Secure MCP Gateway

  

6.4 Ejemplos de indicaciones

• list all servers, get all tools available and echo test
  • Esto usa un servidor MCP de prueba echo_server que está en bad_mcps/echo_mcp.py

6.5 Ejemplo de archivo de configuración generado

• Ejemplo enkrypt_mcp_config.json generado por el script setup en ~/.enkrypt/enkrypt_mcp_config.json en macOS y %USERPROFILE%\.enkrypt\enkrypt_mcp_config.json en Windows

• Si ejecutó el comando docker para instalar el Gateway, el archivo de configuración estará en ~/.enkrypt/docker/enkrypt_mcp_config.json en macOS y %USERPROFILE%\.enkrypt\docker\enkrypt_mcp_config.json en Windows

  {
    "admin_apikey": "AUTO_GENERATED_256_CHAR_ADMIN_API_KEY_FOR_ADMINISTRATIVE_OPERATIONS",
    "enkrypt_config": {
      "api_key": "YOUR_ENKRYPT_API_KEY",
      "base_url": "https://api.enkryptai.com"
    },
    "common_mcp_gateway_config": {
      "enkrypt_log_level": "INFO",
      "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_gateway_cache_expiration_minutes": 5,
      "enkrypt_config_watcher_poll_seconds": 2.0,
      "enkrypt_async_input_guardrails_enabled": false,
      "enkrypt_async_output_guardrails_enabled": false
    },
    "plugins": {
      "auth": { "provider": "local_apikey", "config": {} },
      "guardrails": { "provider": "enkrypt", "config": {} },
      "telemetry": {
        "provider": "opentelemetry",
        "config": {
          "enabled": true,
          "url": "http://localhost:4317",
          "insecure": true
        }
      }
    },
    "mcp_configs": {
      "fcbd4508-1432-4f13-abb9-c495c946f638": {
        "mcp_config_name": "default_config",
        "common_overrides": {
          "server_tools_guardrails_config": { "enabled": false }
        },
        "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 Verificar Cursor

• Puede ver el servidor MCP en la lista de servidores MCP en Cursor navegando a ~/.cursor/mcp.json y también haciendo clic en el ícono de configuración en la esquina superior derecha y luego haciendo clic en Tools & Integrations o en la pestaña MCP

• Generalmente no es necesario reiniciar, pero si permanece en estado de carga durante mucho tiempo, reinicie Cursor

  

• Ahora puede chatear con el servidor MCP.

  • Ejemplos de indicaciones:

    • (Haga clic en Run Tool cuando Cursor se lo solicite)

    • list all servers, get all tools available and echo test

      • Esto utiliza un servidor MCP de prueba echo_server que se encuentra en bad_mcps/echo_mcp.py

    

6.7 Verificar Claude Code

• Ejecute claude mcp list para ver el gateway en la lista de servidores MCP configurados

• Inicie Claude Code y ejecute /mcp para verificar el estado del servidor

• Pruebe list all servers, get all tools available and echo test como indicación para verificar que el gateway está funcionando

• Importante:

  • Con la recarga en caliente (ver Sección 7.0), reiniciar el cliente MCP ya no es necesario para la mayoría de los cambios de configuración. El reinicio solo es necesario para las tres configuraciones enumeradas en la tabla anterior.
  • Para que todas las nuevas herramientas sean accesibles, use la indicación "list all servers, get all tools available" para que el Cliente MCP descubra todas las nuevas herramientas. Después de esto, el Cliente MCP debería poder usar todas las herramientas de los servidores configurados en el archivo de configuración del Gateway

• Puede agregar muchos servidores MCP dentro de la matriz mcp_config de esta configuración del gateway

  • Puede ver aquí ejemplos de servidores

  • También puede probar el Servidor MCP de Enkrypt

  • Ejemplo:

    {
      "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": {},
              "server_tools_guardrails_config": {"enabled": false},
              "input_guardrails_config": {...},
              "output_guardrails_config": {...}
            },
            {
              "server_name": "MCP_SERVER_NAME_2",
              "description": "MCP_SERVER_DESCRIPTION_2",
              "config": {...},
              "tools": {},
              "server_tools_guardrails_config": {"enabled": 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": {...}
      }
    }
    

7.1.1 Claves de plugins.auth.config

{
  "plugins": {
    "auth": {
      "provider": "enkrypt",
      "config": {
        "apikey": "<boot-time fallback enkrypt apikey>",
        "gateway_name": "your-gateway-saved-name",
        "gateway_version": "v1",
        "project_name": "default",
        "base_url": "https://api.enkryptai.com",
        "cache_ttl_seconds": 600
      }
    }
  }
}

apikey y base_url se completan desde el bloque centralizado de nivel raíz enkrypt_config cuando están ausentes aquí, por lo que la mayoría de las configuraciones solo establecen gateway_name (y opcionalmente gateway_version / cache_ttl_seconds) bajo plugins.auth.config.

⚠️ Las claves eliminadas fallan en el arranque. El proveedor anterior a la versión 2.2 aceptaba api_key, use_remote_config y timeout bajo plugins.auth.config. Ahora generan un ValueError al inicio en lugar de ignorarse silenciosamente — usa apikey / gateway_name / gateway_version / project_name / base_url en su lugar, y establece el tiempo de espera de autenticación mediante common_mcp_gateway_config.timeout_settings.auth_timeout.

7.1.2 Encabezados que tu cliente MCP envía al gateway

Si ni la configuración ni el encabezado proporcionan un nombre de gateway, la autenticación falla con Missing X-Enkrypt-MCP-Gateway header and no gateway_name in auth.config.

project_name no tiene equivalente por solicitud — proviene solo de la configuración.

⚠️ No envíes ENKRYPT_GATEWAY_KEY en modo nube. Por compatibilidad hacia atrás, el gateway prefiere un encabezado ENKRYPT_GATEWAY_KEY sobre apikey cuando ambos están presentes, y luego lo reenvía a la nube. Un ENKRYPT_GATEWAY_KEY sobrante de una configuración de cliente local_apikey antigua ocultará tu clave de API de nube correcta y producirá errores 401. Envía solo los encabezados que tu proveedor activo necesite (consulta la tabla de encabezados por proveedor en docs/auth-providers.md).

Nota sobre instalaciones stdio. Los encabezados solo existen en el transporte streamable-HTTP. Cuando el cliente MCP inicia el gateway a través de stdio, las credenciales provienen de variables de entorno (ENKRYPT_APIKEY para el proveedor de nube) y no hay equivalente de variable de entorno para el nombre o la versión del gateway — por lo que los despliegues stdio deben establecer plugins.auth.config.gateway_name (y gateway_version, si el gateway no es v1) en el archivo de configuración.

7.1.3 Encabezados que el gateway envía a la nube de Enkrypt

GET {base_url}/mcp-gateway/get-gateway-config se llama con:

Cada llamada se registra con la clave de API enmascarada, para que puedas confirmar qué gateway/proyecto/clave usó realmente una solicitud:

[EnkryptAuthProvider] fetching gateway config: gateway=my-dev-gateway/v1 project=test apikey=****05yg

Compara los últimos 4 caracteres con la clave que esperas — una discrepancia significa que el cliente está enviando el encabezado incorrecto.

7.1.4 Un proceso de gateway, varios gateways en la nube

Debido a que gateway_name puede llegar por solicitud, un solo despliegue de gateway puede servir a más de una configuración de gateway en la nube: deja plugins.auth.config.gateway_name sin establecer y haz que cada cliente MCP envíe su propio encabezado X-Enkrypt-MCP-Gateway junto con su apikey. Los clientes cuyo gateway está registrado bajo una versión distinta de v1 envían X-Enkrypt-MCP-Gateway-Version junto con él. Las respuestas de la nube se almacenan en caché en el proceso bajo un hash SHA-256 de apikey | gateway_name | gateway_version | project_name, por lo que los inquilinos — y dos versiones del mismo gateway — nunca contaminan cruzadamente la configuración del otro. Consulta §4.4.2 para el JSON del lado del cliente.

Nota la compensación: project_name permanece a nivel de proceso, por lo que todos los clientes en ese proceso lo comparten. Fija gateway_name (y gateway_version) en la configuración en su lugar siempre que un despliegue sirva exactamente a un gateway en la nube — es el valor predeterminado más seguro, ya que el gateway efectivo queda fijado en el lado del servidor y los encabezados proporcionados por el cliente ya no pueden dirigirlo. (La nube de Enkrypt aún autoriza cada clave de API contra el gateway que nombra, por lo que el encabezado no es una evasión de autorización de ninguna manera).

7.1.5 Manejo de fallos

Los errores de transporte en la nube, las respuestas 5xx y los cuerpos no JSON fallan la solicitud de forma definitiva (AuthStatus.ERROR con el mensaje ascendente adjunto) — no hay respaldo de archivo local ni servicio de caché obsoleta. Observa el contador enkrypt.auth.failure (atributos provider / failure_reason) y las líneas de registro [EnkryptAuthProvider] fetching gateway config: ... para alertar sobre interrupciones ascendentes.

La referencia completa del proveedor — mapeo de respuesta en la nube, precedencia de anulación, local_server_overrides e invalidación de caché — se encuentra en docs/auth-providers.md.

Esta sección te guía a través de la gestión del gateway completamente mediante la CLI — desde la configuración inicial hasta agregar servidores, gestionar proyectos y operaciones diarias.

Consejo: Todos los comandos a continuación muestran la versión local (pip). Para Docker, solo agrega --docker a cualquier comando — consulta el patrón de comando de Docker al final de esta sección.

Para la referencia completa de CLI, consulta CLI-Commands-Reference.md.

Paso 1: Genera tu configuración

Si aún no lo has hecho, genera el archivo de configuración predeterminado. Esto crea todo lo que necesitas para comenzar: una configuración con un servidor echo de muestra, un proyecto predeterminado, un usuario y una clave de API.

secure-mcp-gateway generate-config

# To overwrite an existing config and start fresh
secure-mcp-gateway generate-config --overwrite

# Or, for the Enkrypt-cloud-backed variant (no local servers/projects/users;
# the cloud owns those). After running this, edit the file and set
# enkrypt_config.api_key and plugins.auth.config.gateway_name.
secure-mcp-gateway generate-config --provider enkrypt

Qué crea esto:

Ahora que tu configuración está lista, el siguiente paso es informar a tu cliente MCP (Claude Desktop, Cursor o Claude Code) sobre la puerta de enlace. Esta es una configuración única: el comando de instalación escribe los detalles de conexión en la configuración de tu cliente para que sepa cómo comunicarse con la puerta de enlace.

Paso 2: Instala la puerta de enlace para tu cliente MCP

Elige el cliente que uses y ejecuta el comando correspondiente:

# 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

Qué hace esto entre bastidores: el comando de instalación lee las credenciales de autenticación de tu configuración generada y las escribe en el archivo de configuración de tu cliente MCP. Las claves exactas env dependen del plugins.auth.provider de tu puerta de enlace:

• local_apikey (predeterminado) — la instalación lee apikeys.<key> más los IDs de proyecto/usuario correspondientes y escribe ENKRYPT_GATEWAY_KEY + ENKRYPT_PROJECT_ID + ENKRYPT_USER_ID
• enkrypt cloud (cuando se genera con --provider enkrypt) — la instalación lee enkrypt_config.api_key y escribe un único ENKRYPT_APIKEY

Para Cursor y Claude Desktop, verás una salida como:

INFO:  Updated 'Enkrypt Secure MCP Gateway' in C:\Users\<user>\.cursor\mcp.json
INFO: Successfully configured Cursor.

Y el archivo de configuración de tu cliente (por ejemplo, ~/.cursor/mcp.json o ~/Library/Application Support/Claude/claude_desktop_config.json) ahora contendrá una de estas dos formas.

local_apikey proveedor (predeterminado):

{
  "mcpServers": {
    "Enkrypt Secure MCP Gateway": {
      "command": "mcp",
      "args": [
        "run",
        "<path-to-your-install>/secure_mcp_gateway/gateway.py"
      ],
      "env": {
        "ENKRYPT_GATEWAY_KEY": "<your-auto-generated-gateway-key>",
        "ENKRYPT_PROJECT_ID": "<your-project-id>",
        "ENKRYPT_USER_ID": "<your-user-id>"
      }
    }
  }
}

enkrypt proveedor en la nube (generado con --provider enkrypt):

{
  "mcpServers": {
    "Enkrypt Secure MCP Gateway": {
      "command": "mcp",
      "args": [
        "run",
        "<path-to-your-install>/secure_mcp_gateway/gateway.py"
      ],
      "env": {
        "ENKRYPT_APIKEY": "<your-enkrypt-cloud-apikey>"
      }
    }
  }
}

Para Claude Code, el comando de instalación ejecuta claude mcp add entre bastidores y verás:

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

Una vez que la instalación termine, reinicia tu cliente MCP para que tome la nueva configuración. Después del reinicio, la puerta de enlace aparecerá como un servidor MCP conectado y estarás listo para continuar.

En este punto, tu configuración se ve así:

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

Tienes un proyecto (default_project) que apunta a una configuración (default_config), y esa configuración tiene un servidor (echo_server). También se crearon un usuario predeterminado y una clave de API de la puerta de enlace para que todo funcione de inmediato.

Paso 3: Verifica lo que tienes

Puedes verificar esta configuración en cualquier momento:

# 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"

¿Qué puedes hacer desde aquí?

Tienes tres caminos según lo que necesites. Elige el que se ajuste y sigue los pasos debajo de él.

Regla general: Si solo agregas o eliminas servidores dentro de tu configuración actual, simplemente reinicia tu cliente MCP. Si cambias a una configuración diferente o creas un nuevo proyecto, necesitas reinstalar.

  default_project
   └── default_config
        ├── echo_server       (already there)
        └── github_server     ← you are adding this

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"

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 Server

# 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"

  default_project
   ├── default_config         (original, untouched)
   │    └── echo_server
   └── production_config      ← new config you are creating
        └── github_server

# 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"

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"

secure-mcp-gateway project assign-config --project-name "default_project" --config-name "production_config"

secure-mcp-gateway install --client cursor
# or: secure-mcp-gateway install --client claude-desktop
# or: secure-mcp-gateway install --client claude-code

# 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"

  default_project              (original, untouched)
   └── default_config
        └── echo_server

  my_new_project               ← new project you are creating
   └── my_new_config           ← new config
        └── github_server

secure-mcp-gateway config add --config-name "my_new_config"

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"

# 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"

# 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"

secure-mcp-gateway user generate-api-key --project-name "my_new_project" --email "alice@company.com"

secure-mcp-gateway install --client cursor
# or: secure-mcp-gateway install --client claude-desktop
# or: secure-mcp-gateway install --client claude-code

Paso 4: Configura tu clave de API de Enkrypt (para guardrails)

Si quieres usar los guardrails de Enkrypt AI (protección de entrada/salida, redacción de PII, filtrado de toxicidad, etc.), necesitas configurar tu clave de API de Enkrypt. Puedes obtener una desde el panel de 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

Sin esta clave, las funciones de guardrails no funcionarán, pero la puerta de enlace en sí seguirá enrutando las herramientas con normalidad.

Paso 5: Activa o desactiva la telemetría

La puerta de enlace incluye soporte de OpenTelemetry para registro, trazado y métricas. Por defecto está habilitado, pero se omitirá silenciosamente si el endpoint del colector no es accesible. Puedes habilitarlo o deshabilitarlo explícitamente:

# 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

Iniciando la pila de telemetría: La puerta de enlace envía datos de telemetría a un colector de OpenTelemetry — no ejecuta uno por sí misma. El repositorio incluye dos backends listos en observability/: la pila OpenSearch (principal, puertos OTel predeterminados 4317/4318 — consulta observability/README.opensearch.md) y la pila Grafana heredada (colector, Prometheus, Grafana, Jaeger, Loki + 9 reglas de alerta de Slack, en 4327/4328). Ejecuta una. Para la pila Grafana:

cd observability
cp .env.grafana.example .env.grafana    # (edit SLACK_WEBHOOK_URL if you want Slack alerts)
docker compose -f docker-compose.grafana.yml --env-file .env.grafana up -d
# then point plugins.telemetry.config.url at http://localhost:4327

Una vez que la pila esté en ejecución, la puerta de enlace comenzará automáticamente a enviar trazas, registros y métricas al colector. Consulta §5 para obtener todos los detalles y observability/README.md para la inmersión profunda en la personalización de alertas.

Paso 6: Operaciones del sistema

# 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 <backup_file>

# Reset to defaults (⚠️ destructive)
secure-mcp-gateway system reset

Patrón de comando de Docker

Agrega --docker a cualquier comando CLI para ejecutarlo automáticamente dentro del contenedor Docker. La bandera detecta automáticamente tu sistema operativo, establece HOST_OS y HOST_ENKRYPT_HOME, y monta el volumen ~/.enkrypt/docker — no se necesita una larga invocación de docker run.

# Quick (recommended) — works on macOS, Linux, and Windows (all shells)
secure-mcp-gateway --docker <COMMAND_HERE>

# Use a custom Docker image
secure-mcp-gateway --docker --docker-image my-registry/secure-mcp-gateway:v2.1.2 <COMMAND_HERE>

La etiqueta de imagen está fijada a la versión CLI de tu host

A partir de v2.2.0, el envoltorio usa por defecto enkryptai/secure-mcp-gateway:<your-host-CLI-version> (por ejemplo, enkryptai/secure-mcp-gateway:2.2.0) en lugar de :latest. Esto evita errores de desalineación de banderas donde un CLI de host más nuevo pasa banderas que el CLI en contenedor más antiguo no reconoce — por ejemplo:

secure-mcp-gateway: error: unrecognized arguments: --provider enkrypt

(generate-config --provider enkrypt se agregó en v2.2.0; si tu CLI de host es v2.2.0 pero el contenedor es v2.1.6, esa bandera desaparece silenciosamente en tránsito.)

Si --docker-image se anula y la anulación no contiene la cadena de versión del CLI de host, el envoltorio registra una línea WARN: para que la causa de cualquier error de "argumentos no reconocidos" sea obvia.

Si tu etiqueta predeterminada aún no está en Docker Hub (típico justo después de una actualización de pip del host, antes de que se publique la imagen correspondiente), Docker sale con not found:

Unable to find image 'enkryptai/secure-mcp-gateway:2.2.0' locally
docker: Error response from daemon: failed to resolve reference "docker.io/enkryptai/secure-mcp-gateway:2.2.0": ... not found.

Tienes tres soluciones alternativas:

Ejemplos:

# 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 (local_apikey, default)
secure-mcp-gateway --docker generate-config

# Generate config (enkrypt cloud) — requires container CLI >= v2.2.0
secure-mcp-gateway --docker generate-config --provider enkrypt --overwrite

# Health check
secure-mcp-gateway --docker system health-check

┌──────────────────────────────────────────────────────────────────┐
│  ❓ 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)                     │
│                                                                  │
└──────────────────────────────────────────────────────────────────┘

⚠️ Nota importante para usuarios de Docker:

Si estás ejecutando la puerta de enlace de Enkrypt en Docker, usa la versión npx del servidor MCP de GitHub en lugar de la versión Docker que se muestra a continuación. Consulta el ejemplo de configuración basado en npx al final de esta sección.

Para más detalles sobre por qué, consulta Sección 4.3.7: Configuración de servidores MCP cuando la puerta de enlace se ejecuta en Docker.

• GitHub MCP Server se puede ejecutar con docker o npx. La versión Docker requiere que Docker esté instalado y en ejecución en tu máquina.

  • Puedes descargar Docker Desktop desde aquí. Instálalo y ejecútalo si aún no lo tienes.

• Crea un token de acceso personal desde GitHub

  • Crea un token que tenga acceso solo a repositorios públicos y establece una caducidad muy baja inicialmente para pruebas.

  • Agrega el siguiente bloque de servidor de GitHub a enkrypt_mcp_config.json dentro del arreglo "mcp_config": []. Ya debería tener la configuración del servidor echo.

  • NOTA: No olvides agregar la coma , después del bloque del servidor echo

  • Reemplaza REPLACE_WITH_YOUR_PERSONAL_ACCESS_TOKEN con el token de acceso personal que creaste

  • También puedes agregarlo mediante la CLI. Consulta la sección 2. CONFIGURATION MANAGEMENT de CLI-Commands-Reference.md para más detalles.

  • Ejemplo:

      "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": {},
          "server_tools_guardrails_config": {"enabled": 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"
            ]
          }
        }
      ]
  

• Ahora reinicia Claude Desktop para que detecte el nuevo servidor

• Luego ejecuta el prompt list all servers, get all tools available para que descubra el servidor de GitHub y todas sus herramientas disponibles

  

• Ahora ejecuta List all files from https://github.com/enkryptai/enkryptai-mcp-server

  

• ¡Genial! 🎉 Hemos agregado con éxito un servidor MCP de GitHub a la puerta de enlace. Sin embargo, está completamente desprotegido y abierto a todo tipo de abusos y ataques.

• Ahora, digamos que se ejecuta un prompt como este Ask github for the repo "hello; ls -la; whoami"

  

• Esto puede no haber causado daños reales, pero imagina un prompt más complicado que podría haber causado daños reales al sistema.

• Para proteger el servidor MCP, podemos usar Enkrypt Guardrails como se muestra en la siguiente sección.

Configuración del servidor de GitHub (versión npx)

✅ Recomendado para despliegues de Gateway en Docker

Si estás ejecutando el Gateway de Enkrypt en Docker o prefieres no usar Docker-in-Docker, usa el servidor MCP de GitHub basado en npx en su lugar:

{
  "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": {},
  "server_tools_guardrails_config": {"enabled": 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"
    ]
  }
}

Beneficios de la versión npx:

• ✅ Sin complicaciones de Docker-in-Docker
• ✅ Tiempo de inicio más rápido
• ✅ Funciona perfectamente con el gateway dockerizado
• ✅ Gestión de red y volúmenes más simple
• ✅ Menor consumo de recursos

Requisitos previos:

• Node.js y npm deben estar instalados en el contenedor del gateway o en la máquina host
• El Dockerfile predeterminado ya incluye Node.js 22.x LTS

Muchos servidores MCP requieren autenticación OAuth para acceder a recursos protegidos. El Secure MCP Gateway admite OAuth 2.0/2.1 con flujos de Client Credentials y Authorization Code + PKCE para una integración perfecta con servidores habilitados para OAuth.

Resumen

El Gateway gestiona la obtención, el almacenamiento en caché y la renovación automática de tokens OAuth para que no tengas que gestionarlos manualmente. Los tokens se inyectan automáticamente en las solicitudes al conectarse a servidores MCP remotos.

Tipos de concesión admitidos:

• Client Credentials - Para autenticación servidor a servidor (máquina a máquina)
• Authorization Code + PKCE - Para flujos de autorización de usuario con seguridad mejorada

Características clave:

• Autorización automática del navegador para el flujo de Authorization Code
• Soporte de URL de devolución de llamada local y remota
• Renovación automática de tokens antes de su expiración
• Almacenamiento seguro de tokens en caché
• PKCE (S256) para mayor seguridad
• Parámetro de estado para protección contra CSRF

Ejemplos de configuración OAuth

Flujo de Client Credentials (Servidor a Servidor)

Para autenticación máquina a máquina, usa el flujo de Client Credentials:

{
  "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": {},
  "server_tools_guardrails_config": {"enabled": false},
  "input_guardrails_config": {
    "enabled": false
  },
  "output_guardrails_config": {
    "enabled": false
  }
}

Campos OAuth clave

Configuración principal

Parámetros OAuth opcionales

Configuración de seguridad y autenticación

Configuración de TLS mutuo (mTLS)

Revocación de tokens

Flujo de Authorization Code + PKCE

Para autorización de usuario con seguridad mejorada, usa el flujo de Authorization Code con 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": {},
  "server_tools_guardrails_config": {"enabled": true}
}

Autorización automática del navegador

Al usar el flujo de Authorization Code, el gateway automáticamente:

1. Abre tu navegador en la URL de autorización
2. Gestiona la devolución de llamada (localhost o remota)
3. Intercambia el código de autorización por tokens
4. Almacena los tokens en caché para uso futuro

Opciones de flujo:

Devolución de llamada en localhost (automática):

"OAUTH_REDIRECT_URI": "http://localhost:8080/callback"

• El gateway inicia un servidor local en el puerto 8080
• Captura automáticamente el código de autorización
• No se necesita intervención manual

Devolución de llamada remota (entrada manual de código):

"OAUTH_REDIRECT_URI": "https://oauth.yourdomain.com/callback"

• El gateway abre el navegador para la autorización
• El usuario completa la autorización en la página remota
• El usuario copia el código de la página de devolución de llamada
• El usuario pega el código en la terminal
• El gateway intercambia el código por un token

Configuración de devolución de llamada remota

Si deseas usar una URL de devolución de llamada remota (experiencia profesional y de marca):

1. Aloja la página de devolución de llamada:

   # 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.)
   

2. Actualiza tu configuración:

   "OAUTH_REDIRECT_URI": "https://your-domain.com/callback"
   

3. Regístrate con el proveedor OAuth:

   • Añade la URL de devolución de llamada a la configuración de tu aplicación OAuth
   • Auth0: "Allowed Callback URLs"
   • Okta: "Sign-in redirect URIs"
   • Azure AD: "Redirect URIs"
   • Google: "Authorized redirect URIs"

Pruebas con el servidor Echo OAuth

El gateway incluye un servidor echo de prueba que demuestra la inyección de cabeceras OAuth. Puedes usarlo para verificar que OAuth funciona correctamente.

Paso 1: Iniciar el servidor Echo OAuth

El servidor echo OAuth debe ejecutarse en modo HTTP para aceptar conexiones remotas:

macOS/Linux:

# Export the environment variable
export MCP_HTTP_MODE=true

# Start the server
python src/secure_mcp_gateway/bad_mcps/echo_oauth_mcp.py

Windows (PowerShell):

# Set the environment variable
$env:MCP_HTTP_MODE = "true"

# Start the server
python src/secure_mcp_gateway/bad_mcps/echo_oauth_mcp.py

Windows (Símbolo del sistema):

# Set the environment variable
set MCP_HTTP_MODE=true

# Start the server
python src/secure_mcp_gateway/bad_mcps/echo_oauth_mcp.py

El servidor se iniciará en http://localhost:8001/mcp/ e imprimirá las cabeceras relacionadas con OAuth cada vez que se llamen a las herramientas.

Paso 2: Añadir el servidor Echo OAuth a la configuración del gateway

Añade esta configuración a tu enkrypt_mcp_config.json en el array 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": {},
  "server_tools_guardrails_config": {"enabled": false},
  "input_guardrails_config": {
    "enabled": false
  },
  "output_guardrails_config": {
    "enabled": false
  }
}

Nota: OAUTH_ENFORCE_HTTPS: false se establece solo para pruebas locales. ¡Usa siempre HTTPS en producción!

Paso 3: Probar la inyección de tokens OAuth

1. Reinicia Claude Desktop (o tu cliente MCP) para que cargue la nueva configuración del servidor

2. Usa el prompt: list all servers and discover tools from echo_oauth_server

3. Llama a la herramienta echo: call the echo tool from echo_oauth_server with message "test oauth"

4. Revisa la salida de la terminal del servidor echo: deberías ver las cabeceras OAuth impresas:

================================================================================
🔐 OAuth HTTP Headers Check (Remote Mode)
================================================================================
  ✅ AUTHORIZATION: Bearer <token>...
  ❌ 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
================================================================================

Esto confirma que el token OAuth se está adquiriendo e inyectando automáticamente en la cabecera Authorization.

Flujos de tokens OAuth

Flujo de Client Credentials

1. Primera solicitud: El gateway adquiere el token del proveedor OAuth
2. Almacenamiento en caché: El token se almacena en caché con seguimiento de expiración
3. Inyección de token:
   • Servidores remotos: El token se añade como cabecera Authorization: Bearer <token>
   • Servidores locales: El token está disponible en variables de entorno
4. Renovación automática: El token se renueva 5 minutos antes de su expiración (configurable)

Flujo de Authorization Code + PKCE

1. Configuración inicial: El gateway genera el verificador y el desafío de código PKCE
2. Autorización del navegador:
   • El gateway abre el navegador en la URL de autorización
   • El usuario inicia sesión y autoriza la aplicación
3. Gestión de la devolución de llamada:
   • Localhost: El gateway captura automáticamente el código de la devolución de llamada
   • Remoto: El usuario copia el código y lo pega en la terminal
4. Intercambio de tokens: El gateway intercambia el código de autorización por tokens
5. Almacenamiento en caché y renovación: Los tokens se almacenan en caché y se renuevan automáticamente antes de su expiración

Características avanzadas

• Authorization Code + PKCE: Autorización de usuario con seguridad mejorada (S256)
• Flujo automático del navegador: Abre el navegador y gestiona la devolución de llamada automáticamente
• Soporte de devolución de llamada remota: Aloja la página de devolución de llamada en tu dominio
• TLS mutuo (mTLS): Seguridad mejorada con certificados de cliente (RFC 8705)
• Revocación de tokens: Revoca tokens programáticamente (RFC 7009)
• Validación de ámbitos: Verifica que el token devuelto tenga los ámbitos solicitados
• Cabeceras personalizadas: Añade cabeceras HTTP personalizadas a las solicitudes de token
• Parámetro de estado: Protección contra CSRF para el flujo de Authorization Code
• Métricas: Realiza un seguimiento del éxito/fracaso de la adquisición de tokens, proporción de aciertos de caché

Solución de problemas

La solicitud de token OAuth falló:

• Verifica que CLIENT_ID y CLIENT_SECRET sean correctos
• Comprueba que TOKEN_URL sea accesible
• Asegúrate de usar HTTPS (o establece OAUTH_ENFORCE_HTTPS: false para pruebas)

El token no aparece en las solicitudes:

• Confirma is_remote: true para servidores remotos
• Revisa los registros del servidor para ver mensajes de adquisición OAuth
• Habilita el registro de depuración: "enkrypt_log_level": "DEBUG"

Problemas con el flujo de Authorization Code:

• Verifica que AUTHORIZATION_URL y REDIRECT_URI sean correctos
• Asegúrate de que la URL de devolución de llamada esté registrada en el proveedor OAuth
• Comprueba que el navegador se abra automáticamente (o usa la URL manual)
• Para devoluciones de llamada remotas, verifica que la página sea accesible

La devolución de llamada no funciona:

• Localhost: El gateway intenta automáticamente el siguiente puerto disponible si el 8080 está en uso (hasta 10 puertos)
• Remoto: Verifica que la URL de devolución de llamada sea accesible y coincida con la configuración del proveedor OAuth
• Comprueba si el firewall bloquea la devolución de llamada

El servidor echo no recibe cabeceras:

• Asegúrate de que la variable de entorno MCP_HTTP_MODE=true esté configurada
• Verifica que el servidor se esté ejecutando en http://localhost:8001/mcp/

• Hemos encontrado que la mejor manera de usar las Protecciones de Enkrypt en el Gateway MCP es tener una protección separada para cada servidor. De esta manera podemos tener una protección ajustada para cada servidor.

• Debido a que cada Servidor MCP es muy diferente de los demás, no es posible tener una sola protección que funcione para todos los servidores.

• Algunos pueden necesitar Toxicity Detector, otros NSFW Detector, otros Injection Attack Detector, otros Keyword Detector, otros Policy Violation, algunos pueden necesitar el detector Relevancy, algunos pueden necesitar el detector Adherence, etc.

• Algunos pueden necesitar una combinación de estos detectores trabajando juntos para bloquear solicitudes maliciosas.

• Algunos pueden necesitar Protecciones en el lado de entrada, otros en el de salida y algunos pueden necesitar que se apliquen ambas.

• Consulta nuestra documentación para detalles sobre varios detectores disponibles.

• Por lo tanto, ten protecciones separadas para cada servidor y experimenta con la mejor combinación de detectores y bloqueos para cada servidor que bloquee solicitudes maliciosas pero permita que las solicitudes legítimas pasen.

• Prueba nuestro detector Policy Violation con tu propia política personalizada que detalle qué está permitido y qué no. Esta puede ser la mejor manera para tu caso de uso.

11.1 Configuración de Protección por Servidor

Puedes controlar el comportamiento de las protecciones para cada servidor individualmente usando banderas por servidor en tu configuración.

Nota: Este campo tiene como valor predeterminado false; cuando está ausente de common_overrides, tanto el registro de herramientas como la validación de información del servidor se omiten.

server_tools_guardrails_config (objeto, predeterminado: {"enabled": false})

Una configuración unificada obtenida exclusivamente de common_overrides (a nivel de gateway). Controla tanto la validación de la descripción del servidor como la validación del registro de herramientas mediante una única bandera enabled, guardrail_name y la lista block.

Forma:

{
  "enabled": true,
  "guardrail_name": "My Guardrail Policy",
  "block": ["policy_violation", "injection_attack"],
  "additional_config": {}
}

Cuando enabled: true, tanto la validación de la descripción del servidor como las verificaciones de protección del registro de herramientas se ejecutan usando esta política. Cuando enabled: false o está ausente, ambas se omiten.

Cuándo deshabilitar:

• Entornos de prueba/desarrollo con servidores conocidos como seguros
• Servidores internos donde el contenido es totalmente confiable
• Cuando los metadatos del servidor contienen términos técnicos que generan falsos positivos

Niveles de Protección:

El gateway tiene dos niveles distintos de protecciones:

1. Validación de Registro de Servidor y Herramientas (server_tools_guardrails_config)

   • Cuándo: Durante el descubrimiento de servidores y herramientas
   • Qué: Valida descripciones de servidores, descripciones de herramientas y esquemas para contenido dañino
   • Bloquea: Servidores o herramientas con metadatos maliciosos

2. Protecciones en Tiempo de Ejecución (input_guardrails_config / output_guardrails_config)

   • Cuándo: Durante la ejecución de herramientas (entrada antes, salida después)
   • Qué: Valida argumentos y respuestas de herramientas
   • Bloquea: Solicitudes/respuestas que violan políticas

Nota: Los tres niveles son independientes y pueden configurarse por separado para cada servidor.

El Gateway proporciona un servidor de API REST para operaciones administrativas como gestión de usuarios, proyectos, configuraciones y claves API.

Iniciar el Servidor de API REST

secure-mcp-gateway system start-api --host 0.0.0.0 --port 8001

• Documentación de la API: Disponible en http://localhost:8001/docs (Interfaz Swagger)
• Verificación de Salud: http://localhost:8001/health
• Esquema OpenAPI: Cargado desde openapi.json en la raíz del proyecto

Autenticación con Clave API de Administrador

Importante: Las operaciones administrativas requieren una admin_apikey especial en la raíz de la configuración que es separada de las claves API de usuario regulares. Esto proporciona seguridad mejorada para operaciones de administración.

Comportamiento según proveedor (la política de resolución vive en src/secure_mcp_gateway/auth_policy.py):

La ubicación anidada pre-2.2 enkrypt_config.admin_apikey todavía se respeta como respaldo obsoleto para que las configuraciones existentes sigan funcionando sin ediciones.

Obtener tu Clave API de Administrador

La admin_apikey se genera automáticamente en la raíz de la configuración cuando ejecutas secure-mcp-gateway generate-config (la variante predeterminada del proveedor local_apikey). Encuéntrala en tu archivo de configuración:

• Windows: %USERPROFILE%\.enkrypt\enkrypt_mcp_config.json
• macOS/Linux: ~/.enkrypt/enkrypt_mcp_config.json

{
  "admin_apikey": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6...",
  "enkrypt_config": {
    "api_key": "YOUR_ENKRYPT_API_KEY",
    "base_url": "https://api.enkryptai.com"
  },
  "apikeys": {
    "regular_user_key_1": { ... },
    "regular_user_key_2": { ... }
  },
  ...
}

Nota: Si usaste --provider enkrypt para generar la configuración, no verás una admin_apikey en absoluto — la enkrypt_config.api_key en la nube se usa como credencial de administrador por defecto. Añade admin_apikey en la raíz solo si deseas un secreto de administrador separado.

Diferencias Clave

• admin_apikey (a nivel de raíz): Se usa para todas las operaciones administrativas (gestión de usuarios, gestión de proyectos, etc.)

  • Cadena aleatoria de 256 caracteres para máxima seguridad
  • Generada durante secure-mcp-gateway generate-config (solo cuando --provider local_apikey, que es el predeterminado)
  • Requerida para los endpoints de la API REST cuando el proveedor de autenticación es local_apikey. Opcional con el proveedor enkrypt.

• apikeys (en la sección apikeys): Se usa para el acceso al gateway por parte de los usuarios

  • Usada por los clientes MCP para conectarse al gateway
  • Asociada con usuarios y proyectos específicos
  • No se usa para operaciones administrativas

Usar la Clave API de Administrador

Incluye la admin_apikey en el encabezado de Autorización para todas las llamadas administrativas a la API:

curl -X GET "http://localhost:8001/api/v1/users" -H "Authorization: Bearer YOUR_ADMIN_API_KEY_HERE"

Nota de Seguridad:

• Mantén tu clave API de administrador segura y nunca la confirmes en el control de versiones
• Comparte la clave API de administrador solo con administradores autorizados
• Los usuarios regulares nunca deberían tener acceso a la clave API de administrador

Operaciones Administrativas Disponibles

La API REST proporciona endpoints para:

1. Gestión de Usuarios: Crear, listar, actualizar y eliminar usuarios
2. Gestión de Proyectos: Crear proyectos, asignar configuraciones, gestionar usuarios
3. Gestión de Claves API: Generar, rotar, deshabilitar/habilitar y eliminar claves API
4. Gestión de Configuración: Crear, actualizar y gestionar configuraciones y servidores MCP

Para documentación completa de la API y ejemplos, consulta:

• API-Reference.md
• Documentación interactiva de la API en http://localhost:8001/docs

1. Gateway local, Guardrails locales y servidor MCP local

2. Gateway local, servidor MCP local con Guardrails remotos

3. Gateway local con servidor MCP remoto y Guardrails remotos

4. Gateway remoto, servidor MCP remoto y Guardrails remotos

14.1 Gateway local, Guardrails locales y servidor MCP local

14.2 Gateway local, servidor MCP local con Guardrails remotos

14.3 Gateway local con servidor MCP remoto y Guardrails remotos

14.4 Gateway remoto, servidor MCP remoto y Guardrails remotos

• Para eliminar el Gateway de cualquier cliente MCP, simplemente elimine el bloque del servidor MCP "Enkrypt Secure MCP Gateway": {...} del archivo de configuración del cliente. Para Claude Code, ejecute claude mcp remove Enkrypt-Secure-MCP-Gateway.

  • Reinicie el cliente MCP para aplicar los cambios en algunos clientes como Claude Desktop. Cursor no requiere reinicio.

• Para desinstalar el paquete pip, ejecute el siguiente comando:

  pip uninstall secure-mcp-gateway
  

• Si alguna llamada falla en el cliente, consulte los registros mcp del cliente respectivo

  • Consulte esto para la ubicación de los registros de Claude

    • Ejemplo 🍎 Ruta de registro en Linux/macOS: ~/Library/Logs/Claude/mcp-server-Enkrypt Secure MCP Gateway.log
    • Ejemplo 🪟 Ruta de registro en Windows: %USERPROFILE%\AppData\Roaming\Claude\logs\mcp-server-Enkrypt Secure MCP Gateway.log

  • Consulte esta discusión para los registros de Cursor

• Si ve errores como Exception: unhandled errors in a TaskGroup (1 sub-exception), entonces quizás el servidor MCP que el gateway intenta usar no está en ejecución.

  • Por lo tanto, asegúrese de que el archivo al que intenta acceder esté disponible
  • Se cumplan todos los requisitos previos para que el servidor MCP se ejecute, como docker en ejecución, etc.

• Si necesitamos registros más detallados, configure enkrypt_log_level a debug en el archivo enkrypt_mcp_config.json y reinicie el cliente MCP.

16.1 Solución de problemas de OpenTelemetry

1. Errores de handshake SSL

   Si ve errores SSL como:

   SSL_ERROR_SSL: error:100000f7:SSL routines:OPENSSL_internal:WRONG_VERSION_NUMBER
   

   Solución: Agregue insecure=True a la configuración del exportador OTLP en telemetry.py

2. Sin registros en Loki

   • Verifique que el recopilador OTLP esté en ejecución:

     docker logs secure-mcp-gateway-otel-collector-1
     

   • Verifique la configuración del recopilador en otel_collector/otel-collector-config.yaml

   • Verifique que Loki esté recibiendo datos:

     curl -G -s "http://localhost:3100/loki/api/v1/query" --data-urlencode 'query={job="enkrypt"}'
     

3. Métricas faltantes

   • Verifique la canalización de métricas del recopilador OTLP:

     curl http://localhost:8888/metrics
     

   • Verifique las métricas en los registros del recopilador:

     docker logs secure-mcp-gateway-otel-collector-1 | grep "metrics"
     

4. Problemas con Docker

   # Restart the observability stack (use the compose file for whichever
   # backend you run -- the bare `docker compose` form no longer works
   # since both stacks use explicit -f/--env-file).
   cd observability
   # OpenSearch (primary):
   docker compose -f docker-compose.opensearch.yml --env-file .env.opensearch down
   docker compose -f docker-compose.opensearch.yml --env-file .env.opensearch up -d
   # …or legacy Grafana:
   docker compose -f docker-compose.grafana.yml --env-file .env.grafana down
   docker compose -f docker-compose.grafana.yml --env-file .env.grafana up -d
   
   # Check individual service logs
   docker logs <service-name>
   

El gateway incluye un conjunto de pruebas integral que valida toda la funcionalidad principal, incluido el descubrimiento de servidores, la ejecución de herramientas, los guardrails, el almacenamiento en caché, la telemetría y más.

Requisitos previos

• Gateway instalado localmente (siga Instalación local)
• Entorno virtual activado
• Servidor MCP Echo OAuth en ejecución (para probar escenarios de servidor remoto)

Ejecución del conjunto de pruebas

Paso 1: Configurar la variable de entorno

Windows PowerShell:

$env:MCP_HTTP_MODE="true"

Símbolo del sistema de Windows:

set MCP_HTTP_MODE=true

macOS/Linux:

export MCP_HTTP_MODE="true"

Esta variable de entorno permite que el servidor Echo OAuth se ejecute en modo HTTP para pruebas.

Paso 2: Iniciar el servidor Echo OAuth

Navegue al directorio del servidor echo e inícielo:

Windows PowerShell:

cd src\secure_mcp_gateway\bad_mcps
python .\echo_oauth_mcp.py

macOS/Linux:

cd src/secure_mcp_gateway/bad_mcps
python echo_oauth_mcp.py

El servidor se iniciará en http://localhost:8001/mcp/ y permanecerá en ejecución. Mantenga esta terminal abierta.

Paso 3: Ejecutar el conjunto de pruebas

Abra una nueva terminal, active su entorno virtual y ejecute las pruebas:

Windows PowerShell:

# Activate virtual environment
.\.venv\Scripts\activate

# Navigate to tests directory
cd tests

# Run tests
python .\test_gateway.py

macOS/Linux:

# Activate virtual environment
source ./.venv/bin/activate

# Navigate to tests directory
cd tests

# Run tests
python test_gateway.py

Cobertura de pruebas

El conjunto de pruebas incluye:

• Pruebas de descubrimiento de servidores: Listar servidores, obtener información del servidor, descubrir herramientas
• Pruebas de ejecución de herramientas: Llamar a herramientas, múltiples llamadas a herramientas, manejo de errores
• Pruebas de caché: Estado de la caché, limpieza de la caché, expiración de la caché
• Pruebas de guardrails: Guardrails de entrada/salida, guardrails asíncronos, redacción de PII
• Pruebas de telemetría: Integración de OpenTelemetry, métricas, trazas, registros
• Pruebas de configuración: Configuración de tiempo de espera, niveles de registro, caché externa
• Pruebas de integración: Flujos de trabajo completos, recuperación de errores, rendimiento

Salida esperada

El ejecutor de pruebas mostrará:

• Progreso de cada prueba
• Estado de éxito/fallo
• Duración de la ejecución
• Resumen final con recuentos de aprobados/fallidos

Ejemplo de salida:

=== 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

Solución de problemas de las pruebas

Errores de conexión del servidor Echo:

• Verifique que el servidor Echo OAuth se esté ejecutando en el puerto 8001
• Verifique que la variable de entorno MCP_HTTP_MODE esté configurada
• Asegúrese de que ningún otro servicio esté usando el puerto 8001

Errores de configuración del Gateway:

• Verifique que enkrypt_mcp_config.json exista en el directorio ~/.enkrypt/
• Verifique que el archivo de configuración tenga claves de gateway válidas y configuraciones de servidor
• Asegúrese de que el entorno virtual tenga todas las dependencias instaladas

Fallos de prueba:

• Habilite el registro de depuración configurando enkrypt_log_level: "DEBUG" en la configuración
• Consulte los registros del cliente MCP para obtener mensajes de error detallados
• Verifique que todos los requisitos previos estén instalados (Python 3.11+, pip, uv)