Security

The MCP Gateway uses smart authentication based on request source. Local development is frictionless, while remote access requires proper authentication.

Authentication Model

Source	Authentication Required	Default
Localhost (127.0.0.1, ::1)	No	Trusted by default
Local network	Optional	Configure trusted_ips
Remote/Internet	Yes	Bearer token required

Local Access

Requests from localhost skip authentication by default. This keeps local development seamless—no tokens to manage when working on your own machine.

# Works without any auth from localhost
curl http://localhost:8989/mcp -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'

Remote Access

When accessing the gateway from a remote machine, authentication is required.

Configuration

# ~/.mcp-gateway/config.yaml
settings:
  security:
    auth:
      enabled: true

      # IPs that skip auth (checked against TCP connection, not headers)
      trusted_ips:
        - "127.0.0.1"
        - "::1"
        - "192.168.1.0/24"  # Optional: trust local network

      # General API keys
      api_keys:
        - "your-api-key-here"

      # Project tokens: authenticate AND identify project in one step
      project_tokens:
        "proj-token-abc123": "my-project"
        "proj-token-xyz789": "other-project"

Token Management

# Enable HTTP auth and generate token
mcpg enable-http

# View current token
mcpg show-token

# Rotate token (invalidates old one)
mcpg rotate-token

# Disable HTTP auth (localhost only)
mcpg disable-http

Token Types

Type	Use Case	Header
General API Key	Access gateway, project from headers/params	Authorization: Bearer <key>
Project Token	Access gateway + auto-set project context	Authorization: Bearer proj-token-xxx

General API Keys

API keys authenticate requests but require you to specify the project separately:

curl http://your-server:8989/mcp \
  -H "Authorization: Bearer your-api-key" \
  -H "X-MCP-Project: my-project" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'

Project Tokens

Project tokens combine authentication and project identification—ideal for remote integrations:

# Token "proj-token-abc123" maps to "my-project" in config
curl http://your-server:8989/mcp \
  -H "Authorization: Bearer proj-token-abc123" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'

No need for X-MCP-Project header—the project is automatically identified from the token.

Trusted IPs

Configure which IPs can access the gateway without authentication:

settings:
  security:
    auth:
      trusted_ips:
        - "127.0.0.1"           # IPv4 localhost
        - "::1"                 # IPv6 localhost
        - "192.168.1.0/24"      # Local network subnet
        - "10.0.0.5"            # Specific trusted host

warning

Trusted IP checking uses the actual TCP connection source, not HTTP headers like X-Forwarded-For. This prevents header spoofing attacks.

Network Binding

By default, the gateway binds to 127.0.0.1 (localhost only). To accept remote connections:

gateway:
  host: "0.0.0.0"  # Bind to all interfaces
  port: 8989

Required for Remote Binding

When binding to 0.0.0.0, authentication must be enabled. The gateway will refuse to start without a token configured—this prevents accidental exposure.

Credential Protection

Environment Variables

Sensitive credentials belong in .env files, not config. The gateway supports two .env locations:

Gateway .env (shared defaults)

Store credentials shared across multiple workspaces:

# ~/.mcp-gateway/.env
SUPABASE_PROD_TOKEN=sbp_prod_xxxxx
SUPABASE_STAGING_TOKEN=sbp_staging_xxxxx
GITHUB_WORK_TOKEN=ghp_work_xxxxx

Workspace .env (local overrides)

Override gateway defaults for specific workspaces:

# /my-project/.env
GITHUB_TOKEN=ghp_project_specific_xxxxx  # Overrides gateway value
DEBUG=true

Referencing Variables

Use ${VAR} syntax in config to reference environment variables:

profiles:
  github-work:
    servers:
      github:
        transport: stdio
        command: npx
        args: [-y, "@modelcontextprotocol/server-github"]
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: ${GITHUB_WORK_TOKEN}  # From .env files

warning

Never commit .env files to version control. Add .env to your .gitignore.

Log Sanitization

The gateway automatically redacts sensitive data from logs:

• API tokens and keys
• Passwords and secrets
• Bearer tokens
• Credential-like patterns

Lines containing sensitive patterns are logged as:

[REDACTED: contains sensitive data]

Process Security

Path Validation

Working directory (cwd) paths are canonicalized to prevent directory traversal attacks:

../../../etc/passwd → Rejected or resolved to actual path

Shell Escaping

When shell mode is enabled for servers, all arguments are automatically escaped to prevent command injection.

Bounded Resources

Resource	Limit	Purpose
stderr buffer	100 lines × 10KB	Prevent memory exhaustion
Process lifetime	Tracked	Enable idle cleanup
Background tasks	Managed	Prevent resource leaks

Admin Panel Security

When the admin panel is enabled, it has its own authentication:

Access Type	Authentication
Localhost	None required (for convenience)
Remote	Session cookie or API key required

See Admin Panel for user management and API key creation.

Security Checklist

Development (localhost)

• Gateway bound to 127.0.0.1 (default)
• .env files in .gitignore
• No secrets in config files

Production (remote access)

• Authentication enabled (mcpg enable-http)
• Strong API keys/tokens generated
• Trusted IPs configured for known hosts
• Project tokens for automated integrations
• Regular token rotation scheduled
• Audit logs monitored (if admin panel enabled)

Best Practices

1. Use project tokens for remote integrations—they're simpler and more secure than API key + header combinations

2. Rotate tokens periodically—use mcpg rotate-token to invalidate old tokens

3. Minimize trusted IPs—only add networks you fully control

4. Keep credentials in .env—never hardcode tokens in config files

5. Monitor audit logs—if using the admin panel, review failed login attempts