Enkrypt AI Secure MCP Gateway

1. Seu cliente MCP se conecta ao servidor Secure MCP Gateway com a API Key (gerenciado por src/secure_mcp_gateway/gateway.py).

2. O servidor do Gateway busca a configuração do gateway do arquivo enkrypt_mcp_config.json local (plugins.auth.provider = "local_apikey") ou da nuvem remota Enkrypt em https://api.enkryptai.com/mcp-gateway/get-gateway-config (plugins.auth.provider = "enkrypt"). Veja §14.5 Esquema de Configuração do Gateway para ambas as formas.

   • Ele armazena a configuração em cache localmente ou em um servidor de cache externo como KeyDB, se configurado, para melhorar o desempenho.

3. Se os guardrails de entrada estiverem habilitados, a requisição é validada antes da chamada de ferramenta (gerenciado por src/secure_mcp_gateway/guardrail.py).

   • A requisição é bloqueada se violar qualquer um dos guardrails configurados e o detector específico estiver configurado para bloquear.

4. As requisições são encaminhadas ao Gateway Client (gerenciado por src/secure_mcp_gateway/client.py).

5. O cliente do Gateway encaminha a requisição ao servidor MCP apropriado (gerenciado por src/secure_mcp_gateway/client.py).

6. O servidor MCP processa a requisição e retorna a resposta ao cliente do Gateway.

7. Se foi uma chamada de descoberta de ferramentas, o cliente do Gateway armazena as ferramentas em cache localmente ou em um servidor de cache externo como KeyDB, se configurado. Ele então encaminha a resposta ao servidor do Gateway.

8. O servidor do Gateway recebe a resposta do cliente do Gateway e, se os guardrails de saída estiverem habilitados, valida a resposta contra os guardrails configurados (gerenciado por src/secure_mcp_gateway/guardrail.py).

   • A resposta é bloqueada se violar qualquer um dos guardrails configurados e o detector específico estiver configurado para bloquear.

9. O servidor do Gateway encaminha a resposta de volta ao cliente MCP se tudo estiver correto.

• Git 2.43 ou superior

• Python 3.11 ou superior instalado no seu sistema e acessível pela linha de comando usando o comando python ou python3

• pip 25.0.1 ou superior instalado no seu sistema e acessível pela linha de comando usando o comando pip ou python -m pip

• uv 0.7.9 ou superior instalado no seu sistema e acessível pela linha de comando usando o comando uv ou 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

Se você quiser proteger seus MCPs com os Guardrails da Enkrypt, você precisa fazer o seguinte:

• Crie uma nova conta se você não tiver uma. É grátis! 🆓 Sem necessidade de cartão de crédito 💳🚫

• Um ENKRYPT_API_KEY que você pode obter nas Configurações do Painel Enkrypt

• Para proteger seus MCPs com Guardrails, você pode usar o Guardrail de amostra padrão Sample Airline Guardrail para começar ou criar seu próprio Guardrail personalizado

• Para configurar Guardrails personalizados, você precisa fazer login no aplicativo Enkrypt AI ou usar as APIs/SDK

  • Crie Guardrails no Painel do Aplicativo Enkrypt AI ✅

  • Crie Guardrails usando APIs

  • Crie Guardrails usando SDK

  • Você também pode usar o Enkrypt MCP Server 🤯 para criar Guardrails e usá-los no Gateway

4.1.1 Baixe e Instale o Pacote

• Ative um ambiente 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
  

• Instale o pacote. Para mais informações veja https://pypi.org/project/secure-mcp-gateway/

  pip install secure-mcp-gateway
  

4.1.2 Execute o Comando Generate

• Isso gera o arquivo de configuração em ~/.enkrypt/enkrypt_mcp_config.json no macOS e %USERPROFILE%\.enkrypt\enkrypt_mcp_config.json no Windows

  secure-mcp-gateway generate-config
  

⚠️ Reexecutando em uma configuração existente? generate-config se recusa a sobrescrever um arquivo existente por padrão — ele sai com INFO: Config file already exists at <path>. ... use --overwrite flag. Adicione --overwrite para regenerar (um backup .bkp.<YYYYMMDD_HHMMSS> com timestamp é gravado ao lado do original primeiro). A flag também funciona com --provider enkrypt abaixo.

secure-mcp-gateway generate-config --overwrite

Escolhendo um provedor de autenticação no momento da geração

O comando padrão emite o esquema completo de local-apikey — um servidor echo de exemplo, um projeto padrão, um usuário e uma chave de API do gateway gerada automaticamente — tudo o que você precisa para iniciar offline. Se você preferir que o gateway busque seus servidores/projetos/usuários da nuvem Enkrypt, gere o config mínimo com suporte à nuvem:

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

Isso grava um arquivo muito mais curto contendo apenas:

• enkrypt_config.api_key e base_url (você preenche a apikey)
• plugins.auth.provider = "enkrypt" com um placeholder gateway_name
• plugins.guardrails.provider = "enkrypt"
• plugins.telemetry.provider = "opentelemetry" (OTLP gRPC para localhost:4317, correspondendo ao padrão local-apikey e à stack empacotada Prometheus/Grafana/Jaeger/Loki — defina config.enabled: false se você não tiver um coletor em execução)
• Duas entradas comumente ajustadas em common_mcp_gateway_config (enkrypt_log_level, enkrypt_gateway_cache_expiration_minutes)

Sem blocos locais de mcp_configs / projects / users / apikeys — a nuvem é dona deles. Após a geração, edite o arquivo e defina:

1. enkrypt_config.api_key → sua apikey da nuvem Enkrypt
2. plugins.auth.config.gateway_name → o saved_name do gateway que você criou no console Enkrypt

gateway_name é o único valor que também pode chegar por requisição, como o cabeçalho X-Enkrypt-MCP-Gateway do cliente MCP, para que um único processo de gateway possa atender vários gateways na nuvem. Quando definido no config, o config vence. Referência completa de chaves de config e cabeçalhos: §7.1 Provedor de autenticação da nuvem Enkrypt e cabeçalhos de gateway.

O arquivo de referência enviado é src/secure_mcp_gateway/example_enkrypt_cloud_config.json — mesma forma que a CLI gera. Use-o como modelo para configs escritos à mão.

Valores de flag suportados:

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 Exemplo do arquivo de config gerado

Nota: Os exemplos abaixo mostram o esquema completo emitido por secure-mcp-gateway generate-config (padrão --provider local_apikey). Cada campo está incluído para que você possa comparar seu arquivo gerado 1:1. O bloco oauth_config é enviado desabilitado ("enabled": false) — suas chaves são placeholders que você só precisa preencher se um servidor usar OAuth. O bloco timeout_settings contém os timeouts por operação que o gateway usa internamente; os padrões são sensatos e raramente precisam de edição.

{
  "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 Instale o Gateway para Claude Desktop

• Execute o seguinte comando para instalar o gateway para Claude:

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

• Isso registrará o Enkrypt Secure MCP Gateway com o Claude Desktop.

• NOTA: Reinicie o Claude Desktop após a instalação

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 Exemplo do Config do Claude Desktop após a instalação

A forma das variáveis de ambiente depende do plugins.auth.provider do seu gateway. Mesma dicotomia da seção do Cursor abaixo:

• Provedor local_apikey (padrão) → três variáveis de ambiente: ENKRYPT_GATEWAY_KEY + ENKRYPT_PROJECT_ID + ENKRYPT_USER_ID
• Provedor de nuvem enkrypt → variável de ambiente única: ENKRYPT_APIKEY

4.1.6 Instale o Gateway para Cursor

• Execute o comando de instalação da CLI para Cursor

  secure-mcp-gateway install --client cursor
  

• Isso atualiza automaticamente seu ~/.cursor/mcp.json (no Windows fica em: %USERPROFILE%.cursor\mcp.json) com a entrada correta.

• Embora normalmente não seja necessário reiniciar, se você vir em estado de carregamento por muito tempo, reinicie o Cursor

A forma das variáveis de ambiente depende do plugins.auth.provider do seu gateway. O comando de instalação grava a forma que corresponde:

Provedor	Variáveis de ambiente gravadas	Usado para
local_apikey (padrão)	ENKRYPT_GATEWAY_KEY + ENKRYPT_PROJECT_ID + ENKRYPT_USER_ID	Buscar a apikey local + projeto + usuário no seu config local
enkrypt (nuvem)	ENKRYPT_APIKEY	Apikey única da nuvem; projeto/usuário vêm da nuvem Enkrypt

Ambas as formas mcp.json abaixo são válidas — escolha a que corresponde a como você gerou seu config. Veja Seção 4.1.2 para a flag --provider enkrypt.

4.1.7 Instale o Gateway para Claude Code

Claude Code é o agente de codificação baseado em CLI da Anthropic. Ele usa comandos claude mcp add para configurar servidores MCP. Diferente do Claude Desktop e do Cursor, que usam arquivos JSON de config, o Claude Code gerencia servidores MCP por meio de sua própria CLI.

Pré-requisito: A CLI claude deve estar instalada no seu sistema. Veja documentação do Claude Code para instalação.

Passo 1: Instale o gateway

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

Isso automaticamente:

• Lê as credenciais do gateway do seu config gerado (ciente do provedor):
  • Provedor local_apikey (padrão) → emite três flags --env: ENKRYPT_GATEWAY_KEY, ENKRYPT_PROJECT_ID, ENKRYPT_USER_ID
  • Provedor de nuvem enkrypt → emite uma única flag --env: ENKRYPT_APIKEY (originada de enkrypt_config.api_key, ou --apikey <key> se você passar na CLI)
• Executa claude mcp add com --transport stdio e as credenciais corretas e o caminho do gateway
• Registra o servidor como Enkrypt-Secure-MCP-Gateway com --scope user (disponível em todos os projetos do Claude Code)

Passo 2: Verifique se o servidor foi adicionado

claude mcp list

Você deve ver Enkrypt-Secure-MCP-Gateway na lista.

Passo 3: Use o gateway no Claude Code

Inicie o Claude Code e tente:

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 Clone o repositório, configure o ambiente virtual e instale as dependências

• Clone o repositório:

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 Execute o script de configuração

• Este script cria o arquivo de config em ~/.enkrypt/enkrypt_mcp_config.json no macOS e %USERPROFILE%\.enkrypt\enkrypt_mcp_config.json no Windows com base no arquivo src/secure_mcp_gateway/example_enkrypt_mcp_config.json

• Ele substitui UNIQUE_GATEWAY_KEY e outros UUIDs por valores gerados automaticamente e também substitui DUMMY_MCP_FILE_PATH pelo caminho real para o arquivo MCP de teste bad_mcps/echo_mcp.py

• Ele também instala o cliente MCP no Claude Desktop

• NOTA: Por favor, reinicie o Claude Desktop após executar o script de configuração para ver o Gateway em execução no 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 Outros Clientes MCP

4.3.1 Construir a Imagem Docker

docker build -t secure-mcp-gateway .

Marque sua build para que o wrapper --docker a encontre. A partir da v2.2.0, o wrapper secure-mcp-gateway --docker ... puxa enkryptai/secure-mcp-gateway:<your-host-CLI-version> por padrão (ex.: enkryptai/secure-mcp-gateway:2.2.0). Até que essa tag exata seja publicada no Docker Hub, todo comando --docker falha com Unable to find image ... not found. Corrija isso uma vez marcando sua build local para corresponder (encontre sua versão com secure-mcp-gateway --version):

# Substitua 2.2.0 pela saída de `secure-mcp-gateway --version`
docker tag secure-mcp-gateway:latest enkryptai/secure-mcp-gateway:2.2.0

Após este único comando, todo secure-mcp-gateway --docker generate-config, --docker install --client X, --docker config list, etc. no restante da §4.3 funciona sem precisar de substituições de --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 Gerar o arquivo de configuração

• Isso cria um arquivo de configuração no arquivo ~/.enkrypt/docker/enkrypt_mcp_config.json no macOS/Linux e no arquivo %USERPROFILE%\.enkrypt\docker\enkrypt_mcp_config.json no Windows.

Atalho rápido — Se você tiver a CLI instalada localmente via pip, pode usar a flag --docker em qualquer comando e pular a sintaxe verbosa do Docker:

secure-mcp-gateway --docker generate-config

Escolhendo um provedor de autenticação no momento da geração

Idêntico à instalação local — veja §4.1.2 → "Escolhendo um provedor de autenticação no momento da geração" para a explicação completa. Em resumo:

• Padrão (omitir --provider) → esquema completo de local_apikey com um servidor echo de exemplo, projeto, usuário, chave de API do gateway e admin_apikey de nível raiz. Inicializa offline, sem dependência de nuvem.
• --provider enkrypt → esquema mínimo com suporte a nuvem. Após gerar, edite o arquivo e defina enkrypt_config.api_key (sua apikey de nuvem Enkrypt) e plugins.auth.config.gateway_name (o nome salvo do gateway que você criou no console Enkrypt). A nuvem é dona de servidores/projetos/usuários/apikeys, então esses blocos estão ausentes.

Comandos copiar-e-colar (todos os SOs, usando o atalho --docker — funciona em bash, zsh, CMD e PowerShell, pois o wrapper lida com as aspas por SO 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

Após o comando ser bem-sucedido, o arquivo é salvo em:

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

Se você não tiver a CLI instalada localmente via pip, as invocações equivalentes de docker run ... para cada shell de SO estão no bloco de detalhes "Comandos Docker run verbosos" abaixo.

⚠️ Reexecutando sobre uma configuração existente? generate-config se recusa a sobrescrever um arquivo existente por padrão — ele sai com INFO: Config file already exists at <path>. ... use --overwrite flag. Adicione --overwrite ao final do comando para regenerar (um backup .bkp.<YYYYMMDD_HHMMSS> com timestamp é gravado ao lado do original primeiro). A flag funciona da mesma forma para --provider enkrypt e o atalho --docker.

⚠️ "unrecognized arguments: --provider enkrypt" ao usar --docker? Isso significa que a CLI no contêiner é mais antiga que a CLI do seu host (--provider foi adicionado na v2.2.0). O wrapper --docker agora usa como padrão enkryptai/secure-mcp-gateway:<host-version>, mas se essa tag ainda não estiver no Docker Hub, você verá Unable to find image ... not found. Construa a imagem a partir do código-fonte: docker build -t secure-mcp-gateway . && secure-mcp-gateway --docker --docker-image secure-mcp-gateway generate-config --provider enkrypt --overwrite. Veja Padrão de comando Docker → Tag da imagem fixada na versão da CLI do host para a tabela completa de soluções alternativas.

# 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 o Gateway no Claude Desktop

• Você pode encontrar o local da configuração do Claude nos locais abaixo no seu sistema. Para referência, veja a documentação do Claude.
  • macOS: ~/Library/Application Support/Claude
  • Windows: %APPDATA%\Claude

Nota: A configuração gerada inclui MCP_TRANSPORT=stdio para comunicação em modo stdio com o Claude Desktop. O comando é ciente do provedor — ele lê plugins.auth.provider da configuração do seu gateway e emite a forma correta de env/-e (ENKRYPT_GATEWAY_KEY/ENKRYPT_PROJECT_ID/ENKRYPT_USER_ID para local_apikey, um único ENKRYPT_APIKEY para enkrypt).

Comando copiar-e-colar (todos os SOs — o wrapper --docker monta automaticamente seu diretório de configuração do Claude):

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

Encontrou Unable to find image 'enkryptai/secure-mcp-gateway:<version>' ... not found? Você pulou a etapa única de docker tag no final da §4.3.1. Execute-a uma vez e tente novamente.

Após a execução, reinicie o Claude Desktop para aplicar a nova configuração.

# 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 Exemplo de arquivo de configuração do Claude Desktop

O bloco env depende do plugins.auth.provider do seu gateway (veja §4.1.2). Ambas as formas são mostradas abaixo.

{
  "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 o Gateway no Cursor

• Você pode encontrar o local do config do Cursor nos locais abaixo. Para referência, veja a documentação do Cursor.
  • macOS: ~/.cursor
  • Windows: %USERPROFILE%\.cursor

Nota: O config gerado inclui MCP_TRANSPORT=stdio para comunicação em modo stdio com o Cursor. O comando é ciente do provedor — ele lê plugins.auth.provider do seu config do gateway e emite a forma correta de env/-e (ENKRYPT_GATEWAY_KEY/ENKRYPT_PROJECT_ID/ENKRYPT_USER_ID para local_apikey, um único ENKRYPT_APIKEY para enkrypt).

Comando copiar-colar (todos os SOs — o wrapper --docker monta automaticamente ~/.cursor para que o install dentro do contêiner possa gravar de volta nele):

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

Encontrou Unable to find image 'enkryptai/secure-mcp-gateway:<version>' ... not found? Você pulou a etapa única de docker tag no final de §4.3.1. Execute-a uma vez e tente novamente.

Depois que ele for executado, reinicie o Cursor para carregar o novo servidor. A entrada fica em ~/.cursor/mcp.json no macOS/Linux ou %USERPROFILE%\.cursor\mcp.json no 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 o Gateway no Claude Code

O Claude Code usa sua própria CLI (claude mcp add) para gerenciar servidores MCP. Quando o gateway é executado no Docker, o Claude Code se conecta via npx mcp-remote ao endpoint HTTP Streamable do gateway.

Pré-requisitos: Node.js e npm devem estar instalados na sua máquina (node -v e npm -v para verificar).

Passo 1: Execute o contêiner do gateway

Inicie o gateway como um contêiner Docker em segundo plano com o endpoint HTTP Streamable exposto:

# 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

Passo 2: Adicione o gateway ao Claude Code

Os cabeçalhos HTTP variam de acordo com o provedor de autenticação:

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

Substitua os placeholders pelos valores do seu enkrypt_mcp_config.json (apikeys.<key> e os IDs de projeto/usuário correspondentes para local_apikey, ou 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"
  }
}'

Passo 3: Verifique

claude mcp list

Passo 4: Use no Claude Code

Inicie o Claude Code e experimente prompts como list all servers, get all tools available.

4.3.7 Executando o Gateway com Docker Run (Avançado)

Para implantações avançadas do Docker, você pode executar o contêiner do gateway diretamente com configurações personalizadas. As variáveis de ambiente de autenticação dependem do plugins.auth.provider do seu gateway (veja §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

Variáveis de Ambiente

As variáveis de ambiente de autenticação são dependentes do provedor — exatamente uma das duas formas abaixo é necessária:

MCP_TRANSPORT

A variável de ambiente MCP_TRANSPORT controla o modo de transporte do gateway.

Modos de transporte:

• streamable-http (padrão): modo de servidor HTTP na porta 8000. Use com -p 8000:8000 para mapeamento de portas.
• stdio: modo de entrada/saída padrão para clientes MCP que se comunicam via stdin/stdout. Use com o sinalizador -i.

Exemplo 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

A variável de ambiente SKIP_DEPENDENCY_INSTALL controla se o gateway reinstala as dependências do Python em tempo de execução.

Comportamento padrão:

• Ambientes Docker: O padrão é true (detectado automaticamente). As dependências são pré-instaladas na imagem Docker, então a instalação em tempo de execução é pulada automaticamente.
• Ambientes não Docker: O padrão é false. As dependências são instaladas na inicialização para garantir compatibilidade.

Quando definir explicitamente SKIP_DEPENDENCY_INSTALL=false no Docker:

• Ambientes de desenvolvimento onde você está testando novas dependências
• Ao montar volumes de código-fonte para desenvolvimento ao vivo
• Se você não tiver certeza se todas as dependências estão instaladas corretamente

Quando definir explicitamente SKIP_DEPENDENCY_INSTALL=true fora do Docker:

• Implantações de produção onde as dependências são pré-instaladas
• Para reduzir o tempo de inicialização (inicializações a frio mais rápidas)
• Em ambientes onde você já executou pip install

Exemplo com integração 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: O sinalizador --network conecta o gateway à pilha de observabilidade (Grafana, Prometheus, Loki, Jaeger, além das 9 regras de alerta do Slack) se você estiver executando os serviços de monitoramento da seção 5. O nome da rede (secure-mcp-gateway-observability_default) é derivado do nome do projeto compose definido no topo de observability/docker-compose.grafana.yml (o campo name: não é alterado pela renomeação do arquivo, então o nome da rede é estável).

Mapeamento de Portas

• 8000: servidor MCP do gateway (obrigatório) — vinculado ao ENTRYPOINT ["python3", "src/secure_mcp_gateway/gateway.py"] padrão.
• 8080: servidor de callback OAuth (opcional, necessário apenas para o fluxo de Código de Autorização). Também vinculado ao entrypoint do gateway quando o OAuth está configurado.
• 8001: servidor da API administrativa REST. Não iniciado pelo entrypoint padrão. Mapear -p 8001:8001 sozinho não faz nada — não há listener na porta 8001 dentro do contêiner, a menos que você também inicie python -m secure_mcp_gateway.api_server (por exemplo, via um sidecar docker exec, um --entrypoint personalizado ou sua própria imagem que execute ambos os processos). As rotas integradas de limpeza de cache e último recarregamento também são expostas diretamente no gateway (porta 8000) em POST /api/v1/cache/flush-gateway-config e GET /api/v1/cache/last-reload, então a maioria dos operadores não precisa expor a porta 8001.

Montagens de Volume

• ~/.enkrypt/docker:/app/.enkrypt/docker - Local do arquivo de configuração (obrigatório)
• Montagens adicionais podem ser necessárias se seus servidores MCP exigirem acesso a arquivos locais

⚠️ Importante: Os clientes MCP (Claude Desktop, Cursor, Claude Code) iniciam o Docker diretamente sem um shell, então ~ (til) não será expandido. Sempre use caminhos absolutos nos arquivos JSON de configuração do seu cliente MCP (por exemplo, /Users/yourname/.enkrypt/docker:/app/.enkrypt/docker no macOS/Linux ou C:\\Users\\yourname\\.enkrypt\\docker:/app/.enkrypt/docker no Windows).

⚠️ Importante: Configurando Servidores MCP Quando o Gateway é Executado no Docker

Ao executar o Enkrypt Gateway no Docker, NÃO configure seus servidores MCP para também rodarem em modo Docker. Isso causa problemas de Docker-in-Docker, problemas de rede e complicações de montagem de volume.

❌ Evite (servidores MCP baseados em 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"
    }
  }
}

✅ Use em vez disso (servidores baseados em 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 requer modo privilegiado e montagem especial de socket
• O isolamento de rede impede que os contêineres se comuniquem corretamente
• As montagens de volume não funcionam como esperado através das fronteiras dos contêineres
• Sobrecarga de desempenho e preocupações de segurança
• Complexidade aumentada e dificuldade de depuração

Formatos recomendados de servidor MCP quando o Gateway está no Docker:

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

Exceção:

Se você absolutamente precisa usar servidores MCP baseados em Docker, considere:

1. Executar o gateway fora do Docker (instalação local), OU
2. Configurar o networking adequado do Docker com --network host ou redes bridge personalizadas, OU
3. Usar Docker-in-Docker com configuração adequada (requer o sinalizador --privileged e a montagem /var/run/docker.sock - não recomendado para produção)

4.4.1 Execute o Gateway em um servidor remoto

python gateway.py

• Ou execute em k8s usando nossa imagem docker enkryptai/secure-mcp-gateway:vx.x.x

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

• Use a versão mais recente do Docker Hub: https://hub.docker.com/r/enkryptai/secure-mcp-gateway/tags

• Você pode montar o arquivo de configuração localmente ou baixar o arquivo json de um local remoto como S3 usando um initContainer e montar o volume

• Veja docs/secure-mcp-gateway-manifest-example.yaml para a referência completa do arquivo de manifesto

4.4.2 Modifique o config do seu Cliente MCP para usar o Gateway

• Você pode encontrar o local do config do Claude Desktop nos locais abaixo no seu sistema. Para referência, veja a documentação do Claude.

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

• Você pode encontrar o local do config do Cursor nos locais abaixo. Para referência, veja a documentação do Cursor.

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

• Substitua as credenciais pelos valores do seu enkrypt_mcp_config.json. A forma das credenciais depende do plugins.auth.provider do seu gateway:

  • local_apikey (padrão) — cabeçalhos apikey + project_id + user_id, originados de apikeys.<key> e dos IDs de projeto/usuário correspondentes
  • nuvem enkrypt — um único cabeçalho apikey, originado de enkrypt_config.api_key. Adicione um cabeçalho X-Enkrypt-MCP-Gateway somente se o config do gateway deixar plugins.auth.config.gateway_name não definido — veja §7.1

• Substitua o http://0.0.0.0:8000/mcp/ pelo http(s)://<remote_server_ip>:<port>/mcp/

• Se você estiver executando isso localmente, pode usar http://0.0.0.0:8000/mcp/

• Você pode configurar o ingress para rotear o tráfego para o MCP Gateway via https

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

• NOTA: Certifique-se de que node e npm estão instalados na máquina cliente

  • Para verificar, execute node -v e npm -v

• NOTA: Certifique-se de usar a barra final / na URL do MCP, como /mcp/

Para Claude Desktop e Cursor — adicione o seguinte ao seu claude_desktop_config.json ou mcp.json.

local_apikey provedor (padrão) — três cabeçalhos:

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

enkrypt provedor de nuvem (gerado com --provider enkrypt) — cabeçalho único:

{
  "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 — roteando um processo de gateway para vários gateways de nuvem. Se o gateway estiver rodando sem plugins.auth.config.gateway_name, cada cliente também deve enviar X-Enkrypt-MCP-Gateway nomeando o saved_name do gateway de nuvem; o gateway o encaminha para a nuvem Enkrypt para escolher a configuração. Quando gateway_name está definido na configuração do gateway, esse valor vence e este cabeçalho é ignorado — veja §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"
      }
    }
  }
}

Os nomes das variáveis de ambiente aqui são arbitrários — mcp-remote apenas os substitui nos valores dos cabeçalhos. O gateway em si não lê nenhuma variável de ambiente para o nome do gateway, então esse roteamento funciona apenas no transporte streamable-HTTP.

Para Claude Code — use o 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 testes locais com HTTP (não HTTPS), adicione --allow-http se necessário, ou use http://0.0.0.0:8000/mcp/ como URL.

Esta seção explica como configurar e usar a stack de observabilidade incluída com o Enkrypt Secure MCP Gateway. Tudo é modelado como código em observability/: clone, copie .env.grafana.example, execute um docker compose -f docker-compose.grafana.yml, obtenha um dashboard funcional com alertas do Slack.

Dois backends, escolha um. O repositório traz duas stacks de observabilidade paralelas: a stack OpenSearch (primária; portas padrão OTel 4317/4318) e esta stack Grafana legada (4327/4328). Cada uma tem seus próprios arquivos compose + env (docker-compose.grafana.yml + .env.grafana vs docker-compose.opensearch.yml + .env.opensearch) e deve ser invocada com flags explícitas -f/--env-file. Veja observability/README.opensearch.md para o caminho OpenSearch; o restante desta seção cobre a stack Grafana.

Para o mergulho profundo — cada regra de alerta, dashboard e ponto de personalização — veja observability/README.md. Esta seção é o início rápido.

5.1 Arquitetura

┌─────────────────────┐   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 incluídos em observability/docker-compose.grafana.yml:

Nota sobre a porta do Grafana: o arquivo compose publica o Grafana na porta 3001 do host por padrão (o contêiner ainda escuta na 3000) para evitar conflito com um serviço Grafana nativo ou relay Docker WSL que frequentemente ocupa a 3000 no Windows. Defina GRAFANA_HOST_PORT=3030 (ou qualquer porta livre) em observability/.env.grafana para substituir.

5.2 Pré-requisitos

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

• Gateway instalado e em execução (siga a seção 4)

• (Opcional) Uma URL de webhook de entrada do Slack se você quiser que as regras de alerta incluídas publiquem no Slack

5.3 Passos de Configuração

1. Copie o modelo 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. Inicie a Stack de Observabilidade

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

   Isso inicia o OTel Collector, Prometheus, Loki, Jaeger, Promtail e Grafana — com todos os dashboards, regras de alerta e o ponto de contato do Slack pré-provisionados. A autenticação de administrador anônimo está habilitada por padrão (sem tela de login). Veja observability/README.md → Personalizando para definir uma senha de administrador real.

3. Para parar a Stack de Observabilidade

   docker compose down
   

5.4 Configuração

• Edite o arquivo enkrypt_mcp_config.json para habilitar a telemetria. O formato atual usa o bloco de plugin plugins.telemetry (provedor opentelemetry, o padrão emitido por secure-mcp-gateway generate-config):

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

5.5 Passos de Verificação

1. Verifique se os Serviços estão em Execução

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

2. Acesse as UIs dos Serviços

   • Grafana: http://localhost:3001 (admin anônimo habilitado por padrão — sem tela de login; substitua a porta do host via GRAFANA_HOST_PORT em observability/.env.grafana)

   • Jaeger: http://localhost:16686

   • Prometheus: http://localhost:9090

   • Loki: Acesse através do Grafana

     1. Abra o Grafana (http://localhost:3001)
     2. Vá para Explore (barra lateral esquerda)
     3. Selecione "Loki" no menu suspenso de fonte de dados

3. Verifique a Telemetria do Gateway

   • Faça requisições de teste através do Gateway, como List all servers and tools e echo test

   • Verifique traces no Jaeger:

     • Adicione tags opcionais como enkrypt_email=default@example.com ou enkrypt_project_name=default_project ou enkrypt_mcp_config_id=fcbd4508-1432-4f13-abb9-c495c946f638 para ver os traces de um usuário, projeto ou configuração MCP específicos, etc.

     • Também podemos combinar tags separando-as com espaços, como enkrypt_email=default@example.com enkrypt_project_name=default_project

     • Procure por spans enkrypt_discover_all_tools

     • Examine spans filhos para cache, descoberta de ferramentas, etc.

       

   • Verifique métricas no Grafana:

     • Navegue para Drilldown -> metrics

     • Podemos filtrar por vários rótulos como email, user_id, mcp_config_id, project_id, project_name etc.

       

   • Verifique logs no Grafana

     • Navegue para Drilldown -> Logs

     • Selecione o rótulo como service_name=secure-mcp-gateway e clique em Show logs

     • Agora podemos filtrar por vários rótulos como attributes_project_name, attributes_project_id, attributes_email, attributes_user_id, attributes_mcp_config_id, attributes_tool_name etc.

       

   • Verifique Dashboards no Grafana navegando para Dashboards -> OpenTelemetry Gateway Metrics

     • Devido a problemas no Grafana, talvez seja necessário editar cada tile e clicar em Run queries para ver os dados

5.6 Telemetria Disponível (Não exaustiva)

1. Traces

   • Pipeline de processamento de requisições
   • Invocações de ferramentas com rastreamento de duração
   • Operações de cache (acertos/erros)
   • Verificações de guardrails
   • Rastreamento de erros e monitoramento de status
   • Atributos detalhados para depuração

2. Métricas

   • enkrypt_list_all_servers_calls: uso de endpoints da API
   • mcp_cache_misses_total: rastreamento de eficiência do cache
   • enkrypt_servers_discovered: monitoramento de descoberta de servidores
   • mcp_tool_calls_total: rastreamento de invocação de ferramentas
   • mcp_tool_call_duration_seconds: monitoramento de desempenho (histograma)

3. Logs

   • Formato JSON estruturado para melhor consulta
   • Operações do gateway com contexto
   • Condições de erro com stack traces
   • Eventos de segurança e verificações de guardrails
   • Dados de desempenho com informações de tempo

O mapeamento completo de métrica → série Prometheus → regra de alerta está em docs/metric_reference.md, e as constantes de nomes de métrica/span/atributo estão em src/secure_mcp_gateway/plugins/telemetry/conventions.py.

5.7 Regras de Alerta Pré-Provisionadas (Slack)

A stack inclui 9 regras de alerta do Grafana conectadas a um ponto de contato do Slack — coloque sua URL de webhook em observability/.env.grafana (SLACK_WEBHOOK_URL=...) e você começará a receber alertas de guardrail/segurança/saúde imediatamente.

Regras de rajada usam sum by (server_name, tool_name) (ou user_id, failure_reason) para que cada infrator distinto produza uma mensagem separada no Slack em vez de um alerta agregado. Para ajustar limites, edite observability/grafana/provisioning/alerting/rules.yaml e docker compose restart grafana — as regras são recarregadas do disco a cada início. Veja observability/README.md → Personalizando para adicionar novas regras ou trocar o Slack por PagerDuty / Opsgenie / webhook genérico / e-mail.

6.1 Verifique o Claude Desktop

• Para verificar a instalação do Claude, navegue até o arquivo claude_desktop_config.json seguindo estas instruções

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

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

6.2 Exemplo de arquivo de configuração MCP gerado

Os exemplos abaixo usam o formato provedor local_apikey (padrão). Se você gerou com --provider enkrypt, o bloco env tem uma única entrada ENKRYPT_APIKEY em vez disso — veja §4.1.5 para a variante enkrypt cloud.

6.3 Reinicie o Claude Desktop para executar o Gateway

• Após reiniciar, navegue até o Claude Desktop Settings

  

• Clique em Developer -> Enkrypt Secure MCP Gateway

  

6.4 Exemplos de prompts

• list all servers, get all tools available and echo test
  • Isso usa um servidor MCP de teste echo_server que está em bad_mcps/echo_mcp.py

6.5 Exemplo de arquivo de configuração gerado

• Exemplo enkrypt_mcp_config.json gerado pelo script setup em ~/.enkrypt/enkrypt_mcp_config.json no macOS e %USERPROFILE%\.enkrypt\enkrypt_mcp_config.json no Windows

• Se você executou o comando docker para instalar o Gateway, o arquivo de configuração estará em ~/.enkrypt/docker/enkrypt_mcp_config.json no macOS e %USERPROFILE%\.enkrypt\docker\enkrypt_mcp_config.json no 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

• Você pode ver o servidor MCP na lista de servidores MCP no Cursor navegando até ~/.cursor/mcp.json e também clicando no ícone de configurações no canto superior direito e depois clicando em Tools & Integrations ou na aba MCP

• Geralmente não é necessário reiniciar, mas se estiver em estado de carregamento por muito tempo, reinicie o Cursor

  

• Agora você pode conversar com o servidor MCP.

  • Exemplos de prompts:

    • (Clique em Run Tool quando o Cursor solicitar)

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

      • Isso usa um servidor MCP de teste echo_server que está em bad_mcps/echo_mcp.py

    

6.7 Verificar Claude Code

• Execute claude mcp list para ver o gateway na lista de servidores MCP configurados

• Inicie o Claude Code e execute /mcp para verificar o status do servidor

• Tente list all servers, get all tools available and echo test como um prompt para verificar se o gateway está funcionando

• Importante:

  • Com o hot-reload (veja a Seção 7.0), reiniciar o cliente MCP não é mais necessário para a maioria das edições de configuração. A reinicialização só é necessária para as três configurações listadas na tabela acima.

  • Para tornar todas as novas ferramentas acessíveis, use o prompt "list all servers, get all tools available" para o Cliente MCP descobrir todas as novas ferramentas. Depois disso, o Cliente MCP deve ser capaz de usar todas as ferramentas dos servidores configurados no arquivo de configuração do Gateway

• Você pode adicionar muitos servidores MCP dentro do array mcp_config desta configuração do gateway

  • Você pode ver aqui exemplos de servidores

  • Você também pode experimentar o Enkrypt MCP Server

  • Exemplo:

    {
      "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 Chaves 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 e base_url são preenchidos a partir do bloco centralizado de nível raiz enkrypt_config quando ausentes aqui, então a maioria das configurações define apenas gateway_name (e opcionalmente gateway_version / cache_ttl_seconds) sob plugins.auth.config.

⚠️ Chaves removidas falham na inicialização. O provedor pré-2.2 aceitava api_key, use_remote_config e timeout sob plugins.auth.config. Elas agora geram um ValueError na inicialização em vez de serem silenciosamente ignoradas — use apikey / gateway_name / gateway_version / project_name / base_url em vez disso, e defina o timeout de autenticação via common_mcp_gateway_config.timeout_settings.auth_timeout.

7.1.2 Cabeçalhos que seu cliente MCP envia ao gateway

Se nem a configuração nem o cabeçalho fornecerem um nome de gateway, a autenticação falha com Missing X-Enkrypt-MCP-Gateway header and no gateway_name in auth.config.

project_name não tem equivalente por solicitação — vem apenas da configuração.

⚠️ Não envie ENKRYPT_GATEWAY_KEY no modo nuvem. Para compatibilidade retroativa, o gateway prefere um cabeçalho ENKRYPT_GATEWAY_KEY em vez de apikey quando ambos estão presentes, e então o encaminha para a nuvem. Um ENKRYPT_GATEWAY_KEY residual de uma configuração antiga de cliente local_apikey irá, portanto, sobrescrever sua chave de API correta da nuvem e produzir erros 401. Envie apenas os cabeçalhos que seu provedor ativo precisa (veja a tabela de cabeçalhos por provedor em docs/auth-providers.md).

Nota sobre instalações stdio. Cabeçalhos existem apenas no transporte streamable-HTTP. Quando o cliente MCP inicia o gateway via stdio, as credenciais vêm de variáveis de ambiente (ENKRYPT_APIKEY para o provedor de nuvem) e não há equivalente de variável de ambiente para o nome ou versão do gateway — portanto, implantações stdio devem definir plugins.auth.config.gateway_name (e gateway_version, se o gateway não for v1) no arquivo de configuração.

7.1.3 Cabeçalhos que o gateway envia para a nuvem Enkrypt

GET {base_url}/mcp-gateway/get-gateway-config é chamado com:

Cada chamada é registrada com a chave de API mascarada, para que você possa confirmar qual gateway/projeto/chave uma solicitação realmente usou:

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

Compare os últimos 4 caracteres com a chave que você espera — uma incompatibilidade significa que o cliente está enviando o cabeçalho errado.

7.1.4 Um processo de gateway, vários gateways na nuvem

Como gateway_name pode chegar por solicitação, uma única implantação de gateway pode atender a mais de uma configuração de gateway na nuvem: deixe plugins.auth.config.gateway_name não definido e faça cada cliente MCP enviar seu próprio cabeçalho X-Enkrypt-MCP-Gateway junto com seu apikey. Clientes cujo gateway está registrado sob uma versão diferente de v1 enviam X-Enkrypt-MCP-Gateway-Version junto. As respostas da nuvem são armazenadas em cache em processo sob um hash SHA-256 de apikey | gateway_name | gateway_version | project_name, então locatários — e duas versões do mesmo gateway — nunca contaminam a configuração uns dos outros. Veja §4.4.2 para o JSON do lado do cliente.

Observe a compensação: project_name permanece em todo o processo, então todos os clientes nesse processo o compartilham. Fixe gateway_name (e gateway_version) na configuração em vez disso sempre que uma implantação atender exatamente um gateway na nuvem — é o padrão mais seguro, pois o gateway efetivo é então fixado no lado do servidor e cabeçalhos fornecidos pelo cliente não podem mais direcioná-lo. (A nuvem Enkrypt ainda autoriza cada chave de API contra o gateway que ela nomeia, então o cabeçalho não é uma bypass de autorização de qualquer forma.)

7.1.5 Tratamento de falhas

Erros de transporte na nuvem, respostas 5xx e corpos não-JSON falham a solicitação de forma definitiva (AuthStatus.ERROR com a mensagem upstream anexada) — não há fallback de arquivo local nem serviço de cache obsoleto. Observe o contador enkrypt.auth.failure (atributos provider / failure_reason) e as linhas de log [EnkryptAuthProvider] fetching gateway config: ... para alertar sobre interrupções upstream.

Referência completa do provedor — mapeamento de resposta da nuvem, precedência de substituição, local_server_overrides e invalidação de cache — está em docs/auth-providers.md.

Esta seção orienta você no gerenciamento do gateway inteiramente via CLI — desde a configuração inicial até adicionar servidores, gerenciar projetos e operações do dia a dia.

Dica: Todos os comandos abaixo mostram a versão local (pip). Para Docker, basta adicionar --docker a qualquer comando — consulte o padrão de comando Docker no final desta seção.

Para a referência completa da CLI, consulte CLI-Commands-Reference.md.

Etapa 1: Gere sua configuração

Se ainda não fez isso, gere o arquivo de configuração padrão. Isso cria tudo o que você precisa para começar — uma configuração com um servidor echo de exemplo, um projeto padrão, usuário e chave 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

O que isso cria:

Agora que sua configuração está pronta, o próximo passo é informar ao seu cliente MCP (Claude Desktop, Cursor ou Claude Code) sobre o gateway. Esta é uma configuração única — o comando de instalação grava os detalhes de conexão no arquivo de configuração do seu cliente para que ele saiba como se comunicar com o gateway.

Etapa 2: Instale o gateway para o seu cliente MCP

Escolha o cliente que você usa e execute o comando correspondente:

# 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

O que isso faz nos bastidores: o comando de instalação lê as credenciais de autenticação da sua configuração gerada e as grava no arquivo de configuração do seu cliente MCP. As chaves exatas de env dependem do plugins.auth.provider do seu gateway:

• local_apikey (padrão) — a instalação lê apikeys.<key> mais os IDs de projeto/usuário correspondentes e grava ENKRYPT_GATEWAY_KEY + ENKRYPT_PROJECT_ID + ENKRYPT_USER_ID
• enkrypt cloud (quando gerado com --provider enkrypt) — a instalação lê enkrypt_config.api_key e grava um único ENKRYPT_APIKEY

Para Cursor e Claude Desktop, você verá uma saída como:

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

E o arquivo de configuração do seu cliente (por exemplo, ~/.cursor/mcp.json ou ~/Library/Application Support/Claude/claude_desktop_config.json) agora conterá uma destas duas formas.

Provedor local_apikey (padrão):

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

Provedor cloud enkrypt (gerado com --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, o comando de instalação executa claude mcp add nos bastidores e você verá:

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

Quando a instalação terminar, reinicie seu cliente MCP para que ele reconheça a nova configuração. Após a reinicialização, o gateway aparecerá como um servidor MCP conectado e você estará pronto para começar.

Neste ponto, sua configuração se parece com isto:

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

Você tem um projeto (default_project) que aponta para uma configuração (default_config), e essa configuração tem um servidor (echo_server). Um usuário padrão e uma chave de API do gateway também foram criados para que tudo funcione imediatamente.

Etapa 3: Verifique o que você tem

Você pode verificar esta configuração a qualquer 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"

O que você pode fazer a partir daqui?

Você tem três caminhos, dependendo do que precisa. Escolha o que se encaixa e siga os passos abaixo dele.

Regra prática: Se você apenas adicionar ou remover servidores dentro da sua configuração atual, basta reiniciar seu cliente MCP. Se você mudar para uma configuração diferente ou criar um novo projeto, precisará 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

Etapa 4: Defina sua chave de API Enkrypt (para guardrails)

Se você quiser usar os guardrails da Enkrypt AI (proteção de entrada/saída, redação de PII, filtragem de toxicidade, etc.), você precisa definir sua chave de API Enkrypt. Você pode obter uma no painel da 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

Sem esta chave, os recursos de guardrails não funcionarão — mas o gateway em si ainda roteará as ferramentas normalmente.

Etapa 5: Ative ou desative a telemetria

O gateway vem com suporte a OpenTelemetry para logging, tracing e métricas. Por padrão, está habilitado, mas será ignorado silenciosamente se o endpoint do coletor não estiver acessível. Você pode habilitá-lo ou desabilitá-lo explicitamente:

# 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 a pilha de telemetria: O gateway envia dados de telemetria para um coletor OpenTelemetry — ele não executa um por conta própria. O repositório inclui dois backends prontos em observability/: a pilha OpenSearch (principal, portas OTel padrão 4317/4318 — consulte observability/README.opensearch.md) e a pilha legada Grafana (coletor, Prometheus, Grafana, Jaeger, Loki + 9 regras de alerta do Slack, em 4327/4328). Execute um deles. Para a pilha 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

Quando a pilha estiver em execução, o gateway começará automaticamente a enviar traces, logs e métricas para o coletor. Consulte §5 para detalhes completos e observability/README.md para um mergulho profundo na personalização de alertas.

Etapa 6: Operações do 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

Padrão de comando Docker

Adicione --docker a qualquer comando da CLI para executá-lo automaticamente dentro do contêiner Docker. A flag detecta automaticamente seu sistema operacional, define HOST_OS e HOST_ENKRYPT_HOME e monta o volume ~/.enkrypt/docker — sem necessidade de longas invocações 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>

A tag da imagem é fixada na versão da CLI do seu host

A partir da v2.2.0, o wrapper usa por padrão enkryptai/secure-mcp-gateway:<your-host-CLI-version> (por exemplo, enkryptai/secure-mcp-gateway:2.2.0) em vez de :latest. Isso evita bugs de incompatibilidade de flags, onde uma CLI de host mais nova passa flags que a CLI mais antiga no contêiner não reconhece — por exemplo,

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

(generate-config --provider enkrypt foi adicionado na v2.2.0; se sua CLI de host for v2.2.0, mas o contêiner for v2.1.6, essa flag desaparece silenciosamente no trânsito.)

Se --docker-image for substituído e a substituição não contiver a string de versão da CLI do host, o wrapper registrará uma linha de WARN: para que a causa de qualquer erro de "argumentos não reconhecidos" seja óbvia.

Se sua tag padrão ainda não estiver no Docker Hub (típico logo após uma atualização do pip no host, antes que a imagem correspondente seja publicada), o Docker sairá com 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.

Você tem três soluções alternativas:

Exemplos:

# 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 usuários de Docker:

Se você estiver executando o Enkrypt Gateway no Docker, use a versão npx do GitHub MCP server em vez da versão Docker mostrada abaixo. Consulte o exemplo de configuração baseado em npx no final desta seção.

Para detalhes sobre o porquê, consulte Seção 4.3.7: Configurando MCP Servers Quando o Gateway é Executado no Docker.

• GitHub MCP Server pode ser executado com docker ou npx. A versão Docker requer que o Docker esteja instalado e em execução na sua máquina.

  • Você pode baixar o docker desktop daqui. Instale e execute-o se ainda não o tiver.

• Crie um personal access token no GitHub

  • Crie um token que tenha acesso apenas a repositórios públicos e defina uma expiração muito baixa inicialmente para testes

  • Adicione o bloco do servidor GitHub abaixo em enkrypt_mcp_config.json dentro do array "mcp_config": []. Ele já deve ter a configuração do servidor echo.

  • NOTA: Não se esqueça de adicionar a vírgula , após o bloco do servidor echo

  • Substitua REPLACE_WITH_YOUR_PERSONAL_ACCESS_TOKEN pelo personal access token que você criou

  • Você também pode adicionar via CLI. Consulte CLI-Commands-Reference.md, seção 2. CONFIGURATION MANAGEMENT, para detalhes

  • Exemplo:

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

• Agora reinicie o Claude Desktop para que ele detecte o novo servidor

• Em seguida, execute o prompt list all servers, get all tools available para que ele descubra o servidor github e todas as suas ferramentas disponíveis

  

• Agora execute List all files from https://github.com/enkryptai/enkryptai-mcp-server

  

• Ótimo! 🎉 Adicionamos com sucesso um GitHub MCP Server ao Gateway. No entanto, ele está completamente desprotegido e aberto a todos os tipos de abuso e ataques.

• Agora, digamos que um prompt como este seja executado Ask github for the repo "hello; ls -la; whoami"

  

• Isso pode não ter causado danos reais, mas imagine um prompt mais complexo que poderia ter causado danos reais ao sistema.

• Para proteger o MCP server, podemos usar Enkrypt Guardrails como mostrado na próxima seção.

Configuração do GitHub Server (versão npx)

✅ Recomendado para implantações do Gateway em Docker

Se você está executando o Enkrypt Gateway no Docker ou prefere não usar Docker-in-Docker, use o servidor MCP do GitHub baseado em npx:

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

Benefícios da versão npx:

• ✅ Sem complicações de Docker-in-Docker
• ✅ Tempo de inicialização mais rápido
• ✅ Funciona perfeitamente com gateway dockerizado
• ✅ Gerenciamento de rede e volumes mais simples
• ✅ Menor consumo de recursos

Pré-requisitos:

• Node.js e npm devem estar instalados no contêiner do gateway ou na máquina host
• O Dockerfile padrão já inclui Node.js 22.x LTS

Muitos servidores MCP exigem autenticação OAuth para acessar recursos protegidos. O Secure MCP Gateway suporta OAuth 2.0/2.1 com fluxos de Client Credentials e Authorization Code + PKCE para integração perfeita com servidores habilitados para OAuth.

Visão Geral

O Gateway gerencia a obtenção, o cache e a renovação automática de tokens OAuth, para que você não precise gerenciar tokens manualmente. Os tokens são injetados automaticamente nas requisições ao conectar-se a servidores MCP remotos.

Tipos de Concessão Suportados:

• Client Credentials - Para autenticação servidor-a-servidor (máquina-a-máquina)
• Authorization Code + PKCE - Para fluxos de autorização de usuário com segurança aprimorada

Principais Recursos:

• Autorização automática do navegador para o fluxo Authorization Code
• Suporte a URLs de callback locais e remotas
• Renovação automática de tokens antes da expiração
• Cache seguro de tokens
• PKCE (S256) para segurança aprimorada
• Parâmetro de estado para proteção contra CSRF

Exemplos de Configuração OAuth

Fluxo Client Credentials (Servidor-a-Servidor)

Para autenticação máquina-a-máquina, use o fluxo 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
  }
}

Principais Campos OAuth

Configuração Principal

Parâmetros OAuth Opcionais

Configurações de Segurança e Autenticação

Configuração de Mutual TLS (mTLS)

Revogação de Token

Fluxo Authorization Code + PKCE

Para autorização de usuário com segurança aprimorada, use o fluxo Authorization Code com 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}
}

Autorização Automática do Navegador

Ao usar o fluxo Authorization Code, o gateway automaticamente:

1. Abre seu navegador na URL de autorização
2. Gerencia o callback (localhost ou remoto)
3. Troca o código de autorização por tokens
4. Armazena tokens em cache para uso futuro

Opções de Fluxo:

Callback Localhost (Automático):

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

• O Gateway inicia um servidor local na porta 8080
• Captura automaticamente o código de autorização
• Nenhuma intervenção manual necessária

Callback Remoto (Entrada Manual de Código):

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

• O Gateway abre o navegador para autorização
• O usuário conclui a autorização na página remota
• O usuário copia o código da página de callback
• O usuário cola o código no terminal
• O Gateway troca o código pelo token

Configurando Callback Remoto

Se você quiser usar uma URL de callback remota (experiência profissional e personalizada):

1. Hospede a página de callback:

   # 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. Atualize sua configuração:

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

3. Registre-se no provedor OAuth:

   • Adicione a URL de callback às configurações do seu aplicativo OAuth
   • Auth0: "Allowed Callback URLs"
   • Okta: "Sign-in redirect URIs"
   • Azure AD: "Redirect URIs"
   • Google: "Authorized redirect URIs"

Testando com o Servidor Echo OAuth

O Gateway inclui um servidor echo de teste que demonstra a injeção de cabeçalhos OAuth. Você pode usá-lo para verificar se o OAuth está funcionando corretamente.

Passo 1: Inicie o Servidor Echo OAuth

O servidor echo OAuth precisa ser executado em modo HTTP para aceitar conexões 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 (Prompt de Comando):

# Set the environment variable
set MCP_HTTP_MODE=true

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

O servidor iniciará em http://localhost:8001/mcp/ e imprimirá cabeçalhos relacionados ao OAuth sempre que ferramentas forem chamadas.

Passo 2: Adicione o Servidor Echo OAuth à Configuração do Gateway

Adicione esta configuração ao seu enkrypt_mcp_config.json no 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 é definido apenas para testes locais. Sempre use HTTPS em produção!

Passo 3: Teste a Injeção de Token OAuth

1. Reinicie o Claude Desktop (ou seu cliente MCP) para carregar a nova configuração do servidor

2. Use o prompt: list all servers and discover tools from echo_oauth_server

3. Chame a ferramenta echo: call the echo tool from echo_oauth_server with message "test oauth"

4. Verifique a saída do terminal do servidor echo - você deve ver os cabeçalhos OAuth sendo impressos:

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

Isso confirma que o token OAuth está sendo adquirido e injetado automaticamente no cabeçalho Authorization.

Fluxos de Token OAuth

Fluxo Client Credentials

1. Primeira Requisição: O Gateway adquire o token do provedor OAuth
2. Cache: O token é armazenado em cache com rastreamento de expiração
3. Injeção de Token:
   • Servidores remotos: Token adicionado como cabeçalho Authorization: Bearer <token>
   • Servidores locais: Token disponível em variáveis de ambiente
4. Renovação automática: Token renovado 5 minutos antes da expiração (configurável)

Fluxo Authorization Code + PKCE

1. Configuração Inicial: O Gateway gera o verificador e o desafio de código PKCE
2. Autorização no Navegador:
   • O Gateway abre o navegador na URL de autorização
   • O usuário faz login e autoriza o aplicativo
3. Tratamento do Callback:
   • Localhost: O Gateway captura automaticamente o código do callback
   • Remoto: O usuário copia o código e cola no terminal
4. Troca de Token: O Gateway troca o código de autorização por tokens
5. Cache e Renovação: Tokens armazenados em cache e renovados automaticamente antes da expiração

Recursos Avançados

• Authorization Code + PKCE: Autorização de usuário com segurança aprimorada (S256)
• Fluxo Automático do Navegador: Abre o navegador e gerencia o callback automaticamente
• Suporte a Callback Remoto: Hospede a página de callback no seu domínio
• Mutual TLS (mTLS): Segurança aprimorada com certificados de cliente (RFC 8705)
• Revogação de Token: Revogue tokens programaticamente (RFC 7009)
• Validação de Escopos: Verifica se o token retornado possui os escopos solicitados
• Cabeçalhos Personalizados: Adicione cabeçalhos HTTP personalizados às requisições de token
• Parâmetro de Estado: Proteção contra CSRF para o fluxo Authorization Code
• Métricas: Acompanhe sucesso/falha na aquisição de tokens, taxa de acerto do cache

Solução de Problemas

Falha na requisição de token OAuth:

• Verifique se CLIENT_ID e CLIENT_SECRET estão corretos
• Verifique se TOKEN_URL está acessível
• Garanta que HTTPS seja usado (ou defina OAUTH_ENFORCE_HTTPS: false para testes)

Token não aparecendo nas requisições:

• Confirme is_remote: true para servidores remotos
• Verifique os logs do servidor para mensagens de aquisição OAuth
• Habilite o log de depuração: "enkrypt_log_level": "DEBUG"

Problemas no fluxo Authorization Code:

• Verifique se AUTHORIZATION_URL e REDIRECT_URI estão corretos
• Garanta que a URL de callback esteja registrada no provedor OAuth
• Verifique se o navegador abre automaticamente (ou use a URL manual)
• Para callbacks remotos, verifique se a página de callback está acessível

Callback não funcionando:

• Localhost: O Gateway tenta automaticamente a próxima porta disponível se a 8080 estiver em uso (até 10 portas)
• Remoto: Verifique se a URL de callback está acessível e corresponde às configurações do provedor OAuth
• Verifique se o firewall não está bloqueando o callback

Servidor echo não recebendo cabeçalhos:

• Garanta que a variável de ambiente MCP_HTTP_MODE=true esteja definida
• Verifique se o servidor está rodando em http://localhost:8001/mcp/

• Descobrimos que a melhor maneira de usar os Guardrails da Enkrypt no MCP Gateway é ter um guardrail separado para cada servidor. Dessa forma, podemos ter um guardrail ajustado para cada servidor.

• Como cada Servidor MCP é muito diferente dos demais, não é possível ter um único guardrail que funcione para todos os servidores.

• Alguns podem precisar de Toxicity Detector, outros de NSFW Detector, outros de Injection Attack Detector, outros de Keyword Detector, outros de Policy Violation, alguns podem precisar do detector Relevancy, outros do detector Adherence, etc.

• Alguns podem precisar de uma combinação desses detectores trabalhando juntos para bloquear solicitações maliciosas.

• Alguns podem precisar de Guardrails no lado de entrada, outros no lado de saída, e alguns podem precisar de ambos aplicados.

• Consulte nossa documentação para detalhes sobre vários detectores disponíveis.

• Portanto, tenha guardrails separados para cada servidor e experimente a melhor combinação de detectores e bloqueios para cada servidor que bloqueie solicitações maliciosas, mas permita que solicitações legítimas passem.

• Experimente nosso detector Policy Violation com sua própria política personalizada que detalha o que é permitido e o que não é. Esta pode ser a melhor abordagem para o seu caso de uso.

11.1 Configuração de Guardrail por Servidor

Você pode controlar o comportamento dos guardrails para cada servidor individualmente usando sinalizadores por servidor na sua configuração.

Observação: Este campo tem como padrão false; quando ausente de common_overrides, tanto o registro de ferramentas quanto a validação de informações do servidor são ignorados.

server_tools_guardrails_config (objeto, padrão: {"enabled": false})

Uma configuração unificada originada exclusivamente de common_overrides (em todo o gateway). Ela controla tanto a validação da descrição do servidor quanto a validação do registro de ferramentas por meio de um único sinalizador enabled, guardrail_name e da lista block.

Formato:

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

Quando enabled: true, tanto a validação da descrição do servidor quanto as verificações de guardrail do registro de ferramentas são executadas usando esta política. Quando enabled: false ou ausente, ambas são ignoradas.

Quando desabilitar:

• Ambientes de teste/desenvolvimento com servidores conhecidos e seguros
• Servidores internos onde o conteúdo é totalmente confiável
• Quando os metadados do servidor contêm termos técnicos que geram falsos positivos

Níveis de Guardrail:

O gateway possui dois níveis distintos de guardrails:

1. Validação de Registro de Servidor e Ferramentas (server_tools_guardrails_config)

   • Quando: Durante a descoberta de servidores e ferramentas
   • O quê: Valida descrições de servidores, descrições de ferramentas e esquemas para conteúdo prejudicial
   • Bloqueia: Servidores ou ferramentas com metadados maliciosos

2. Guardrails em Tempo de Execução (input_guardrails_config / output_guardrails_config)

   • Quando: Durante a execução de ferramentas (entrada antes, saída depois)
   • O quê: Valida argumentos e respostas de ferramentas
   • Bloqueia: Solicitações/respostas que violam políticas

Observação: Todos os três níveis são independentes e podem ser configurados separadamente por servidor.

O Gateway fornece um servidor de API REST para operações administrativas, como gerenciamento de usuários, projetos, configurações e chaves de API.

Iniciando o Servidor de API REST

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

• Documentação da API: Disponível em http://localhost:8001/docs (Interface Swagger)
• Verificação de Integridade: http://localhost:8001/health
• Esquema OpenAPI: Carregado de openapi.json na raiz do projeto

Autenticação com Chave de API de Administrador

Importante: Operações administrativas exigem uma admin_apikey especial na raiz da configuração, separada das chaves de API regulares de usuários. Isso fornece segurança aprimorada para operações administrativas.

Comportamento dependente do provedor (a política de resolução está em src/secure_mcp_gateway/auth_policy.py):

O local aninhado pré-2.2 enkrypt_config.admin_apikey ainda é honrado como um fallback obsoleto para que as configurações existentes continuem funcionando sem edições.

Obtendo sua Chave de API de Administrador

A admin_apikey é gerada automaticamente na raiz da configuração quando você executa secure-mcp-gateway generate-config (a variante padrão do provedor local_apikey). Encontre-a no seu arquivo de configuração:

• 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": { ... }
  },
  ...
}

Observação: Se você usou --provider enkrypt para gerar a configuração, não verá uma admin_apikey — a enkrypt_config.api_key da nuvem é usada como credencial de administrador por padrão. Adicione admin_apikey na raiz somente se quiser um segredo de administrador separado.

Principais Diferenças

• admin_apikey (nível raiz): Usada para todas as operações administrativas (gerenciamento de usuários, gerenciamento de projetos, etc.)

  • String aleatória de 256 caracteres para máxima segurança
  • Gerada durante secure-mcp-gateway generate-config (somente quando --provider local_apikey, que é o padrão)
  • Necessária para endpoints da API REST quando o provedor de autenticação é local_apikey. Opcional com o provedor enkrypt.

• apikeys (na seção apikeys): Usada para acesso ao gateway por usuários

  • Usada por clientes MCP para se conectar ao gateway
  • Associada a usuários e projetos específicos
  • Não usada para operações administrativas

Usando a Chave de API de Administrador

Inclua a admin_apikey no cabeçalho de Autorização para todas as chamadas administrativas da API:

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

Observação de Segurança:

• Mantenha sua chave de API de administrador segura e nunca a envie para o controle de versão
• Compartilhe a chave de API de administrador apenas com administradores autorizados
• Usuários regulares nunca devem ter acesso à chave de API de administrador

Operações Administrativas Disponíveis

A API REST fornece endpoints para:

1. Gerenciamento de Usuários: Criar, listar, atualizar e excluir usuários
2. Gerenciamento de Projetos: Criar projetos, atribuir configurações, gerenciar usuários
3. Gerenciamento de Chaves de API: Gerar, rotacionar, desabilitar/habilitar e excluir chaves de API
4. Gerenciamento de Configurações: Criar, atualizar e gerenciar configurações e servidores MCP

Para documentação completa da API e exemplos, consulte:

• API-Reference.md
• Documentação interativa da API em http://localhost:8001/docs

1. Gateway Local, Guardrails Locais e Servidor MCP Local

2. Gateway Local, Servidor MCP Local com Guardrails Remotos

3. Gateway Local com Servidor MCP Remoto e Guardrails Remotos

4. Gateway Remoto, Servidor MCP Remoto e Guardrails Remotos

14.1 Gateway Local, Guardrails Locais e Servidor MCP Local

14.2 Gateway Local, Servidor MCP Local com Guardrails Remotos

14.3 Gateway Local com Servidor MCP Remoto e Guardrails Remotos

14.4 Gateway Remoto, Servidor MCP Remoto e Guardrails Remotos

• Para remover o Gateway de qualquer cliente MCP, basta remover o bloco do servidor MCP "Enkrypt Secure MCP Gateway": {...} do arquivo de configuração do cliente. Para Claude Code, execute claude mcp remove Enkrypt-Secure-MCP-Gateway.

  • Reinicie o cliente MCP para aplicar as alterações em alguns clientes, como Claude Desktop. O Cursor não requer reinicialização.

• Para desinstalar o pacote pip, execute o seguinte comando:

  pip uninstall secure-mcp-gateway
  

• Se alguma chamada falhar no cliente, consulte os logs do MCP do respectivo cliente

  • Veja isto para a localização dos logs do Claude

    • Exemplo 🍎 Caminho do log Linux/macOS: ~/Library/Logs/Claude/mcp-server-Enkrypt Secure MCP Gateway.log
    • Exemplo 🪟 Caminho do log Windows: %USERPROFILE%\AppData\Roaming\Claude\logs\mcp-server-Enkrypt Secure MCP Gateway.log

  • Veja esta discussão para logs do Cursor

• Se você vir erros como Exception: unhandled errors in a TaskGroup (1 sub-exception), talvez o servidor MCP que o gateway está tentando usar não esteja em execução.

  • Portanto, certifique-se de que o arquivo que ele está tentando acessar esteja disponível
  • Quaisquer pré-requisitos para o servidor MCP ser executado sejam atendidos, como docker em execução, etc.

• Se precisarmos de logs mais detalhados, defina o enkrypt_log_level para debug no arquivo enkrypt_mcp_config.json e reinicie o cliente MCP.

16.1 Solução de problemas do OpenTelemetry

1. Erros de handshake SSL

   Se você vir erros SSL como:

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

   Solução: Adicione insecure=True à configuração do exportador OTLP em telemetry.py

2. Sem logs no Loki

   • Verifique se o coletor OTLP está em execução:

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

   • Verifique a configuração do coletor em otel_collector/otel-collector-config.yaml

   • Verifique se o Loki está recebendo dados:

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

3. Métricas ausentes

   • Verifique o pipeline de métricas do coletor OTLP:

     curl http://localhost:8888/metrics
     

   • Verifique as métricas nos logs do coletor:

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

4. Problemas com 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>
   

O gateway inclui uma suíte de testes abrangente que valida todas as funcionalidades principais, incluindo descoberta de servidores, execução de ferramentas, guardrails, cache, telemetria e muito mais.

Pré-requisitos

• Gateway instalado localmente (siga a Instalação Local)
• Ambiente virtual ativado
• Servidor MCP Echo OAuth em execução (para testar cenários de servidor remoto)

Executando a Suíte de Testes

Etapa 1: Definir Variável de Ambiente

Windows PowerShell:

$env:MCP_HTTP_MODE="true"

Prompt de Comando do Windows:

set MCP_HTTP_MODE=true

macOS/Linux:

export MCP_HTTP_MODE="true"

Esta variável de ambiente permite que o servidor Echo OAuth seja executado em modo HTTP para testes.

Etapa 2: Iniciar o Servidor Echo OAuth

Navegue até o diretório do servidor echo e inicie-o:

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

O servidor iniciará em http://localhost:8001/mcp/ e permanecerá em execução. Mantenha este terminal aberto.

Etapa 3: Executar a Suíte de Testes

Abra um novo terminal, ative seu ambiente virtual e execute os testes:

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 Testes

A suíte de testes inclui:

• Testes de Descoberta de Servidores: Listar servidores, obter informações do servidor, descobrir ferramentas
• Testes de Execução de Ferramentas: Chamar ferramentas, múltiplas chamadas de ferramentas, tratamento de erros
• Testes de Cache: Status do cache, limpeza do cache, expiração do cache
• Testes de Guardrails: Guardrails de entrada/saída, guardrails assíncronos, redação de PII
• Testes de Telemetria: Integração OpenTelemetry, métricas, rastreamentos, logs
• Testes de Configuração: Configurações de tempo limite, níveis de log, cache externo
• Testes de Integração: Fluxos de trabalho completos, recuperação de erros, desempenho

Saída Esperada

O executor de testes exibirá:

• Progresso para cada teste
• Status de sucesso/falha
• Duração da execução
• Resumo final com contagens de aprovação/reprovação

Exemplo de saída:

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

Solução de Problemas nos Testes

Erros de conexão do servidor Echo:

• Verifique se o servidor Echo OAuth está em execução na porta 8001
• Verifique se a variável de ambiente MCP_HTTP_MODE está definida
• Certifique-se de que nenhum outro serviço esteja usando a porta 8001

Erros de configuração do Gateway:

• Verifique se enkrypt_mcp_config.json existe no diretório ~/.enkrypt/
• Verifique se o arquivo de configuração possui chaves de gateway válidas e configurações de servidor
• Certifique-se de que o ambiente virtual tenha todas as dependências instaladas

Falhas nos testes:

• Habilite o log de depuração definindo enkrypt_log_level: "DEBUG" na configuração
• Verifique os logs do cliente MCP para mensagens de erro detalhadas
• Verifique se todos os pré-requisitos estão instalados (Python 3.11+, pip, uv)