Adding MCP Servers - Secure MCP Gateway

Overview

Secure MCP Gateway allows you to add multiple MCP servers to your configuration and access them through a unified interface. This guide covers everything from basic server addition to advanced configurations with OAuth, environment variables, and tools.

Prerequisites

Gateway installed and configured
MCP server details (command, arguments, dependencies)
For remote servers: Server URL and authentication credentials
For OAuth servers: OAuth client credentials

Adding Your First Server

Using the CLI

The simplest way to add a server is using the config add-server command:

secure-mcp-gateway config add-server \
  --config-name "default_config" \
  --server-name "my-server" \
  --server-command "python" \
  --args="server.py" \
  --description "My first MCP server"

Using JSON Configuration

You can also manually edit the configuration file at ~/.enkrypt/enkrypt_mcp_config.json:

{
  "mcp_configs": {
    "config-id": {
      "mcp_config": [
        {
          "server_name": "my-server",
          "description": "My first MCP server",
          "config": {
            "command": "python",
            "args": ["server.py"]
          },
          "tools": {},
          "input_guardrails_policy": {
            "enabled": false
          },
          "output_guardrails_policy": {
            "enabled": false
          }
        }
      ]
    }
  }
}

Common MCP Servers

GitHub MCP Server

Add the official GitHub MCP server with NPX:

secure-mcp-gateway config add-server \
  --config-name "production-config" \
  --server-name "github" \
  --server-command "npx" \
  --args="-y,@modelcontextprotocol/server-github" \
  --env '{"GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_your_token_here"}' \
  --description "GitHub MCP Server"

Multiple arguments are passed as comma-separated values in --args. The = sign is required when args start with -.

Filesystem MCP Server

secure-mcp-gateway config add-server \
  --config-name "default_config" \
  --server-name "filesystem" \
  --server-command "npx" \
  --args="-y,@modelcontextprotocol/server-filesystem,/path/to/allowed/directory" \
  --description "Filesystem access server"

Brave Search MCP Server

secure-mcp-gateway config add-server \
  --config-name "default_config" \
  --server-name "brave-search" \
  --server-command "npx" \
  --args="-y,@modelcontextprotocol/server-brave-search" \
  --env '{"BRAVE_API_KEY": "your_brave_api_key"}' \
  --description "Brave Search API integration"

Advanced Configuration

Servers with Environment Variables

Pass environment variables using the --env flag with JSON:

secure-mcp-gateway config add-server \
  --config-name "production-config" \
  --server-name "database-server" \
  --server-command "python" \
  --args="db_server.py" \
  --env '{
    "DB_HOST": "localhost",
    "DB_PORT": "5432",
    "DB_NAME": "production",
    "DB_USER": "admin",
    "DB_PASSWORD": "secure_password",
    "DEBUG": "false"
  }' \
  --description "Database MCP Server"

Servers with Tool Restrictions

Restrict which tools are exposed from a server:

secure-mcp-gateway config add-server \
  --config-name "default_config" \
  --server-name "restricted-server" \
  --server-command "python" \
  --args="tools_server.py" \
  --tools '{
    "read_file": {"enabled": true},
    "search": {"enabled": true},
    "delete_file": {"enabled": false},
    "execute_command": {"enabled": false}
  }' \
  --description "Server with restricted tool access"

How tool restrictions work

When you specify tools in the config:

Only listed tools with "enabled": true will be discovered and accessible
All other tools from the server will be hidden
If tools: {} (empty), all tools are discovered (default behavior)
This is useful for security: limit access to dangerous operations

Remote MCP Servers

Using mcp-remote

For servers that expose HTTP/SSE endpoints:

secure-mcp-gateway config add-server \
  --config-name "default_config" \
  --server-name "remote-api" \
  --server-command "npx" \
  --args="-y,mcp-remote,https://api.example.com/mcp" \
  --description "Remote MCP server via HTTP"

With Custom Headers

For remote servers requiring authentication headers:

{
  "server_name": "remote-authenticated",
  "config": {
    "command": "npx",
    "args": [
      "-y",
      "mcp-remote",
      "https://api.example.com/mcp",
      "--header",
      "Authorization: Bearer token123",
      "--header",
      "X-API-Key: your-api-key"
    ]
  }
}

OAuth-Enabled Servers

For servers requiring OAuth 2.0/2.1 authentication, see the OAuth Setup Guide for complete details.

Quick Example

{
  "server_name": "oauth-server",
  "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": "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"
  }
}

Server Management

List All Servers in a Config

secure-mcp-gateway config list-servers --config-name "production-config"

Get Server Details

secure-mcp-gateway config get-server \
  --config-name "production-config" \
  --server-name "github"

Update Server Configuration

# Update command and args
secure-mcp-gateway config update-server \
  --config-name "production-config" \
  --server-name "github" \
  --server-command "node" \
  --args="github-server.js"

# Update environment variables
secure-mcp-gateway config update-server \
  --config-name "production-config" \
  --server-name "database-server" \
  --env '{"DB_HOST": "db.production.com", "DB_PORT": "5433"}'

# Update tool restrictions
secure-mcp-gateway config update-server \
  --config-name "default_config" \
  --server-name "tools-server" \
  --tools '{"dangerous_tool": {"enabled": false}}'

Remove a Server

secure-mcp-gateway config remove-server \
  --config-name "production-config" \
  --server-name "old-server"

Verification

Test Server Connection

After adding a server, verify it’s working by discovering tools:

Restart Claude Desktop

Close and reopen Claude Desktop to load the updated configuration.

List all servers

In Claude, ask:

List all available MCP servers

Your new server should appear in the list.

Discover tools

Ask Claude to:

Discover all tools from [your-server-name]

This tests the server’s ability to respond to tool discovery requests.

Test a tool

Try executing a simple tool:

Use [tool-name] from [server-name] to [perform action]

Check Gateway Logs

For debugging, check the gateway logs in the Claude Desktop log directory: macOS:

tail -f ~/Library/Logs/Claude/mcp*.log

Windows:

Get-Content "$env:APPDATA\Claude\logs\mcp*.log" -Wait

Troubleshooting

Server Not Appearing

Check config file syntax

Validate your configuration:

secure-mcp-gateway config validate --config-name "your-config"

Verify server command is accessible

Test the command manually:

# For NPX servers
npx -y @modelcontextprotocol/server-github --version

# For Python servers
python server.py --help

Check environment variables

Ensure required environment variables are set in the server config:

secure-mcp-gateway config get-server \
  --config-name "config" \
  --server-name "server"

Restart Claude Desktop

Configuration changes require a restart:

Close Claude Desktop completely
Wait 5 seconds
Reopen Claude Desktop

Tool Discovery Fails

Check server logs: Look for error messages in the MCP logs
Test independently: Run the server outside the gateway to verify it works
Verify transport: Ensure server supports stdio transport
Check permissions: Verify file paths and execute permissions

Authentication Errors

API keys: Verify environment variables contain valid keys
OAuth: Check client credentials and token URL
Tokens: Ensure tokens haven’t expired

Best Practices

Use Descriptive Names

Name servers clearly: github-prod, database-dev, search-staging

Document Dependencies

Include installation instructions in the description field

Separate Environments

Use different configs for dev/staging/production

Restrict Tools

Limit tool access to only what’s needed for security

Use Environment Variables

Never hardcode credentials; always use env vars

Test Before Deployment

Validate servers in development configs first

Example: Complete Production Setup

Here’s a complete example of a production configuration with multiple servers:

# 1. Create production config
secure-mcp-gateway config add --config-name "production"

# 2. Add GitHub server
secure-mcp-gateway config add-server \
  --config-name "production" \
  --server-name "github" \
  --server-command "npx" \
  --args="-y,@modelcontextprotocol/server-github" \
  --env '{"GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_prod_token"}' \
  --description "GitHub integration for prod"

# 3. Add search server with tool restrictions
secure-mcp-gateway config add-server \
  --config-name "production" \
  --server-name "search" \
  --server-command "npx" \
  --args="-y,@modelcontextprotocol/server-brave-search" \
  --env '{"BRAVE_API_KEY": "prod_search_key"}' \
  --tools '{"search": {"enabled": true}, "summarize": {"enabled": true}}' \
  --description "Search with limited tools"

# 4. Add database server
secure-mcp-gateway config add-server \
  --config-name "production" \
  --server-name "database" \
  --server-command "python" \
  --args="/opt/mcp/db_server.py" \
  --env '{
    "DB_HOST": "db.prod.company.com",
    "DB_PORT": "5432",
    "DB_NAME": "production",
    "READ_ONLY": "true"
  }' \
  --description "Production database (read-only)"

# 5. Validate configuration
secure-mcp-gateway config validate --config-name "production"

# 6. Create project and assign config
secure-mcp-gateway project create --project-name "Production"
secure-mcp-gateway project assign-config \
  --project-name "Production" \
  --config-name "production"

# 7. Create users and generate API keys
secure-mcp-gateway user create --email "[email protected]"
secure-mcp-gateway project add-user \
  --project-name "Production" \
  --email "[email protected]"
secure-mcp-gateway user generate-api-key \
  --email "[email protected]" \
  --project-name "Production"

Next Steps

Configure Guardrails

Add input/output protection to your servers

OAuth Setup

Configure OAuth authentication for remote servers

External Cache

Set up Redis/KeyDB for improved performance

Custom Plugins

Create your own auth and guardrail plugins

Get Started

Core Concepts

Features

Deployment

Client Integration

Observability

Security

Guides

​Overview

​Prerequisites

​Adding Your First Server

​Using the CLI

​Using JSON Configuration

​Common MCP Servers

​GitHub MCP Server

​Filesystem MCP Server

​Brave Search MCP Server

​Advanced Configuration

​Servers with Environment Variables

​Servers with Tool Restrictions

​Remote MCP Servers

​Using mcp-remote

​With Custom Headers

​OAuth-Enabled Servers

​Quick Example

​Server Management

​List All Servers in a Config

​Get Server Details

​Update Server Configuration

​Remove a Server

​Verification

​Test Server Connection

​Check Gateway Logs

​Troubleshooting

​Server Not Appearing

​Tool Discovery Fails

​Authentication Errors

​Best Practices

Use Descriptive Names

Document Dependencies

Separate Environments

Restrict Tools

Use Environment Variables

Test Before Deployment

​Example: Complete Production Setup

​Next Steps

Configure Guardrails

OAuth Setup

External Cache

Custom Plugins

Build docs developers (and LLMs) love

Overview

Prerequisites

Adding Your First Server

Using the CLI

Using JSON Configuration

Common MCP Servers

GitHub MCP Server

Filesystem MCP Server

Brave Search MCP Server

Advanced Configuration

Servers with Environment Variables

Servers with Tool Restrictions

Remote MCP Servers

Using mcp-remote

With Custom Headers

OAuth-Enabled Servers

Quick Example

Server Management

List All Servers in a Config

Get Server Details

Update Server Configuration

Remove a Server

Verification

Test Server Connection

Check Gateway Logs

Troubleshooting

Server Not Appearing

Tool Discovery Fails

Authentication Errors

Best Practices

Example: Complete Production Setup

Next Steps